deepschema

DeepSchema

DeepSchemas define rich schemas for files in your project. They provide:

• Automatic write-time validation — when you write or edit a file, applicable schemas are checked immediately and errors are reported inline
• Review generation — schemas automatically generate review rules that run during /review and workflow quality gates
• RFC 2119 requirements — requirements use MUST/SHOULD/MAY keywords to control enforcement severity

Two Types of DeepSchemas

Named Schemas

Named schemas live in .deepwork/schemas/<name>/ and match files via glob patterns. Use these for file types that appear throughout your project.

.deepwork/schemas/api_endpoint/
  deepschema.yml          # Manifest with requirements, matchers, etc.
  endpoint.schema.json    # Optional JSON Schema for structural validation
  examples/               # Optional example files
  references/             # Optional reference docs

Anonymous Schemas

Anonymous schemas are single files placed alongside the file they apply to. Use these for one-off requirements on a specific file.

src/config.yml                    # The file
.deepschema.config.yml.yml        # Its anonymous schema

The naming convention is .deepschema.<filename>.yml.

Creating a Named Schema

1. Create the directory: .deepwork/schemas/<name>/
2. Create deepschema.yml inside it:

summary: Short description of this file type
instructions: |
  Guidelines for creating and modifying files of this type.

matchers:
  - "**/*.config.yml"
  - "src/configs/**/*.json"

requirements:
  # Semantic rules only — structural constraints go in config.schema.json
  documented-fields: "All fields SHOULD have inline comments explaining their purpose."
  no-secrets: "Config files MUST NOT contain secrets or credentials."

# Structural validation — enforce types, required fields, enums, etc. here
json_schema_path: "config.schema.json"

# Optional: custom validation commands (file path passed as $1)
verification_bash_command:
  - "yamllint -d relaxed"

3. Call get_named_schemas to verify your schema is discovered.

Creating an Anonymous Schema

Place a .deepschema.<filename>.yml file next to the target file:

requirements:
  api-key-rotated: "The API key MUST be rotated every 90 days."
  no-plaintext-secrets: "Credentials MUST use environment variable references, not literal values."

# Reference a named schema for shared requirements
parent_deep_schemas:
  - api_endpoint

JSON Schema First: Maximize Structural Validation

The json_schema_path file is the primary enforcement mechanism. Every constraint that can be expressed structurally MUST go in the JSON Schema, not in requirements. Requirements exist only for semantic rules that JSON Schema cannot express.

Put in the JSON Schema (not requirements):

• File format validity (valid JSON, valid YAML)
• Field types (string, number, boolean, array, object)
• Required fields
• Allowed property names (additionalProperties: false)
• Enum values and allowed constants
• Array item types and constraints (minItems, uniqueItems)
• Numeric ranges (minimum, maximum)
• String patterns (pattern, format)
• Conditional field presence (if/then — e.g., "when type is 'http', url is required")
• Nested object shapes and their constraints

Put in requirements (not the JSON Schema):

• Semantic rules about meaning ("secrets MUST NOT appear in shared settings")
• Cross-file concerns ("this field MUST reference an existing named schema")
• Behavioral gotchas ("sandbox paths use different prefix semantics than permission paths")
• Design guidance ("deny rules SHOULD be used for hard security boundaries, not soft preferences")
• Anything requiring judgment or context a machine validator cannot assess

Build the JSON Schema to be as strict and comprehensive as possible. Use additionalProperties: false to catch typos. Use enums for closed sets. Use if/then for conditional requirements. Use pattern for string formats. Use $defs and $ref for reusable types. Use anyOf for discriminated unions. Use uniqueItems, minLength, minItems where appropriate. A good JSON Schema catches errors at write time before a reviewer ever sees the file. Requirements that duplicate what the schema already enforces are noise — they dilute the reviewer's attention and risk contradicting the schema.

Verification Commands for Non-JSON Files

For files that aren't JSON or YAML (markdown, shell scripts, plain text, custom formats), verification_bash_command serves the same role as json_schema_path — it's the primary structural enforcement mechanism. The same principle applies: anything a command can check exactly MUST go in a verification command, not in requirements.

# Example: RFC 2119 requirements files (markdown)
verification_bash_command:
  - "grep -nE '^[0-9]+\\.' \"$1\" | grep -vE 'MUST|SHALL|SHOULD|MAY|REQUIRED|RECOMMENDED|OPTIONAL' | { if read -r line; then echo \"FAIL: Requirement without RFC 2119 keyword: $line\"; exit 1; fi; }"

requirements:
  # Only semantic rules the command can't check
  testability: "Each requirement MUST be specific enough to be verifiable."

Commands receive the file path as $1, must exit 0 on success and non-zero on failure, and have a 30-second timeout.

Check SchemaStore for Existing Schemas

Before writing a JSON Schema from scratch, check whether a published schema already exists at SchemaStore (https://json.schemastore.org/<name>.json). SchemaStore hosts community-maintained schemas for hundreds of config file formats.

If a good schema exists:

1. Vendor a local copy into your schema directory (e.g., claude_settings.schema.json)
2. Add a _source field at the top of the file with the original URL and sync date:

   {
     "_source": "Vendored from https://json.schemastore.org/example.json. To update: fetch the latest version from that URL and replace this file. Last synced: 2026-04-01."
   }
   

3. Point json_schema_path at the local copy — this avoids network dependencies during validation
4. Periodically re-fetch the upstream schema to pick up improvements — the _source field tells future maintainers where to look

Schema Fields Reference

Field	Description
summary	Brief description for discoverability
instructions	Guidelines for working with these files
matchers	Glob patterns this schema applies to (named schemas)
requirements	Key-value pairs of RFC 2119 requirements
parent_deep_schemas	Named schemas to inherit requirements from
json_schema_path	Relative path to a JSON Schema file
verification_bash_command	Shell commands to validate the file (receives path as $1)
examples	Array of {path, description} for example files
references	Array of {path, description} or {url, description} for reference docs

How Validation Works

When you write or edit a file:

1. DeepWork finds all applicable schemas (named schemas with matching globs + any anonymous schema for the file)
2. A conformance note is injected listing applicable schemas
3. json_schema_path validation runs automatically
4. verification_bash_command commands run with the file path as $1
5. Failures are reported as errors the agent must fix

During /review and workflow quality gates, each schema generates a review rule that checks all requirements.

Discovery Sources

Named schemas are loaded from multiple directories in priority order (first match wins):

1. .deepwork/schemas/ — project-local schemas
2. DeepWork built-in standard schemas (e.g., job_yml, deepschema)
3. DEEPWORK_ADDITIONAL_SCHEMAS_FOLDERS env var — colon-delimited extra directories

MCP Tools

• get_named_schemas — list all discovered named schemas with their names, summaries, and matchers