JSON Schema

The Seal specification ships an official JSON Schema as an informative companion to seal.json. It is intended for:

• Editor integrations (autocomplete, hover, inline validation in VS Code, JetBrains, etc.).
• CI tooling that wants a quick structural check before invoking seal verify.
• Bundle authors and reviewers who want a typed view of the lockfile structure.

The prose spec is the source of truth

A lockfile that fails the JSON Schema is invalid. But passing the schema is necessary, not sufficient. Conforming implementations MUST enforce normative requirements from SPEC.md that cannot be fully expressed in JSON Schema, including:

• Path normalisation (NFC, no .., no repeated separators, leading ./ rules).
• Duplicate bundle keys after normalisation.
• Recomputing contentHash from the recorded files map and comparing.
• Bundle‑key derivation and the no‑nested‑bundle‑keys rule.
• The deterministic serialization order.
• The case‑sensitive, true‑case path resolution requirement.

These must be enforced by conforming Seal implementations rather than by schema alone. The schema is one layer of defence; the spec is the law.

Source

The schema lives at seal.schema.json in the spec repository. Its $schema declares JSON Schema draft 2020‑12.

Top‑level structure

The snippets below show the shape of the official schema. Use the linked seal.schema.json file for the exact schema text, including descriptions and comments.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "additionalProperties": false,
  "required": ["version", "policy", "bundles"],
  "properties": {
    "version": { "const": 1 },
    "policy":  { "$ref": "#/$defs/enforcementMode" },
    "discovery": {
      "type": "array",
      "items": { "$ref": "#/$defs/discoveryPattern" }
    },
    "bundles": {
      "type": "object",
      "propertyNames": { "$ref": "#/$defs/bundleKey" },
      "additionalProperties": { "$ref": "#/$defs/bundleEntry" }
    }
  }
}

Key definitions:

"$defs": {
  "sha256":           { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
  "enforcementMode":  { "type": "string", "enum": ["block", "warn"] },
  "bundleKey":        { "type": "string", "pattern": "^\\./(?!\\.\\.?($|/))[^/\\\\\\r\\n]+(?:/(?!\\.\\.?($|/))[^/\\\\\\r\\n]+)*$" },
  "discoveryPattern": { "type": "string", "pattern": "^(?!\\./)(?!/)(?!.*\\*\\*)(?!.*\\\\)(?!.*(?:^|/)\\.{1,2}(?:/|$))(?!.*//)(?!.*/$).+$" },
  "sealedRootRelativePath": { "type": "string", "pattern": "^(?:\\.|(?!\\./)(?!/)(?!.*//)(?!.*(?:^|/)\\.{1,2}(?:/|$))(?!.*\\\\)(?!.*/$).+)$" },
  "bundleEntry": {
    "type": "object",
    "additionalProperties": false,
    "required": ["contentHash", "files"],
    "properties": {
      "revision":    { "type": "string", "minLength": 1 },
      "contentHash": { "$ref": "#/$defs/sha256" },
      "files": {
        "type": "object",
        "minProperties": 1,
        "propertyNames": { "$ref": "#/$defs/sealedRootRelativePath" },
        "additionalProperties": { "$ref": "#/$defs/sha256" }
      }
    }
  }
}

Editor integration

VS Code

Add to your project’s .vscode/settings.json:

{
  "json.schemas": [
    {
      "fileMatch": ["seal.json"],
      "url": "https://raw.githubusercontent.com/SamyGhannad/seal-spec/main/seal.schema.json"
    }
  ]
}

This gives autocomplete on policy, inline error messages for malformed hashes, and warnings if you forget a required field.

JetBrains IDEs

Preferences → Languages & Frameworks → Schemas and DTDs → JSON Schema Mappings, then add:

• Name: Seal lockfile
• Schema file or URL: https://raw.githubusercontent.com/SamyGhannad/seal-spec/main/seal.schema.json
• File path pattern: seal.json

Schema reference in seal.json

A pragmatic alternative: reference the schema directly from seal.json. Some editors honour $schema on the root object. Note: per SPEC, additional top‑level fields are not permitted in the lockfile. Adding $schema to your committed seal.json would make it invalid. Use the editor‑side configuration above instead.

What the schema does NOT catch

Examples of conformance violations a JSON Schema cannot validate, which Seal implementations must enforce directly:

• A bundle’s contentHash not matching the cryptographic aggregate of its files.
• Two bundle keys that are byte‑different but normalise (NFC) to the same value.
• A bundle key being a subdirectory of another bundle key (no nested keys allowed).
• A recorded bundle key not being statically produced by any discovery pattern.
• Two discovery patterns being valid individually but expressing incompatible nested boundaries, such as skills with skills/*, or skills/* with skills/foo/*.
• Out‑of‑order top‑level or bundle‑entry keys (the serialisation rule is byte‑level).
• Missing trailing newline, CRLF line endings, or tabs instead of spaces.

For the standalone CLI, run seal verify as the project gate. Native integrations should enforce the same prose rules before loading bundles.

Why ship a schema at all

The schema is the cheapest way to give bundle authors and reviewers immediate feedback on structural errors (missing fields, wrong types, malformed hashes). It catches “I forgot a comma” before CI does. It does not replace seal verify (or an agent’s conforming verification step). It complements them.

If you are integrating Seal into tooling, treat the schema as a fast pre‑check and seal verify (or your native equivalent) as the conformance gate.