buyer_request_match.response.schema.json (12447B)
1 { 2 "$schema": "https://json-schema.org/draft/2020-12/schema", 3 "$id": "hyf_ops_v2/buyer_request_match.response.schema.json", 4 "title": "hyf_ops_v2 buyer_request.match strict response (ADR-0025 D45 CB01-CB04, ADR-0026 D46 CR01-CR02)", 5 "$comment": "Exact pre-activation wire algebra: ok:true requires output and forbids error; ok:false requires error and forbids output and meta. Assessments and bounded single-supplier plans are suggestions, never reservations. Allocated quantities use the D23 reported projection and carry the lot revision. Envelope version stays 1. output.versions echoes the requested seven axes; execution.model is the actual model use.", 6 "type": "object", 7 "properties": { 8 "version": { 9 "type": "integer", 10 "const": 1 11 }, 12 "request_id": { 13 "type": "string" 14 }, 15 "trace_id": { 16 "type": "string", 17 "minLength": 1 18 }, 19 "ok": { 20 "type": "boolean" 21 }, 22 "output": { 23 "$ref": "#/$defs/match_output" 24 }, 25 "error": { 26 "$ref": "#/$defs/wire_error" 27 }, 28 "meta": { 29 "type": "object", 30 "additionalProperties": true 31 } 32 }, 33 "required": ["version", "request_id", "ok"], 34 "additionalProperties": false, 35 "allOf": [ 36 { 37 "if": { 38 "properties": {"ok": {"const": true}}, 39 "required": ["ok"] 40 }, 41 "then": { 42 "required": ["output"], 43 "properties": {"request_id": {"type": "string", "minLength": 1}}, 44 "not": {"required": ["error"]} 45 } 46 }, 47 { 48 "if": { 49 "properties": {"ok": {"const": false}}, 50 "required": ["ok"] 51 }, 52 "then": { 53 "required": ["error"], 54 "not": {"anyOf": [{"required": ["output"]}, {"required": ["meta"]}]} 55 } 56 } 57 ], 58 "$defs": { 59 "wire_error": { 60 "type": "object", 61 "properties": { 62 "code": { 63 "type": "string", 64 "enum": [ 65 "invalid_request", 66 "unsupported_capability", 67 "capability_disabled", 68 "capability_unavailable", 69 "internal_error" 70 ] 71 }, 72 "message": {"type": "string"} 73 }, 74 "required": ["code", "message"], 75 "additionalProperties": false 76 }, 77 "output_versions": { 78 "type": "object", 79 "properties": { 80 "schema": {"type": "string", "const": "hyf_ops_v2"}, 81 "taxonomy": {"type": "string", "minLength": 1}, 82 "normalization": {"type": "string", "minLength": 1}, 83 "review_policy": {"type": "string", "minLength": 1}, 84 "ranking_policy": {"type": "string", "minLength": 1}, 85 "question_bundle": {"type": "string", "minLength": 1}, 86 "model": {"type": "string", "minLength": 1} 87 }, 88 "required": [ 89 "schema", 90 "taxonomy", 91 "normalization", 92 "review_policy", 93 "ranking_policy", 94 "question_bundle", 95 "model" 96 ], 97 "additionalProperties": false 98 }, 99 "evidence_span": { 100 "type": "object", 101 "properties": { 102 "kind": {"type": "string", "const": "span"}, 103 "source_id": {"type": "string", "minLength": 1}, 104 "revision": {"type": "string", "minLength": 1}, 105 "start": {"type": "integer", "minimum": 0}, 106 "end": {"type": "integer", "minimum": 0}, 107 "method": {"type": "string", "minLength": 1} 108 }, 109 "required": ["kind", "source_id", "revision", "start", "end", "method"], 110 "additionalProperties": false 111 }, 112 "record_field_evidence": { 113 "type": "object", 114 "properties": { 115 "kind": {"type": "string", "const": "record_field"}, 116 "source_id": {"type": "string", "minLength": 1}, 117 "revision": {"type": "string", "minLength": 1}, 118 "record_id": {"type": "string", "minLength": 1}, 119 "field": {"type": "string", "minLength": 1}, 120 "method": {"type": "string", "const": "trusted_record"} 121 }, 122 "required": [ 123 "kind", 124 "source_id", 125 "revision", 126 "record_id", 127 "field", 128 "method" 129 ], 130 "additionalProperties": false 131 }, 132 "evidence_ref": { 133 "oneOf": [ 134 {"$ref": "#/$defs/evidence_span"}, 135 {"$ref": "#/$defs/record_field_evidence"} 136 ] 137 }, 138 "reported_quantity": { 139 "type": "object", 140 "properties": { 141 "state": {"type": "string", "enum": ["known", "unknown"]}, 142 "value": { 143 "type": ["string", "null"], 144 "pattern": "^-?(0|[1-9][0-9]*)(\\.[0-9]{1,9})?$" 145 }, 146 "unit": {"type": ["string", "null"], "minLength": 1}, 147 "qualifier": {"type": "string", "enum": ["exact", "approximate"]} 148 }, 149 "required": ["state", "qualifier"], 150 "additionalProperties": false, 151 "allOf": [ 152 { 153 "if": { 154 "properties": {"state": {"const": "unknown"}}, 155 "required": ["state"] 156 }, 157 "then": { 158 "properties": {"value": {"type": "null"}, "unit": {"type": "null"}} 159 } 160 }, 161 { 162 "if": { 163 "properties": {"state": {"const": "known"}}, 164 "required": ["state"] 165 }, 166 "then": { 167 "properties": { 168 "value": { 169 "type": "string", 170 "pattern": "^-?(0|[1-9][0-9]*)(\\.[0-9]{1,9})?$" 171 }, 172 "unit": {"type": "string", "minLength": 1} 173 }, 174 "required": ["value", "unit"] 175 } 176 } 177 ] 178 }, 179 "check": { 180 "type": "object", 181 "properties": { 182 "kind": {"type": "string", "minLength": 1}, 183 "result": {"type": "string", "enum": ["pass", "fail", "unknown"]}, 184 "reason": {"type": "string", "minLength": 1}, 185 "evidence": { 186 "type": "array", 187 "items": {"$ref": "#/$defs/evidence_ref"} 188 } 189 }, 190 "required": ["kind", "result", "reason"], 191 "additionalProperties": false 192 }, 193 "assessment": { 194 "type": "object", 195 "properties": { 196 "candidate_id": {"type": "string", "minLength": 1}, 197 "eligibility": { 198 "type": "string", 199 "enum": ["eligible", "conditional", "ineligible"] 200 }, 201 "checks": { 202 "type": "array", 203 "items": {"$ref": "#/$defs/check"} 204 } 205 }, 206 "required": ["candidate_id", "eligibility", "checks"], 207 "additionalProperties": false 208 }, 209 "allocation": { 210 "type": "object", 211 "properties": { 212 "lot_id": {"type": "string", "minLength": 1}, 213 "revision": {"type": "string", "minLength": 1}, 214 "line_id": {"type": "string", "minLength": 1}, 215 "quantity": {"$ref": "#/$defs/reported_quantity"} 216 }, 217 "required": ["lot_id", "revision", "line_id", "quantity"], 218 "additionalProperties": false 219 }, 220 "plan": { 221 "type": "object", 222 "properties": { 223 "plan_id": {"type": "string", "minLength": 1}, 224 "supplier_id": {"type": "string", "minLength": 1}, 225 "allocations": { 226 "type": "array", 227 "items": {"$ref": "#/$defs/allocation"} 228 }, 229 "coverage": { 230 "type": "object", 231 "properties": { 232 "lines_covered": { 233 "type": "array", 234 "items": {"type": "string", "minLength": 1} 235 }, 236 "uncovered": { 237 "type": "array", 238 "items": {"type": "string", "minLength": 1} 239 }, 240 "partial": {"type": "boolean"} 241 }, 242 "required": ["lines_covered", "uncovered", "partial"], 243 "additionalProperties": false 244 }, 245 "unresolved": { 246 "type": "array", 247 "items": { 248 "type": "object", 249 "properties": { 250 "kind": {"type": "string", "minLength": 1}, 251 "reason": {"type": "string", "minLength": 1} 252 }, 253 "required": ["kind", "reason"], 254 "additionalProperties": false 255 } 256 }, 257 "preference": { 258 "type": "object", 259 "properties": { 260 "policy": {"type": "string", "minLength": 1}, 261 "score": {"type": "integer"} 262 }, 263 "required": ["policy", "score"], 264 "additionalProperties": false 265 } 266 }, 267 "required": ["plan_id", "supplier_id", "allocations", "coverage"], 268 "additionalProperties": false 269 }, 270 "limitations": { 271 "type": "object", 272 "properties": { 273 "scope": {"type": "string", "enum": ["supplied_only"]}, 274 "truncated": {"type": "boolean"}, 275 "supported_mode": {"type": "string", "minLength": 1}, 276 "unsupported": { 277 "type": "array", 278 "items": {"type": "string", "minLength": 1} 279 } 280 }, 281 "required": ["scope", "truncated", "supported_mode", "unsupported"], 282 "additionalProperties": false 283 }, 284 "execution": { 285 "type": "object", 286 "properties": { 287 "status": {"type": "string", "enum": ["complete", "degraded", "failed"]}, 288 "provider_calls": {"type": "integer", "minimum": 0}, 289 "model": {"type": ["string", "null"]}, 290 "question_bundle": {"type": ["string", "null"]}, 291 "degraded_reason": {"type": ["string", "null"], "minLength": 1} 292 }, 293 "required": [ 294 "status", 295 "provider_calls", 296 "model", 297 "question_bundle", 298 "degraded_reason" 299 ], 300 "additionalProperties": false, 301 "allOf": [ 302 { 303 "if": { 304 "properties": {"status": {"const": "degraded"}}, 305 "required": ["status"] 306 }, 307 "then": { 308 "required": ["degraded_reason"], 309 "properties": {"degraded_reason": {"type": "string", "minLength": 1}} 310 } 311 }, 312 { 313 "if": { 314 "properties": {"status": {"enum": ["complete", "failed"]}}, 315 "required": ["status"] 316 }, 317 "then": {"properties": {"degraded_reason": {"type": "null"}}} 318 }, 319 { 320 "if": { 321 "properties": {"provider_calls": {"const": 0}}, 322 "required": ["provider_calls"] 323 }, 324 "then": {"properties": {"model": {"type": "null"}}} 325 } 326 ] 327 }, 328 "need_identity": { 329 "type": "object", 330 "properties": { 331 "need_id": {"type": "string", "minLength": 1}, 332 "revision": {"type": "string", "minLength": 1} 333 }, 334 "required": ["need_id", "revision"], 335 "additionalProperties": false 336 }, 337 "snapshot_identity": { 338 "type": "object", 339 "properties": { 340 "lot_id": {"type": "string", "minLength": 1}, 341 "revision": {"type": "string", "minLength": 1} 342 }, 343 "required": ["lot_id", "revision"], 344 "additionalProperties": false 345 }, 346 "match_output_provenance": { 347 "type": "object", 348 "$comment": "ADR-0027 D47 BP01: immutable identities actually used for every successful match, independently of optional detailed evidence and context.return_provenance. need equals the interpreted input.need identity/revision; snapshots lists the supplied snapshots actually assessed, even when assessments fail or no plans result. An empty list means no snapshots were assessed; a nonempty assessed scope with zero plans still records its revisions. Never copy all supplied inputs as proof of use. Repeated identical pairs and identity/coverage-allocation disagreement are semantic obligations owned by C023/C041.", 349 "properties": { 350 "need": {"$ref": "#/$defs/need_identity"}, 351 "snapshots": { 352 "type": "array", 353 "items": {"$ref": "#/$defs/snapshot_identity"} 354 } 355 }, 356 "required": ["need", "snapshots"], 357 "additionalProperties": false 358 }, 359 "match_output": { 360 "type": "object", 361 "properties": { 362 "versions": {"$ref": "#/$defs/output_versions"}, 363 "provenance": {"$ref": "#/$defs/match_output_provenance"}, 364 "assessments": { 365 "type": "array", 366 "items": {"$ref": "#/$defs/assessment"} 367 }, 368 "plans": { 369 "type": "array", 370 "items": {"$ref": "#/$defs/plan"} 371 }, 372 "limitations": {"$ref": "#/$defs/limitations"}, 373 "execution": {"$ref": "#/$defs/execution"} 374 }, 375 "required": [ 376 "versions", 377 "provenance", 378 "assessments", 379 "plans", 380 "limitations", 381 "execution" 382 ], 383 "additionalProperties": false 384 } 385 } 386 }