Documentation

AODM 1.2 — namespace http://nesaraq.com/aodm/1.2

Getting started

Declare the namespace on the document element, then add markup:

<aodm:knowledge version="1.2" xmlns:aodm="http://nesaraq.com/aodm/1.2">
  <aodm:entity id="engine" type="component" label="Engine"/>
  <aodm:entity id="fuel"   type="substance" label="Fuel"/>
  <aodm:relationship type="requires" subject="engine"
                     predicate="requires" object="fuel"/>
</aodm:knowledge>

The same document in JSON:

{
  "aodm_version": "1.2",
  "entities": [
    { "id": "engine", "type": "component", "label": "Engine" },
    { "id": "fuel",   "type": "substance", "label": "Fuel" }
  ],
  "relationships": [
    { "type": "requires", "subject": "engine",
      "predicate": "requires", "object": "fuel" }
  ]
}

XML attributes are hyphenated (valid-from); their JSON counterparts are snake_cased (valid_from). Otherwise the two serialisations map field for field.

The seven core elements

entity — a thing

An object, concept, component, actor or place. id and type are required.

<aodm:entity id="engine" type="component" label="Engine">
  Internal combustion engine, 4-cylinder.
  <aodm:source uri="https://example.com/spec-24" title="Test Report 24"/>
  <aodm:confidence value="0.95"/>
</aodm:entity>

relationship — a directed link

subject and object must both resolve to entity ids in the same document. 

<aodm:relationship type="requires" subject="engine"
                   predicate="requires" object="fuel"
                   valid-from="2024-01-01">
  <aodm:confidence value="1.0"/>
</aodm:relationship>

fact — an assertion

Optionally scoped to an entity or relationship with about.

<aodm:fact id="temp-rise" about="engine" valid-from="2026-01-15">
  Temperature rise under sustained load.
  <aodm:value number="1.2" unit="Cel" tolerance="0.1"/>
  <aodm:source uri="https://example.com/report-24" retrieved="2026-01-15"/>
  <aodm:confidence value="0.9"/>
</aodm:fact>

rule — IF conditions THEN conclusion

Rules are expressed by reference. A condition may be negated with polarity="negative". 

<aodm:rule id="risk-rule">
  <aodm:condition ref="temp-rise"/>
  <aodm:condition ref="pressure-fact" polarity="negative"/>
  <aodm:conclusion ref="failure-risk"/>
  <aodm:confidence value="0.7"/>
</aodm:rule>

source — provenance

retrieved is when you obtained it; asserted is when the source itself made the claim. 

<aodm:source uri="https://example.com/report-24" title="Test Report 24"
             asserted="2025-11-02" retrieved="2026-01-15"/>

confidence — certainty

<aodm:confidence value="0.82" method="model-estimate"/>

value — structured measurement

Either a point value (number, optionally with tolerance) or a range (min and max) — never both, never neither. 

<aodm:value number="1.2" unit="Cel" tolerance="0.1"/>
<aodm:value min="5" max="10" unit="bar"/>

unit should be a UCUM code. A magnitude with no unit is a common source of silently wrong data, so validators warn on it unless the quantity is genuinely dimensionless.

Data quality attributes

These are optional attributes on the elements above. A consumer that ignores them still parses documents correctly.

AttributeOnMeaning
valid-from / valid-to fact, relationship, rule When the assertion holds. A missing bound is open-ended, never invalid. Expired knowledge is excluded from present-tense queries but retained for audit.
polarity fact, relationship, condition positive (default) or negative. A negative assertion states something is known false, which differs from having no information.
derived-from fact, relationship Space-separated ids of the rule and facts that produced this. Makes inference auditable and retraction possible. The derivation graph must be acyclic.
hash entity, fact Content digest as <algorithm>:<hex>, e.g. sha256:9f86d081…, computed over the element's UTF-8 text content with surrounding whitespace stripped.

Validation and conformance

Schemas cannot express every constraint in the specification. Referential integrity, cardinality limits, measurement coherence and temporal ordering are defined as written rules that processors must enforce directly. The full list ships as VALIDATION-RULES.md in the download.

Note for implementers: the XSD types reference attributes as xs:IDREF, but do not rely on that for integrity. Widely used validators — libxml2, and therefore lxml, Python and much of the XML ecosystem — do not enforce IDREF resolution for XML Schema, only for DTDs. A dangling reference passes schema validation silently, so those checks must live in your processor.

Core-conformant processors validate all seven elements against the schema and enforce every MUST-level rule. Strict-conformant processors additionally enforce the SHOULD-level rules. An implementation must state which level it claims.

Validate a document Download the full specification