JSON Schema¶
Draft 2020-12 schema for validating .cart files.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://github.com/danielrosehill/Dot-Cart/blob/main/schema/cart.schema.json",
"title": ".cart document",
"description": "An open, interoperable, vendor-neutral representation of an ecommerce shopping cart. Spec v0.1.",
"type": "object",
"required": ["cart_version", "id", "created_at", "merchant", "currency", "items", "totals"],
"properties": {
"cart_version": {
"type": "string",
"pattern": "^0\\.1(\\.\\d+)?$",
"description": "Version of the .cart spec this file conforms to."
},
"id": {
"type": "string",
"description": "Unique identifier for this cart snapshot (UUID recommended)."
},
"created_at": { "type": "string", "format": "date-time" },
"updated_at": { "type": "string", "format": "date-time" },
"expires_at": {
"type": "string",
"format": "date-time",
"description": "When the captured prices/quote stop being valid, if stated by the merchant."
},
"locale": {
"type": "string",
"description": "BCP 47 locale the cart was presented in (e.g. he-IL, en-US)."
},
"transaction_type": {
"type": "string",
"enum": ["b2c", "b2b"],
"default": "b2c",
"description": "b2c (default) or b2b. When b2b, buyer and both parties' VAT details become relevant."
},
"source": {
"type": "object",
"properties": {
"platform": {
"type": "string",
"description": "Ecommerce backend/storefront platform, if known or detected (e.g. shopify, woocommerce, magento, custom)."
},
"platform_detected": {
"type": "boolean",
"description": "True if platform was auto-detected rather than supplied by a human."
},
"platform_confidence": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Detector confidence in platform, when platform_detected is true."
},
"cart_url": { "type": "string", "format": "uri" },
"captured_by": { "type": "string" },
"capture_method": {
"type": "string",
"enum": ["browser_agent", "api", "manual", "ocr", "other"]
}
},
"additionalProperties": true
},
"merchant": {
"type": "object",
"required": ["name"],
"properties": {
"name": { "type": "string" },
"legal_name": { "type": "string" },
"website": { "type": "string", "format": "uri" },
"merchant_id": { "type": "string" },
"vat_id": { "type": "string", "description": "Seller VAT/tax registration number." },
"vat_issuing_authority": { "type": "string", "description": "Authority/country that issued the seller's VAT ID." },
"country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "Seller country; defaults to address.country when present." },
"compliance": {
"type": "array",
"items": { "type": "string" },
"description": "Data-protection/security standards the merchant attests to (e.g. soc2, iso_27001, gdpr). Relevant to (government) procurement."
},
"global_merchant_id": {
"type": "string",
"description": "Reserved/placeholder for a future universal merchant identifier; no ecosystem registry exists yet."
},
"address": { "$ref": "#/$defs/address" },
"contact": {
"type": "object",
"properties": {
"email": { "type": "string" },
"phone": { "type": "string" }
},
"additionalProperties": true
}
},
"additionalProperties": true
},
"buyer": {
"type": "object",
"description": "The purchasing party. Present chiefly for B2B (transaction_type=b2b).",
"properties": {
"business_name": { "type": "string", "x-sensitivity": "personal" },
"vat_id": { "type": "string", "x-sensitivity": "personal" },
"vat_issuing_authority": { "type": "string" },
"country": { "type": "string", "pattern": "^[A-Z]{2}$" },
"contact": {
"type": "object",
"properties": {
"name": { "type": "string", "x-sensitivity": "personal" },
"email": { "type": "string", "x-sensitivity": "personal" },
"phone": { "type": "string", "x-sensitivity": "personal" }
},
"additionalProperties": true
}
},
"additionalProperties": true
},
"currency": {
"type": "string",
"pattern": "^[A-Z]{3}$",
"description": "ISO 4217 currency code applying to all monetary amounts in the file."
},
"multi_currency": {
"type": "boolean",
"description": "False by default. When true, items may carry their own currency and exchange-rate fields; totals stay in the top-level currency."
},
"tax": {
"type": "object",
"properties": {
"scheme": { "type": "string", "enum": ["vat", "sales_tax", "none"] },
"default_rate": { "$ref": "#/$defs/rate" },
"prices_include_tax": { "type": "boolean" }
},
"additionalProperties": true
},
"items": {
"type": "array",
"minItems": 1,
"items": { "$ref": "#/$defs/item" }
},
"shipping": {
"type": "object",
"properties": {
"ship_to": {
"allOf": [{ "$ref": "#/$defs/address" }],
"properties": {
"name": { "type": "string", "x-sensitivity": "personal" },
"address_type": {
"type": "string",
"enum": ["residential", "business", "warehouse", "other"],
"description": "Nature of the delivery address; affects carrier options/surcharges."
}
}
},
"incoterms": {
"type": "string",
"description": "Delivery terms for (international) B2B, e.g. EXW, FOB, CIF, DAP, DDP."
},
"selected_method_id": { "type": "string" },
"available_methods": {
"type": "array",
"items": { "$ref": "#/$defs/shipping_method" }
}
},
"additionalProperties": true
},
"totals": {
"type": "object",
"required": [
"items_subtotal_excl_tax",
"items_subtotal_incl_tax",
"tax_total",
"grand_total",
"amount_pending_payment"
],
"properties": {
"items_subtotal_excl_tax": { "$ref": "#/$defs/money" },
"items_subtotal_incl_tax": { "$ref": "#/$defs/money" },
"shipping_excl_tax": { "$ref": "#/$defs/money" },
"shipping_incl_tax": { "$ref": "#/$defs/money" },
"discount_total": { "$ref": "#/$defs/money" },
"tax_total": { "$ref": "#/$defs/money" },
"grand_total": { "$ref": "#/$defs/money" },
"amount_pending_payment": { "$ref": "#/$defs/money" }
},
"additionalProperties": true
},
"payment": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": ["cart", "quote_requested", "po_issued", "awaiting_payment", "partially_paid", "paid"]
},
"method": {
"type": "string",
"description": "Payment method the buyer selected/intends to use; a single value from methods_accepted (e.g. credit_card, bank_transfer, purchase_order)."
},
"terms": { "type": "string" },
"methods_accepted": { "type": "array", "items": { "type": "string" } },
"reference": { "type": "string" },
"card": {
"type": "object",
"description": "Payment card the buyer intends to use. MUST NOT contain full PAN, CVV/CVC, PIN, or full expiry (see SPEC §3.7, §8).",
"properties": {
"cardholder_name": {
"type": "string",
"description": "Name printed on the card.",
"x-sensitivity": "sensitive"
},
"is_business_card": {
"type": "boolean",
"description": "True for a business/corporate card, false for a personal card."
},
"brand": {
"type": "string",
"description": "Card network if known, e.g. visa, mastercard, amex."
},
"last4": {
"type": "string",
"pattern": "^[0-9]{4}$",
"description": "Last four digits, as a masked reference only.",
"x-sensitivity": "sensitive"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
},
"notes": { "type": "string" },
"extensions": {
"type": "object",
"description": "Namespaced vendor/tool-specific data. Consumers must preserve unknown namespaces.",
"additionalProperties": { "type": "object" }
}
},
"additionalProperties": true,
"$defs": {
"money": {
"type": "number",
"description": "Monetary amount in major units of the document's currency."
},
"rate": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Tax rate as a decimal fraction (0.18 = 18%)."
},
"address": {
"type": "object",
"properties": {
"street": { "type": "string" },
"city": { "type": "string" },
"region": { "type": "string" },
"postal_code": { "type": "string" },
"country": { "type": "string", "pattern": "^[A-Z]{2}$" }
},
"additionalProperties": true
},
"item": {
"type": "object",
"required": [
"name",
"quantity",
"unit_price_excl_tax",
"unit_price_incl_tax",
"line_total_excl_tax",
"line_total_incl_tax"
],
"properties": {
"sku": { "type": "string" },
"name": { "type": "string" },
"description": { "type": "string" },
"variant": { "type": "string", "description": "Human-readable variant label (e.g. 'Blue / XL')." },
"options": {
"type": "array",
"description": "Structured variant selections.",
"items": {
"type": "object",
"required": ["name", "value"],
"properties": {
"name": { "type": "string" },
"value": { "type": "string" }
},
"additionalProperties": true
}
},
"quantity": { "type": "number", "exclusiveMinimum": 0 },
"unit": { "type": "string", "default": "each" },
"unit_price_excl_tax": { "$ref": "#/$defs/money" },
"unit_price_incl_tax": { "$ref": "#/$defs/money" },
"rrp_excl_tax": { "$ref": "#/$defs/money" },
"rrp_incl_tax": { "$ref": "#/$defs/money" },
"currency": {
"type": "string",
"pattern": "^[A-Z]{3}$",
"description": "Item currency; only when the cart's multi_currency is true and it differs from the cart currency."
},
"exchange_rate": {
"type": "number",
"exclusiveMinimum": 0,
"description": "Rate to convert this item's currency to the cart currency."
},
"exchange_rate_calculated": {
"type": "boolean",
"description": "True if the rate was computed by the producing tool rather than quoted by the merchant."
},
"tax_rate": { "$ref": "#/$defs/rate" },
"line_total_excl_tax": { "$ref": "#/$defs/money" },
"line_total_incl_tax": { "$ref": "#/$defs/money" },
"discount": {
"type": "object",
"properties": {
"description": { "type": "string" },
"amount": { "$ref": "#/$defs/money" },
"percentage": { "$ref": "#/$defs/rate" },
"type": {
"type": "string",
"enum": ["automatic", "manual", "coupon", "negotiated", "promotion"],
"description": "Distinguishes a manually applied discount from an automatic one."
}
},
"additionalProperties": true
},
"product_url": { "type": "string", "format": "uri" },
"image_url": { "type": "string", "format": "uri" },
"manufacturer": { "type": "string" },
"mpn": { "type": "string" },
"gtin": { "type": "string" },
"availability": {
"type": "string",
"enum": ["in_stock", "backorder", "preorder", "unknown"]
},
"min_order_quantity": {
"type": "number",
"exclusiveMinimum": 0,
"description": "Minimum orderable quantity (MOQ)."
},
"lead_time_days": {
"type": "number",
"minimum": 0,
"description": "Quoted lead time in days for backordered/made-to-order items."
},
"price_breaks": {
"type": "array",
"description": "Quantity-tiered pricing offered for this item.",
"items": {
"type": "object",
"required": ["min_quantity"],
"properties": {
"min_quantity": { "type": "number", "exclusiveMinimum": 0 },
"unit_price_excl_tax": { "$ref": "#/$defs/money" },
"unit_price_incl_tax": { "$ref": "#/$defs/money" }
},
"additionalProperties": true
}
},
"notes": { "type": "string" }
},
"additionalProperties": true
},
"shipping_method": {
"type": "object",
"required": ["id", "name"],
"properties": {
"id": { "type": "string" },
"name": { "type": "string" },
"cost_excl_tax": { "$ref": "#/$defs/money" },
"cost_incl_tax": { "$ref": "#/$defs/money" },
"estimated_delivery": { "type": "string" }
},
"additionalProperties": true
}
}
}