AXIS Composition and Governance Rules

Purpose

This document captures the established rules, constraints, and best practices for composing AXIS artifacts from primitives through reports. It serves as the operational reference for schema design decisions before implementation.

Status: Planning reference. Superseded by formal decision records and docs/model/AXIS_NORMATIVE.md where conflicts exist.

See also: - docs/decisions/2026-05-16-entities-as-validator-contracts.md - docs/decisions/2026-05-16-field-optionality-hierarchy.md - docs/decisions/2026-05-16-source-of-truth-precedence.md

Architecture Layers (6 Levels)

Level 1: Primitives + Enumerations
  - Define type constraints, formats, and governed value sets

Level 2: Components
  - Reusable atomic structures built from primitives (Address, Money, Signature)

Level 3: Entities
  - Reusable domain objects and validator contracts built from components and primitive-typed fields

Level 4: Forms (Form DDs)
  - Workflow-facing contracts that assemble entities and components

Level 5: Reports and Reviews (Report/Review DDs)
  - Final document contracts that assemble forms and governance rules

Level 6: Instances
  - Governed by selected DD versions and carrying actual data

What Each Layer Owns and Does Not Own

Layer Owns Does Not Own
Primitive Type definition, format constraint, pattern validation Names, domain meaning, composition
Component Named fields, atomic domain semantics, type constraints Workflow behavior, requiredness, flags
Entity Domain object contract, validator schema, field vocabulary Business logic, workflow behavior, requiredness activation
Form DD Section behavior, requiredness declarations, available_flags, form-specific fields Report identity, review outcome/disposition
Report/Review DD Assembly contract, report/review identity, version anchoring, outcome/disposition Implementation, transport format, vendor-specific behavior
Instance Actual data values and active flags Structure authoring and governance rules

Composition Rules: What References What

Primitives: - Used by every layer above as type definitions in field declarations. - No layer imports or references primitives as separate runtime artifacts.

Components: - Referenced by entities, forms, and DDs. - Entities compose components (for example, Address into Subject Property). - Forms may reference components directly for atomic concepts (for example, signatures).

Entities: - Referenced by forms and DDs. - Forms assemble entities and components together. - Reports/reviews may compose form DDs (which embed entities) and may reference entities/components directly for DD-level contract fields. - Entity-to-entity composition is deferred in v0.1.

Form DDs: - Referenced by report and review DDs. - Form DDs assemble entities and components, not other forms. - A report DD composes one or more form DDs to create a report contract.

Report/Review DDs: - Governed by instances. - Instances declare which DD version they conform to.

Naming Rules by Layer

Primitives: - Use type identifiers such as string_text, decimal_amount, decimal_ratio, date_iso8601, boolean_flag, json_pointer_ref. - Define string length tiers in Level 1 primitives (for example, short/medium/long) and reuse them in higher layers instead of embedding ad hoc length policy in each schema. - Define dedicated image primitives in Level 1 and reuse them consistently (image_ref_uri preferred; image_data_uri only when embedding is required). - Use boolean_checkbox for checkbox-style yes/no capture where UI intent should be explicit in schema.

Components: - Use domain-independent concepts such as address, money, signature. - Component field names stay canonical across contexts (for example, line_1, city, currency_code). - Select the appropriate Level 1 string tier for each field (for example, postal/code fields as short, address/name fields as medium, narrative/comment fields as long). - For images (photos, signature images), prefer reference fields using image_ref_uri so JSON remains lightweight and transport-neutral. - When image metadata and payload details are needed (filename, media type, size, checksum, content), model them as a dedicated Level 2 component object composed from Level 1 primitives.

Entities: - Use semantic grouping names such as subject_property, comparable_sale, market_area. - Distinct contextual entities are allowed only when semantically distinct, not merely field-count variants.

Forms (Form DDs): - Use purpose-based names such as market_conditions_form_v0_1. - Never rename component/entity fields at form level.

Reports/Reviews (DDs): - Use document type names such as report_standard_v0_1, review_standard_v0_1. - Composition references preserve canonical field names. - Canonical AXIS schema artifacts must not include aliases or synonyms for governed names. - Alias/synonym handling belongs in external mapping artifacts maintained by implementers or delivery-profile authors.

Instances: - Report IDs follow report_<uuid-v4> with integer progression (v1, v2, v3). - Review IDs follow review_<uuid-v4> with integer progression.

Requiredness and Omission Semantics

Required fields: - Fields start optional at their definition layer unless explicitly justified otherwise. - Requiredness is activated upward by forms, DDs, and instance flags. - Higher layers may add requiredness but may not remove lower-layer requiredness.

Optional fields: - Absence of a non-required field is valid. - Do not use empty string as absence signal. - Do not use null unless explicitly permitted by governing constraints.

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 arithmetic are out of scope for AXIS schema validation. For example, checks like "sum of income streams equals gross income" or "gross income minus expenses equals net income" are implementer responsibilities.

Conformance checks are split into two independent obligations: - unknown-field rejection, - and contract-claim parity (a processor that claims AXIS conformance must enforce the claimed contract requirements).

Repeated-field and cross-field consistency checks remain downstream or delivery-profile concerns unless elevated by accepted AXIS decision.

Enumerations Lifecycle Rule

Governed enum values should carry lifecycle metadata fields: - status (active or deprecated), - introduced_in_version, - deprecated_in_version (optional), - replacement_value (optional).

Deprecation should use explicit compatibility windows in release notes rather than immediate hard invalidation.

No-Duplication Governance Rule

Principle: If a concept already exists at a lower layer, higher layers reference it rather than redefining it.

Checklist before defining a new field or entity: 1. Does this field already exist in a component? 2. Does this grouping already exist as an entity? 3. Is this truly semantically distinct, or only a subset/variant? 4. Can form-level requiredness solve the difference without creating a new entity?

Enforcement: - Every new component, entity, or form field should include rationale for why existing artifacts were insufficient.

Component Design Guidance

Create a component when: - Meaning is stable independent of workflow. - It appears in multiple contexts. - It groups primitive fields that consistently belong together.

Do not create a component when: - It is workflow-specific. - It appears only in one form and has no reuse value. - It is only a subset of an existing component.

Component metadata should include: - schema, schema_version, document_type, artifact_version, status, fields, conformance_rules.

Entity Design Guidance

Create an entity when: - It groups components and primitive-typed fields into a reusable domain object. - It appears in multiple forms or is a stable domain pattern. - It provides a validator-ready contract useful before report assembly.

Do not create an entity when: - It appears in only one form and is unlikely to be reused. - It is better represented as a component.

Entity metadata should include: - schema, schema_version, entity_type, artifact_version, status, component_refs, fields, conformance_rules.

Entities do not control: - Workflow behavior, - Flags, - Outcome/disposition, - Final requiredness activation.

Form DD Design Guidance

Form purpose: - Declare workflow contract behavior, requiredness, sections, and flag-based conditional activation.

Form composition: - One or more entities, - One or more components, - Form-specific fields.

Forms do not: - Redefine component/entity semantics, - Rename canonical fields, - Replace report/review governance behavior.

Form metadata should include: - schema, schema_version, document_type, artifact_version, status, - entity_refs, component_refs, fields, required_fields, available_flags, conformance_rules.

Report/Review DD Design Guidance

Report DD purpose: - Assemble forms into a report contract, - Declare report metadata and signature requirements, - Define instance-level flag activation boundaries.

Review DD purpose: - Assemble review structure, - Define review identity/anchoring, - Govern outcome/disposition and fieldset coverage mode, - Require review signatures.

Report/Review DDs do not: - Redefine form/entity/component semantics, - Create ad hoc semantic entities, - Allow unknown unmanaged fields.

Report DD assignment-context direction: - intended_use and intended_user are governed optional report fields.

Instance provenance direction: - generator and generator_version are governed optional instance header fields for producer provenance.

Delivery Profiles and Supplemental Guidance

Delivery Profiles may define packaging, transport, embedding, and partner contract constraints.

Delivery Profiles are subordinate to AXIS normative behavior and may add constraints only. They may not weaken or override AXIS normative semantics.

Supplemental guidance must include explicit precedence language stating that docs/model/AXIS_NORMATIVE.md controls on conflict.

EPM may be recommended as a delivery envelope for carrying AXIS payloads inside host PDF documents without sidecar files. EPM usage is optional and does not change AXIS conformance semantics.

Change Acceptance Gate

Compatibility-affecting and breaking changes must not be accepted without a conformance suite delta (updated tests and expected outcomes).

Version Management

Schema version: - Semantic versioning (Major.Minor.Patch) for core semantic evolution.

Artifact version: - Semantic versioning for components, entities, and DD artifacts.

Instance version: - Integer progression (v1, v2, v3) for report/review instance evolution. - Once a report version is referenced by a review, that report version is immutable.

Governance Against Sprawl

Core discipline: - Reuse before creating new artifacts. - Use form-level requiredness before introducing structural variants. - Require explicit rationale for any new semantic artifact.

Documentation requirement: - Every new component/entity/form should explain why composition of existing artifacts was insufficient.

Best Practices Summary

  1. Define at the right layer.
  2. Prefer optional fields with upward requiredness activation.
  3. Name once and reuse canonical names.
  4. Keep schema validation separate from business logic.
  5. Treat omission as valid for non-required fields.
  6. Resist unnecessary specialization.
  7. Preserve the composition chain: Primitives -> Components -> Entities -> Forms -> Reports/Reviews -> Instances.

Open Questions for Refinement

  1. Entity-to-entity composition in v0.2 or later?
  2. Criteria for promoting a form-local structure to reusable entity?
  3. Form-to-form composition policy for future versions?
  4. Entity version change impact policy on dependent forms?

References