Przejdź do treści

Node Advertisement v1

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

Machine-readable schema for signed endpoint advertisements exchanged during Node discovery. In v1 the signed surface is the deterministic CBOR image of the whole advertisement payload excluding only the signature field itself. Transport-mutable per-hop metadata, if introduced later, must remain outside this semantic payload.

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 signed endpoint advertisement.
node/id yes string Node addressed by this advertisement. In v1 this MUST use the canonical node:did:key:z... format.
sequence/no yes integer Monotonic per-node advertisement sequence number inside the signed payload. In v1 discovery state keeps only the latest advertisement per node/id, so higher sequence numbers supersede older ones.
advertised-at yes string Timestamp when the advertisement was published. This is part of the signed payload.
expires-at yes string Timestamp after which this advertisement must be treated as stale. This is part of the signed payload.
key/alg yes enum: ed25519 Algorithm of the key used to sign this advertisement.
key/public yes string Canonical did:key fingerprint payload corresponding to node/id.
federation/id no string Optional federation scope advertised for bootstrap policy decisions.
succession no ref: #/$defs/succession Optional future-facing identity succession hint. In the MVP baseline this field has no runtime semantics yet and should be treated as an informational contract seed for later rotation procedures.
endpoints yes array Currently valid live endpoints exposed by the Node. Receivers first filter unsupported transports and then use endpoint priority as the sender-side preference hint among compatible endpoints.
transports/supported yes array Baseline transport profiles currently supported by the Node.
signature yes ref: #/$defs/signature
policy_annotations no object Optional local or federation-local annotations that do not change core discovery semantics.

Definitions

Definition Shape Description
endpoint object
signature object
succession object
## Field Semantics

schema/v

  • Required: yes
  • Shape: const: 1

Schema version.

advertisement/id

  • Required: yes
  • Shape: string

Stable identifier of this signed endpoint advertisement.

node/id

  • Required: yes
  • Shape: string

Node addressed by this advertisement. In v1 this MUST use the canonical node:did:key:z... format.

sequence/no

  • Required: yes
  • Shape: integer

Monotonic per-node advertisement sequence number inside the signed payload. In v1 discovery state keeps only the latest advertisement per node/id, so higher sequence numbers supersede older ones.

advertised-at

  • Required: yes
  • Shape: string

Timestamp when the advertisement was published. This is part of the signed payload.

expires-at

  • Required: yes
  • Shape: string

Timestamp after which this advertisement must be treated as stale. This is part of the signed payload.

key/alg

  • Required: yes
  • Shape: enum: ed25519

Algorithm of the key used to sign this advertisement.

key/public

  • Required: yes
  • Shape: string

Canonical did:key fingerprint payload corresponding to node/id.

federation/id

  • Required: no
  • Shape: string

Optional federation scope advertised for bootstrap policy decisions.

succession

  • Required: no
  • Shape: ref: #/$defs/succession

Optional future-facing identity succession hint. In the MVP baseline this field has no runtime semantics yet and should be treated as an informational contract seed for later rotation procedures.

endpoints

  • Required: yes
  • Shape: array

Currently valid live endpoints exposed by the Node. Receivers first filter unsupported transports and then use endpoint priority as the sender-side preference hint among compatible endpoints.

transports/supported

  • Required: yes
  • Shape: array

Baseline transport profiles currently supported by the Node.

signature

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

policy_annotations

  • Required: no
  • Shape: object

Optional local or federation-local annotations that do not change core discovery semantics.

Definition Semantics

$defs.endpoint

  • Shape: object

$defs.signature

  • Shape: object

$defs.succession

  • Shape: object