{"$id":"https://KATA.org/schemas/intent.json","$schema":"https://json-schema.org/draft/2020-12/schema","additionalProperties":true,"description":"Conceptual schema for structured, machine-readable intent declared by a principal, including optional price and counterparty constraints. Status: Concept / Open Design \u2014 not production ready.","examples":[{"allowed_actions":["search","compare","purchase"],"category":"electronics","constraints":{"max_items":1},"currency":"CAD","intent_id":"int_9f31","maximum_amount":1500,"merchant_constraints":[],"natural_language_source":"Find and buy a laptop for me, maximum CAD 1,500.","purpose":"purchase","time_limit":"2026-10-10T23:59:59Z","version":1}],"properties":{"allowed_actions":{"description":"Verbs the agent may perform under this intent.","items":{"type":"string"},"type":"array"},"category":{"description":"Domain category, e.g. 'electronics', 'travel', 'groceries'.","type":"string"},"constraints":{"additionalProperties":true,"description":"Additional key-value limits (e.g. max_items, shipping class).","type":"object"},"counterparty_constraints":{"additionalProperties":true,"description":"Who may be paid under this intent. Complements merchant_constraints with settlement identity. Empty or omitted means no extra constraint.","properties":{"allowed_merchant_ids":{"description":"Merchant identifiers the principal has accepted.","items":{"type":"string"},"type":"array"},"allowed_settlement_addresses":{"description":"Settlement or payee addresses the principal has accepted.","items":{"type":"string"},"type":"array"},"maximum_risk":{"description":"Highest counterparty risk the intent accepts.","enum":["low","medium","high"],"type":"string"}},"type":"object"},"currency":{"description":"ISO 4217 currency code.","pattern":"^[A-Z]{3}$","type":"string"},"fee_policy":{"additionalProperties":true,"description":"Fees the principal has accepted up front. A line outside this policy is an undisclosed-fee signal. It is not, by itself, a finding of fraud.","properties":{"allow_undisclosed":{"description":"When false, a fee marked disclosed=false is a price-integrity signal.","type":"boolean"},"allowed_codes":{"description":"Fee codes the principal has accepted, e.g. tax, shipping.","items":{"type":"string"},"type":"array"}},"type":"object"},"intent_id":{"description":"Unique identifier for this intent declaration.","type":"string"},"maximum_amount":{"description":"Hard spending ceiling for the intent, in the given currency.","minimum":0,"type":"number"},"merchant_constraints":{"description":"Allowed or blocked merchants / merchant categories. Empty = no constraint.","items":{"type":"string"},"type":"array"},"natural_language_source":{"description":"The original human instruction, preserved for audit and explainability.","type":"string"},"price_expectation":{"additionalProperties":true,"description":"Optional quote and list anchors, plus a tolerance band. A charge under maximum_amount can still disagree with the quote. Compare with the band, not with equality.","properties":{"currency":{"description":"ISO 4217 code for the prices in this object. Falls back to the intent currency when omitted.","pattern":"^[A-Z]{3}$","type":"string"},"listed_price":{"description":"Advertised or catalogue price the principal expects, if known when intent is declared.","minimum":0,"type":"number"},"quoted_price":{"description":"Price quoted to the principal or the agent before commitment.","minimum":0,"type":"number"},"tolerance_ratio":{"description":"Charged-to-reference ratio still treated as ordinary movement for this intent. Do not set this to 1. AgentCommerceBench (Apache-2.0) reports that 14.6% of legitimate purchases exceed 1.15 times the quoted price and 4.8% exceed 1.45 times, and its overcharge class overlaps that tail. This field is a declared band, not a universal detector threshold.","exclusiveMinimum":0,"type":"number"}},"type":"object"},"purpose":{"description":"High-level purpose: purchase, transfer, booking, data_access, communication, etc.","type":"string"},"time_limit":{"description":"The intent expires after this timestamp.","format":"date-time","type":"string"},"version":{"description":"Intent version; increments when the principal re-declares intent.","minimum":1,"type":"integer"}},"required":["intent_id","purpose","version"],"title":"KATA Intent","type":"object"}