JSON Schema#

HushSpec provides JSON Schema files for document validation. These schemas are the machine-readable counterpart to the prose specification and can be used with any JSON Schema validator.

Available Schemas#

The schemas are in the schemas/ directory:

The complete generated inventory below includes the frozen schemas too. Every schema is also embedded in the h2h binary; h2h schema --list prints the names and h2h schema <name> prints one to stdout.

Schema lineage#

The *-experimental.v1.schema.json companion artifacts declare their own 0.1.0 contract version. Their filename lineage does not make them stable or change the existing policy, receipt, log, report or conformance-report formats.

Document-format schemas are named per major version (spec/versioning.md section 9). The .v1. files above are the current lineage: the schemas HushSpec 1.0.0 published, referenced by every SDK, the CLI, the testkit, and the fixture modelines. The .v0. files describe the 0.x line and are frozen: each carries a $comment saying so, schemas/frozen-v0.json records their sha256: digests, and a test in the reference implementation fails when one of them changes. A document that declares a 0.x hushspec version validates against its .v0. schema; a document declaring 1.0.z validates against .v1..

hushspec-core.v1.schema.json differs from hushspec-core.v0.schema.json in two keywords: hushspec matches ^(0|1)\.\d+\.\d+$, and name carries minLength: 1. The receipt, log-entry, and report schemas widen their spec_version patterns the same way, so a receipt for a 1.0.z policy validates. Those four are the only validation differences between the lineages: every other .v1. file constrains exactly what its .v0. predecessor constrained.

The .v1. files also carry their own identity, which never affects validation. Each has a v1 $id and no frozen $comment, a title naming the lineage it belongs to (a title ending in a minor -- HushSpec Decision Receipt v0.2, HushSpec Log Entry v0.1 -- names a wire format version, which 1.0.0 did not change), and prose that points at .v1. companions: hushspec-bundle.v1 sends a verifier to hushspec-core.v1 for the canonical projection, and hushspec-log-entry.v1 to hushspec-receipt.v1 for an entry's receipt. The .v0. file of each pair still points at the .v0. companion, which is what a 0.x document needs.

The registry schemas (hushspec-registry-*.v0.schema.json) describe the files under spec/registries/ rather than documents and keep the .v0. name.

h2h schema <name> prints the current lineage by bare name (h2h schema core); the frozen file is addressed as core.v0. h2h schema --list names both.

Where the schemas are served#

Each v1 schema declares its own $id under the project's owned domain:

https://hushspec.org/schemas/<file>

The Vercel website serves a static snapshot exported from a clean source commit using python3 scripts/build_schema_index.py --site-root ../hush-ui/public. Its build checks every indexed byte digest. Alongside the schemas it publishes:

• https://hushspec.org/schemas/index.json -- one entry per schema, carrying its file name, $id, retrieval url, SHA-256, title and description, with the source commit. The index also lists registry URLs and byte digests.
• https://hushspec.org/registries/<file> -- every registry under spec/registries/, published so the normative lists are readable at a stable URL. Nothing resolves these over the network: the schemas above pin the registries by shape, and the SDKs embed them.

Frozen v0 schemas keep their historical hushspec.dev identifiers byte for byte. The project does not operate that host: use the .org mirror's retrieval url for legacy schemas, without rewriting their IDs. Bundle predicate URIs are identifiers, not schema download URLs, and remain unchanged.

The mdBook deployment includes schema and registry copies as a documentation mirror. For an exact release revision, fetch a schema from GitHub:

https://raw.githubusercontent.com/backbay-labs/hush/v1.0.0/schemas/hushspec-core.v1.schema.json

The canonical host serves its indexed source commit. The release URL pins the same release lineage. Index hashes check byte consistency; they do not independently authenticate the website.

Usage#

Validate with ajv (Node.js)#

npm install -g ajv-cli

ajv validate -s schemas/hushspec-core.v1.schema.json -d policy.yaml

Validate with check-jsonschema (Python)#

pip install check-jsonschema

check-jsonschema --schemafile schemas/hushspec-core.v1.schema.json policy.yaml

Editor Integration#

Add a $schema comment to your HushSpec YAML files for editor autocompletion and validation:

# yaml-language-server: $schema=https://hushspec.org/schemas/hushspec-core.v1.schema.json
hushspec: "1.0.0"
name: "my-policy"

rules:
  forbidden_paths:
    patterns:
      - "**/.ssh/**"

See Where the schemas are served for pinned GitHub retrieval URLs and the distinction between identity and retrieval.

Most YAML-aware editors (VS Code with the YAML extension, IntelliJ, etc.) will pick up the schema directive and provide autocompletion, hover documentation, and inline validation. See the Editor Setup guide for the SchemaStore zero-configuration option and workspace-settings alternative.

Schema Structure#

The core schema uses additionalProperties: false at every level, enforcing the fail-closed principle. Any field not defined in the specification will cause validation failure.

That holds inside extensions too. The core schema is a compound schema document: extensions.posture, extensions.origins and extensions.detection each $ref their companion schema by that schema's own $id, and the three companion documents are carried verbatim in the core schema's $defs. So a validator resolves the whole composition from the one file, with no network access, and an unknown key inside an extension block is a rejection rather than an annotation (core spec 2.1 and 9.5). Each reference also carries unevaluatedProperties: false, which keeps the block closed even if a companion schema's root ever stops setting additionalProperties: false.

The embedded copies are byte-for-byte the published companion files; the test suites compare them, so a companion schema and the copy inside the core schema cannot drift apart.

CLI and Editor Checks#

h2h validate --strict policy.yaml applies parsing and semantic validation; a YAML linter alone cannot establish either. A JSON Schema validator checks structure after YAML decoding, and therefore cannot recover duplicate keys or anchors that a permissive decoder already erased. Prefer the SDK or CLI parser.

VS Code's YAML extension accepts the inline directive # yaml-language-server: $schema=https://hushspec.org/schemas/hushspec-core.v1.schema.json. JetBrains editors can associate that URL with policy filenames in JSON Schema Mappings. For yq/Ajv pipelines, choose a YAML 1.2 decoder, retain parse-profile validation, and use the strict CLI gate before deployment. See editor setup.

Complete Published Schema Inventory#

Generated from release schema identities. Frozen v0 IDs retain hushspec.dev; retrieval mirrors are served on hushspec.org. The JSON index carries every byte digest.