What is in the specification
The document that ships in the package is the authoritative definition. This page summarises it; the specification settles it.
| Section | Covers |
|---|---|
| 1. Abstract | What AODM is, in a paragraph |
| 2. Design philosophy | The small core, and expressiveness through attributes rather than new elements |
| 3. Namespace and versioning | What a version number promises, and what forces a new one |
| 4. Relationship to v1.1 | The earlier HTML embedding approach, and what replaces it |
| 5. Core ontology | The eight elements, each in XML and JSON form |
| 6. Data quality features | Hashing, polarity, derivation, self-generated knowledge, temporal validity |
| 7. Validation | Pointer to the rules a processor must enforce beyond schema checking |
| 8. Conformance | Core-conformant and Strict-conformant, and what each requires |
| 9. Provenance and trust | Where a statement came from, and how far to trust it |
| 10. Inference | What a conditional statement means, precisely enough that two engines agree |
| 11. Extending AODM | How domain vocabularies add to it without changing the core |
| 12. Changelog | What changed, and what it supersedes |
Getting started
Declare the namespace on the document element, then add markup:
<aodm:knowledge version="1.2" xmlns:aodm="http://fucaspark.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 eight core elements
Four knowledge primitives — entity, relationship,
fact, rule — and four annotations that attach to
them: source, confidence, value,
evidence. A rule additionally has two structural children,
condition and conclusion, which are parts of a rule rather
than elements you use on their own.
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>
Ids are unique across the whole document, not just within a kind — an entity
and a fact cannot share one. type should be a lowercase,
hyphen-separated token so vocabularies stay comparable.
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>
A dangling reference passes XML Schema validation silently, because the common
validators do not enforce IDREF resolution for XSD. Processors must
check it themselves, which is why it is a documented rule rather than left to the
schema.
fact — an assertion
Optionally scoped to an entity or relationship with about. At most one
value and one confidence per fact.
<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>
asserted="false" declares a fact without claiming it, so a rule can
point at it before anything derives it. Until then it satisfies no premise and is
not knowledge the document asserts.
rule — a conditional statement that connects assertions
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>
A rule may not list its own conclusion among its conditions, and every
ref must resolve to a fact or entity in the same document. AODM defines
the shape of a rule; executing it is optional and specified separately.
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"/>
retrieved cannot be in the future, and asserted cannot
follow it — you cannot have fetched a document before it was written. A fact
with neither a source nor a confidence is valid, but should be treated as
unverified.
confidence — certainty
A number from 0.0 to 1.0, optionally tagged with the method that
produced it.
<aodm:confidence value="0.82" method="model-estimate"/>Out-of-range values are rejected rather than clamped: a confidence of 1.5 is a bug in whatever wrote it, and silently rewriting it to 1.0 hides that. Below 0.5, a processor should surface the uncertainty rather than present the fact as settled.
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.
evidence — the passage a claim came from
source says where something came from; evidence quotes the
part it came from. Repeatable — a claim may rest on several passages.
<aodm:fact id="fatigue-risk" about="engine" origin="generated">
Cyclic loading above 200 hours may accelerate bearing fatigue.
<aodm:confidence value="0.45" method="llm-extraction"/>
<aodm:evidence uri="https://example.com/report-24" locator="p.12, lines 4-9"
retrieved="2026-01-15">
Beyond 200 hours of sustained load, bearing temperatures rose faster than
the linear model predicts.
</aodm:evidence>
</aodm:fact>
locator — a page, line range, cell or timestamp — is what
makes a proposal reviewable in seconds instead of requiring someone to re-read the
source. A machine-proposed claim must carry a confidence and should carry evidence;
with neither there is nothing to review.
Element reference
| Element | Purpose | Key attributes |
|---|---|---|
| Knowledge primitives | ||
entity |
A thing: object, concept, component, actor, place | id, type, label, hash |
relationship |
A directed, typed link between two entities | subject, predicate, object, polarity, origin, valid-from, valid-to, derived-from |
fact |
An assertion, optionally scoped to an entity or relationship | about, asserted, origin, polarity, valid-from, valid-to, hash, derived-from |
rule |
A conditional statement that connects assertions, by reference | id, origin, valid-from, valid-to |
Children of rule | ||
condition |
One premise of a rule | ref, polarity |
conclusion |
What a rule concludes when its conditions hold | ref |
| Annotations | ||
source |
Provenance — where a statement came from | uri, title, retrieved, asserted |
evidence |
The passage supporting a claim, quoted rather than cited | uri, locator, retrieved; excerpt as text |
confidence |
How sure we are, 0.0–1.0 | value, method |
value |
A structured measurement on a fact | number, min, max, tolerance, unit |
Attribute reference
| Attribute | Values | What it decides |
|---|---|---|
origin |
observed (default), derived, generated |
Whether a person recorded it, a rule guarantees it, or a system merely proposed it. A proposal can be wrong in ways a derivation cannot. |
asserted |
true (default), false |
Whether the fact is claimed at all. false marks a rule conclusion awaiting derivation — declared so a rule can point at it, but satisfying nothing until derived. |
polarity |
positive (default), negative |
Known-true versus known-false. Distinct from absence, which means unknown. |
valid-from / valid-to |
ISO 8601 date or date-time | When the statement holds. A missing bound is open-ended, never invalid. |
derived-from |
Space-separated ids | The rule and premises that produced an inference. Makes it explainable and retractable. |
hash |
<algorithm>:<hex> |
Content digest, so the same fact from two pipelines is recognised as one. |
Data quality attributes
These are optional attributes on the elements above. A consumer that ignores them still parses documents correctly.
| Attribute | On | Meaning |
|---|---|---|
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. |
asserted |
fact | true (default) or false. false marks a fact that is declared but not claimed — a rule conclusion present so the rule has something to point at. It satisfies nothing until derived. |
origin |
fact, relationship, rule | observed (default), derived, or generated. A derivation is guaranteed by a rule; a generated claim is a proposal and may be wrong in ways a derivation cannot be. |
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. |
Self-generated knowledge
A system that can only store knowledge is a database. Carrying provenance and confidence means a system can also propose — read a document, notice a pattern, and offer a claim for review.
<aodm:fact id="fatigue-risk" about="engine" origin="generated">
Cyclic loading above 200 hours may accelerate bearing fatigue.
<aodm:confidence value="0.45" method="llm-extraction"/>
<aodm:evidence uri="https://example.com/report-24"
locator="p.12, lines 4-9" retrieved="2026-01-15">
Beyond 200 hours of sustained load, bearing temperatures rose faster
than the linear model predicts.
</aodm:evidence>
</aodm:fact>
source says where something came from; evidence shows
the passage it came from, with a locator so a reviewer can confirm
or reject it in seconds. A generated claim must carry a confidence, and should
carry evidence — without both it is unreviewable.
Inference
A rule is a conditional statement connecting assertions. The specification’s inference section (10) defines exactly what that means, so two conformant engines reach the same conclusions: conditions are conjunctive, confidence is the product of the rule and its premises, evaluation is relative to an instant, and derived facts record what produced them.
Absence never satisfies a condition. A negative condition
needs a fact explicitly marked polarity="negative" — not a
missing fact. AODM distinguishes “known false” from
“unknown”, so an engine must not treat failure to find something
as proof of its negation.
Executing rules is optional. A processor that does evaluate them must follow the specification’s inference section (10) and may then claim Inference-conformance, which is separate from Core- and Strict-conformance.
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 eight 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.