microsoft/hve-core
Publicmirrored from https://github.com/microsoft/hve-coreAvailable
scripts/linting/schemas/adr-frontmatter.schema.json
312lines · modecode
| 1 | { |
| 2 | "$schema": "http://json-schema.org/draft-07/schema#", |
| 3 | "$id": "https://github.com/microsoft/hve-core/schemas/adr-frontmatter.schema.json", |
| 4 | "title": "ADR Frontmatter Schema", |
| 5 | "description": "Frontmatter schema for Architecture Decision Records authored under docs/planning/adrs/NNNN-{kebab-case}.md. Aligns with MADR v4.0.0 plus the hve-core ADR Planner extensions for ID, lineage, and Architecturally Significant Requirement (ASR) triggers.", |
| 6 | "type": "object", |
| 7 | "required": [ |
| 8 | "id", |
| 9 | "title", |
| 10 | "status", |
| 11 | "proposed_date", |
| 12 | "deciders", |
| 13 | "affected_components" |
| 14 | ], |
| 15 | "additionalProperties": false, |
| 16 | "properties": { |
| 17 | "id": { |
| 18 | "type": "string", |
| 19 | "pattern": "^\\d{4}$", |
| 20 | "description": "Four-digit zero-padded ADR identifier scoped to the owning project_slug (e.g. '0001')." |
| 21 | }, |
| 22 | "title": { |
| 23 | "type": "string", |
| 24 | "minLength": 1, |
| 25 | "description": "Short, decision-focused title." |
| 26 | }, |
| 27 | "description": { |
| 28 | "type": "string", |
| 29 | "minLength": 1, |
| 30 | "description": "One-line summary of the decision used by the docs frontmatter validator and search indexes." |
| 31 | }, |
| 32 | "author": { |
| 33 | "type": "string", |
| 34 | "minLength": 1, |
| 35 | "description": "Optional primary author or owning role for docs metadata." |
| 36 | }, |
| 37 | "ms.date": { |
| 38 | "type": "string", |
| 39 | "pattern": "^\\d{4}-\\d{2}-\\d{2}$", |
| 40 | "description": "Optional YYYY-MM-DD publish date for docs metadata." |
| 41 | }, |
| 42 | "ms.topic": { |
| 43 | "type": "string", |
| 44 | "enum": ["overview", "concept", "tutorial", "reference", "how-to", "troubleshooting"], |
| 45 | "description": "Optional Microsoft docs topic type." |
| 46 | }, |
| 47 | "status": { |
| 48 | "type": "string", |
| 49 | "enum": [ |
| 50 | "proposed", |
| 51 | "accepted", |
| 52 | "rejected", |
| 53 | "deprecated", |
| 54 | "superseded", |
| 55 | "withdrawn" |
| 56 | ], |
| 57 | "description": "Canonical six-value ADR status taxonomy from adr-standards.instructions.md (MADR v4.0.0 plus 'withdrawn' for proposals retired before acceptance or rejection)." |
| 58 | }, |
| 59 | "proposed_date": { |
| 60 | "type": "string", |
| 61 | "format": "date", |
| 62 | "pattern": "^\\d{4}-\\d{2}-\\d{2}$", |
| 63 | "description": "ISO 8601 date (YYYY-MM-DD) the ADR was first proposed. Required for every ADR regardless of status." |
| 64 | }, |
| 65 | "accepted_date": { |
| 66 | "type": [ |
| 67 | "string", |
| 68 | "null" |
| 69 | ], |
| 70 | "format": "date", |
| 71 | "pattern": "^\\d{4}-\\d{2}-\\d{2}$", |
| 72 | "description": "ISO 8601 date (YYYY-MM-DD) the decision was accepted. Required when status='accepted' (enforced by validator). Null until acceptance." |
| 73 | }, |
| 74 | "effort": { |
| 75 | "type": "string", |
| 76 | "enum": [ |
| 77 | "S", |
| 78 | "M", |
| 79 | "L", |
| 80 | "XL" |
| 81 | ], |
| 82 | "description": "T-shirt sizing of implementation effort. S=days, M=weeks, L=quarter, XL=multi-quarter." |
| 83 | }, |
| 84 | "affected_components": { |
| 85 | "type": "array", |
| 86 | "minItems": 1, |
| 87 | "items": { |
| 88 | "type": "string", |
| 89 | "minLength": 1 |
| 90 | }, |
| 91 | "description": "Repository-relative paths, package names, or named components materially changed by this decision. At least one entry required; use ['none'] only for purely informational decisions." |
| 92 | }, |
| 93 | "success_criteria": { |
| 94 | "type": "array", |
| 95 | "items": { |
| 96 | "type": "object", |
| 97 | "required": [ |
| 98 | "metric", |
| 99 | "target", |
| 100 | "measurement_window", |
| 101 | "source" |
| 102 | ], |
| 103 | "additionalProperties": false, |
| 104 | "properties": { |
| 105 | "metric": { |
| 106 | "type": "string", |
| 107 | "minLength": 1, |
| 108 | "description": "Named, observable metric (e.g., 'p95 cold-start latency', 'frontmatter-validation pass rate')." |
| 109 | }, |
| 110 | "target": { |
| 111 | "type": "string", |
| 112 | "minLength": 1, |
| 113 | "description": "Concrete target value or threshold (e.g., '<200ms', '>=99%', 'zero CI failures over 30 days')." |
| 114 | }, |
| 115 | "measurement_window": { |
| 116 | "type": "string", |
| 117 | "minLength": 1, |
| 118 | "description": "Window over which the metric is evaluated (e.g., '30 days post-merge', 'per-PR', 'first production week')." |
| 119 | }, |
| 120 | "source": { |
| 121 | "type": "string", |
| 122 | "minLength": 1, |
| 123 | "description": "Where the metric is read from (e.g., 'logs/pester-summary.json', 'Application Insights', 'GitHub Actions run summary')." |
| 124 | } |
| 125 | } |
| 126 | }, |
| 127 | "description": "Measurable, time-bound criteria for declaring this decision successful. Required (non-empty) when asr_triggers is non-empty (enforced by validator)." |
| 128 | }, |
| 129 | "deciders": { |
| 130 | "type": "array", |
| 131 | "minItems": 1, |
| 132 | "items": { |
| 133 | "type": "string", |
| 134 | "minLength": 1 |
| 135 | }, |
| 136 | "description": "People or roles accountable for the decision." |
| 137 | }, |
| 138 | "consulted": { |
| 139 | "type": "array", |
| 140 | "items": { |
| 141 | "type": "string", |
| 142 | "minLength": 1 |
| 143 | }, |
| 144 | "description": "Subject-matter experts consulted with two-way communication." |
| 145 | }, |
| 146 | "informed": { |
| 147 | "type": "array", |
| 148 | "items": { |
| 149 | "type": "string", |
| 150 | "minLength": 1 |
| 151 | }, |
| 152 | "description": "Stakeholders kept up-to-date with one-way communication." |
| 153 | }, |
| 154 | "tags": { |
| 155 | "type": "array", |
| 156 | "items": { |
| 157 | "type": "string", |
| 158 | "minLength": 1 |
| 159 | }, |
| 160 | "description": "Optional free-form classification tags." |
| 161 | }, |
| 162 | "supersedes": { |
| 163 | "type": [ |
| 164 | "string", |
| 165 | "null" |
| 166 | ], |
| 167 | "pattern": "^\\d{4}$", |
| 168 | "description": "Single-parent supersession (GP-06): the four-digit ID of the prior ADR this decision supersedes within the same project." |
| 169 | }, |
| 170 | "superseded-by": { |
| 171 | "type": [ |
| 172 | "string", |
| 173 | "null" |
| 174 | ], |
| 175 | "pattern": "^\\d{4}$", |
| 176 | "description": "Four-digit ID of the ADR that supersedes this one, when applicable." |
| 177 | }, |
| 178 | "related": { |
| 179 | "type": "array", |
| 180 | "items": { |
| 181 | "type": "object", |
| 182 | "required": [ |
| 183 | "path", |
| 184 | "relation" |
| 185 | ], |
| 186 | "additionalProperties": false, |
| 187 | "properties": { |
| 188 | "path": { |
| 189 | "type": "string", |
| 190 | "minLength": 1, |
| 191 | "description": "Repository-relative path to the related ADR or artifact." |
| 192 | }, |
| 193 | "relation": { |
| 194 | "type": "string", |
| 195 | "enum": [ |
| 196 | "informational", |
| 197 | "influenced-by", |
| 198 | "influences" |
| 199 | ], |
| 200 | "description": "Nature of the relationship." |
| 201 | }, |
| 202 | "note": { |
| 203 | "type": "string", |
| 204 | "maxLength": 280, |
| 205 | "description": "Optional short rationale (<= 280 chars)." |
| 206 | } |
| 207 | } |
| 208 | }, |
| 209 | "description": "Cross-references to other ADRs or supporting artifacts." |
| 210 | }, |
| 211 | "asr_triggers": { |
| 212 | "type": "array", |
| 213 | "items": { |
| 214 | "type": "object", |
| 215 | "required": [ |
| 216 | "kind", |
| 217 | "evidence" |
| 218 | ], |
| 219 | "additionalProperties": false, |
| 220 | "properties": { |
| 221 | "kind": { |
| 222 | "type": "string", |
| 223 | "enum": [ |
| 224 | "cost", |
| 225 | "performance", |
| 226 | "security", |
| 227 | "compliance", |
| 228 | "availability", |
| 229 | "scalability", |
| 230 | "maintainability" |
| 231 | ], |
| 232 | "description": "ASR trigger taxonomy (GP-07, 7-kind enum)." |
| 233 | }, |
| 234 | "evidence": { |
| 235 | "type": "string", |
| 236 | "minLength": 1, |
| 237 | "description": "Required citation, link, or quoted constraint that justifies the trigger." |
| 238 | }, |
| 239 | "note": { |
| 240 | "type": "string", |
| 241 | "maxLength": 280, |
| 242 | "description": "Optional short clarification (<= 280 chars)." |
| 243 | } |
| 244 | } |
| 245 | }, |
| 246 | "description": "Architecturally Significant Requirements that motivated the decision." |
| 247 | }, |
| 248 | "migrated-from": { |
| 249 | "type": "string", |
| 250 | "minLength": 1, |
| 251 | "description": "Provenance: relative path to the source template or prior format the ADR was migrated from." |
| 252 | }, |
| 253 | "migrated-on": { |
| 254 | "type": "string", |
| 255 | "format": "date", |
| 256 | "pattern": "^\\d{4}-\\d{2}-\\d{2}$", |
| 257 | "description": "Provenance: ISO 8601 date the migration completed." |
| 258 | }, |
| 259 | "migrated-by": { |
| 260 | "type": "string", |
| 261 | "minLength": 1, |
| 262 | "description": "Provenance: tool or person responsible for the migration." |
| 263 | }, |
| 264 | "original-id": { |
| 265 | "type": "string", |
| 266 | "minLength": 1, |
| 267 | "description": "Provenance: identifier used in the prior system before migration." |
| 268 | }, |
| 269 | "decisionMetadata": { |
| 270 | "type": "object", |
| 271 | "additionalProperties": false, |
| 272 | "properties": { |
| 273 | "driverToTriggerMap": { |
| 274 | "type": "object", |
| 275 | "patternProperties": { |
| 276 | "^.+$": { |
| 277 | "type": "string", |
| 278 | "minLength": 1 |
| 279 | } |
| 280 | }, |
| 281 | "additionalProperties": false, |
| 282 | "description": "Map from Decision Driver labels (free-text strings matching the driver bullets in the body) to ASR trigger references; populated by the ADR Planner at Decide exit and enforced by Validate-AdrConsistency rule ADR-CONSISTENCY-008 (driver-trigger-map-complete). Map keys are substring-matched against driver bullet text after normalization, so they may be short labels or full sentences as long as each driver has at least one corresponding key." |
| 283 | } |
| 284 | }, |
| 285 | "description": "Optional planner-internal metadata serialized into ADR frontmatter. Mirrors `state.json.decisionMetadata` from the ADR Planner; not authored by hand." |
| 286 | } |
| 287 | }, |
| 288 | "allOf": [ |
| 289 | { |
| 290 | "if": { |
| 291 | "properties": { |
| 292 | "status": { |
| 293 | "const": "accepted" |
| 294 | } |
| 295 | }, |
| 296 | "required": [ |
| 297 | "status" |
| 298 | ] |
| 299 | }, |
| 300 | "then": { |
| 301 | "required": [ |
| 302 | "accepted_date" |
| 303 | ], |
| 304 | "properties": { |
| 305 | "accepted_date": { |
| 306 | "type": "string" |
| 307 | } |
| 308 | } |
| 309 | } |
| 310 | } |
| 311 | ] |
| 312 | } |