Relationships

ACP’s relationship model builds a knowledge graph into every ACO. Rather than flat “related IDs,” each relationship edge carries a type, optional confidence score, and optional provenance.

---

The relationships Field

relationships is an array of typed edge objects on an ACO.

relationships:
  - rel_type: "derived-from"
    target_id: "01952a3b-0000-0000-0000-000000000001"
    confidence: 0.95
    provenance:
      model: "claude-haiku-4-5"
      timestamp: "2026-02-23T10:31:00Z"
  - rel_type: "references"
    target_id: "01952a3b-0000-0000-0000-000000000002"
  - rel_type: "supersedes"
    target_id: "01952a3b-0000-0000-0000-000000000003"
    confidence: 1.0

Subfield	Type	Required	Description
rel_type	string	Yes	Relationship type. See core types below.
target_id	string	Yes	ID of the related object. UUID for ACP objects; URL for external references.
confidence	float 0.0–1.0	No	Confidence score for auto-detected relationships. Omit for human-asserted.
provenance	object	No	Which model/process created this edge. Same structure as per-field provenance records.

---

Core Relationship Types

Type	Meaning	Example
references	This ACO cites or links to the target	An article that links to a paper it draws from
derived-from	This ACO was created from or inspired by the target	A summary ACO derived from a longer source ACO
supersedes	This ACO replaces the target	An updated version that obsoletes the previous one
supports	This ACO provides evidence for the target’s claims	Research findings that support a thesis ACO
contradicts	This ACO disputes the target’s claims	A rebuttal or counter-analysis
part-of	This ACO is a component of the target	A chapter that is part of a larger document ACO
related	General association	When no specific type applies

---

Extension Types

Custom relationship types use the x- prefix:

relationships:
  - rel_type: "x-annotates"
    target_id: "01952a3b-0000-0000-0000-000000000001"
  - rel_type: "x-translates"
    target_id: "01952a3b-0000-0000-0000-000000000002"

Extension types are implementation-defined. They MUST be preserved by compliant implementations even if unrecognized.

---

Outbound-Only Storage

All stored edges are outbound — they represent “this object → target.”

Implementations MAY compute inbound views (which objects reference this ACO) at query time, but MUST NOT store inbound edges on the target object.

Why: Outbound-only storage eliminates referential integrity problems. If the source ACO is deleted, no stale inbound edges remain on any other object. If the target ACO is deleted, the edge on the source becomes a dangling reference — which is acceptable and expected behavior.

---

Human-Asserted vs. Auto-Detected

Human-asserted relationships: Omit confidence and provenance. These are definitive.

relationships:
  - rel_type: "supersedes"
    target_id: "01952a3b-0000-0000-0000-000000000001"

Auto-detected relationships: Include confidence and provenance. These reflect the generating model’s certainty.

relationships:
  - rel_type: "supports"
    target_id: "01952a3b-0000-0000-0000-000000000002"
    confidence: 0.78
    provenance:
      model: "claude-haiku-4-5"
      timestamp: "2026-02-23T10:31:00Z"

---

External References

target_id can be a URL for external references (content that is not an ACP object):

relationships:
  - rel_type: "references"
    target_id: "https://modelcontextprotocol.io/specification"

This enables ACOs to express relationships to any content on the web, not just other ACOs.

---

v0.1 Migration

v0.1 had separate top-level fields for common relationship types. All relationship information is now consolidated in the relationships array.

v0.1	v0.2 equivalent
related_objects: ["id1", "id2"]	relationships: [{rel_type: "related", target_id: "id1"}, {rel_type: "related", target_id: "id2"}]
derived_from: "id1"	relationships: [{rel_type: "derived-from", target_id: "id1"}]
supersedes: "id1"	relationships: [{rel_type: "supersedes", target_id: "id1"}]