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.
Codes, flags, and confidence
- issues[]: discrete problems with severity, code, and message (machine + human readable).
- node.flags[]: lightweight machine-readable tags on a node, suitable for routing and filtering.
- node.confidence: numeric indicator of certainty in inferred fields on that node (0–1), not overall document quality.
For interoperability, issue codes and flags SHOULD use lowercase identifiers with dots/underscores/dashes (e.g. role_ambiguous).
Standard registry (v1)
| Identifier | Type | Meaning |
|---|---|---|
| layout_fallback | flag | Layout emitted as a fallback (e.g. absolute) |
| token_missing | flag / issue | Expected token mapping could not be resolved |
| token_ref_invalid | issue | Token reference points to a missing token key |
| role_ambiguous | issue | Semantic role could not be determined confidently |
| role_inferred | flag | Role was inferred heuristically (not explicit) |
| instance_unresolved | flag / issue | Component instance relationship could not be resolved |
| unsupported_feature | issue | Source feature cannot be represented in Forma v1 |
| text_missing | issue | Text node missing required content from source |
| asset_missing | flag / issue | Image/icon node has no resolvable asset reference |
| ai_handler_order_ambiguous | flag / issue | Multiple AI-native event handlers match with ambiguous ordering |
| ai_fixture_missing | issue | AI-native invoke references a fixture that is not declared |
| ai_contract_remote_ref | flag / issue | Capability/event contract uses a remote $ref (not deterministic) |
| source_incomplete | flag | Source metadata is incomplete for stable export |
Producers MAY define additional codes and flags. Consumers MUST ignore unknown codes/flags safely.
{
"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.