Summary
Validation error messages during deserialization should provide sufficient detail to support user debugging of content. Currently, some error messages lack location information (line/column) and contextual details that would help users pinpoint and understand problems.
Current State
Required Field Validation (needs improvement)
The new required field validation (DESERIALIZE_VALIDATE_REQUIRED_FIELDS) produces messages like:
Missing required property in root: required-flag
Missing required properties in root: required-flag, required-field, required-assembly
Issues:
- No file location (line/column numbers)
- No XPath or element path context
- Generic "property" term doesn't distinguish flag/field/assembly
- Uses JSON names only (may confuse XML users)
Other Parsing Errors (good examples to follow)
XML malformed data errors include location:
Malformed data 'invalid-number' in 'file:///data.xml' at 3:10. For input string: "invalid-number"
JSON missing property errors include location:
Failed to find property with name 'required-field' in 'file:///data.json' at '2:5'.
Format Inconsistency
| Error Source |
Location Format |
| XML parsing |
at [line]:[column] |
| JSON parsing |
at '[line]:[column]' (with quotes) |
| Required field validation |
None |
Options
Option A: Minimal Enhancement (add location only)
Add file and line/column to existing message format:
Missing required property in root: required-flag
at file:///example.xml line 3
Pros:
- Simple implementation
- Maintains current message style
- Low risk of breaking existing error handling
Cons:
- Still uses generic "property" terminology
- No element path context for deeply nested structures
Option B: Detailed Context (location + type + path)
Provide richer context with element types and paths:
Missing required flag 'required-flag' in assembly 'root'
Location: file:///example.xml at 3:45
XPath: /root
Pros:
- Clear distinction between flags, fields, and assemblies
- Path helps locate issues in complex documents
- More actionable for users
Cons:
- More complex implementation
- Requires tracking parser position during validation
Option C: Multi-line Rich Format (maximum context)
Maximum debugging information:
Validation Error: Missing required properties
File: example.xml
Location: line 3, column 45
Parent: assembly 'root' (namespace: http://example.com/ns)
Missing:
- flag 'required-flag' (XML: @required-flag)
- field 'required-field' (XML: <required-field>)
XPath: /root
Pros:
- Maximum debuggability
- Shows both JSON and XML representations
- Groups multiple errors together
Cons:
- Verbose output
- Significant refactoring required
- May be overkill for simple cases
Recommendation
Option B (Detailed Context) provides the best balance:
- Includes location information (file, line, column)
- Distinguishes between property types (flag/field/assembly)
- Provides path context for navigation
- Reasonable implementation complexity
Implementation Considerations
-
Location Tracking: The problem handler receives instances after parsing completes, so location information must be captured during parsing and associated with validation errors.
-
Consistent Format: Standardize location format across XML and JSON (e.g., always use at line:column without quotes).
-
Choice Group Context: When reporting missing required fields in choice groups, indicate which alternatives were expected.
-
Internationalization: Consider whether error messages should be externalizable for i18n.
Acceptance Criteria
Related
Summary
Validation error messages during deserialization should provide sufficient detail to support user debugging of content. Currently, some error messages lack location information (line/column) and contextual details that would help users pinpoint and understand problems.
Current State
Required Field Validation (needs improvement)
The new required field validation (
DESERIALIZE_VALIDATE_REQUIRED_FIELDS) produces messages like:Issues:
Other Parsing Errors (good examples to follow)
XML malformed data errors include location:
JSON missing property errors include location:
Format Inconsistency
at [line]:[column]at '[line]:[column]'(with quotes)Options
Option A: Minimal Enhancement (add location only)
Add file and line/column to existing message format:
Pros:
Cons:
Option B: Detailed Context (location + type + path)
Provide richer context with element types and paths:
Pros:
Cons:
Option C: Multi-line Rich Format (maximum context)
Maximum debugging information:
Pros:
Cons:
Recommendation
Option B (Detailed Context) provides the best balance:
Implementation Considerations
Location Tracking: The problem handler receives instances after parsing completes, so location information must be captured during parsing and associated with validation errors.
Consistent Format: Standardize location format across XML and JSON (e.g., always use
at line:columnwithout quotes).Choice Group Context: When reporting missing required fields in choice groups, indicate which alternatives were expected.
Internationalization: Consider whether error messages should be externalizable for i18n.
Acceptance Criteria
Related