AXIS Layered Definition Plan

Status And Purpose

This document is the evolving formal plan for the AXIS layered definition system.

It replaces concept-only framing with a planning document intended to guide formal schema, component, and document-definition development.

AXIS is meant to provide a clear, durable path for the appraisal profession by defining a stable semantic foundation that can support appraisal reporting, appraisal review, and future implementations without letting any one product determine the meaning of the data.

The canonical machine-readable identifier for the shared semantic foundation remains axis.schema.core.

Normative Source

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

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

Role Of The Layered Model

AXIS defines what each data piece means, how common data associations are grouped, and how document definitions declare governed report and review contracts.

AXIS is not just the report layout.

AXIS is not just the review form.

AXIS is not a packaging format.

AXIS is the governed layered model.

Active Definition Levels

The current planning direction uses six architecture layers:

  • Level 1: schema primitives plus governed enumerations for foundational data,
  • Level 2: reusable component definitions for common field associations,
  • Level 3: reusable entity definitions as validator contracts,
  • Level 4: workflow-facing Form DD contracts,
  • Level 5: Report and Review DD contracts,
  • Level 6: report and review workflow instances governed by selected DD versions.

The first three levels remain workflow-neutral. Levels 4 through 6 carry workflow-specific contract and instance behavior.

Architecture And DD Mapping

To keep terminology and layering aligned, use this mapping:

  • Primitive schema definition: a foundational data definition that establishes meaning, type, and minimal constraints.
  • Component definition: a reusable grouped structure built from primitive definitions and common field associations.
  • Form DD: reusable form-level DD used as a sub-assembly where applicable.
  • Report DD: report-level DD that composes form DDs plus report metadata.
  • Review DD: review-level DD that carries review-specific structure plus report identity anchoring.

DD taxonomy and architecture layers are compatible. Form DD operates at layer 4, Report and Review DDs operate at layer 5, and those DD contracts govern layer 6 instances.

Reconciliation: Architecture Layers and DD Taxonomy

The six-layer architecture and the DD taxonomy (Form DD, Report DD, Review DD) serve different purposes but work together:

Layer Artifacts DD Type Purpose
L1 Primitives, Enumerations — Foundational types and governed value sets
L2 Components — Reusable grouped structures (Address, Money, Signature)
L3 Entities — Validator contracts and semantic boundaries
L4 Form schemas Form DD Reusable form-level DDs (sub-assemblies)
L5 Report and Review schemas Report DD, Review DD Document-level DDs that compose forms and entities
L6 Instances — Actual report/review data governed by L5 DD versions

Key point: L1-L3 are workflow-neutral foundations. L4-L6 are workflow-aware and include DD contracts and their governed instances. All DD taxonomy items operate within this six-layer model.

Design Goals

The AXIS layered model should:

  • define stable, vendor-agnostic appraisal semantics,
  • support reusable components such as grouped address and identity structures,
  • support both appraisal reporting and appraisal review workflows without mixing them,
  • keep AXIS core at the top of the semantic hierarchy,
  • remain independent from any single implementation,
  • support versioned DD contracts without being reshaped by UI concerns,
  • support interoperability, vendor adoption, and downstream reuse,
  • and evolve in a way that strengthens long-term industry trust.

AXIS can also provide a consistent semantic foundation for external validation engines and other downstream structured-data consumers.

Bridge Schema Position

The bridge schema is not a dependency that sits outside AXIS.

It is the core reason AXIS exists.

AXIS is intended to bridge appraisal-specific semantics to adjacent structured-data ecosystems without allowing any external standard to define AXIS meaning.

The current planning direction is that AXIS will define its own governed semantics. External standards may be reviewed for comparison or for future mapping where useful, but they do not define the AXIS source model.

At present:

  • RESO may be reviewed as a comparison reference and possible mapping target,
  • AXIS semantics should still be defined independently,
  • and MISMO is not part of the direct AXIS source-model posture.

If future interoperability is needed, it should be handled through explicit mapping artifacts rather than by importing outside schema meaning into AXIS core.

Until that mapping posture is formalized, AXIS should be treated as a governed planning direction for a bridge schema rather than as a fully settled formal specification.

What The First Three Levels Own

At a minimum, the workflow-neutral AXIS foundation should own:

  • entity definitions,
  • primitive field definitions,
  • canonical identifiers,
  • data types,
  • cardinality,
  • relationships and references,
  • controlled vocabularies and scales,
  • semantic invariants,
  • required semantic constraints,
  • missing-data semantics,
  • extension boundaries,
  • and reusable component definitions built from those primitives.

Examples of foundation-level rules include:

  • an Adjustment must reference a valid Comparable,
  • governed ratings must use governed scales,
  • a field must satisfy its declared type and cardinality,
  • an Address component must maintain clear meaning for its composed fields,
  • and semantic absence must not be represented casually by blank strings where the meaning would be ambiguous.

What The Schema Does Not Own

The schema should not own:

  • section ordering,
  • visible layout decisions,
  • workflow-specific document composition,
  • report-specific or review-specific narrative placement,
  • form-specific grouping rules,
  • or output-format implementation details.

Those concerns belong in document definitions or downstream implementations.

Core Semantic Boundary

The shared AXIS foundation exists because reporting and review rely on overlapping appraisal meaning even when they produce different workflow artifacts.

That means the default model is:

  • one shared semantic foundation,
  • one reusable component layer built from that foundation,
  • DD contracts for appraisal reporting and appraisal review,
  • instance rules that preserve report/review identity and version anchoring,
  • and review-specific semantics only where review adds meaning beyond the shared core.

This boundary is intended to prevent schema bloat and reduce drift across implementations.

Hierarchy, Composition, And Version Model

AXIS core should remain at the top of the semantic hierarchy.

Report and review artifacts should be produced from governed DD contracts rather than allowed to redefine the core meaning.

That means:

  • shared appraisal semantics belong in AXIS core,
  • common grouped structures belong in reusable components,
  • DD contracts declare workflow-facing requirements,
  • report and review instances declare DD identity and version metadata,
  • and review remains a separate but dependent workflow that targets a specific appraisal-report version.

Multiple reviews may exist for the same appraisal-report version where workflow requires it, but if the underlying appraisal report changes materially, the next review should target the new report version.

Reusable Narrative Model

The schema should use one reusable Narrative object rather than many narrowly named narrative entity types.

That reusable model keeps the core smaller and allows narrative content to attach compositionally to the entities and contexts that need it.

In practice, this means:

  • a Comparable may carry one or more related narratives,
  • Subject or MarketConditions may carry related narratives,
  • and document definitions may name or organize those narrative uses without creating new core semantic entities for every narrative context.

This same model also creates a clean base for review-specific comments.

Initial Core Entities

The current planning set of core entities includes:

  • Subject
  • Comparable
  • Adjustment
  • MarketConditions
  • Narrative
  • Photo
  • Addendum

This list remains an evolving plan and should be refined as the formal schema takes shape.

Initial Reusable Components

The current planning direction also expects reusable Level 2 components such as:

  • Address
  • PartyIdentity
  • SaleReference
  • QualityAndConditionSummary
  • ReviewFindingTarget

These components should remain reusable across multiple forms and workflows rather than being locked to only one report type.

Initial Entity Field Outlines

The following field outlines are preserved from the earlier concept work and remain part of the evolving plan.

Subject

Key fields, conceptually:

  • subject.id
  • subject.address.full
  • subject.address.components
  • subject.geo.location
  • subject.property_type
  • subject.gla
  • subject.site_area
  • subject.condition_rating
  • subject.quality_rating
  • subject.year_built
  • subject.year_renovated
  • subject.bedrooms
  • subject.bathrooms
  • subject.parking
  • subject.utilities
  • subject.zoning
  • subject.highest_and_best_use

Comparable

Key fields, conceptually:

  • comp.id
  • comp.role
  • comp.address.full
  • comp.address.components
  • comp.geo.location
  • comp.sale_price
  • comp.sale_date
  • comp.gla
  • comp.site_area
  • comp.condition_rating
  • comp.quality_rating
  • comp.bedrooms
  • comp.bathrooms
  • comp.parking
  • comp.distance_to_subject
  • comp.source

Adjustment

Key fields, conceptually:

  • adjustment.id
  • adjustment.comp_id
  • adjustment.category
  • adjustment.basis
  • adjustment.amount
  • adjustment.direction
  • adjustment.explanation

MarketConditions

Key fields, conceptually:

  • market.period
  • market.trend_price
  • market.trend_inventory
  • market.trend_marketing_time
  • market.supporting_data
  • market.commentary

Narrative

Key fields, conceptually:

  • narrative.id
  • narrative.role
  • narrative.subject
  • narrative.text
  • narrative.related_entity
  • narrative.source

Photo

Key fields, conceptually:

  • photo.id
  • photo.role
  • photo.caption
  • photo.file_reference
  • photo.related_entity

Addendum

Key fields, conceptually:

  • addendum.id
  • addendum.type
  • addendum.text

Review Extension Direction

Where review introduces additional semantic meaning beyond AXIS core, that meaning is modeled as a review extension layer built on top of the shared foundation.

Detailed normative behavior for review structure, fieldset coverage mode, requiredness, and outcome/disposition is defined in docs/model/AXIS_NORMATIVE.md.

The first expected review-specific object is ReviewComment.

ReviewComment should be derived from the reusable Narrative model rather than introduced as an unrelated text object.

That allows AXIS to keep one narrative base model while still supporting review-specific meaning such as:

  • review target,
  • severity,
  • review classification or code,
  • and suggested corrective action.

Key fields for ReviewComment, conceptually:

  • review_comment.id
  • review_comment.target
  • review_comment.code
  • review_comment.severity
  • review_comment.text
  • review_comment.suggested_action
  • review_comment.related_entity

Layering And Rule Inheritance

The schema family uses a layered governance model.

The most important rule is that changes should respect the boundary between primitive definitions, reusable components, and DD contracts. Higher workflow layers must not rewrite the semantic meaning established in the shared foundation.

This rule matters because it:

  • keeps the core stable,
  • prevents schema sprawl,
  • preserves interoperability,
  • supports predictable composition,
  • and makes governance more defensible.

Schema Rules

Schema rule intent and examples are summarized here for planning context.

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

Missing And Optional Data

Missing-data semantics and conformance are summarized here for planning context.

Normative omission, requiredness, and validation behavior are defined in docs/model/AXIS_NORMATIVE.md.

Representation Examples

The schema is not identical to any single serialization format.

JSON, XML, and YAML are all reasonable ways to express the same governed AXIS semantics.

The important constraint is that the representation must preserve the same entity meaning, identifiers, relationships, and rules.

JSON Example

{
    "schema": "axis.schema.core",
    "schema_version": "0.1.0",
    "subject": {
        "id": "subject-1",
        "property_type": "single_family"
    },
    "narratives": [
        {
            "id": "narrative-1",
            "role": "market_conditions",
            "related_entity": "subject-1",
            "text": "Inventory remains constrained in the subject market area."
        }
    ]
}

XML Example

<axis-document schema="axis.schema.core" schema_version="0.1.0">
    <subject id="subject-1">
        <property_type>single_family</property_type>
    </subject>
    <narrative id="narrative-1" role="market_conditions" related_entity="subject-1">
        <text>Inventory remains constrained in the subject market area.</text>
    </narrative>
</axis-document>

YAML Example

schema: axis.schema.core
schema_version: 0.1.0
subject:
    id: subject-1
    property_type: single_family
narratives:
    - id: narrative-1
        role: market_conditions
        related_entity: subject-1
        text: Inventory remains constrained in the subject market area.

Downstream Structured Consumers

Downstream consumers will expect stable structured JSON derived from the schema.

Examples include:

  • review-oriented structured consumers that need Subject, Comparables, Adjustments, MarketConditions, and Narratives,
  • comp-selection or analysis consumers that need Subject, candidate Comparables, and market context,
  • narrative-support systems that need Subject, Comparables, Adjustments, and MarketConditions.

Schema stability matters because downstream consumers should not break every time a vendor changes its internal model.

Versioning And Stability

The schema should be versioned explicitly.

Versioning should allow the profession and implementers to know:

  • which semantic contract is in force,
  • which document definitions are compatible,
  • and whether a given extension or implementation targets the correct schema version.

Versioning uses semver for schema and DD artifacts, with instance version progression handled independently as defined in docs/model/AXIS_NORMATIVE.md.

Public Posture

The current planning direction is that the AXIS shared semantic schema can become public and eventually open source.

The reason is not simply transparency. The reason is that the schema should be able to evolve in a profession-first way, without hidden product incentives becoming the de facto source of meaning.

That public posture should help:

  • adoption,
  • contribution,
  • trust,
  • and long-term industry durability.

Relationship To Document Definitions

The schema is the semantic foundation for document definitions.

Document definitions consume the schema. They do not replace it.

The schema must therefore remain clean enough that multiple standard and custom document definitions can be built on top of it without fragmenting semantic meaning.

Relationship To Other Implementations

The schema is intended to remain independent from specific implementations, products, transport formats, and runtime systems.

Other systems may consume AXIS, but AXIS should not depend on them for its meaning.

Immediate Planning Questions

  • Which core entities and fields belong in the first formal schema draft?
  • Which review-only semantics belong in the review extension layer versus AXIS core?
  • Which semantic constraints belong in the base schema versus a future extension model if one is needed?
  • What additional compatibility constraints should govern evolution across Form DD, Report DD, and Review DD?
  • What public governance model should eventually control schema evolution?
  • What limited comparison and mapping posture should AXIS use for external standards while keeping the core fully self-defined?