Capability Schema v1¶
Source schema: doc/schemas/capability-schema.v1.schema.json
Portable, content-addressed machine-readable schema artifact for one capability profile. Nodes may serve this artifact over the authenticated peer-message channel so receivers can validate capability scope, inputs, outputs, error profiles, and retry semantics without depending on an external URL.
Governing Basis¶
doc/project/40-proposals/024-capability-passports-and-network-ledger-delegation.mddoc/project/40-proposals/025-seed-directory-as-capability-catalog.mddoc/project/40-proposals/027-middleware-peer-message-dispatch.mddoc/project/60-solutions/007-capability-advertisement/007-capability-advertisement.md
Project Lineage¶
Requirements¶
doc/project/50-requirements/requirements-006-node-networking-mvp.mddoc/project/50-requirements/requirements-010-middleware-executor.mddoc/project/50-requirements/requirements-011-dator-arca-contracts.md
Stories¶
doc/project/30-stories/story-001-swarm-node-onboarding.mddoc/project/30-stories/story-004-pod-client-onboarding.mddoc/project/30-stories/story-006-buyer-node-components.mddoc/project/30-stories/story-006-voluntary-swarm-exchange.mddoc/project/30-stories/story-007-settlement-capable-node.md
Fields¶
| Field | Required | Shape | Description |
|---|---|---|---|
schema |
yes |
const: capability-schema.v1 |
Schema discriminator. MUST be exactly capability-schema.v1. |
schema/id |
yes |
string | Stable logical identifier of the capability schema contract. This identifies what contract the content describes, not where it is hosted. |
schema/ref |
yes |
string | Content-addressed reference to the canonical schema content. Receivers MUST verify that content hashes to this reference before using the schema. |
schema/media-type |
yes |
string | Media type of content, for example application/schema+json, application/vnd.malli+edn, or another profile-accepted machine-readable schema format. |
capability/id |
no |
string | Optional capability id this schema describes. Formal profiles may use a bare id; sovereign or private profiles may use an identity-anchored id. |
compatible_with |
no |
string | Optional formal capability id whose public contract this schema claims to implement. Omit for purely custom ~...@... protocols. |
wire/name |
no |
string | Optional wire-visible projection associated with the capability id. |
display/name |
no |
string | Short human-readable capability name for UI display. |
description |
no |
string | Human-readable capability explanation. |
lang |
no |
string | BCP 47-style language tag for human-readable fields. |
doc/ref |
no |
string | Optional content-addressed reference to human-readable documentation. |
doc/url |
no |
string | Optional convenience URL for human-readable documentation. This is a mirror or hint, not a protocol dependency. |
content |
yes |
unspecified | Machine-readable schema content. The interpretation is selected by schema/media-type. |
published-at |
yes |
string | Timestamp when this schema artifact was published. |
author/node-id |
yes |
string | Node identity that publishes this schema artifact. |
author/participant-id |
no |
string | Optional participant identity responsible for authoring or approving this schema artifact. |
signature |
yes |
ref: #/$defs/signature |
|
policy_annotations |
no |
object | Optional local or federation-local annotations that do not change core schema semantics. |
Definitions¶
| Definition | Shape | Description |
|---|---|---|
signature |
object | Signature over the deterministic canonical form of this artifact with the top-level signature field omitted. The schema/ref still addresses only the canonical content value. |
| ## Field Semantics |
schema¶
- Required:
yes - Shape: const:
capability-schema.v1
Schema discriminator. MUST be exactly capability-schema.v1.
schema/id¶
- Required:
yes - Shape: string
Stable logical identifier of the capability schema contract. This identifies what contract the content describes, not where it is hosted.
schema/ref¶
- Required:
yes - Shape: string
Content-addressed reference to the canonical schema content. Receivers MUST verify that content hashes to this reference before using the schema.
schema/media-type¶
- Required:
yes - Shape: string
Media type of content, for example application/schema+json, application/vnd.malli+edn, or another profile-accepted machine-readable schema format.
capability/id¶
- Required:
no - Shape: string
Optional capability id this schema describes. Formal profiles may use a bare id; sovereign or private profiles may use an identity-anchored id.
compatible_with¶
- Required:
no - Shape: string
Optional formal capability id whose public contract this schema claims to implement. Omit for purely custom ~...@... protocols.
wire/name¶
- Required:
no - Shape: string
Optional wire-visible projection associated with the capability id.
display/name¶
- Required:
no - Shape: string
Short human-readable capability name for UI display.
description¶
- Required:
no - Shape: string
Human-readable capability explanation.
lang¶
- Required:
no - Shape: string
BCP 47-style language tag for human-readable fields.
doc/ref¶
- Required:
no - Shape: string
Optional content-addressed reference to human-readable documentation.
doc/url¶
- Required:
no - Shape: string
Optional convenience URL for human-readable documentation. This is a mirror or hint, not a protocol dependency.
content¶
- Required:
yes - Shape: unspecified
Machine-readable schema content. The interpretation is selected by schema/media-type.
published-at¶
- Required:
yes - Shape: string
Timestamp when this schema artifact was published.
author/node-id¶
- Required:
yes - Shape: string
Node identity that publishes this schema artifact.
author/participant-id¶
- Required:
no - Shape: string
Optional participant identity responsible for authoring or approving this schema artifact.
signature¶
- Required:
yes - Shape: ref:
#/$defs/signature
policy_annotations¶
- Required:
no - Shape: object
Optional local or federation-local annotations that do not change core schema semantics.
Definition Semantics¶
$defs.signature¶
- Shape: object
Signature over the deterministic canonical form of this artifact with the top-level signature field omitted. The schema/ref still addresses only the canonical content value.