feat: add price_treatment to the price type

docs/specification/catalog/index.md

@@ -189,7 +189,13 @@ Businesses determine market assignment—including currency—based on context
 signals. Price filter values are denominated in `context.currency`; when
 the presentment currency differs, businesses SHOULD convert before applying
 (see [Price Filter](search.md#price-filter)). Response prices include
-explicit currency codes confirming the resolution.
+explicit currency codes confirming the resolution. Where tax treatment
+varies by market, `price_treatment.tax.inclusion` states whether the
+amount includes tax as resolved for that market, so agents do not have
+to infer it from the country. An absent field is equivalent to
+`not_asserted`. Prices within a single product response **SHOULD**
+share the same tax treatment. During checkout, the itemized `totals`
+breakdown remains authoritative.
 
 When `context.eligibility` claims are present, Businesses that accept them
 **MAY** adjust `price` / `list_price` directly for strikethrough display and

source/schemas/common/types/price.json

@@ -17,6 +17,10 @@
       "type": "string",
       "description": "ISO 4217 currency code (e.g., 'USD', 'EUR', 'GBP').",
       "pattern": "^[A-Z]{3}$"
+    },
+    "price_treatment": {
+      "$ref": "price_treatment.json",
+      "description": "How the amount should be interpreted for display and downstream calculation. When omitted, treatment follows the resolved market."
     }
   }
 }

source/schemas/common/types/price_treatment.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/schemas/common/types/price_treatment.json",
+  "title": "Price Treatment",
+  "description": "How a price amount should be interpreted for display and downstream calculation.",
+  "type": "object",
+  "properties": {
+    "tax": {
+      "$ref": "tax_treatment.json",
+      "description": "Tax treatment of the amount."
+    }
+  }
+}

source/schemas/common/types/tax_treatment.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/schemas/common/types/tax_treatment.json",
+  "title": "Tax Treatment",
+  "description": "Tax treatment of a price amount.",
+  "type": "object",
+  "required": [
+    "inclusion"
+  ],
+  "properties": {
+    "inclusion": {
+      "type": "string",
+      "enum": [
+        "included",
+        "excluded",
+        "not_applicable",
+        "not_asserted"
+      ],
+      "description": "Whether the amount includes tax (e.g. VAT, GST) as resolved for the market. 'included': tax is part of the amount. 'excluded': tax is added downstream. 'not_applicable': no tax applies to this amount. 'not_asserted': equivalent to omitting the field."
+    }
+  }
+}