microsoft / microsoft/hve-core

Evaluate YAML-canonical schema source for ADR consistency linter

Open
#1,697 0 comments 1 reaction 1 assignee Claimed by @WilliamBerryiii View on GitHub
infrastructure maintenance
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.