AXIS Normative Behavior Rules v0.1

Purpose

This section defines normative behavioral rules that govern AXIS schema implementation. These rules remove ambiguity before any schema implementation work begins. All schema, component, entity, DD, and instance work must conform to these rules.

See also: entities-as-validator-contracts decision record (not published in public site set) — Entities as validator contracts and the boundary between schema validation and business logic.

0. Conformance Authority, Core Representation, and Delivery Boundary

  • AXIS core conformance is JSON-first in v0.1.
  • AXIS defines semantic and conformance behavior, not transport or packaging.
  • Implementer-side transformation to other representations is permitted at implementer risk and does not modify AXIS conformance semantics.
  • Canonical AXIS schema definitions use governed canonical field names only. Aliases and synonyms are not permitted in canonical schema artifacts.
  • Alias handling is permitted only in external mapping artifacts maintained by implementers or profile authors.
  • A conformant processor must satisfy two independent obligations:
  • unknown-field rejection: undeclared fields are non-conformant,
  • contract-claim parity: any declared conformance claim must be enforced.

1. Report Identity And Version Rules

  • A report instance must be identified by report_id plus version.
  • A review must reference exactly one report_id plus one report_version.
  • Once a report version is referenced by a review, that report version is immutable.
  • A new report version must be created if the underlying report requires change after a review references it.
  • Report assignment-context fields intended_use and intended_user are optional in v0.1 and do not affect baseline conformance when omitted.

Note: v0.1 uses new_version as the correction path. A separate errata mechanism is deferred to a future version.

Versioning rule:

  • schema_version and DD artifact_version use semantic versioning (Major.Minor.Patch).
  • Instance version progression uses integer-style sequence (v1, v2, v3).

2. Review Anchoring And Peer Model

  • Reviews are peer artifacts with no parent-child review hierarchy.
  • Each review anchors directly to exactly one report version via report_id plus report_version.
  • referenced_review_id is optional and carries zero or one reference to another review instance.
  • Semantic purpose of referenced_review_id: an optional informed_by trace link to prior review context.
  • A referenced_review_id reference does not change or replace the required anchoring to report_id plus report_version.
  • All reviews within a single review chain resolve to the same root report version anchor.
  • A new_version disposition starts a new root anchor. The resulting new report version begins an independent review chain if reviewed again.
  • If referenced_review_id is present, the referenced review must share the same report_id and report_version as the current review instance.

Enforcement responsibility:

  • DD and instance validators must enforce this cross-check when both review instances are available in the same validation context.
  • If the referenced review artifact is unavailable to a validator, the cross-check result is unresolved and must not be treated as a pass.

3. Flag-Driven Requiredness

  • A DD defines available flags and the requiredness effects each flag activates.
  • Instance-level flags may activate additional conditional requiredness for fields or fieldsets not globally required by the DD.
  • Flag-driven requiredness reflects methodology and context that cannot be known until the report instance is developed.
  • If a field is required — whether globally by the DD or conditionally by an active instance flag — and no valid value exists, the instance is invalid.
  • Flags not set at the instance level do not activate their associated requiredness rules.

Flag structure rule:

  • DDs should declare available_flags with typed effects.
  • Instances should declare active_flags to activate those effects.
  • Initial canonical effect type: activate_required.

Flag resolution semantics:

  • Activating a flag not declared in DD available_flags is invalid.
  • Flag activation is explicit at the instance level only. Flags do not transitively activate other flags in v0.1.
  • If multiple active flags target overlapping fields or fieldsets, requiredness effects resolve as a union. Ordering does not change outcome.
  • Flag names are DD-scoped identifiers and are governed by the declaring DD.

Requiredness Precedence

  • DD-level required cannot be weakened or removed by an instance flag.
  • Instance flags may only activate additional requiredness.
  • Instance flags may never remove or override base DD requiredness.
  • Explicit required always overrides conditional optional.

4. Output And Absence Semantics

  • Non-required fields and fieldsets may be absent without invalidating the instance.
  • Absence of a non-required field is a valid omission signal and must not be interpreted as an error by conforming consumers.
  • Required fields cannot rely on silent omission. A required field with no valid value produces an invalid instance.
  • Empty strings must not be used as a substitute for absence. A field is either present with a valid value or absent.

Validator Scope vs. Business Logic

AXIS schemas (entities, components, forms) define structure, types, requiredness, and patterns. Validators built on these schemas can automatically check for missing required fields, type mismatches, and pattern violations.

Business logic and cross-field rules (e.g., sums, consistency checks) are out of scope for AXIS schema validation. These must be implemented by vendors or downstream consumers as needed. See entities-as-validator-contracts decision record (not published in public site set) for rationale and examples.

Conformance checks that are in scope:

  • Unknown-field rejection is required.
  • Contract-claim parity is required: if a processor claims conformance to an AXIS contract, it must enforce all requirements in that contract.

Conformance checks that are out of core scope by default:

  • Repeated-field and cross-field consistency checks are Delivery Profile or downstream validation concerns unless explicitly elevated by a later accepted AXIS decision.

Null semantics:

  • JSON null is distinct from absence.
  • In v0.1, null is invalid unless the governing primitive or DD field constraint explicitly permits null.
  • If null is permitted, it must be treated as an explicit value state, not as implicit omission.

Array semantics:

  • For non-required arrays, absence and empty array are both valid unless a DD declares stronger constraints.
  • For required arrays, absence is invalid.
  • For required arrays with minimum cardinality greater than zero, empty array is invalid.

Invalid-instance operational semantics:

  • Invalidity is a validation-layer state.
  • Invalid instances may be serialized for diagnostics, testing, or draft workflows, but they must not be published as conformant artifacts.
  • Conformant consumers may reject invalid instances or process them in non-conformant diagnostic mode if clearly marked invalid.

Optional provenance header semantics:

  • generator and generator_version are optional instance header fields.
  • Omission of either or both is conformant in v0.1.
  • If present, each must satisfy its declared type constraints.

Money representation rule:

  • Monetary values use amount plus currency_code.
  • currency_code must use ISO 4217 three-letter codes.
  • No default currency is assumed in v0.1.

Component conformance:

  • A component instance is conformant when all component-required fields are present with valid values and optional fields (if present) satisfy declared type and value constraints.
  • Component-level requiredness is evaluated before DD-level composition requiredness.

5. Review Fieldset Model

  • By default, review fieldsets are selective. A reviewer generates a fieldset only for fields considered material in that review instance.
  • Absence of a fieldset in selective mode signals that the field was considered immaterial or not applicable in this instance. It is not an error.
  • A DD or instance-level flag full_field_coverage may activate generated fieldsets for all fields present in the referenced report instance.
  • In full_field_coverage mode, absent fieldsets for present report fields are invalid.
  • In full_field_coverage mode, fields permissibly absent from the report instance do not require fieldsets.
  • For arrays in full_field_coverage mode, fieldsets are generated per element path (for example /comparables/0/sale_price).
  • Each fieldset carries:
  • field_reference — JSON Pointer (RFC 6901) path to the field in the report instance (example: /subject/address/city)
  • original_value — the value as it appears in the report instance
  • is_valid — reviewer determination of field validity
  • severity_category — reviewer assigned categorical severity (a, b, or c)
  • comment — optional reviewer commentary
  • Canonical severity_category values are lowercase a, b, and c. Uppercase display labels may be used in documentation, but uppercase values are not canonical data values.
  • severity_category is assigned by the reviewer at review time based on full report context. It cannot be predetermined at the DD level because field relevance and impact depend on the methodology used in the report instance.

Field-reference resolution across versions:

  • field_reference is resolved against the report version explicitly declared by report_id plus report_version in the review instance.
  • A review finding that points to a field not present in that anchored report version is invalid.

Semantic definitions for a, b, and c are deferred to a future version.

Known limitation: JSON Pointer field references may be brittle across future DD structural reorganizations. Field-reference stability across DD versions is deferred to a future version.

Third review finding state beyond selective absence signaling is deferred to a future version.

6. Review Outcome And Disposition

  • outcome is constrained to satisfactory or unsatisfactory.
  • A satisfactory outcome implies terminal disposition. The review chain ends.
  • An unsatisfactory outcome must carry a disposition value.
  • disposition is constrained to terminal or new_version.
  • terminal disposition ends the review chain regardless of outcome.
  • new_version disposition signals that a new report version must be created. The new report version starts a new independent review chain and a new root anchor. It is not a continuation of the prior chain.

Outcome/disposition requiredness:

  • For satisfactory, disposition may be omitted or explicitly set to terminal.
  • For unsatisfactory, disposition is required and must be either terminal or new_version.

7. Signature Conformance

  • Report DD and Review DD must include the signatures component.
  • A report instance without a valid signature is invalid.
  • A review instance without a valid signature is invalid.
  • signatures is an array. At least one signature object must be present for a valid instance.
  • Each signature object must carry:
  • signer_name — non-empty string
  • certification_number — non-empty string
  • certification_state — non-empty string
  • role — non-empty value from governed enumeration (see below)
  • signature_date — valid ISO 8601 date-only string (YYYY-MM-DD)
  • signature_image is optional.
  • is_digital is a boolean flag indicating digital versus wet signature.
  • role is constrained to a governed enumeration:
  • appraiser
  • supervisory_appraiser
  • trainee_appraiser
  • reviewer
  • collateral_evaluator

Identifier rule:

  • Instance identifiers should use UUID v4 values.
  • For report_id and review_id, v0.1 conformance requires type-prefixed snake_case forms:
  • report_<uuid-v4>
  • review_<uuid-v4>
  • Cross-instance identity comparisons use the full identifier value as serialized.

Date-only handling rule: unless a field explicitly requires time precision, date values should use ISO 8601 date-only format (YYYY-MM-DD).

8. Delivery Profiles, Supplemental Guidance, and Change Gate

  • Delivery Profiles are permitted as subordinate artifacts that add implementation-facing delivery constraints.
  • A Delivery Profile may add constraints but may not weaken, redefine, or override AXIS normative semantics.
  • If a Delivery Profile or other supplemental guidance conflicts with this document, this document controls.
  • Supplemental guidance documents must include explicit precedence language stating that AXIS normative behavior controls on conflict.
  • EPM may be used as an implementation-facing envelope for embedding AXIS payloads in host documents. EPM usage is informative and recommended where applicable, but it is not required for AXIS conformance.
  • Compatibility-affecting and breaking AXIS changes must include a conformance suite delta (tests and expected outcomes) before acceptance.

Signature date constraints:

  • Signature-date temporal ordering constraints relative to other dates are deferred to a future version.

8. Naming And Representation Boundary

  • Canonical identifiers name governed AXIS artifacts in normative and specification language only.
  • Canonical identifiers are valid in identity-bearing metadata fields where artifact identity is explicitly declared (for example schema and document_type). Version fields such as schema_version carry version values, not canonical artifact identifiers.
  • Canonical identifiers are not valid as runtime business field values.
  • Canonical identifiers are not valid as filenames or directory names.
  • Runtime fields, JSON objects, filenames, and directory names follow snake_case with full words.
  • Arrays use plural names.
  • Boolean fields use the is_ prefix.
  • Canonical identifiers use dot-separated namespacing with hyphens where appropriate (example: axis.document.appraisal-report).
  • When first introducing a canonical artifact in normative text, state the canonical ID first followed by an implementation example in parentheses. Example: axis.document.appraisal-report (example DD: report_standard_v0_1)

Canonical conformance representation for v0.1:

  • JSON is the canonical representation for conformance and validator behavior.
  • XML/YAML representations are permitted as equivalent expressions only when mappings preserve canonical JSON semantics.

Allowed abbreviations guidance is maintained in CLAUDE_CONTEXT.md.

Extension mechanism declaration and namespacing are deferred to a future version.

Unknown-field behavior for v0.1:

  • Unknown fields are non-conformant unless explicitly declared by the governing DD schema constraints.

Source References

  • Report identity and review anchoring: CLAUDE_CONTEXT.md
  • Flag-driven requiredness: CLAUDE_CONTEXT.md
  • Fieldset model and selective default: CLAUDE_CONTEXT.md, AXIS.md, AXISDD.md
  • Outcome and disposition: CLAUDE_CONTEXT.md
  • Signature conformance: CLAUDE_CONTEXT.md
  • Naming and representation: GLOSSARY.md, 2026-04-23-naming-taxonomy-lock-v0.1.md
  • JSON Pointer path format: RFC 6901