Přeskočit obsah

Capability Advertisement v1

Source schema: doc/schemas/capability-advertisement.v1.schema.json

Machine-readable schema for baseline capability exchange after peer session establishment. The advertisement is a node-signed presentation of capability assertions in passport form. Seed Directory publication is optional: a Node may broadcast or directly answer with this artifact and include the credentials needed by the receiver to evaluate each presented capability under local policy.

Governing Basis

Project Lineage

Requirements

Stories

Fields

Field Required Shape Description
schema/v yes const: 1 Schema version.
advertisement/id yes string Stable identifier of this capability advertisement.
node/id yes string Node advertising its baseline capability surface. In v1 this MUST use the canonical node:did:key:z... format.
published-at yes string Timestamp when the capability set was published.
protocol/version yes string Protocol version for which the capability advertisement is valid.
transport/profiles yes array Transport profiles currently exposed by the Node.
capabilities/core yes array Compatibility and routing projection of the wire-visible capability identifiers supported by the Node. Values SHOULD be derived from capabilities/presented[*].wire/name. Known formal capabilities use stable core/ or role/ names, sovereign capabilities use sovereign/; sovereign-informal/ remains accepted for legacy advertisements but new ~...@... capability ids project to sovereign/.... Unknown formal capabilities may be advertised as bare names.
capabilities/presented yes array Passport-form capability assertions presented directly by this Node. Each item carries the canonical capability id, the wire-visible projection, an assertion kind, and the passport or passport-compatible credential needed to evaluate the claim without querying a Seed Directory.
anchor_identities no object Optional sovereign capability anchor map keyed by the sovereign short name. Empty or absent for formal capabilities.
roles/attached no array Optional attached roles or plugin-process capabilities visible at the Node boundary. Not required in MVP.
surfaces/exposed no array Exposed APIs, channels, or queues that can be used by peers or attached roles.
messages/supported yes array Protocol message families currently supported by the Node.
signature yes ref: #/$defs/signature
policy_annotations no object Optional annotations that do not change the core advertised capability semantics.

Definitions

Definition Shape Description
capabilityPresentation object
capabilityProfile object
signature object

Conditional Rules

Rule 1

Constraint:

{
  "properties": {
    "capabilities/core": {
      "contains": {
        "const": "core/messaging"
      }
    }
  },
  "required": [
    "capabilities/core"
  ]
}

Rule 2

Constraint:

{
  "properties": {
    "capabilities/presented": {
      "contains": {
        "type": "object",
        "properties": {
          "wire/name": {
            "const": "core/messaging"
          }
        },
        "required": [
          "wire/name"
        ]
      }
    }
  },
  "required": [
    "capabilities/presented"
  ]
}

Field Semantics

schema/v

  • Required: yes
  • Shape: const: 1

Schema version.

advertisement/id

  • Required: yes
  • Shape: string

Stable identifier of this capability advertisement.

node/id

  • Required: yes
  • Shape: string

Node advertising its baseline capability surface. In v1 this MUST use the canonical node:did:key:z... format.

published-at

  • Required: yes
  • Shape: string

Timestamp when the capability set was published.

protocol/version

  • Required: yes
  • Shape: string

Protocol version for which the capability advertisement is valid.

transport/profiles

  • Required: yes
  • Shape: array

Transport profiles currently exposed by the Node.

capabilities/core

  • Required: yes
  • Shape: array

Compatibility and routing projection of the wire-visible capability identifiers supported by the Node. Values SHOULD be derived from capabilities/presented[*].wire/name. Known formal capabilities use stable core/ or role/ names, sovereign capabilities use sovereign/; sovereign-informal/ remains accepted for legacy advertisements but new ~...@... capability ids project to sovereign/.... Unknown formal capabilities may be advertised as bare names.

capabilities/presented

  • Required: yes
  • Shape: array

Passport-form capability assertions presented directly by this Node. Each item carries the canonical capability id, the wire-visible projection, an assertion kind, and the passport or passport-compatible credential needed to evaluate the claim without querying a Seed Directory.

anchor_identities

  • Required: no
  • Shape: object

Optional sovereign capability anchor map keyed by the sovereign short name. Empty or absent for formal capabilities.

roles/attached

  • Required: no
  • Shape: array

Optional attached roles or plugin-process capabilities visible at the Node boundary. Not required in MVP.

surfaces/exposed

  • Required: no
  • Shape: array

Exposed APIs, channels, or queues that can be used by peers or attached roles.

messages/supported

  • Required: yes
  • Shape: array

Protocol message families currently supported by the Node.

signature

  • Required: yes
  • Shape: ref: #/$defs/signature

policy_annotations

  • Required: no
  • Shape: object

Optional annotations that do not change the core advertised capability semantics.

Definition Semantics

$defs.capabilityPresentation

  • Shape: object

$defs.capabilityProfile

  • Shape: object

$defs.signature

  • Shape: object