Schema validation

The Envelope schema is published at https://schema.openenvelope.org/team/v1.json (Apache 2.0). Any .envelope.json file — whether exported from the workspace or hand-edited — can be validated against it using standard JSON Schema tooling.

VS Code setup

Add this to your workspace .vscode/settings.json:

{
  "json.schemas": [
    {
      "fileMatch": ["*.envelope.json"],
      "url": "https://schema.openenvelope.org/team/v1.json"
    }
  ]
}

VS Code will show inline errors, autocomplete field names, and hover documentation as you edit any .envelope.json file. No extension install required.

CLI validation

Install the Envelope schema package:

npm install -D @openenvelope/schema

Then validate any file:

npx @openenvelope/schema validate path/to/my-team.envelope.json

Exit code 0 means valid. Non-zero exit with error output means the file has schema violations. Use this in pre-commit hooks or local CI.

GitHub Actions

Add a validation step to your workflow:

- name: Validate Envelope specs
  run: |
    npm install -D @openenvelope/schema
    npx @openenvelope/schema validate **/*.envelope.json

This catches structural errors — missing required fields, invalid field types, unknown adapter keys — before they reach a runtime.

Common validation errors

agentKey contains invalid characters — agent keys must be lowercase alphanumeric with hyphens only. Support Triage → support-triage.

adapter is not a recognised value — the schema enumerates valid adapter strings. Check the schema reference for the current list.

requiredSecrets entries must be strings — each entry is a plain string name, not an object. Use ["OPENAI_KEY", "SENDGRID_KEY"], not [{ name: "OPENAI_KEY" }].

reportingLine references unknown agent — the reportsTo value must match an agentKey defined elsewhere in the same team definition.

File passes validation but runtime rejects it — runtime-specific fields (model overrides, credential bindings) are not part of the published schema. The schema validates the portable spec; runtime config is separate.

→ Full schema reference — every field, type, and constraint
→ Storing specs in Git — how to commit and version-control your team definitions