AXIS Form And Report Definition Plan

Status And Purpose

This document is the evolving formal plan for AXIS document definitions.

It replaces concept-only framing for the document-definition layer with a planning document intended to guide formal workflow-definition development.

AXIS form and report definitions are the governed workflow contracts that sit on top of the AXIS shared semantic foundation.

They define how semantically valid data becomes a concrete appraisal report or appraisal review artifact without changing the meaning of the underlying data.

Normative Source

Normative behavior requirements are defined in docs/model/AXIS_NORMATIVE.md.

This document is planning and summary guidance only. If wording conflicts with the normative source, docs/model/AXIS_NORMATIVE.md controls.

Core Position

Form and report definitions are a necessary layer.

They allow the profession to support standard and custom workflow contracts while keeping the schema narrow, durable, and semantically stable.

This is a required capability, not an optional convenience.

Layer Mapping

AXIS currently maps document-definition planning to a six-layer architecture:

• Level 1: schema primitives plus governed enumerations
• Level 2: reusable components
• Level 3: entities as validator contracts
• Level 4: Form DD contracts
• Level 5: Report and Review DD contracts
• Level 6: report/review workflow instances

This document focuses on layers 4 and 5 and how those contracts govern layer 6 instances.

Why This Layer Exists

When schema, component, form, and report concerns are blended, the result tends to accumulate workflow-specific requiredness, presentation-driven structure, and output-specific constraints in the wrong layer.

That is one of the main paths to schema bloat and drift.

The form and report-definition layers exist to preserve a clean semantic model while still allowing reporting and review workflows to diverge where they actually need to diverge.

They also allow AXIS core to remain at the top of the hierarchy while concrete forms and final assembled outputs build on the governed foundation.

Canonical Standard Document Definitions

The first standard document definitions are planned as:

• axis.document.appraisal-report
• axis.document.appraisal-review

Recommended human-readable titles:

• AXIS Appraisal Report Document Definition
• AXIS Appraisal Review Document Definition

These standard document definitions should be versioned public artifacts.

Slash forms such as AXIS/AR and AXIS/ARV may remain useful as conversational shorthand, but they should not be treated as the primary formal names for these document-definition artifacts.

Role Of Form And Report Definitions

Document definitions should define how schema-governed data is organized into a specific workflow contract.

At a minimum, these layers may own:

• report and review contract requirements,
• required sections,
• section ordering,
• grouping of governed content,
• visible versus machine-readable expectations,
• narrative slots,
• photo and exhibit requirements,
• form-specific requiredness,
• report/review instance contract rules,
• traceability requirements for represented content,
• review-targeting rules,
• and representation contract requirements.

What Document Definitions Must Not Do

Document definitions must not:

• redefine schema meaning,
• change the semantics of shared fields,
• override core data types or relationships,
• or become a substitute for semantic version governance.

Document definitions are allowed to shape document behavior. They are not allowed to rewrite the semantic model.

Relationship To The Shared Schema Boundary

Reporting and review are similar because they rely on overlapping appraisal semantics.

They are different because they produce different workflow artifacts and support different steps in the lifecycle.

That means the default planning model is:

• one shared semantic schema,
• one reusable component layer,
• one or more appraisal form definitions at layer 4 built on AXIS core,
• one or more review form definitions at layer 4 built on AXIS core plus the review extension layer where applicable,
• and layer 5 report/review assemblies that combine selected form versions into a final artifact.

Review should not be treated as a detached peer to appraisal reporting, but it should also not be collapsed into the appraisal-report object itself.

The current planning direction is that every review should declare the exact appraisal-report version it targets, along with the relevant schema and form-definition versions.

Standard And Custom Document Definitions

AXIS should support both standard and custom document definitions.

Standard Document Definitions

Standard document definitions are centrally versioned and governed artifacts intended for broad industry use.

Examples may include:

• standard appraisal report contracts,
• standard appraisal review contracts,
• and later standardized forms or common workflow contracts.

Custom Document Definitions

Custom document definitions are also necessary.

They allow organizations to define lender-specific, AMC-specific, form-specific, or workflow-specific document contracts while still using the shared semantic foundation.

Custom document definitions are a positive and necessary feature as long as they stay inside clear guardrails.

Guardrails For Custom Document Definitions

Custom document definitions may:

• add document-specific structure,
• add workflow-specific sectioning,
• define visible-field expectations,
• define section ordering,
• define narrative placement,
• and add organization-specific document-contract behavior.

Custom document definitions must not:

• redefine schema meaning,
• rename schema semantics as if they were new meanings,
• break compatibility with declared schema versions,
• or present proprietary document behavior as though it were a shared semantic standard.

Custom document definitions should declare:

• targeted schema version,
• targeted standard document-definition base where applicable,
• compatibility posture,
• and their own explicit version.

Compatibility should mean that a custom document definition preserves the semantic meaning of its targeted schema and declared base document definition even when it adds organization-specific contract behavior.

In practice, a compatible custom document definition may add sectioning, visibility requirements, and named narrative or comment uses, but it must not change what the underlying AXIS data means.

Conformance Direction

Document-definition conformance should focus on whether a document contract is satisfied in a clear, versioned, and portable way.

That means the document-definition layer should remain understandable without requiring any particular runtime or implementation model.

Normative Behavior

All normative behavior rules for report and review identity, anchoring, requiredness, omission semantics, fieldset coverage modes, outcome/disposition, signature conformance, and naming boundaries are maintained in docs/model/AXIS_NORMATIVE.md.

This document intentionally summarizes planning direction and does not restate normative rule text.

Versioning

All DD artifacts should be versioned.

At a minimum, a DD artifact should declare:

• its own version,
• the schema version it targets,
• whether it is standard or custom,
• whether it composes other governed definitions,
• and, for review definitions, the exact appraisal-report version it evaluates.

Report and review instances should preserve clear identity and the referenced DD versions used to construct the artifact.

This is necessary for interoperability and controlled evolution.

Document-Definition Artifact Direction

The project will likely need a compiled or execution-ready document-definition artifact.

At a planning level, that artifact would likely need:

• document-definition identity,
• document type,
• selected version,
• required sections,
• required visible fields,
• narrative slots,
• document-level requiredness,
• and representation contract requirements relevant to downstream implementations.

Relationship To Standard Forms And Review

DD artifacts are the natural place to support evolving standard appraisal and appraisal-review contracts.

The current initial scope emphasis is on non-Fannie and more general reporting patterns, including forms commonly used in non-residential and broader secondary-market workflows where a neutral appraisal model may be especially valuable.

That emphasis does not prevent AXIS from defining its own governed document definitions for familiar 1004-style or other widely recognized reporting structures when useful. The important point is that AXIS DD contracts should be expressed in the document-definition layer without forcing the shared schema to become an outside standard or delivery format.

If a vendor wishes to translate between AXIS and another ecosystem, that compatibility should be handled through a separate mapping layer rather than by redefining AXIS semantics.

Review findings should be able to target a section, component, or specific field where needed, but the model should not require a review item for every field by default. Named review comments should be treated as governed uses of the reusable narrative and review-finding model rather than as separate core semantic entities for every section.

Relationship To The Schema

The AXIS shared semantic schema remains the authority on meaning.

Document definitions consume that meaning and organize it into a governed document contract.

This relationship is what allows the system to support multiple document paths without semantic drift.

Relationship To Downstream Implementations

Document definitions are not transport or packaging specifications.

They may include implementation-neutral expectations about what must be visible, traceable, or represented, but they should not be written as an instruction language for any one downstream system.

Delivery Profile artifacts may be used to capture implementation-facing packaging and transport constraints for specific exchange contexts.

When used, Delivery Profiles are subordinate to docs/model/AXIS_NORMATIVE.md and may only add constraints, not weaken or redefine AXIS normative behavior.

As one implementation-facing option, EPM envelopes may carry AXIS payloads inside host PDF documents without sidecar files. This is a delivery mechanism, not a replacement for AXIS conformance semantics.

Public Posture

The current planning direction is that standard document definitions can become public artifacts alongside the public schema.

That public posture supports:

• adoption,
• shared governance,
• transparent evolution,
• and room for the profession to grow as needs change.

Custom document definitions do not need to be public by default, but the public standard document-definition model should remain clear enough that custom work can declare compatibility against it.

Immediate Planning Questions

• What is the minimum required structure of a standard DD artifact?
• What compatibility model should govern custom DD artifacts?
• Which existing report and review expectations belong in the first standard AXIS DD artifacts?
• What publication and governance model should apply once standard AXIS workflow definitions move out of planning?
• What minimum review-target and report-version declaration should every review definition carry?