buyer_request_interpret.response.schema.json (11312B)
1 { 2 "$schema": "https://json-schema.org/draft/2020-12/schema", 3 "$id": "hyf_ops_v2/buyer_request_interpret.response.schema.json", 4 "title": "hyf_ops_v2 buyer_request.interpret 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. Typed demand lines with the D23 reported decimal-string projection; inference is never treated as confirmation. 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/interpret_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 "product_ref": { 180 "type": "object", 181 "properties": { 182 "phrase": {"type": "string", "minLength": 1}, 183 "catalogue_id": {"type": ["string", "null"], "minLength": 1}, 184 "resolution": {"type": "string", "enum": ["resolved", "unresolved"]} 185 }, 186 "required": ["phrase", "catalogue_id", "resolution"], 187 "additionalProperties": false 188 }, 189 "demand_line": { 190 "type": "object", 191 "properties": { 192 "line_id": {"type": "string", "minLength": 1}, 193 "product": {"$ref": "#/$defs/product_ref"}, 194 "quantity": {"$ref": "#/$defs/reported_quantity"}, 195 "conditions": { 196 "type": "array", 197 "items": { 198 "type": "object", 199 "properties": { 200 "kind": { 201 "type": "string", 202 "enum": [ 203 "fulfillment", 204 "window", 205 "grade", 206 "price", 207 "attribute", 208 "substitution" 209 ] 210 }, 211 "strength": { 212 "type": "string", 213 "enum": ["mandatory", "preferred", "excluded", "permitted"] 214 }, 215 "value": {"type": ["string", "null"]}, 216 "evidence": { 217 "type": "array", 218 "items": {"$ref": "#/$defs/evidence_ref"} 219 } 220 }, 221 "required": ["kind", "strength", "evidence"], 222 "additionalProperties": false 223 } 224 }, 225 "evidence": { 226 "type": "array", 227 "items": {"$ref": "#/$defs/evidence_ref"} 228 }, 229 "review_required": {"type": "boolean"} 230 }, 231 "required": [ 232 "line_id", 233 "product", 234 "quantity", 235 "conditions", 236 "evidence", 237 "review_required" 238 ], 239 "additionalProperties": false 240 }, 241 "review": { 242 "type": "object", 243 "properties": { 244 "required": {"type": "boolean"}, 245 "clarifications": { 246 "type": "array", 247 "items": { 248 "type": "object", 249 "properties": { 250 "field": {"type": "string", "minLength": 1}, 251 "reason": {"type": "string", "minLength": 1} 252 }, 253 "required": ["field", "reason"], 254 "additionalProperties": false 255 } 256 } 257 }, 258 "required": ["required", "clarifications"], 259 "additionalProperties": false 260 }, 261 "execution": { 262 "type": "object", 263 "properties": { 264 "status": {"type": "string", "enum": ["complete", "degraded", "failed"]}, 265 "provider_calls": {"type": "integer", "minimum": 0}, 266 "model": {"type": ["string", "null"]}, 267 "question_bundle": {"type": ["string", "null"]}, 268 "degraded_reason": {"type": ["string", "null"], "minLength": 1} 269 }, 270 "required": [ 271 "status", 272 "provider_calls", 273 "model", 274 "question_bundle", 275 "degraded_reason" 276 ], 277 "additionalProperties": false, 278 "allOf": [ 279 { 280 "if": { 281 "properties": {"status": {"const": "degraded"}}, 282 "required": ["status"] 283 }, 284 "then": { 285 "required": ["degraded_reason"], 286 "properties": {"degraded_reason": {"type": "string", "minLength": 1}} 287 } 288 }, 289 { 290 "if": { 291 "properties": {"status": {"enum": ["complete", "failed"]}}, 292 "required": ["status"] 293 }, 294 "then": {"properties": {"degraded_reason": {"type": "null"}}} 295 }, 296 { 297 "if": { 298 "properties": {"provider_calls": {"const": 0}}, 299 "required": ["provider_calls"] 300 }, 301 "then": {"properties": {"model": {"type": "null"}}} 302 } 303 ] 304 }, 305 "provenance_identity": { 306 "type": "object", 307 "properties": { 308 "source_id": {"type": "string", "minLength": 1}, 309 "revision": {"type": "string", "minLength": 1} 310 }, 311 "required": ["source_id", "revision"], 312 "additionalProperties": false 313 }, 314 "clarification_identity": { 315 "type": "object", 316 "properties": { 317 "source_id": {"type": "string", "minLength": 1}, 318 "revision": {"type": "string", "minLength": 1} 319 }, 320 "required": ["source_id", "revision"], 321 "additionalProperties": false 322 }, 323 "interpret_output_provenance": { 324 "type": "object", 325 "$comment": "ADR-0027 D47 BP01: immutable identities actually used for every successful buyer interpretation, independently of optional detailed evidence and context.return_provenance. source equals the interpreted input.source revision; clarification is non-null only when that supplied clarification was used. The farm-only prior_records field is forbidden here. Repeated identical identity pairs and identity/coverage disagreement are semantic obligations owned by C023/C030.", 326 "properties": { 327 "source": {"$ref": "#/$defs/provenance_identity"}, 328 "clarification": { 329 "oneOf": [ 330 {"type": "null"}, 331 {"$ref": "#/$defs/clarification_identity"} 332 ] 333 } 334 }, 335 "required": ["source", "clarification"], 336 "additionalProperties": false 337 }, 338 "interpret_output": { 339 "type": "object", 340 "properties": { 341 "versions": {"$ref": "#/$defs/output_versions"}, 342 "provenance": {"$ref": "#/$defs/interpret_output_provenance"}, 343 "demand_lines": { 344 "type": "array", 345 "items": {"$ref": "#/$defs/demand_line"} 346 }, 347 "review": {"$ref": "#/$defs/review"}, 348 "execution": {"$ref": "#/$defs/execution"} 349 }, 350 "required": [ 351 "versions", 352 "provenance", 353 "demand_lines", 354 "review", 355 "execution" 356 ], 357 "additionalProperties": false 358 } 359 } 360 }