Struct ValidationIssue 

#[non_exhaustive]
pub struct ValidationIssue {

    pub error_code: Option<&'static str>,
    pub severity: ValidationSeverity,
    pub message: String,
    pub offset: Option<usize>,
    pub segment_tag: Option<String>,
    pub rule_id: Option<String>,
    pub element_index: Option<u8>,
    pub component_index: Option<u8>,
    pub segment_occurrence: Option<u16>,
    pub message_ref: Option<String>,
    pub suggestion: Option<String>,
    pub segment_group: Option<Arc<str>>,
    pub context: Vec<(String, String)>,
}

A structured validation issue.

Marked #[non_exhaustive] so that new diagnostic fields (e.g. segment_group) can be added in future releases without breaking downstream code that constructs issues via struct literals. Always use ValidationIssue::new + builder methods (with_*) rather than constructing directly.

Rule ID prefix convention

The rule_id field doubles as a lightweight metadata carrier when no full context map is needed. Use a namespaced, structured prefix so consumers can extract domain-specific information without parsing the human-readable message:

"<PACK>-<SCOPE>-<TAG>-<STATUS>"
 ^^^^^^^^                        — identifies the pack / profile (e.g. "AHB-13001")
             ^^^^^^^             — identifies the rule scope (e.g. "SG5", "BGM")
                     ^^^         — identifies the affected segment
                         ^^^^^^^  — M/C/... status or short discriminator

Example: "AHB-13001-BGM-M" encodes the AHB process identifier (13001), the affected segment (BGM), and the mandatory status (M). Downstream code can extract the PID with a simple string split:

if let Some(pid) = rule_id.strip_prefix("AHB-").and_then(|s| s.splitn(2, '-').next()) {
    println!("process identifier: {pid}"); // "13001"
}

For truly arbitrary domain metadata, use the context map and with_context_entry.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

error_code: Option<&'static str>

Stable error code, if known.

Not preserved across serialization round-trips: deserialized issues always have error_code = None because error codes are compile-time library constants, not external data.

severity: ValidationSeverity

The severity of this issue.

message: String

The error or warning message.

offset: Option<usize>

Byte offset in the source (if available).

segment_tag: Option<String>

Segment tag involved (if known).

rule_id: Option<String>

Profile/MIG rule identifier, if applicable.

By convention, rule IDs are namespaced hierarchically so that downstream code can extract domain-specific metadata (pack name, process ID, rule scope) from the string. See the ValidationIssue type-level docs for the recommended naming convention.

element_index: Option<u8>

Element index (0-based), if known.

u8 is sufficient: EDIFACT segments have at most 99 data elements per the UN/EDIFACT standard, so an index fits comfortably in one byte.

component_index: Option<u8>

Component index (0-based), if known.

u8 is sufficient: composite data elements have at most 99 components per the UN/EDIFACT standard.

segment_occurrence: Option<u16>

Zero-based occurrence index among segments with the same tag in the message.

When multiple segments share the same tag (e.g. repeated DTM lines), this field indicates which occurrence (0 = first) was the source of this issue. None when occurrence tracking is not available for this rule.

message_ref: Option<String>

Message reference (UNH element 0, DE 0062) that this issue belongs to.

Populated automatically when the context was built with ValidationContextBuilder::with_message_ref. Useful in batch processing where many messages are validated and issues from different messages must be correlated back to the originating UNH/UNT envelope.

suggestion: Option<String>

Suggested remediation (if available).

segment_group: Option<Arc<str>>

Segment group (e.g. "SG6") in which the issue occurred, if known.

Populated by group-aware rule functions when they evaluate sub-slices of a crate::group::SegmentGroupIndexed tree. None for flat-segment rules that do not have group context.

context: Vec<(String, String)>

Arbitrary domain-specific key-value metadata attached to this issue.

Use this for information that does not fit into the structured fields above — for example the PID a downstream MIG crate is validating against, a trading-partner identifier, or a document UUID:

let issue = ValidationIssue::new(ValidationSeverity::Error, "BGM code invalid")
    .with_rule_id("AHB-13001-BGM-M")
    .with_context_entry("pid", "13001")
    .with_context_entry("partner", "9900123456789");
assert_eq!(issue.context_get("pid"), Some("13001"));

The vec is empty by default and is never populated by the built-in rules; it is reserved exclusively for caller-supplied metadata.

Entries are stored in insertion order; duplicate keys are allowed and context_get returns the first match. with_context_entry uses upsert semantics (updates an existing key in place rather than duplicating it).

Implementations

impl ValidationIssue

pub fn new(severity: ValidationSeverity, message: impl Into<String>) -> Self

Create a new validation issue.

pub fn with_error_code(self, code: &'static str) -> Self

Set stable error code metadata.

pub fn with_offset(self, offset: usize) -> Self

Set the byte offset for this issue.

pub fn with_segment(self, tag: impl Into<String>) -> Self

Set the segment tag for this issue.

pub fn with_rule_id(self, rule_id: impl Into<String>) -> Self

Set the profile/MIG rule identifier for this issue.

pub fn with_element_index(self, element_index: u8) -> Self

Set the element index (0-based) for this issue.

pub fn with_component_index(self, component_index: u8) -> Self

Set the component index (0-based) for this issue.

pub fn with_suggestion(self, suggestion: impl Into<String>) -> Self

Set a suggestion for resolving this issue.

pub fn with_segment_occurrence(self, occurrence: u16) -> Self

Set the zero-based occurrence index for this issue.

Use this when the same segment tag appears multiple times in a message and you want to identify which occurrence is affected.

pub fn with_message_ref(self, message_ref: impl Into<String>) -> Self

Set the message reference (UNH element 0) for this issue.

Use this to correlate an issue back to a specific message in a multi-message interchange.

pub fn with_segment_group(self, group: impl Into<Arc<str>>) -> Self

Set the segment group (e.g. "SG6") in which this issue occurred.

Use this from group-aware rule functions that evaluate a sub-slice of a crate::group::SegmentGroupIndexed tree so that consumers can identify the exact group occurrence without re-reading the raw message.

pub fn with_context_entry( self, key: impl Into<String>, value: impl Into<String>, ) -> Self

Insert a single key-value entry into the domain-specific context map.

Calling this multiple times accumulates entries; duplicate keys overwrite the previous value.

Example

let issue = ValidationIssue::new(ValidationSeverity::Error, "BGM code invalid")
    .with_rule_id("AHB-13001-BGM-M")
    .with_context_entry("pid", "13001")
    .with_context_entry("partner", "9900123456789");

assert_eq!(issue.context_get("pid"), Some("13001"));
assert_eq!(issue.context_get("partner"), Some("9900123456789"));

pub fn with_context_entries<K, V, I>(self, entries: I) -> Self

where K: Into<String>, V: Into<String>, I: IntoIterator<Item = (K, V)>,

Extend the domain-specific context map from an iterator of (key, value) pairs.

Example

let meta = [("pid", "13001"), ("partner", "9900123456789")];
let issue = ValidationIssue::new(ValidationSeverity::Error, "test")
    .with_context_entries(meta);

assert_eq!(issue.context_get("pid"), Some("13001"));

pub fn context_get(&self, key: &str) -> Option<&str>

Look up a value in the domain-specific context map.

pub fn severity_label(&self) -> &'static str

Short label for the severity level, suitable for display.

pub fn error_code(&self) -> Option<&'static str>

Stable error code, if available.

pub fn offset(&self) -> Option<usize>

Byte offset in the source, if available.

pub fn segment_tag(&self) -> Option<&str>

Segment tag involved in this issue, if known.

pub fn rule_id(&self) -> Option<&str>

Profile/MIG rule identifier, if applicable.

pub fn element_index(&self) -> Option<u8>

Zero-based element index, if known.

pub fn component_index(&self) -> Option<u8>

Zero-based component index, if known.

pub fn segment_occurrence(&self) -> Option<u16>

Zero-based occurrence index among same-tag segments, if known.

pub fn message_ref(&self) -> Option<&str>

Message reference (UNH element 0), if set.

pub fn suggestion(&self) -> Option<&str>

Suggested remediation, if available.

pub fn segment_group(&self) -> Option<&str>

Segment group (e.g. "SG6") in which the issue occurred, if known.

Trait Implementations

impl Clone for ValidationIssue

fn clone(&self) -> ValidationIssue

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ValidationIssue

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for ValidationIssue

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for ValidationIssue

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Error for ValidationIssue

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl PartialEq for ValidationIssue

fn eq(&self, other: &ValidationIssue) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for ValidationIssue

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for ValidationIssue