Skip to content
Universal Manifest

Reference Implementation

This page describes one reference implementation pattern for applying Universal Manifest without introducing new normative requirements.

Boundary: normative vs non-normative

Section titled “Boundary: normative vs non-normative”
  • Normative contract: Specification and Conformance sections
  • Non-normative guidance: this page

Architecture pattern

Section titled “Architecture pattern”

Common reference implementations separate:

  • a subject-controlled runtime that holds current state and mediates disclosure,
  • issuer or edge surfaces that package manifests,
  • consumer surfaces that resolve and enforce manifest policy,
  • and optional admin surfaces for enrollment and debugging.

This keeps Universal Manifest pointer-first and storage-neutral.

Role taxonomy

Section titled “Role taxonomy”

Use a role-based model instead of treating one substrate as the whole architecture.

  • Canonical private state authority: the subject-controlled runtime decides current consent, pointer routing, freshness, and disclosure.
  • Public projection broker: reduced public-facing views can be emitted to external surfaces without becoming the private authority.
  • Trust federation gatekeeper: verifier or issuer trust evaluation is a separate role from storage or sync.
  • Relay/sync coordinator: update propagation and stale-cache recovery are separate from where data is stored.
  • Edge availability custodian: local caches and relays are responsible for bounded offline behavior.
  • Closed-surface bridge adapter: proprietary integrations remain implementation detail.

No single external substrate is normative for UM.

Subject-controlled runtime

Section titled “Subject-controlled runtime”
  • Maintains current subject state
  • Mediates consent before sharing
  • Coordinates push notifications and pull/request retrieval
  • Can operate bridge adapters for open or closed surfaces

Source-of-truth rule

Section titled “Source-of-truth rule”
  • Treat the runtime as the current authority when it exists.
  • Treat public projection endpoints and external stores as attached systems, not automatic authority replacements.
  • Use explicit authoritative pointers when a consumer needs to know where to refresh from.

Common active-runtime loop

Section titled “Common active-runtime loop”
  1. Observe a state change
  2. Signal or receive update intent
  3. Fetch or assemble current manifest state
  4. Verify TTL and policy
  5. Project only the allowed subset
  6. Revoke or refresh when consent or freshness changes

What you implement (minimum checklist)

Section titled “What you implement (minimum checklist)”

Inputs

Section titled “Inputs”
  • Manifest payloads conforming to v0.1 (or v0.2 when enabled)
  • Subject and policy data needed by display/admin surfaces
  • Change signal containing at least displayId and manifestId

Outputs

Section titled “Outputs”
  • Deterministic behavior driven by the current valid manifest
  • Operational telemetry keyed by manifest IDs
  • Explicit invalid/expired handling

Minimum behaviors

Section titled “Minimum behaviors”
  • Enforce TTL for use (expiresAt)
  • Ignore unknown fields safely
  • Cache full manifests only while in active use
  • Persist logs as ID references, not full payload history

Discovery and transport

Section titled “Discovery and transport”

Recommended discovery descriptor:

  • GET /.well-known/um/edge.json

Push signal minimum fields:

  • displayId
  • manifestId

Then pull the manifest by ID over HTTP.

Bridge adapters

Section titled “Bridge adapters”

Some implementations project manifest-controlled state into third-party APIs or closed surfaces. That is an implementation pattern, not a UM conformance requirement. The same consent, TTL, and pointer-first rules still apply.

Recommended bridge behavior:

  • keep projections reduced and audience-scoped,
  • fail closed or restrict sensitive actions when freshness or trust checks fail,
  • do not let the closed surface become the canonical state authority.

Signature policy

Section titled “Signature policy”
  • v0.1: signature is optional (permissive placeholder)
  • v0.2: signature profile (JCS + Ed25519) can be required for trusted surfaces

Reference fixtures

Section titled “Reference fixtures”

Next

Section titled “Next”