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: falseis 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.