1. Canonical Schemas & Protocols (fleetmesh_schema)

The schema repository defines the canonical, machine-readable specifications that govern the entire Fleetmesh network. It acts as the single authoritative source of truth across all implementations—including the Python reference (fleetmesh_core and meshnode), the Rust control CLI (meshctl), the relay bridge (fleetmesh-strfry), and external ecosystem integrations.

Fleetmesh Logo

1.1. Design Principles

  1. Protocol Immutability & Verifiability: Core protocol constants, event kind registries, and message formats are cryptographically hashed into an authoritative protocol digest (schema/DIGEST). Two nodes must agree on this digest to establish higher peering tiers.

  2. Draft 2020-12 Formal Schemas: Every Nostr event kind, DIDComm message envelope, decrypted payload, and manifest resource is formally defined using standard JSON Schema Draft 2020-12 specifications under schemas/.

  3. Declarative Kubernetes-Style Manifests: Infrastructure resources (nodes, peerings, grant policies, compute providers) use the Kubernetes CRD conventions (apiVersion: fleetmesh.org/v1alpha1).

  4. Zero-Overhead Python Access: The fleetmesh_schema Python package provides lightweight, cached access to all schema definitions with zero runtime dependencies.

1.2. Repository Structure

Directory / File

Description

schema/constants.json

Normative cryptographic primitives, window timeframes, rate ceilings, and pricing ladders.

schema/kinds.json

Formal definitions and tagging rules for all Fleetmesh Nostr event kinds (11801–31803).

schema/messages.json

Wire message envelope definitions for all DIDComm protocol families.

schema/DIGEST

The SHA-256 hash over canonical representations of constants, kinds, and messages.

schema/PROTOCOLS

Supported protocol capability URIs (https://fleetmesh.org/*).

schema/conformance.json

Catalogue of conformance operations and test vectors used by scripts/conform.py.

schemas/

Directory tree of JSON Schema Draft 2020-12 documents organized by plane.

manifests/

Declarative CRD manifests (apiVersion: fleetmesh.org/v1alpha1).

fleetmesh_schema/

Installable Python package exposing cached loaders and path helpers.

1.3. Validation Suite

To validate all manifests and schemas against their Draft 2020-12 meta-schemas:

python3 schema/scripts/check-manifests.py
python3 schema/scripts/validate-schemas.py

1.4. Specifications Reference

Specification

Description

Nostr Event Kinds Registry

Canonical Nostr event kinds registry (11801–31803), required and optional tags, and semantics.

Wire Message Catalog & DIDComm Protocols

Wire message catalog and DIDComm protocol families (peering, budget, transport, compute, sync, blossom).

Declarative Manifests & CRDs

Declarative Kubernetes-style CRD manifests (MeshNode, Peering, GrantPolicy, ComputeProvider, Routers).

The Protocol Digest & Version Verification

The protocol digest verification system (schema/DIGEST), cryptographic hashing, and drift defense.

JSON Schema Specifications (Draft 2020-12)

Formal JSON Schema Draft 2020-12 specifications directory structure and validation workflows.

Python API Reference (fleetmesh_schema)

Python fleetmesh_schema module documentation (path, schema_path, load_json, text, digest).