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. .. image:: ../_static/logo-fleetmesh.svg :align: center :alt: Fleetmesh Logo :width: 240px \ 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. Repository Structure -------------------- .. list-table:: :widths: 25 75 :header-rows: 1 * - 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. Validation Suite ---------------- To validate all manifests and schemas against their Draft 2020-12 meta-schemas: .. code-block:: sh python3 schema/scripts/check-manifests.py python3 schema/scripts/validate-schemas.py Specifications Reference ------------------------ .. list-table:: :widths: 25 75 :header-rows: 1 * - Specification - Description * - :doc:`kinds` - Canonical Nostr event kinds registry (11801–31803), required and optional tags, and semantics. * - :doc:`messages` - Wire message catalog and DIDComm protocol families (peering, budget, transport, compute, sync, blossom). * - :doc:`manifests` - Declarative Kubernetes-style CRD manifests (MeshNode, Peering, GrantPolicy, ComputeProvider, Routers). * - :doc:`digest` - The protocol digest verification system (schema/DIGEST), cryptographic hashing, and drift defense. * - :doc:`json_schemas` - Formal JSON Schema Draft 2020-12 specifications directory structure and validation workflows. * - :doc:`api` - Python fleetmesh_schema module documentation (path, schema_path, load_json, text, digest).