N-ADR-001: Schema Validation Strictness Policy

Metadata

• ADR ID: N-ADR-001
• Title: Payload Schema Validation Strictness (Strict vs. Lenient)
• Status: Proposed
• Date: 2026-03-15 (proposed)
• Owner: Node firmware lead
• Target Decision Date: 2026-04-03
• Relates to: Node-Gaps-Deferred#schema-validation-strictness-policy

Problem / Context

The node decodes incoming frames against a schema (Node-FrameConfig-PayloadTyping). The decoder must handle schema mismatches, but the behavior is undefined:

1. Extra fields: If incoming frame has fields not in schema, accepted or rejected?
2. Missing fields: If incoming frame lacks fields in schema, accepted with nulls or rejected?
3. Type mismatches: If field is expected int but data looks like string, convert or error?
4. Partial matches: If 90% of schema is correct but 10% malformed, process the 90%?
5. Unknown payload types: If frame type is not in schema, drop or attempt raw fallback?
6. Strictness flags: Can operator adjust strictness at runtime (e.g., "lenient mode" for anomalous targets)?

Current State

• Node-FrameConfig-PayloadTyping defines schema structure but not validation policy
• Prototypes use Python JSON schema library (default: fail on extra keys)
• No fallback for schema violations

Why This Matters

• Robustness: Corrupted frames shouldn't crash decoder; should gracefully degrade
• Flexibility: Targets with slightly different payloads (e.g., optional field) should still decode
• Debugging: Operator needs clear error messages when schema doesn't match reality
• Safety: Too-lenient validation may hide real data corruption

Deferred Decision Options

Option A: Strict Schema Enforcement (Conservative)

Approach: Require exact schema match. Any deviation (extra field, missing field, type mismatch) causes entire frame to be dropped.

Rules:

• Extra fields → Error (unexpected data)
• Missing fields → Error (incomplete frame)
• Type mismatch (e.g., string instead of int) → Error (corrupted)
• Unknown payload type → Error (not in schema registry)

Pros:

• Safety: prevents silent data corruption
• Clear intent: schema is a contract, violations obvious
• Debugging easier: operator knows exactly what's wrong
• Standards-aligned: many APIs (gRPC, REST with strict validation) use this model

Cons:

• Fragile: any firmware mismatch breaks decoding
• High operational overhead: schema updates must be synchronized across all nodes/targets
• Loss of data during transitions: if firmware changes payload mid-mission, lose that frame

Implementation:

import jsonschema

def validate_frame_strict(frame_data, schema):
    """Strict validation: any deviation is an error."""
    try:
        jsonschema.validate(instance=frame_data, schema=schema, format_checker=jsonschema.FormatChecker())
        return True, frame_data
    except jsonschema.ValidationError as e:
        log_error(f"Schema validation failed: {e}")
        return False, None  # Frame rejected

Option B: Lenient Parsing with Warnings (Flexible)

Approach: Accept frames with deviations, but log warnings. Use best-effort parsing: decode what you can, fill missing fields with nulls, ignore extra fields.

Rules:

• Extra fields → Accepted, ignored (warn once per frame type)
• Missing fields → Accepted, field set to null (warn)