Errors and ambiguity

Not every source feature maps cleanly into Forma. This section standardizes how producers represent ambiguity, unsupported constructs, fallback behavior, and validation-relevant issues.

Issue severities

info
warning
error

Common flags

layout_fallback
token_missing
role_ambiguous
instance_unresolved

Standard behavior

When a producer cannot represent a source feature exactly, it should preserve the closest valid Forma representation and emit an issue or flag rather than emitting invalid data.

Issue exampleJSON

{
  "severity": "warning",
  "code": "role_ambiguous",
  "message": "Semantic role could not be determined with confidence",
  "nodeId": "grp_header_actions"
}

Error model principles

Never use issues as a substitute for required fields.
Use issues to explain lossy transforms and ambiguity.
Preserve machine-readable codes for automated pipelines.