JSON schema reference

Use the version named by the payload

A protocol identifies its schema version. Do not silently validate one version as another or use a schema's filename as a claim of origin. A schema checks structure; it does not prove a wallet approved, an install is trusted, a network observation is genuine or an external effect occurred.

These downloads are an explicit public subset. They include app/route/data definitions, server demand/supply, native public identity/auth state, gateway trust/assertion shapes, receipts and sync, plus testing, public demos and the selected Sidecar protocols. They do not publish the internal work graph, authoring stores, deployment credentials or private application configuration.

Choose the correct contract family

Some older protocol versions remain downloadable for compatibility. Consult the emitting component's current reference; “highest version in the directory” is not a migration algorithm. Protocols and page URLs are stable links, not permission to fetch a schema URL supplied by untrusted input.

Validate locally with an explicit registry

Download the three named schemas from this page into a local schemas/ folder. The following Python module uses your installed jsonschema package, rejects unknown protocols and oversized/non-JSON payloads, and performs no remote schema lookup. It is a structural validator, not an authenticated endpoint.

import json
from pathlib import Path
from jsonschema import Draft202012Validator, FormatChecker

SCHEMA_FILES = {
    "capp.sync-ack.v1": "capp.sync-ack.v1.schema.json",
    "capp.sync-page.v1": "capp.sync-page.v1.schema.json",
    "capp.data-record.v1": "capp.data-record.v1.schema.json",
}

def reject_constant(value):
    raise ValueError("Non-JSON numeric constant")

def check_local_refs(value):
    if isinstance(value, dict):
        for key, child in value.items():
            if key in {"$ref", "$dynamicRef"} and (
                not isinstance(child, str) or not child.startswith("#")
            ):
                raise ValueError("External schema references are not enabled")
            check_local_refs(child)
    elif isinstance(value, list):
        for child in value:
            check_local_refs(child)

def validate_protocol_bytes(payload: bytes, schema_dir: Path) -> dict:
    if not isinstance(payload, bytes) or len(payload) > 131072:
        raise ValueError("Use a JSON payload of at most 131072 bytes")
    value = json.loads(payload.decode("utf-8"), parse_constant=reject_constant)
    if not isinstance(value, dict) or not isinstance(value.get("protocol"), str) or value["protocol"] not in SCHEMA_FILES:
        raise ValueError("Unsupported protocol")
    schema = json.loads((schema_dir / SCHEMA_FILES[value["protocol"]]).read_text(encoding="utf-8"))
    check_local_refs(schema)
    Draft202012Validator.check_schema(schema)
    Draft202012Validator(schema, format_checker=FormatChecker()).validate(value)
    return value

The registry is application-owned; never concatenate an incoming protocol into an arbitrary path or accept an incoming $schema as a download instruction. Keep reviewed schema bytes with your dependency version. Catch errors at your HTTP/import boundary without exposing raw private payloads in public logs. The 128 KiB example limit is this helper's choice, not a universal cApp transport limit.

Value validation is a different layer

The app SDK's validateCappValue() is a bounded collection-value validator, not a full JSON Schema 2020-12 implementation. It handles the supported basic type/property/array/bounds/enum/format checks and legacy fields normalization. It does not resolve $ref or enforce every composition keyword such as oneOf. Prefer standard properties for new collection definitions and test against the actual runtime's supported subset.

A schema-valid data-contract envelope can still contain a value schema whose advanced features are unsupported by that runtime. A schema-valid sync acknowledgement can still refer to the wrong operation. A schema-valid gateway assertion can still have a forged signature. Run semantic validation, policy, cryptographic verification and authoritative state checks at their respective boundaries.

Diagnose a rejection without changing the evidence

Keep the exact protocol, schema version and a redacted validation error path. Distinguish an incompatible version from a missing required field, malformed value or forbidden state transition. Do not silently add missing approval flags, replace an unknown network, coerce an atomic amount through a floating-point number or rewrite a receipt merely to make validation pass.

For SDK-generated server objects, inspect the selected schema before exposing them: optional undefined fields disappear from TypeScript JSON, whereas Python objects can serialize optional fields as null. Omit unsupported null optionals deliberately; do not suppress the validator. See the Python acknowledgement example.

Public schema downloads

The generated inventory below lists the exact approved schemas. The schema's $id is an identifier; local validation does not require a live service at that address. See routes and data, server integration and Solana verification for the semantic checks that accompany these shapes.