{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "urn:orbiplex:schema:capability-advertisement:v1",
  "title": "CapabilityAdvertisement v1",
  "description": "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.",
  "type": "object",
  "additionalProperties": true,
  "x-dia-workflow": "project",
  "x-dia-status": "draft",
  "x-dia-basis": [
    "doc/project/40-proposals/014-node-transport-and-discovery-mvp.md",
    "doc/project/50-requirements/requirements-006-node-networking-mvp.md",
    "doc/project/60-solutions/000-node/000-node.md"
  ],
  "required": [
    "schema/v",
    "advertisement/id",
    "node/id",
    "published-at",
    "protocol/version",
    "transport/profiles",
    "capabilities/core",
    "capabilities/presented",
    "messages/supported",
    "signature"
  ],
  "properties": {
    "schema/v": {
      "const": 1,
      "description": "Schema version."
    },
    "advertisement/id": {
      "type": "string",
      "minLength": 1,
      "description": "Stable identifier of this capability advertisement."
    },
    "node/id": {
      "type": "string",
      "minLength": 1,
      "pattern": "^node:did:key:z[1-9A-HJ-NP-Za-km-z]+$",
      "description": "Node advertising its baseline capability surface. In v1 this MUST use the canonical `node:did:key:z...` format."
    },
    "published-at": {
      "type": "string",
      "format": "date-time",
      "description": "Timestamp when the capability set was published."
    },
    "protocol/version": {
      "type": "string",
      "minLength": 1,
      "description": "Protocol version for which the capability advertisement is valid."
    },
    "transport/profiles": {
      "type": "array",
      "minItems": 1,
      "uniqueItems": true,
      "items": {
        "type": "string",
        "enum": [
          "wss"
        ]
      },
      "description": "Transport profiles currently exposed by the Node."
    },
    "capabilities/core": {
      "type": "array",
      "minItems": 1,
      "uniqueItems": true,
      "items": {
        "type": "string",
        "pattern": "^((core|role|plugin)/[a-z0-9-]+(?:/[a-z0-9-]+)*|(sovereign|sovereign-informal)/[A-Za-z0-9_-]+(?:/[A-Za-z0-9_-]+)*|[A-Za-z0-9_-]+)$"
      },
      "description": "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": {
      "type": "array",
      "minItems": 1,
      "items": {
        "$ref": "#/$defs/capabilityPresentation"
      },
      "description": "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": {
      "type": "object",
      "additionalProperties": {
        "type": "string",
        "minLength": 1
      },
      "description": "Optional sovereign capability anchor map keyed by the sovereign short name. Empty or absent for formal capabilities."
    },
    "roles/attached": {
      "type": "array",
      "uniqueItems": true,
      "items": {
        "type": "string",
        "minLength": 1
      },
      "description": "Optional attached roles or plugin-process capabilities visible at the Node boundary. Not required in MVP."
    },
    "surfaces/exposed": {
      "type": "array",
      "uniqueItems": true,
      "items": {
        "type": "string",
        "minLength": 1
      },
      "description": "Exposed APIs, channels, or queues that can be used by peers or attached roles."
    },
    "messages/supported": {
      "type": "array",
      "minItems": 1,
      "uniqueItems": true,
      "items": {
        "type": "string",
        "minLength": 1
      },
      "description": "Protocol message families currently supported by the Node."
    },
    "signature": {
      "$ref": "#/$defs/signature"
    },
    "policy_annotations": {
      "type": "object",
      "additionalProperties": true,
      "description": "Optional annotations that do not change the core advertised capability semantics."
    }
  },
  "$defs": {
    "capabilityPresentation": {
      "type": "object",
      "additionalProperties": true,
      "required": [
        "capability/id",
        "wire/name",
        "assertion/kind",
        "passport"
      ],
      "properties": {
        "capability/id": {
          "type": "string",
          "minLength": 1,
          "pattern": "^[~]?[a-z0-9][a-z0-9_/-]*(?:@(participant|node|org):did:key:z[1-9A-HJ-NP-Za-km-z]+)?$",
          "description": "Canonical capability id in the same namespace used by `capability-passport.v1`."
        },
        "wire/name": {
          "type": "string",
          "pattern": "^((core|role|plugin)/[a-z0-9-]+(?:/[a-z0-9-]+)*|(sovereign|sovereign-informal)/[A-Za-z0-9_-]+(?:/[A-Za-z0-9_-]+)*|[A-Za-z0-9_-]+)$",
          "description": "Wire-visible projection of `capability/id` used for fast matching and routing."
        },
        "assertion/kind": {
          "type": "string",
          "enum": [
            "self-issued-passport",
            "issuer-passport",
            "federation-endorsed-passport"
          ],
          "description": "`self-issued-passport` means the Node or its operator asserts its own capability. `issuer-passport` means a distinct issuer delegates or accepts the capability. `federation-endorsed-passport` means the presented passport is accompanied by federation policy or endorsement material."
        },
        "passport": {
          "type": "object",
          "additionalProperties": true,
          "description": "Full `capability-passport.v1` or profile-compatible passport assertion for this capability. Receivers MUST verify it under the capability profile and local policy before trusting the claim."
        },
        "passport/hash": {
          "type": "string",
          "pattern": "^sha256:[A-Za-z0-9_-]+$",
          "description": "Optional hash of the presented passport for cache lookup and deduplication."
        },
        "capability/profile": {
          "$ref": "#/$defs/capabilityProfile",
          "description": "Optional display and schema metadata for this presented capability. It is a presentation copy or summary; the passport and local policy remain authoritative."
        },
        "endorsements": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": true
          },
          "description": "Optional federation or issuer endorsement artifacts. These are policy inputs, not replacements for the passport signature."
        },
        "scope/summary": {
          "type": "object",
          "additionalProperties": true,
          "description": "Optional non-authoritative summary of passport scope for UI and routing. The passport remains authoritative."
        }
      }
    },
    "capabilityProfile": {
      "type": "object",
      "additionalProperties": true,
      "properties": {
        "compatible_with": {
          "type": "string",
          "minLength": 1,
          "description": "Optional formal capability id whose public contract this presented profile claims to implement. This is a compatibility claim checked by receivers against local policy and schema evidence; it does not replace the passport capability id."
        },
        "display/name": {
          "type": "string",
          "minLength": 1,
          "description": "Short human-readable capability name intended for UI display. It MUST NOT replace `capability/id` as protocol identity."
        },
        "description": {
          "type": "string",
          "minLength": 1,
          "description": "Human-readable capability explanation."
        },
        "lang": {
          "type": "string",
          "pattern": "^[A-Za-z]{2,8}(-[A-Za-z0-9]{1,8})*$",
          "description": "BCP 47-style language tag for human-readable profile fields."
        },
        "doc/ref": {
          "type": "string",
          "pattern": "^orbiplex:blob:sha256:[A-Za-z0-9_-]+$",
          "description": "Optional content-addressed Orbiplex reference to a human-readable capability document."
        },
        "doc/url": {
          "type": "string",
          "format": "uri",
          "description": "Optional convenience URL for human-readable documentation. This is not a protocol dependency."
        },
        "schema/id": {
          "type": "string",
          "minLength": 1,
          "description": "Stable logical identifier of the machine-readable capability schema."
        },
        "schema/ref": {
          "type": "string",
          "pattern": "^orbiplex:blob:sha256:[A-Za-z0-9_-]+$",
          "description": "Content-addressed Orbiplex reference to a `capability-schema.v1` artifact retrievable over the peer protocol, Seed Directory, cache, or archivist surface."
        },
        "schema/media-type": {
          "type": "string",
          "minLength": 1,
          "description": "Media type of the capability schema content, for example `application/schema+json`."
        }
      }
    },
    "signature": {
      "type": "object",
      "additionalProperties": true,
      "required": [
        "alg",
        "value"
      ],
      "properties": {
        "alg": {
          "type": "string",
          "minLength": 1
        },
        "value": {
          "type": "string",
          "minLength": 1
        }
      }
    }
  },
  "allOf": [
    {
      "properties": {
        "capabilities/core": {
          "contains": {
            "const": "core/messaging"
          }
        }
      },
      "required": [
        "capabilities/core"
      ]
    },
    {
      "properties": {
        "capabilities/presented": {
          "contains": {
            "type": "object",
            "properties": {
              "wire/name": {
                "const": "core/messaging"
              }
            },
            "required": [
              "wire/name"
            ]
          }
        }
      },
      "required": [
        "capabilities/presented"
      ]
    }
  ]
}