microsoft / microsoft/hve-core
Evaluate YAML-canonical schema source for ADR consistency linter
- Dominant language
- Python
- Stars
- 1.5k
- Forks
- 301
- Avg merge
- 3d 3h
- Merged PRs (30d)
- 92
Description
## Context
The ADR consistency linter (`scripts/linting/Validate-AdrConsistency.ps1`, added in #1552) uses JSON Schema (Draft-07) files for validating ADR frontmatter, the rule registry, and `.adr-config.yml`. JSON was chosen because PowerShell''s built-in `Test-Json` cmdlet supports JSON Schema validation natively, while `PowerShell-Yaml` (0.4.7) only handles serialization.
The tradeoff: JSON is less token-efficient than YAML when the schemas are themselves consumed by AI models (e.g., during ADR drafting or review).
## Design options
Two approaches were raised in #1552 (see [this thread](https://github.com/microsoft/hve-core/pull/1552#discussion_r3305922699)):
1. **YAML-canonical, JSON-generated** — Maintain canonical schemas as YAML, generate JSON files as build artifacts for `Test-Json` to consume. Pros: token-efficient for models, no new validation dependency. Cons: introduces a build step; two files per schema (one tracked, one generated).
2. **YAML validation wrapper** — Either add a YAML-schema validation dependency or wrap `ConvertFrom-Yaml | ConvertTo-Json` before every `Test-Json` call. Pros: single source of truth. Cons: new dependency or runtime overhead on every validation call.
## Acceptance criteria
- [ ] Decision recorded (ADR or design note) covering: canonical format, validation mechanism, generation/build step (if any), dependency footprint.
- [ ] If option 1: build script generates JSON from YAML, wired into `npm run` and pre-commit/CI, with `.gitignore` or regeneration semantics for the JSON artifacts.
- [ ] If option 2: dependency vetted (license, maintenance, supply chain) or wrapper implemented with tests covering the round-trip.
- [ ] `scripts/linting/schemas/*.schema.json` (and any new YAML siblings) updated accordingly.
- [ ] `scripts/linting/Validate-AdrConsistency.ps1` and module tests still pass with the chosen approach.
- [ ] Schema-mapping (`scripts/linting/schemas/schema-mapping.json`) and `.vscode/settings.json` bindings reflect the canonical format.
## References
- Source PR: #1552
- Reviewer comment: https://github.com/microsoft/hve-core/pull/1552#discussion_r3305922699
Contributor guide
Assessment
This issue has not been assessed yet.