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:

Usage

Validate with ajv (Node.js)

npm install -g ajv-cli

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

Validate with check-jsonschema (Python)

pip install check-jsonschema

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

Validate with yq + ajv

If your toolchain works with JSON, convert the YAML first:

# Convert YAML to JSON, then validate
yq -o json policy.yaml | ajv validate -s schemas/hushspec-core.v0.schema.json -d /dev/stdin

Lint with yamllint

For YAML syntax and style checking before schema validation:

pip install yamllint

# Check YAML syntax and style
yamllint policy.yaml

# Then validate against schema
check-jsonschema --schemafile schemas/hushspec-core.v0.schema.json policy.yaml

Validate with h2h CLI

The HushSpec CLI layers schema validation, version checks, and regex safety checks on top of raw document parsing:

# Validate a policy document
h2h validate policy.yaml

# Also verify that extends references resolve
h2h validate --strict policy.yaml

# Emit machine-readable results
h2h validate --format json policy.yaml

Editor Integration

Inline Schema Directive

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

# yaml-language-server: $schema=https://raw.githubusercontent.com/backbay-labs/hush/main/schemas/hushspec-core.v0.schema.json
hushspec: "0.1.0"
name: "my-policy"

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

VS Code (YAML Extension)

Install the Red Hat YAML extension, then add schema associations to your .vscode/settings.json:

{
  "yaml.schemas": {
    "https://raw.githubusercontent.com/backbay-labs/hush/main/schemas/hushspec-core.v0.schema.json": [
      "*.hushspec.yaml",
      "*.hushspec.yml",
      "hushspec.yaml",
      "hushspec.yml"
    ],
    "https://raw.githubusercontent.com/backbay-labs/hush/main/schemas/hushspec-evaluator-test.v0.schema.json": [
      "*.test.yaml"
    ]
  }
}

This gives you autocompletion, hover documentation, and inline validation for all HushSpec policy files in the workspace.

IntelliJ / WebStorm

IntelliJ-based IDEs support JSON Schema mapping natively:

1. Open Settings > Languages & Frameworks > Schemas and DTDs > JSON Schema Mappings
2. Click + to add a new mapping
3. Set the schema URL to https://raw.githubusercontent.com/backbay-labs/hush/main/schemas/hushspec-core.v0.schema.json
4. Add file path patterns: *.hushspec.yaml, *.hushspec.yml
5. Click OK to apply

IntelliJ will provide autocompletion, validation, and navigation for matched files.

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.

Extension schemas are designed to be composed with the core schema. The core schema's extensions object accepts the known extension keys (posture, origins, detection); each extension key references its own schema.

The receipt and signature schemas define output formats produced by evaluators and signing tools, not input document formats. The evaluator test schema defines the conformance fixture format used for Level 3 testing.