ADR-017: Namespaced extensions in batch metadata (schema 1.3.0)

Fields that a rule or add-on adds to a batch live in the metadata document under extensions.<key>, one object per rule, each validated by the JSON Schema fragment the rule publishes in its descriptor.

Context

Hooks are the single extension point of A-REX Core, and anyone can deploy one. A rule often needs facts about a batch that the core fields do not hold. Examples: a moisture reading at intake, the registry serials of carbon credits set aside for a lot, the cold-chain profile of a delivery. Today an issuer can add such fields anywhere, because the schema allows additional properties at the top level ("additionalProperties": true). Two rules can then pick the same name with different meanings. A validator cannot check the fields, and a reader cannot tell which rule they belong to.

Issue

Where do fields contributed by rules and add-ons go in the batch metadata document, and how are they validated?

Assumptions

• Rules publish a descriptor (interop/RULE-DESCRIPTOR.md) with a stable key (^[a-z][a-z_]{2,40}$) and, optionally, a JSON Schema fragment lotFields.schema.
• The metadata document is committed on chain by metadataHash, so fields can never be added to a batch afterwards, only to a new document (setBatchMetadata) or a new batch.

Constraints

• Every document valid under 1.0.0, 1.1.0 and 1.2.0 stays valid (minor release).
• No personal data in public documents (AREX-CORE §3.5, restricted).

Alternatives considered

Decision (proposed)

Schema 1.3.0 adds one optional top-level property:

"extensions": {
  "type": "object",
  "description": "Fields contributed by rules (hooks) and add-ons, one object per rule, keyed by the rule descriptor's `key` (interop/RULE-DESCRIPTOR.md). Each object is validated by the JSON Schema fragment of that rule's descriptor (`lotFields.schema`). Personal data never goes here; use `restricted`.",
  "propertyNames": { "pattern": "^[a-z][a-z_]{2,40}$" },
  "additionalProperties": { "type": "object" }
}

and schemaVersion accepts "1.3.0" besides "1.0.0", "1.1.0" and "1.2.0".

Rules:

• A rule's fields MUST be placed under extensions.<key> of that rule.
• A validator that has the descriptor of a rule SHOULD validate extensions.<key> with its lotFields.schema. Without the descriptor it accepts the object as opaque.
• Top-level additional properties stay allowed for backward compatibility. New rules SHOULD NOT use them.
• EPCIS mappings (interop/EPCIS.md) carry extensions.<key> as ILMD under a namespace derived from the rule's publisher id.

Argument

The rule's key already identifies it across versions, and its descriptor already carries the schema. Keying the fields by the same key makes every field traceable to the rule that asked for it. Validation is per rule, so one malformed rule never blocks the rest of the document.

Consequences

Positive

• Rules from different publishers can add fields without colliding.
• Forms and validators are generated from the descriptor.

Negative

• A reader without the descriptor sees opaque objects.

Obligations it creates

• A test in test/metadata-schema.test.mjs for extensions (valid object, invalid key, old documents still valid).
• interop/EPCIS.md: an ILMD mapping for extensions.

Implementation and evidence

Related decisions

• ADR-001: only the specification and the interfaces are normative (the descriptor is informative)
• ADR-004: every rule is an independent IARexHook contract
• ADR-008: no coordinates or natural-person identifiers in the batch record
• ADR-014: carbon credits as records of immobilised registry credits (a first user of extensions)