farm_update_interpret.response.schema.json (12799B)
1 { 2 "$schema": "https://json-schema.org/draft/2020-12/schema", 3 "$id": "hyf_ops_v2/farm_update_interpret.response.schema.json", 4 "title": "hyf_ops_v2 farm_update.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. Proposals only, never inventory mutation. quantity uses the D23 reported decimal-string projection. 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/farm_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 "claim": { 190 "type": "object", 191 "properties": { 192 "claim_id": {"type": "string", "minLength": 1}, 193 "product": {"$ref": "#/$defs/product_ref"}, 194 "status": { 195 "type": "string", 196 "enum": ["offered", "forecast", "unavailable", "correction", "unclear"] 197 }, 198 "quantity": {"$ref": "#/$defs/reported_quantity"}, 199 "evidence": { 200 "type": "array", 201 "items": {"$ref": "#/$defs/evidence_ref"} 202 }, 203 "review_required": {"type": "boolean"} 204 }, 205 "required": ["claim_id", "product", "status", "evidence", "review_required"], 206 "additionalProperties": false 207 }, 208 "proposed_change": { 209 "type": "object", 210 "properties": { 211 "target": { 212 "type": "object", 213 "properties": { 214 "kind": {"type": "string", "enum": ["listing", "product", "farm"]}, 215 "id": {"type": ["string", "null"], "minLength": 1} 216 }, 217 "required": ["kind", "id"], 218 "additionalProperties": false 219 }, 220 "operation": { 221 "type": "string", 222 "enum": [ 223 "addition", 224 "remaining", 225 "replacement", 226 "withdrawal", 227 "correction", 228 "unresolved" 229 ] 230 }, 231 "expected_revision": {"type": ["string", "null"], "minLength": 1}, 232 "evidence": { 233 "type": "array", 234 "items": {"$ref": "#/$defs/evidence_ref"} 235 } 236 }, 237 "required": ["target", "operation", "evidence"], 238 "additionalProperties": false, 239 "allOf": [ 240 { 241 "if": { 242 "properties": { 243 "target": { 244 "properties": {"id": {"type": "string", "minLength": 1}}, 245 "required": ["id"] 246 } 247 }, 248 "required": ["target"] 249 }, 250 "then": { 251 "required": ["expected_revision"], 252 "properties": { 253 "expected_revision": {"type": "string", "minLength": 1} 254 } 255 } 256 }, 257 { 258 "if": { 259 "properties": { 260 "target": { 261 "properties": {"id": {"type": "null"}}, 262 "required": ["id"] 263 } 264 }, 265 "required": ["target"] 266 }, 267 "then": { 268 "properties": {"expected_revision": {"type": "null"}} 269 } 270 } 271 ] 272 }, 273 "review": { 274 "type": "object", 275 "properties": { 276 "required": {"type": "boolean"}, 277 "clarifications": { 278 "type": "array", 279 "items": { 280 "type": "object", 281 "properties": { 282 "field": {"type": "string", "minLength": 1}, 283 "reason": {"type": "string", "minLength": 1} 284 }, 285 "required": ["field", "reason"], 286 "additionalProperties": false 287 } 288 } 289 }, 290 "required": ["required", "clarifications"], 291 "additionalProperties": false 292 }, 293 "execution": { 294 "type": "object", 295 "properties": { 296 "status": {"type": "string", "enum": ["complete", "degraded", "failed"]}, 297 "provider_calls": {"type": "integer", "minimum": 0}, 298 "model": {"type": ["string", "null"]}, 299 "question_bundle": {"type": ["string", "null"]}, 300 "degraded_reason": {"type": ["string", "null"], "minLength": 1} 301 }, 302 "required": [ 303 "status", 304 "provider_calls", 305 "model", 306 "question_bundle", 307 "degraded_reason" 308 ], 309 "additionalProperties": false, 310 "allOf": [ 311 { 312 "if": { 313 "properties": {"status": {"const": "degraded"}}, 314 "required": ["status"] 315 }, 316 "then": { 317 "required": ["degraded_reason"], 318 "properties": {"degraded_reason": {"type": "string", "minLength": 1}} 319 } 320 }, 321 { 322 "if": { 323 "properties": {"status": {"enum": ["complete", "failed"]}}, 324 "required": ["status"] 325 }, 326 "then": {"properties": {"degraded_reason": {"type": "null"}}} 327 }, 328 { 329 "if": { 330 "properties": {"provider_calls": {"const": 0}}, 331 "required": ["provider_calls"] 332 }, 333 "then": {"properties": {"model": {"type": "null"}}} 334 } 335 ] 336 }, 337 "provenance_identity": { 338 "type": "object", 339 "properties": { 340 "source_id": {"type": "string", "minLength": 1}, 341 "revision": {"type": "string", "minLength": 1} 342 }, 343 "required": ["source_id", "revision"], 344 "additionalProperties": false 345 }, 346 "clarification_identity": { 347 "type": "object", 348 "properties": { 349 "source_id": {"type": "string", "minLength": 1}, 350 "revision": {"type": "string", "minLength": 1} 351 }, 352 "required": ["source_id", "revision"], 353 "additionalProperties": false 354 }, 355 "prior_record_identity": { 356 "type": "object", 357 "properties": { 358 "record_id": {"type": "string", "minLength": 1}, 359 "revision": {"type": "string", "minLength": 1} 360 }, 361 "required": ["record_id", "revision"], 362 "additionalProperties": false 363 }, 364 "farm_output_provenance": { 365 "type": "object", 366 "$comment": "ADR-0027 D47 BP01: immutable identities actually used for every successful farm 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; prior_records lists only supplied records actually consulted. Repeated identical identity/revision pairs and identity/coverage disagreement are semantic obligations owned by C023/C030.", 367 "properties": { 368 "source": {"$ref": "#/$defs/provenance_identity"}, 369 "clarification": { 370 "oneOf": [ 371 {"type": "null"}, 372 {"$ref": "#/$defs/clarification_identity"} 373 ] 374 }, 375 "prior_records": { 376 "type": "array", 377 "items": {"$ref": "#/$defs/prior_record_identity"} 378 } 379 }, 380 "required": ["source", "clarification", "prior_records"], 381 "additionalProperties": false 382 }, 383 "farm_output": { 384 "type": "object", 385 "properties": { 386 "versions": {"$ref": "#/$defs/output_versions"}, 387 "provenance": {"$ref": "#/$defs/farm_output_provenance"}, 388 "claims": { 389 "type": "array", 390 "items": {"$ref": "#/$defs/claim"} 391 }, 392 "proposed_changes": { 393 "type": "array", 394 "items": {"$ref": "#/$defs/proposed_change"} 395 }, 396 "review": {"$ref": "#/$defs/review"}, 397 "execution": {"$ref": "#/$defs/execution"} 398 }, 399 "required": [ 400 "versions", 401 "provenance", 402 "claims", 403 "proposed_changes", 404 "review", 405 "execution" 406 ], 407 "additionalProperties": false 408 } 409 } 410 }