Extensions

A DCP extension is an optional, namespaced object — keyed x-<vendor> — attached to the envelope, the Event, or an entity to carry vendor-specific data outside the protocol core. Extensions are always ignorable: a conformant consumer that does not recognize an extension key simply skips it, so unknown extensions never cause rejection.

The core never grows

The DCP core is closed. SPEC.md §4 defines the envelope as strict (additionalProperties: false); the same is true of the Event and every entity. New top-level fields are never added to accommodate a single vendor’s needs. Instead, all growth happens through one escape hatch: an optional extensions object, present in three places — the envelope, the Event, and every one of the eight entities.

This is what keeps DCP vendor-neutral. Tokonomix, GitHub integrations, or any future adopter can attach their own metadata without petitioning for a schema change, and without one vendor’s needs shaping the shared core that every other implementation has to parse.

The rules

Extensions follow a small, strict set of constraints (SPEC §9):

• Key pattern. Every extension key MUST match ^x-<vendor>$, lowercase — for example x-tokonomix or x-github. The extensions wrapper itself is additionalProperties: false over that pattern, so anything not shaped like x-vendor is rejected at the wrapper level.
• Always optional, never must-understand. There is no flag that forces a consumer to understand an extension before proceeding. A producer cannot emit a message that a conformant consumer is obligated to reject just because it doesn’t recognize an x- key. If you don’t know what x-tokonomix means, you ignore it and keep processing the rest of the message.
• No smuggled authority. Producers MUST NOT use extensions to carry transport, trust, identity, or routing data. This follows directly from DCP’s prime directive — DCP carries no trust, and that doesn’t change just because the data sits inside an x- object. Reserved-looking prefixes such as x-auth-*, x-signed-*, x-permission-*, and x-agentixmesh-* carry no authority. A consumer MUST NOT read them as authenticated transport claims, no matter how official the name looks.
• Bounded size. Each extension value is an object with at most 20 properties, keeping the payload predictable and preventing extensions from becoming an unbounded side-channel.

Why this guarantees forward compatibility

Extensions solve one half of DCP’s forward-compatibility story; open-token vocabularies solve the other. Together they mean a message from a newer producer never breaks an older validator:

• A new vendor field arrives inside extensions — a key an old consumer has never seen. Because extensions are always optional and always ignorable, the old validator passes the message through untouched.
• A new value for a growable field — status, verb, priority, severity, and the like — arrives as an open token rather than a closed enum member. As covered in versioning and compatibility, consumers MUST tolerate and pass through unknown verbs and unknown enumerated values, the same discipline behind status being a vocabulary, not a state machine.

Neither path requires a major version bump or a coordinated rollout. entity_type and the rel vocabulary stay closed because they’re structural guards, but everything a vendor actually needs to say fits through extensions or an open token.

A worked example

Here’s a task.completed message where a vendor attaches its own review-council metadata via extensions, alongside a delta describing what changed:

{
  "dcp_version": "1.0",
  "message_id": "msg_01HZ0TASK0042",
  "message_type": "task.completed",
  "issued_at": "2026-06-29T10:00:00Z",
  "extensions": {
    "x-tokonomix": { "council_run_id": "run_123" }
  },
  "body": {
    "event_id": "evt_01HZ0TASK0042",
    "entity_type": "task",
    "verb": "completed",
    "entity_id": "task_42",
    "delta": {
      "status": { "from": "in_progress", "to": "completed" }
    },
    "extensions": {
      "x-github": { "pull_request": "org/example#128" }
    }
  }
}

An older consumer that has never heard of x-tokonomix or x-github still validates and processes this message correctly: it reads the standard delta, ignores both extensions objects, and moves on. A DCP-conformant implementation, as of 2026-07-03, validates 70 passing tests and 25 conformance cases across the reference schemas — none of which depend on any particular vendor extension existing or being understood.

What extensions are not

Extensions are not a way to bypass DCP’s closed sets. entity_type (the eight nouns) and rel (the eight-value relation vocabulary) stay closed regardless of what vendors put in extensions — those remain single-responsibility structural guards, changeable only in a major version. Extensions also aren’t a workaround for the prime directive: if data in an x- object looks like it’s granting permission or authenticating a sender, that’s a misuse of the mechanism, not a loophole in it.

If an extension turns out to be broadly useful — several independent vendors converge on the same shape, and it’s genuinely descriptive project-coordination metadata rather than transport concerns — it can be proposed for promotion to an optional core field through the governance process. Promotion is additive, landing in a minor version, and the original extension form keeps working after promotion.

By InterIP Networks · Last updated 2026-07-01.