6. JSON Schema Specifications (Draft 2020-12)

While schema/kinds.json and schema/messages.json provide summary catalogues, the schemas/ directory contains formal, machine-readable specifications conforming to the JSON Schema Draft 2020-12 standard.

These schemas enable static validation, code generation, and automated runtime input sanitization across client libraries in any programming language.

6.1. Schema Directory Structure

The schemas are divided into functional directories by architectural plane:

schemas/
├── common/                                       # Base cryptographic primitives, IDs, timestamps
│   └── primitives.schema.json
├── compute/                                      # Non-deterministic & batch compute job schemas
│   ├── bacalhau-batch-job.schema.json
│   └── llm-inference-job.schema.json
├── didcomm/                                      # DIDComm v2 protocol message schemas
│   ├── budget/
│   │   └── receipt.schema.json
│   ├── compute/
│   │   ├── cancel.schema.json
│   │   ├── progress.schema.json
│   │   ├── sealed.schema.json
│   │   └── stream.schema.json
│   └── peering/
│       └── propose.schema.json
├── events/                                       # Nostr event schemas by kind number
│   ├── kind-11801-descriptor.schema.json         # Node Descriptor
│   ├── kind-11802-revocation.schema.json         # Node Revocation
│   ├── kind-11803-compute-offer.schema.json      # Compute Offer
│   ├── kind-21801-heartbeat.schema.json          # Node Heartbeat
│   ├── kind-21802-telemetry.schema.json          # Diagnostic Telemetry
│   ├── kind-30801-grant-envelope.schema.json     # Peer Grant Envelope
│   ├── kind-30802-conformance-report.schema.json # Conformance Report
│   ├── kind-30803-coverage-claim.schema.json     # Coverage Claim
│   ├── kind-30804-gossip-membership.schema.json  # Gossip Topic Membership
│   ├── kind-30810-compute-ask.schema.json        # Compute Ask
│   └── kind-30811-compute-receipt.schema.json    # Job Receipt
├── identity/                                     # W3C DID Documents & verification methods
│   └── did-nostr-node.schema.json
├── manifests/                                    # Declarative v1alpha1 manifest schemas
│   ├── compute-provider.schema.json
│   ├── grant-policy.schema.json
│   ├── inference-router.schema.json
│   ├── meshnode.schema.json
│   ├── peering.schema.json
│   └── workload-router.schema.json
└── payloads/                                     # Decrypted NIP-44 payload bodies
    ├── compute-ask-payload.schema.json
    ├── compute-receipt-payload.schema.json
    └── grant-payload.schema.json

6.2. Schema Design Patterns

6.2.1. Strict Validation Rules

Every schema in the repository enforces strict constraints to prevent ambiguous or malformed payloads:

  • additionalProperties: false is applied universally. Unknown fields are rejected immediately.

  • Regular expressions validate string formats (e.g. ^did:key:z[1-9a-km-zA-HJ-NP-Z]+$ for DIDs, ^[0-9a-f]{64}$ for 32-byte hashes).

  • Numerical boundaries enforce non-negative integers and realistic limits (e.g. rate limits, window durations, byte sizes).

6.2.2. Re-usable Definitions & $ref Resolution

Sub-schemas link to shared common definitions using standard $ref URIs:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://fleetmesh.org/schemas/v1/events/kind-11801-descriptor.schema.json",
  "title": "Kind 11801 - Mesh Node Descriptor",
  "type": "object",
  "required": ["id", "pubkey", "created_at", "kind", "tags", "content", "sig"],
  "properties": {
    "id": { "$ref": "../common/primitives.schema.json#/$defs/eventIdHex" },
    "pubkey": { "$ref": "../common/primitives.schema.json#/$defs/pubkeyHex" },
    "created_at": { "$ref": "../common/primitives.schema.json#/$defs/unixTimestamp" },
    "kind": { "const": 11801 },
    "tags": { "type": "array", "items": { "type": "array" } },
    "content": { "type": "string" },
    "sig": { "$ref": "../common/primitives.schema.json#/$defs/signatureHex" }
  },
  "additionalProperties": false
}

6.3. Automated Validation

The repository includes a validation script that runs against every schema:

python3 schema/scripts/validate-schemas.py

The validator performs two checks: 1. Validates every schema against the official JSON Schema Draft 2020-12 meta-schema. 2. Runs sample events and test vectors against each schema to verify positive matches and ensure intentionally malformed inputs are correctly rejected.