Skip to Content
Data Structures

Data Structures

This page provides detailed technical schemas for the core data structures used in the APL Protocol.

1. Reference Object

All content-addressed references in APL (frame, bridge, transformation) use a common shape, the Reference Object.

{
  "hash": "sha256:0123abcd...",
  "resolver_hint": "optional-location-or-uri"
}
  • hash (REQUIRED): Canonical identity. Lowercase hex, prefixed with sha256:. MUST be computed as SHA-256(JCS(artifact)).
  • resolver_hint (OPTIONAL): Non-empty string. Used for discovery only. MUST NOT be used as identity.

2. APL Receipt (APL-on-ATL JSON)

In the reference profile APL-on-ATL, the APL Receipt is an ATL Receipt carrying metadata.apl inside entry.metadata. The full ATL structure (proof, super_proof, anchors) is reproduced below for completeness; normative ATL field definitions live in ATL — Data Structures .

{
  "spec_version": "2.0.0",
  "upgrade_url": "https://api.example.com/v1/receipts/550e8400.../upgrade",
  "entry": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "payload_hash": "sha256:e3b0c442...",
    "metadata_hash": "sha256:9f86d081...",
    "metadata": {
      "apl": {
        "version": "1.0",
        "claim": {
          "kind": "observation",
          "subject": {
            "id": "model:acme-gpt-7b-build-42"
          },
          "aspect_refs": ["accuracy"],
          "statement": {
            "predicate": "score",
            "content": {
              "benchmark": "MMLU",
              "value": 0.781,
              "unit": "fraction"
            }
          }
        },
        "frame_ref": {
          "hash": "sha256:1111111111111111111111111111111111111111111111111111111111111111",
          "resolver_hint": "https://registry.example/frames/ai-eval/mmlu-v1.json"
        }
      }
    }
  },
  "proof": {
    "tree_size": 1450,
    "root_hash": "sha256:7f83b165...",
    "inclusion_path": [
      "sha256:a1b2...",
      "sha256:c3d4..."
    ],
    "leaf_index": 142,
    "checkpoint": {
      "origin": "sha256:9988...",
      "tree_size": 1450,
      "root_hash": "sha256:7f83...",
      "timestamp": 1704067200000000000,
      "key_id": "sha256:4433...",
      "signature": "base64:SGVsbG8..."
    }
  },
  "super_proof": {
    "genesis_super_root": "sha256:1122...",
    "data_tree_index": 5,
    "super_tree_size": 12,
    "super_root": "sha256:aabb...",
    "inclusion": [
      "sha256:ccdd...",
      "sha256:eeff..."
    ],
    "consistency_to_origin": [
      "sha256:1234...",
      "sha256:5678..."
    ]
  },
  "anchors": [
    {
      "type": "rfc3161",
      "target": "data_tree_root",
      "target_hash": "sha256:7f83b165...",
      "tsa_url": "https://freetsa.org/tsr",
      "timestamp": "2026-01-04T12:00:00Z",
      "token_der": "base64:MIAGCS..."
    },
    {
      "type": "bitcoin_ots",
      "target": "super_root",
      "target_hash": "sha256:aabb...",
      "timestamp": "2026-01-04T14:30:00Z",
      "bitcoin_block_height": 876543,
      "bitcoin_block_time": "2026-01-04T14:28:00Z",
      "ots_proof": "base64:AE9wZW5..."
    }
  ]
}

Fields omitted from metadata.apl in the example above (bridge_refs, transformation_refs) are absent in this minimal case. If present, each MUST be a non-empty array of Reference Objects. The ATL-side wrapping (proof, super_proof, anchors) is normatively defined in the ATL Protocol Specification  and summarized in ATL — Data Structures ; it is reproduced here for completeness of the APL-on-ATL Receipt example.

Key Fields (APL-specific):

  • entry.metadata.apl.version (REQUIRED): Protocol version. MUST be "1.0" for APL Core v1.0.
  • entry.metadata.apl.claim (REQUIRED): The APL Claim object. See Section 3.
  • entry.metadata.apl.frame_ref (REQUIRED): Reference Object pinning the frame.
  • entry.metadata.apl.bridge_refs (OPTIONAL): If present, MUST be a non-empty array of Reference Objects pointing to APL Bridge artifacts. If absent, the field MUST be omitted (not set to []).
  • entry.metadata.apl.transformation_refs (OPTIONAL): If present, MUST be a non-empty array of Reference Objects pointing to APL Transformation artifacts. If absent, the field MUST be omitted (not set to []).

3. APL Claim (JSON)

The claim object, always nested inside metadata.apl.

{
  "kind": "observation",
  "subject": {
    "id": "model:acme-gpt-7b-build-42"
  },
  "aspect_refs": ["accuracy"],
  "statement": {
    "predicate": "score",
    "content": {
      "benchmark": "MMLU",
      "value": 0.781,
      "unit": "fraction"
    }
  }
}

Key Fields:

  • kind (REQUIRED): MUST be "observation" in v1.0.
  • subject (REQUIRED): JSON object. MUST contain at least one of id (non-empty string) or digest (valid hash string).
  • aspect_refs (REQUIRED): Non-empty array of unique non-empty strings. Every element MUST appear in frame.aspect.
  • statement (REQUIRED): JSON object with REQUIRED predicate (non-empty string) and content (any JSON value).
  • related_frames (OPTIONAL): If present, MUST be a non-empty array of unique hash strings. Relation-layer discovery hint only. If absent, the field MUST be omitted (not set to []).

4. APL Frame (JSON)

An APL Frame is a standalone content-addressed artifact. Identity is SHA-256(JCS(frame)).

{
  "version": "1.0",
  "observer": "acme-eval-runner",
  "procedure": "benchmark-run/lm-eval-harness@0.4.2",
  "aspect": ["accuracy"],
  "scope": "mmlu/dev",
  "invariance": ["score object serialization"],
  "exclusions": [
    "no claim about production readiness",
    "no claim about deployment safety"
  ]
}

Key Fields:

  • version (REQUIRED): MUST be "1.0" for APL Core v1.0.
  • observer (REQUIRED): Non-empty JSON string or object.
  • aspect, invariance, exclusions (REQUIRED): Each a non-empty array of unique non-empty strings.
  • At least one of procedure or instrument (REQUIRED): Non-empty string or object.
  • At least one of scope or resolution (REQUIRED): Non-empty string or object.
  • extends (OPTIONAL): Reference Object. Composition only — MUST NOT substitute for mandatory kernel.
  • aliases, notes (OPTIONAL): Human-readable metadata. Not part of identity except by JCS canonicalization.

5. APL Bridge (JSON)

An APL Bridge is a content-addressed artifact declaring the conditions under which claims from two frames MAY be treated as comparable.

{
  "version": "1.0",
  "source_frame": {
    "hash": "sha256:aaaa..."
  },
  "target_frame": {
    "hash": "sha256:bbbb..."
  },
  "comparison_scope": {
    "source_aspects": ["accuracy"],
    "target_aspects": ["accuracy"],
    "relation_type": "benchmark-score-comparison"
  },
  "assumptions": [
    "subject identity matches via artifact_digest"
  ],
  "losses": [
    "harness differences not reconciled"
  ]
}

Key Fields:

  • version (REQUIRED): MUST be "1.0" for APL Core v1.0.
  • source_frame, target_frame (REQUIRED): Reference Objects. Bridges are directional (source → target).
  • comparison_scope (REQUIRED): JSON object with REQUIRED source_aspects, target_aspects (both non-empty string arrays), and relation_type (non-empty string).
  • assumptions (REQUIRED): Array of unique non-empty strings. MAY be empty.
  • losses (REQUIRED): Array of unique non-empty strings. MAY be empty, but MUST NOT mean “unknown”.

6. APL Transformation (JSON)

An APL Transformation is a content-addressed artifact declaring the semantic effect of applying a transformation to observations.

{
  "version": "1.0",
  "procedure": "raw-to-denoised-jpeg",
  "preserves": [
    "subject identity",
    "capture timestamp"
  ],
  "losses": [
    "per-pixel sensor noise",
    "raw color-response curve"
  ]
}

Key Fields:

  • version (REQUIRED): MUST be "1.0" for APL Core v1.0.
  • procedure (REQUIRED): Non-empty string or object identifying the transformation.
  • preserves (REQUIRED): Array of explicitly preserved invariants.
  • losses (REQUIRED): Array of explicitly declared losses. Empty array means “nothing is lost” — never “unknown”.

7. Relation Query (JSON)

The input to a pairwise verifier (alongside two receipts). See The Protocol § 5.8.

{
  "left_aspects": ["accuracy"],
  "right_aspects": ["accuracy"],
  "predicate": "score",
  "relation_type": "benchmark-score-comparison"
}

Key Fields:

  • left_aspects, right_aspects (REQUIRED): Non-empty arrays of unique non-empty strings. Each MUST be a subset of the corresponding receipt’s claim.aspect_refs.
  • predicate (REQUIRED): Non-empty string. MUST match claim.statement.predicate on both sides.
  • relation_type (REQUIRED): Non-empty string. MUST align with any applicable bridge’s comparison_scope.relation_type.

8. Verifier Output (JSON)

The canonical output of a conforming APL verifier.

{
  "core_outcome": "apl-valid",
  "relation_outcome": "relation-not-evaluated",
  "failure_classes": [],
  "diagnostics": [
    "carrier-valid",
    "apl-present",
    "apl-frame-bound"
  ]
}

Key Fields:

  • core_outcome (REQUIRED): Exactly one of apl-valid, apl-invalid.
  • relation_outcome (SHOULD be present): One of relation-not-evaluated, same-frame-comparable, bridged-comparable, incomparable.
  • failure_classes (SHOULD be empty for apl-valid; SHOULD contain at least one class marker for apl-invalid): Subset of { carrier-failure, claim-structure-failure, reference-failure, frame-failure, semantic-linkage-failure, relation-structure-failure }.
  • diagnostics (OPTIONAL, RECOMMENDED): Array of fine-grained status codes from Section 9.

A typical apl-invalid output:

{
  "core_outcome": "apl-invalid",
  "relation_outcome": "relation-not-evaluated",
  "failure_classes": ["semantic-linkage-failure"],
  "diagnostics": [
    "failure-semantic-linkage",
    "apl-aspect-ref-out-of-frame"
  ]
}

9. Verifier Status Codes

A conforming verifier SHOULD emit diagnostics from the enumeration below. Codes are grouped by the aspect of the receipt they describe. Profiles MAY extend this enumeration with profile-specific codes; they MUST NOT redefine Core codes.

Top-level failure classes:

failure-carrier, failure-claim-structure, failure-reference, failure-frame, failure-semantic-linkage, failure-relation-structure

Carrier:

carrier-valid, carrier-invalid

APL payload presence and shape:

apl-present, apl-missing, apl-invalid-shape, apl-version-missing, apl-version-unsupported

Claim:

apl-claim-missing, apl-claim-invalid, apl-claim-kind-missing, apl-claim-kind-unsupported

Subject:

apl-subject-missing, apl-subject-invalid, apl-subject-id-invalid, apl-subject-digest-invalid

Aspect references:

apl-aspect-refs-missing, apl-aspect-refs-invalid, apl-aspect-ref-out-of-frame

Statement:

apl-statement-missing, apl-statement-invalid, apl-predicate-missing, apl-content-missing

Frame binding and identity:

apl-frame-bound, apl-frame-ref-invalid, apl-frame-missing, apl-frame-hash-invalid, apl-frame-unresolved, apl-frame-hash-mismatch

Frame kernel:

apl-frame-version-missing, apl-frame-version-unsupported, apl-frame-observer-invalid, apl-frame-aspect-invalid, apl-frame-invariance-invalid, apl-frame-exclusions-invalid, apl-frame-procedure-or-instrument-missing, apl-frame-scope-or-resolution-missing, apl-frame-kernel-missing, apl-frame-kernel-invalid

Relation-layer structural:

apl-related-frames-invalid, apl-bridge-refs-invalid, apl-transformation-refs-invalid

Core outcomes:

apl-valid, apl-invalid

Relation outcomes and context:

same-frame, cross-frame, bridged, unbridged, comparable, incomparable

Transformation:

transformation-declared, transformation-missing, loss-declared, loss-undeclared

Pairwise preconditions:

apl-pair-left-invalid, apl-pair-right-invalid, apl-relation-query-invalid, apl-relation-query-left-aspects-out-of-claim, apl-relation-query-right-aspects-out-of-claim, apl-relation-query-predicate-mismatch

Pairwise same-frame:

apl-same-frame, apl-same-frame-aspect-match, apl-same-frame-aspect-mismatch

Pairwise statement compatibility:

apl-statement-content-type-mismatch, apl-statement-object-shape-mismatch

Pairwise cross-frame and bridge:

apl-cross-frame, apl-bridge-invalid, apl-bridge-not-found, apl-bridge-frame-mismatch, apl-bridge-hash-mismatch, apl-bridge-scope-mismatch, apl-bridge-applicable

Pairwise transformation context:

apl-transformation-declared

10. Content-Addressed Identity Construction

APL Frame, APL Bridge, and APL Transformation are identified by the SHA-256 of their JCS-canonicalized JSON bytes. The construction is:

Identity = SHA-256(
  JCS(artifact)         // RFC 8785 canonicalized JSON bytes
)

Where:

  • JCS is the JSON Canonicalization Scheme defined by RFC 8785 .
  • SHA-256 is computed over the exact bytes emitted by JCS canonicalization.

The identity is encoded as a lowercase hexadecimal string, prefixed with sha256:, and placed in a Reference Object hash field. Aliases, URLs, and registry paths MUST NOT substitute for the hash.

If two artifacts are compared after removing one or more fields, the comparing party MUST:

  1. Remove the specified fields from each object.
  2. JCS-canonicalize the resulting objects.
  3. Compare the resulting byte sequences for exact equality.

No other field-order-sensitive, whitespace-sensitive, or implementation-specific textual comparison is normatively compatible.

Last updated on
The ProtocolOverview