{
  "name": ".cart Data Dictionary",
  "description": "Flat, machine-readable dictionary of every field defined by the .cart file format. One entry per field, keyed by dotted path (array elements use the [] suffix). This is a companion to the JSON Schema (cart.schema.json); the JSON Schema is authoritative for validation, this dictionary is authoritative for the human-facing field catalogue.",
  "spec_version": "0.1.0",
  "cart_version": "0.1",
  "generated_from": "SPEC.md",
  "license": "MIT",
  "attribution": "Daniel Rosehill",
  "columns": {
    "path": "Dotted field path from the cart document root. Array elements are written as parent[].child.",
    "type": "JSON type. Composite types are written as array<string> / array<object>.",
    "required": "true = required whenever its parent object is present. false = optional. conditional = required only under a stated condition (see notes).",
    "profile": "core = part of the minimum Core profile (see spec 2.1). expanded = part of the richer Expanded profile.",
    "sensitivity": "normal | personal | sensitive — see spec 8 (Data sensitivity & PII).",
    "enum": "Closed set of permitted values, where the field is an enumeration.",
    "format": "Value format convention (e.g. date-time, iso-4217, iso-3166-1-alpha-2).",
    "notes": "Extra semantics, conditions, or references."
  },
  "sensitivity_levels": {
    "normal": "Not PII. May be shared and stored freely.",
    "personal": "Personal / business data (GDPR-relevant). Minimize and avoid sharing beyond the intended recipient.",
    "sensitive": "Sensitive PII. Include only when genuinely required; never persist longer than needed."
  },
  "fields": [
    { "path": "cart_version", "type": "string", "required": true, "profile": "core", "sensitivity": "normal", "description": "Version of this spec the file conforms to (\"0.1\")." },
    { "path": "id", "type": "string", "required": true, "profile": "core", "sensitivity": "normal", "description": "Unique identifier for this cart snapshot (UUID recommended)." },
    { "path": "created_at", "type": "string", "required": true, "profile": "core", "sensitivity": "normal", "format": "date-time", "description": "When the cart was captured / exported (ISO 8601 with timezone)." },
    { "path": "updated_at", "type": "string", "required": false, "profile": "expanded", "sensitivity": "normal", "format": "date-time", "description": "Last modification of this file." },
    { "path": "expires_at", "type": "string", "required": false, "profile": "expanded", "sensitivity": "normal", "format": "date-time", "description": "When the captured prices / quote stop being valid, if the merchant states it." },
    { "path": "locale", "type": "string", "required": false, "profile": "expanded", "sensitivity": "normal", "format": "bcp-47", "description": "Locale the cart was presented in (e.g. \"he-IL\", \"en-US\"). Helps interpret names and formatting." },
    { "path": "transaction_type", "type": "string", "required": false, "profile": "expanded", "sensitivity": "normal", "enum": ["b2c", "b2b"], "description": "\"b2c\" (default) or \"b2b\". When \"b2b\", the buyer object and both parties' VAT details become relevant." },

    { "path": "source", "type": "object", "required": false, "profile": "expanded", "sensitivity": "normal", "description": "Where and how the cart was captured (provenance)." },
    { "path": "source.platform", "type": "string", "required": false, "profile": "expanded", "sensitivity": "normal", "description": "Ecommerce backend / storefront platform powering the merchant, if known or detected (e.g. \"shopify\", \"woocommerce\", \"magento\", \"custom\")." },
    { "path": "source.platform_detected", "type": "boolean", "required": false, "profile": "expanded", "sensitivity": "normal", "description": "true if platform was auto-detected by the capturing agent rather than supplied by a human." },
    { "path": "source.platform_confidence", "type": "number", "required": false, "profile": "expanded", "sensitivity": "normal", "description": "Detector confidence in platform, 0-1, when platform_detected is true." },
    { "path": "source.cart_url", "type": "string", "required": false, "profile": "expanded", "sensitivity": "personal", "description": "URL of the live cart, if one exists. May embed a session token." },
    { "path": "source.captured_by", "type": "string", "required": false, "profile": "expanded", "sensitivity": "normal", "description": "Tool / agent that produced the file (e.g. \"cart-exporter-mcp/0.3\")." },
    { "path": "source.capture_method", "type": "string", "required": false, "profile": "expanded", "sensitivity": "normal", "enum": ["browser_agent", "api", "manual", "ocr", "other"], "description": "How the cart was captured." },

    { "path": "merchant", "type": "object", "required": true, "profile": "core", "sensitivity": "normal", "description": "The seller the cart belongs to." },
    { "path": "merchant.name", "type": "string", "required": true, "profile": "core", "sensitivity": "normal", "description": "Merchant / vendor display name." },
    { "path": "merchant.legal_name", "type": "string", "required": false, "profile": "expanded", "sensitivity": "normal", "description": "Registered company name, if different." },
    { "path": "merchant.website", "type": "string", "required": false, "profile": "expanded", "sensitivity": "normal", "description": "Merchant homepage URL." },
    { "path": "merchant.merchant_id", "type": "string", "required": false, "profile": "expanded", "sensitivity": "normal", "description": "Merchant identifier (company / VAT registration number, etc.)." },
    { "path": "merchant.vat_id", "type": "string", "required": false, "profile": "expanded", "sensitivity": "normal", "description": "Seller VAT / tax registration number (the seller side of a B2B transaction)." },
    { "path": "merchant.vat_issuing_authority", "type": "string", "required": false, "profile": "expanded", "sensitivity": "normal", "description": "Authority / country that issued the seller's VAT ID (e.g. \"IL\", \"DE\")." },
    { "path": "merchant.country", "type": "string", "required": false, "profile": "expanded", "sensitivity": "normal", "format": "iso-3166-1-alpha-2", "description": "Seller's country; defaults to merchant.address.country when present." },
    { "path": "merchant.compliance", "type": "array<string>", "required": false, "profile": "expanded", "sensitivity": "normal", "description": "Data-protection / security standards the merchant attests to (e.g. [\"soc2\", \"iso_27001\", \"gdpr\"]). Useful for (government) procurement." },
    { "path": "merchant.global_merchant_id", "type": "string", "required": false, "profile": "expanded", "sensitivity": "normal", "reserved": true, "description": "Reserved / placeholder for a future universal merchant identifier. Populate only against an agreed scheme." },
    { "path": "merchant.address", "type": "object", "required": false, "profile": "expanded", "sensitivity": "normal", "description": "Postal address." },
    { "path": "merchant.address.street", "type": "string", "required": false, "profile": "expanded", "sensitivity": "normal", "description": "Street address." },
    { "path": "merchant.address.city", "type": "string", "required": false, "profile": "expanded", "sensitivity": "normal", "description": "City." },
    { "path": "merchant.address.region", "type": "string", "required": false, "profile": "expanded", "sensitivity": "normal", "description": "State / province / region." },
    { "path": "merchant.address.postal_code", "type": "string", "required": false, "profile": "expanded", "sensitivity": "normal", "description": "Postal / ZIP code." },
    { "path": "merchant.address.country", "type": "string", "required": false, "profile": "expanded", "sensitivity": "normal", "format": "iso-3166-1-alpha-2", "description": "Country code." },
    { "path": "merchant.contact", "type": "object", "required": false, "profile": "expanded", "sensitivity": "personal", "description": "Merchant contact details. Treat as personal data when a named person." },
    { "path": "merchant.contact.email", "type": "string", "required": false, "profile": "expanded", "sensitivity": "personal", "description": "Contact email." },
    { "path": "merchant.contact.phone", "type": "string", "required": false, "profile": "expanded", "sensitivity": "personal", "description": "Contact phone." },

    { "path": "buyer", "type": "object", "required": false, "profile": "expanded", "sensitivity": "personal", "description": "The purchasing party (chiefly for B2B). Supplies the buyer side of a PO / RFQ / reverse-charge VAT document." },
    { "path": "buyer.business_name", "type": "string", "required": false, "profile": "expanded", "sensitivity": "personal", "description": "Legal name of the purchasing organization." },
    { "path": "buyer.vat_id", "type": "string", "required": false, "profile": "expanded", "sensitivity": "personal", "description": "Buyer's VAT / tax registration number." },
    { "path": "buyer.vat_issuing_authority", "type": "string", "required": false, "profile": "expanded", "sensitivity": "personal", "description": "Authority / country that issued the buyer's VAT ID." },
    { "path": "buyer.country", "type": "string", "required": false, "profile": "expanded", "sensitivity": "personal", "format": "iso-3166-1-alpha-2", "description": "Buyer's country." },
    { "path": "buyer.contact", "type": "object", "required": false, "profile": "expanded", "sensitivity": "personal", "description": "Optional name / email / phone for the purchaser." },
    { "path": "buyer.contact.name", "type": "string", "required": false, "profile": "expanded", "sensitivity": "personal", "description": "Purchaser name." },
    { "path": "buyer.contact.email", "type": "string", "required": false, "profile": "expanded", "sensitivity": "personal", "description": "Purchaser email." },
    { "path": "buyer.contact.phone", "type": "string", "required": false, "profile": "expanded", "sensitivity": "personal", "description": "Purchaser phone." },

    { "path": "currency", "type": "string", "required": true, "profile": "core", "sensitivity": "normal", "format": "iso-4217", "description": "Currency for all amounts in the file." },
    { "path": "multi_currency", "type": "boolean", "required": false, "profile": "expanded", "sensitivity": "normal", "description": "false by default. When true, individual items may carry their own currency and exchange-rate fields; totals stay in the top-level currency." },

    { "path": "tax", "type": "object", "required": false, "profile": "expanded", "sensitivity": "normal", "description": "Cart-level tax context." },
    { "path": "tax.scheme", "type": "string", "required": false, "profile": "expanded", "sensitivity": "normal", "enum": ["vat", "sales_tax", "none"], "description": "Tax scheme in effect." },
    { "path": "tax.default_rate", "type": "number", "required": false, "profile": "expanded", "sensitivity": "normal", "description": "Default rate (decimal fraction, 0.18 = 18%) applied to items unless overridden per item." },
    { "path": "tax.prices_include_tax", "type": "boolean", "required": false, "profile": "expanded", "sensitivity": "normal", "description": "Whether the merchant's displayed prices include tax." },

    { "path": "items", "type": "array<object>", "required": true, "profile": "core", "sensitivity": "normal", "description": "Line items." },
    { "path": "items[].sku", "type": "string", "required": "conditional", "profile": "expanded", "sensitivity": "normal", "notes": "Required if the merchant exposes a SKU.", "description": "Merchant SKU / catalog number." },
    { "path": "items[].name", "type": "string", "required": true, "profile": "core", "sensitivity": "normal", "description": "Short product name." },
    { "path": "items[].description", "type": "string", "required": false, "profile": "expanded", "sensitivity": "normal", "description": "Longer description." },
    { "path": "items[].variant", "type": "string", "required": false, "profile": "expanded", "sensitivity": "normal", "description": "Human-readable variant label (e.g. \"Blue / XL\")." },
    { "path": "items[].options", "type": "array<object>", "required": false, "profile": "expanded", "sensitivity": "normal", "description": "Structured variant selections." },
    { "path": "items[].options[].name", "type": "string", "required": false, "profile": "expanded", "sensitivity": "normal", "description": "Option name (e.g. \"Color\")." },
    { "path": "items[].options[].value", "type": "string", "required": false, "profile": "expanded", "sensitivity": "normal", "description": "Option value (e.g. \"Blue\")." },
    { "path": "items[].quantity", "type": "number", "required": true, "profile": "core", "sensitivity": "normal", "description": "Quantity in the cart." },
    { "path": "items[].unit", "type": "string", "required": false, "profile": "expanded", "sensitivity": "normal", "description": "Unit of measure (\"each\", \"box\", \"m\", \"kg\"...). Defaults to \"each\"." },
    { "path": "items[].unit_price_excl_tax", "type": "number", "required": true, "profile": "expanded", "sensitivity": "normal", "description": "Price per unit before VAT / tax." },
    { "path": "items[].unit_price_incl_tax", "type": "number", "required": true, "profile": "core", "sensitivity": "normal", "description": "Price per unit after VAT / tax." },
    { "path": "items[].rrp_excl_tax", "type": "number", "required": false, "profile": "expanded", "sensitivity": "normal", "description": "Regular / reference price (RRP) per unit before tax, when discounted from a higher list price." },
    { "path": "items[].rrp_incl_tax", "type": "number", "required": false, "profile": "expanded", "sensitivity": "normal", "description": "Regular / reference price (RRP) per unit after tax. Discount percentage is measured against this." },
    { "path": "items[].currency", "type": "string", "required": false, "profile": "expanded", "sensitivity": "normal", "format": "iso-4217", "notes": "Only when cart multi_currency is true and it differs from the cart currency.", "description": "Item currency." },
    { "path": "items[].exchange_rate", "type": "number", "required": false, "profile": "expanded", "sensitivity": "normal", "description": "Rate used to convert this item's currency to the cart currency." },
    { "path": "items[].exchange_rate_calculated", "type": "boolean", "required": false, "profile": "expanded", "sensitivity": "normal", "description": "true if the rate was computed by the producing tool rather than quoted by the merchant." },
    { "path": "items[].tax_rate", "type": "number", "required": false, "profile": "expanded", "sensitivity": "normal", "description": "Item-level tax rate if it differs from tax.default_rate." },
    { "path": "items[].line_total_excl_tax", "type": "number", "required": true, "profile": "expanded", "sensitivity": "normal", "description": "quantity x unit_price_excl_tax (after line discounts)." },
    { "path": "items[].line_total_incl_tax", "type": "number", "required": true, "profile": "core", "sensitivity": "normal", "description": "Line total after VAT / tax." },
    { "path": "items[].discount", "type": "object", "required": false, "profile": "expanded", "sensitivity": "normal", "description": "Discount applied to this line (already reflected in line totals)." },
    { "path": "items[].discount.description", "type": "string", "required": false, "profile": "expanded", "sensitivity": "normal", "description": "Human-readable label (\"Summer sale\", \"Contract price\")." },
    { "path": "items[].discount.amount", "type": "number", "required": false, "profile": "expanded", "sensitivity": "normal", "description": "Absolute discount per line, in cart currency." },
    { "path": "items[].discount.percentage", "type": "number", "required": false, "profile": "expanded", "sensitivity": "normal", "description": "Discount as a decimal fraction of the RRP (0.15 = 15%)." },
    { "path": "items[].discount.type", "type": "string", "required": false, "profile": "expanded", "sensitivity": "normal", "enum": ["automatic", "manual", "coupon", "negotiated", "promotion"], "description": "Distinguishes a manually applied discount from an automatic one." },
    { "path": "items[].product_url", "type": "string", "required": false, "profile": "expanded", "sensitivity": "normal", "description": "Canonical product page URL." },
    { "path": "items[].image_url", "type": "string", "required": false, "profile": "expanded", "sensitivity": "normal", "description": "Product image URL." },
    { "path": "items[].manufacturer", "type": "string", "required": false, "profile": "expanded", "sensitivity": "normal", "description": "Brand / manufacturer name." },
    { "path": "items[].mpn", "type": "string", "required": false, "profile": "expanded", "sensitivity": "normal", "description": "Manufacturer part number (distinct from merchant SKU)." },
    { "path": "items[].gtin", "type": "string", "required": false, "profile": "expanded", "sensitivity": "normal", "description": "Barcode (EAN / UPC), when known. Key for cross-vendor comparison." },
    { "path": "items[].availability", "type": "string", "required": false, "profile": "expanded", "sensitivity": "normal", "enum": ["in_stock", "backorder", "preorder", "unknown"], "description": "Stock availability." },
    { "path": "items[].min_order_quantity", "type": "number", "required": false, "profile": "expanded", "sensitivity": "normal", "description": "Minimum orderable quantity (MOQ), common in B2B." },
    { "path": "items[].lead_time_days", "type": "number", "required": false, "profile": "expanded", "sensitivity": "normal", "description": "Quoted lead time in days for backordered / made-to-order items." },
    { "path": "items[].price_breaks", "type": "array<object>", "required": false, "profile": "expanded", "sensitivity": "normal", "description": "Quantity-tiered pricing offered for this item. Essential for B2B comparison and RFQs." },
    { "path": "items[].price_breaks[].min_quantity", "type": "number", "required": true, "profile": "expanded", "sensitivity": "normal", "description": "Quantity at which this tier's price applies." },
    { "path": "items[].price_breaks[].unit_price_excl_tax", "type": "number", "required": false, "profile": "expanded", "sensitivity": "normal", "description": "Per-unit price at this tier, before tax." },
    { "path": "items[].price_breaks[].unit_price_incl_tax", "type": "number", "required": false, "profile": "expanded", "sensitivity": "normal", "description": "Per-unit price at this tier, after tax." },
    { "path": "items[].notes", "type": "string", "required": false, "profile": "expanded", "sensitivity": "normal", "description": "Free-text line notes." },

    { "path": "shipping", "type": "object", "required": false, "profile": "expanded", "sensitivity": "normal", "description": "Shipping methods and destination." },
    { "path": "shipping.ship_to", "type": "object", "required": false, "profile": "expanded", "sensitivity": "personal", "description": "Destination address (merchant.address shape plus name and address_type)." },
    { "path": "shipping.ship_to.name", "type": "string", "required": false, "profile": "expanded", "sensitivity": "personal", "description": "Recipient name." },
    { "path": "shipping.ship_to.address_type", "type": "string", "required": false, "profile": "expanded", "sensitivity": "normal", "enum": ["residential", "business", "warehouse", "other"], "description": "Affects carrier options and, sometimes, surcharges." },
    { "path": "shipping.ship_to.street", "type": "string", "required": false, "profile": "expanded", "sensitivity": "personal", "description": "Street address." },
    { "path": "shipping.ship_to.city", "type": "string", "required": false, "profile": "expanded", "sensitivity": "personal", "description": "City." },
    { "path": "shipping.ship_to.region", "type": "string", "required": false, "profile": "expanded", "sensitivity": "personal", "description": "State / province / region." },
    { "path": "shipping.ship_to.postal_code", "type": "string", "required": false, "profile": "expanded", "sensitivity": "personal", "description": "Postal / ZIP code." },
    { "path": "shipping.ship_to.country", "type": "string", "required": false, "profile": "expanded", "sensitivity": "personal", "format": "iso-3166-1-alpha-2", "description": "Country code." },
    { "path": "shipping.incoterms", "type": "string", "required": false, "profile": "expanded", "sensitivity": "normal", "enum": ["EXW", "FCA", "CPT", "CIP", "DAP", "DPU", "DDP", "FAS", "FOB", "CFR", "CIF"], "description": "Delivery terms for (international) B2B (ICC Incoterms 2020)." },
    { "path": "shipping.selected_method_id", "type": "string", "required": false, "profile": "expanded", "sensitivity": "normal", "description": "id of the chosen method from available_methods." },
    { "path": "shipping.available_methods", "type": "array<object>", "required": false, "profile": "expanded", "sensitivity": "normal", "description": "All methods the merchant offered at capture time." },
    { "path": "shipping.available_methods[].id", "type": "string", "required": false, "profile": "expanded", "sensitivity": "normal", "description": "Stable identifier within this file (e.g. \"courier-48h\")." },
    { "path": "shipping.available_methods[].name", "type": "string", "required": false, "profile": "expanded", "sensitivity": "normal", "description": "Display name (\"Courier, 2 business days\")." },
    { "path": "shipping.available_methods[].cost_excl_tax", "type": "number", "required": false, "profile": "expanded", "sensitivity": "normal", "description": "Shipping cost before VAT / tax." },
    { "path": "shipping.available_methods[].cost_incl_tax", "type": "number", "required": false, "profile": "expanded", "sensitivity": "normal", "description": "Shipping cost after VAT / tax." },
    { "path": "shipping.available_methods[].estimated_delivery", "type": "string", "required": false, "profile": "expanded", "sensitivity": "normal", "description": "Free-text or ISO 8601 estimate." },

    { "path": "totals", "type": "object", "required": true, "profile": "core", "sensitivity": "normal", "description": "Cart-level monetary totals (all in currency)." },
    { "path": "totals.items_subtotal_excl_tax", "type": "number", "required": true, "profile": "expanded", "sensitivity": "normal", "description": "Sum of line totals before tax, before shipping." },
    { "path": "totals.items_subtotal_incl_tax", "type": "number", "required": true, "profile": "expanded", "sensitivity": "normal", "description": "Sum of line totals after tax, before shipping." },
    { "path": "totals.shipping_excl_tax", "type": "number", "required": false, "profile": "expanded", "sensitivity": "normal", "description": "Cost of the selected shipping method, before tax." },
    { "path": "totals.shipping_incl_tax", "type": "number", "required": false, "profile": "expanded", "sensitivity": "normal", "description": "Cost of the selected shipping method, after tax." },
    { "path": "totals.discount_total", "type": "number", "required": false, "profile": "expanded", "sensitivity": "normal", "description": "Cart-level discounts (already reflected in the grand total)." },
    { "path": "totals.tax_total", "type": "number", "required": true, "profile": "expanded", "sensitivity": "normal", "description": "Total VAT / tax across items and shipping." },
    { "path": "totals.grand_total", "type": "number", "required": true, "profile": "core", "sensitivity": "normal", "description": "Final amount: items + shipping - discounts, tax included." },
    { "path": "totals.amount_pending_payment", "type": "number", "required": true, "profile": "core", "sensitivity": "normal", "description": "Amount currently awaiting payment (usually equals grand_total; may differ with deposits / partial payments)." },

    { "path": "payment", "type": "object", "required": false, "profile": "expanded", "sensitivity": "normal", "description": "Payment status / expectations." },
    { "path": "payment.status", "type": "string", "required": false, "profile": "expanded", "sensitivity": "normal", "enum": ["cart", "quote_requested", "po_issued", "awaiting_payment", "partially_paid", "paid"], "description": "Lifecycle status of the cart / order." },
    { "path": "payment.method", "type": "string", "required": false, "profile": "expanded", "sensitivity": "normal", "description": "The payment method the buyer has selected or intends to use (a single value drawn from methods_accepted)." },
    { "path": "payment.terms", "type": "string", "required": false, "profile": "expanded", "sensitivity": "normal", "description": "Payment terms if known (e.g. \"net_30\", \"net_60\", \"prepaid\", \"cod\")." },
    { "path": "payment.methods_accepted", "type": "array<string>", "required": false, "profile": "expanded", "sensitivity": "normal", "description": "Methods the merchant offers (e.g. [\"credit_card\", \"bank_transfer\", \"purchase_order\"])." },
    { "path": "payment.reference", "type": "string", "required": false, "profile": "expanded", "sensitivity": "normal", "description": "Quote / PO / invoice reference once one exists." },
    { "path": "payment.card", "type": "object", "required": false, "profile": "expanded", "sensitivity": "sensitive", "notes": "Never store full PAN, CVV/CVC, PIN, or full expiry.", "description": "The payment card the buyer intends to use." },
    { "path": "payment.card.cardholder_name", "type": "string", "required": false, "profile": "expanded", "sensitivity": "sensitive", "description": "Name printed on the card." },
    { "path": "payment.card.is_business_card", "type": "boolean", "required": false, "profile": "expanded", "sensitivity": "normal", "description": "true if a business / corporate card, false for a personal card." },
    { "path": "payment.card.brand", "type": "string", "required": false, "profile": "expanded", "sensitivity": "normal", "description": "Card network if known (e.g. \"visa\", \"mastercard\", \"amex\")." },
    { "path": "payment.card.last4", "type": "string", "required": false, "profile": "expanded", "sensitivity": "sensitive", "description": "Last four digits, when a masked reference is needed to disambiguate which card." },

    { "path": "notes", "type": "string", "required": false, "profile": "expanded", "sensitivity": "normal", "description": "Free-text notes (human or agent authored)." },
    { "path": "extensions", "type": "object", "required": false, "profile": "expanded", "sensitivity": "normal", "description": "Namespaced vendor / tool-specific data. Consumers must preserve content they don't understand when re-writing a file." }
  ]
}