[DX] JSON Schema for declarative policy files with editor validation

[dgenio]

Summary

Publish a JSON Schema describing the declarative policy file format (YAML/TOML) so editors validate and autocomplete policy files as users type, and CI can lint policy files without loading the Python engine.

Why this matters

Policy files are the main artifact users author by hand, and today the first feedback on a typo (decison: deny, wrong nesting, unknown safety class) arrives at runtime as a PolicyConfigError. A schema moves that feedback into the editor — red squiggles and field completion in VS Code/JetBrains via the YAML language server — which is a disproportionate quality-of-life win for a config-driven feature.

Proposed scope

• schemas/policy.schema.json (JSON Schema draft 2020-12) covering the full DSL: rule fields, match conditions (capability, namespace, safety class, sensitivity, roles, intent, scope), decisions, and reason metadata.
• Enums in the schema sourced from the real ones (SafetyClass, SensitivityTag, decision kinds) — with a test asserting schema enums equal code enums, so they cannot drift.
• A test validating every policy file in the repo (examples/policies/**) against the schema.
• Usage docs: one-line # yaml-language-server: $schema=... header convention + editor setup note in the policy docs.
• Submit to SchemaStore (follow-up checkbox) so association is automatic for files named e.g. weaver-policy.yaml.

Implementation notes

• Source of truth is policy_dsl_parser.py — write the schema to match the parser, and where the parser is more permissive than intended, note it rather than silently encoding looseness.
• Validation test can use jsonschema as a dev-only dependency (justify in PR per the minimal-deps rule; it does not enter runtime deps).
• TOML files validate by loading to dict first (tomllib) then applying the same schema.

Acceptance criteria

• Schema validates all in-repo policy files; an intentionally broken fixture fails with a useful message.
• Enum-drift test ties schema values to enums.py / decision kinds.
• Docs show editor wiring (yaml-language-server header) in under five lines.
• Dev-only dependency; runtime install unchanged.

Out of scope

• Changing the DSL itself.
• A Python-side validation API beyond what DeclarativePolicyEngine already does.
• SchemaStore submission (tracked as a follow-up task in this issue, done after the schema stabilizes).

References

• JSON Schema + yaml-language-server editor integration pattern (standard across GitHub Actions, Compose, etc.).
• In-repo: policy_dsl_parser.py, examples/policies/, enums.py.

---

Priority: P3 · Effort: S · Impact: Medium