Status: Stable Schemas:
MDA defines explicit, typed relationships between documents using two complementary mechanisms:
- Inline relationship footnotes — standard Markdown footnotes whose payload is a JSON object. Authored in the body, mirrored to frontmatter. Edges are typed (
parent,child,cites, …) and human-readable in context. depends-ondeclarations — frontmatter-only edges with SemVer ranges and optional content-digest pinning. Used when one artifact functionally requires another at runtime.
Both mechanisms make MDA documents directly graph-ready: relationship edges are machine-readable without custom parsing of prose.
The relationship lives in the body of the source as a standard Markdown footnote definition:
This document outlines changes[^ref1] and implications[^ref2].
[^ref1]: {"rel-type": "parent", "doc-id": "UUID-of-parent-doc", "rel-desc": "Derived from SEC docs"}
[^ref2]: {"rel-type": "related", "doc-id": "UUID-of-related-doc", "rel-desc": "Provides context"}Rules:
- The footnote ID (e.g.
ref1) MUST be unique within the document. - The footnote definition's content MUST be a single JSON object that conforms to
schemas/relationship-footnote.schema.json. - The footnote MAY appear anywhere a Markdown footnote is legal (typically at the end of the document).
| Field | Type | Required | Notes |
|---|---|---|---|
rel-type |
enum | yes | One of parent, child, related, cites, supports, contradicts, extends. |
doc-id |
string | yes | Target document's doc-id (UUID recommended). |
rel-desc |
string | no | Human-readable description. |
rel-strength |
number [0,1] | no | Confidence/relevance. |
bi-directional |
boolean | no | Whether the link implies an inverse from the target. |
context |
object | no | Free-form scoping details (section, relevance, etc.). |
| Type | Direction | Typical use |
|---|---|---|
parent |
this ← target | This document is derived from or scoped under the target. |
child |
this → target | This document defines or owns the target. |
related |
symmetric | Two documents discuss overlapping topics. |
cites |
this → target | This document references the target as evidence/source. |
supports |
this → target | This document provides evidence for the target's claim. |
contradicts |
this → target | This document disputes the target's claim. |
extends |
this → target | This document adds capability or scope to the target. |
For non-trivial graphs, prefer cites over related (more precise) and prefer parent/child over both (most precise).
A .mda source MAY declare functional runtime dependencies on other MDA artifacts. In source frontmatter the field MAY appear at the top level as depends-on: (the source schema accepts both top-level placement and nesting under metadata.mda.depends-on for source-side authoring convenience); in any compiled .md output it MUST be relocated under metadata.mda.depends-on per §01-4. Unlike footnote relationships (which describe documentary lineage), depends-on describes resolution: a consumer that activates this artifact MUST be able to resolve every entry to a concrete artifact that satisfies the version constraint.
metadata:
mda:
depends-on:
- name: pdf-tools
version-range: "^1.2.0"
digest: "sha256:a4f9c0d2e8b3a1..." # optional pinning
- name: web-fetch
version-range: "1.0.3" # exact pin| Field | Type | Required | Notes |
|---|---|---|---|
name |
string | yes | Kebab-case identifier of the depended-upon artifact (matches that artifact's top-level name). |
version-range |
string | yes | A valid range per §03-3.2. |
digest |
string | no | Content digest pin in <algorithm>:<hex> form. When present, the resolved artifact's integrity.digest (§08) MUST match. |
Schema: _defs/depends-on.schema.json.
To keep agent and human authoring unambiguous, MDA v1.0 admits a strict subset of SemVer range syntax:
| Form | Meaning | Example |
|---|---|---|
| Exact | The single SemVer 2.0.0 version. | 1.2.0 |
| Caret | Any version >=X.Y.Z and <(X+1).0.0 (compatible-with-next-major). For 0.x, caret behaves as ~ per SemVer convention: ^0.2.3 ⇒ >=0.2.3 <0.3.0. |
^1.2.0 |
Out of scope for v1.0:
- Tilde ranges (
~1.2.0) - Compound ranges (
>=1.2.0 <2.0.0,||, hyphen ranges) - Wildcards (
1.x,*) - Pre-release matching across boundaries
A range that fails to parse as one of the two forms MUST be rejected by the source schema. Schema: _defs/version-range.schema.json.
A consumer (or build/install tool) that resolves depends-on:
- MUST locate an artifact whose
namematches and whosemetadata.mda.versionsatisfies the range per §03-3.2. - MUST, when
digestis present, verify that the resolved artifact'sintegrity.digestequals the declareddigestand refuse to load on mismatch. - SHOULD prefer the highest satisfying version when multiple candidates exist.
- MAY fail closed (refuse to activate) when no satisfying artifact is found; this is the recommended default.
A circular depends-on graph is not defined behavior; tools SHOULD detect and reject cycles.
Footnote relationships describe the document graph (lineage, citation, contradiction). depends-on describes the runtime graph (what must be resolvable for this artifact to function). Mixing the two would force every consumer to walk the document graph at activation time even when only the runtime graph matters.
When the .mda source contains one or more relationship footnotes, the compiler MUST emit the same payloads as an array under metadata.mda.relationships in the output frontmatter. This is normative: SKILL-only consumers, knowledge-graph indexers, and other readers that do not parse Markdown footnotes rely on the mirror.
The compiler MAY also preserve the footnote definitions verbatim in the output body. Standard Markdown footnotes degrade gracefully in every consumer.
metadata:
mda:
relationships:
- rel-type: parent
doc-id: UUID-of-parent-doc
rel-desc: Derived from SEC docs
- rel-type: related
doc-id: UUID-of-related-doc
rel-desc: Provides contextThe order of entries in the mirror MUST follow the order in which the corresponding footnote references first appear in the body.
A compiled output that contains relationship footnotes in its body MUST also contain the mirror. A compiled output that contains the mirror MAY omit the footnotes from the body. Both forms are conformant; the mirror is the authoritative machine-readable copy.
A .mda source MAY also include the mirror directly (Agent and Human modes commonly do), in which case the compiler MUST verify that the mirror agrees with the footnotes and reject on mismatch.
See examples/source-only/intro-example.mda for footnote use, the matching examples/skill-md/intro/SKILL.md for the mirrored frontmatter, and examples/skill-md/pdf-tools/SKILL.md (when added) for depends-on with both range and digest pinning.
Conformance fixtures live under conformance/valid/ (03-relationships-with-mirror) and conformance/compile/ (mirror requirement and depends-on resolution).