{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://docs.datashift.com.au/edi/contracts/releases/1.0.6/schemas/purchase-order.schema.json",
  "title": "Purchase Order (PO) Canonical Schema",
  "description": "Public canonical Purchase Order contract used to represent a buyer's order before acknowledgement, shipment, and invoice events.",
  "version": "1.0.6",
  "type": "object",
  "required": [
    "docType",
    "correlationId",
    "timestamp",
    "metadata",
    "data"
  ],
  "properties": {
    "docType": {
      "const": "PO",
      "x-datashift-managed": true,
      "x-datashift-system": true,
      "description": "Canonical document type. For purchase orders this value is PO.",
      "x-order": 1
    },
    "correlationId": {
      "type": "string",
      "format": "uuid",
      "description": "Stable UUID used to trace this purchase order through downstream acknowledgements, shipments, invoices, and support workflows.",
      "x-datashift-managed": true,
      "x-datashift-system": true,
      "x-order": 2
    },
    "timestamp": {
      "type": "string",
      "format": "date-time",
      "description": "UTC timestamp indicating when DataShift created the canonical document.",
      "x-datashift-managed": true,
      "x-datashift-system": true,
      "x-order": 3
    },
    "metadata": {
      "type": "object",
      "description": "Public source metadata retained for integration troubleshooting without exposing tenant or credential details.",
      "required": [
        "sourceLanguage",
        "sourceVersion",
        "userAgent"
      ],
      "properties": {
        "sourceLanguage": {
          "type": "string",
          "enum": [
            "json",
            "cxml"
          ],
          "x-order": 1
        },
        "sourceVersion": {
          "type": "string",
          "x-order": 2
        },
        "payloadId": {
          "type": "string",
          "description": "Original cXML payload ID",
          "x-order": 3
        },
        "userAgent": {
          "type": "string",
          "description": "System that generated the document",
          "x-order": 4
        }
      },
      "additionalProperties": false,
      "x-order": 4
    },
    "data": {
      "type": "object",
      "required": [
        "poNumber",
        "poVersion",
        "operation",
        "orderDate",
        "requestedDeliveryDate",
        "buyer",
        "supplier",
        "billTo",
        "shipTo",
        "lineItems",
        "orderTotals"
      ],
      "properties": {
        "poNumber": {
          "type": "string",
          "description": "Buyer-issued purchase order number. Use this as the primary business reference.",
          "x-order": 1
        },
        "poVersion": {
          "type": "string",
          "description": "Buyer-issued version or revision for this purchase order.",
          "x-order": 2
        },
        "operation": {
          "type": "string",
          "enum": [
            "new",
            "update",
            "delete"
          ],
          "description": "Standard document operation. Legacy PO change requests map to update.",
          "x-enum-descriptions": {
            "new": "Creates a new purchase order.",
            "update": "Updates a previously issued purchase order.",
            "delete": "Deletes or cancels a previously issued purchase order."
          },
          "x-order": 3
        },
        "orderType": {
          "type": "string",
          "enum": [
            "regular",
            "blanket",
            "release",
            "standing"
          ],
          "description": "Type of purchase order",
          "x-order": 4
        },
        "orderDate": {
          "type": "string",
          "format": "date-time",
          "description": "Date and time the buyer issued the order.",
          "x-order": 5
        },
        "requestedDeliveryDate": {
          "type": "string",
          "format": "date-time",
          "description": "Buyer-requested delivery date for the order.",
          "x-order": 6
        },
        "comments": {
          "type": "string",
          "description": "General order comments or instructions",
          "x-order": 7
        },
        "dropship": {
          "type": "boolean",
          "description": "Indicates if this is a direct ship/dropship order. When true, shipping address should be included in outbound mappings (e.g., NetSuite sales orders).",
          "x-order": 8
        },
        "buyer": {
          "title": "Party Definition",
          "description": "Party placing the order.",
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "x-order": 1
            },
            "name": {
              "type": "string",
              "x-order": 2
            },
            "taxRegistrations": {
              "type": "object",
              "description": "Australian tax registrations for the party",
              "required": [
                "type",
                "value"
              ],
              "properties": {
                "type": {
                  "type": "string",
                  "enum": [
                    "ABN"
                  ],
                  "x-order": 1
                },
                "value": {
                  "type": "string",
                  "x-order": 2
                }
              },
              "additionalProperties": false,
              "x-order": 3
            },
            "contact": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string",
                  "x-order": 1
                },
                "phone": {
                  "type": "string",
                  "x-order": 2
                },
                "email": {
                  "type": "string",
                  "anyOf": [
                    {
                      "format": "email"
                    },
                    {
                      "const": ""
                    }
                  ],
                  "x-order": 3
                },
                "role": {
                  "type": "string",
                  "x-order": 4
                }
              },
              "additionalProperties": false,
              "x-order": 4
            },
            "address": {
              "title": "Address Definition",
              "description": "Standard address structure for DataShift canonical documents",
              "type": "object",
              "properties": {
                "addressId": {
                  "type": "string",
                  "x-order": 1
                },
                "addressee": {
                  "type": "string",
                  "x-order": 2
                },
                "street1": {
                  "type": "string",
                  "x-order": 3
                },
                "street2": {
                  "type": "string",
                  "x-order": 4
                },
                "city": {
                  "type": "string",
                  "x-order": 5
                },
                "state": {
                  "type": "string",
                  "x-order": 6
                },
                "postalCode": {
                  "type": "string",
                  "x-order": 7
                },
                "country": {
                  "type": "string",
                  "enum": [
                    "AU"
                  ],
                  "x-order": 8
                }
              },
              "required": [
                "street1",
                "city",
                "state",
                "postalCode",
                "country"
              ],
              "additionalProperties": false,
              "x-order": 5
            }
          },
          "required": [
            "id",
            "name"
          ],
          "additionalProperties": false,
          "x-order": 9
        },
        "supplier": {
          "title": "Party Definition",
          "description": "Party expected to fulfil the order.",
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "x-order": 1
            },
            "name": {
              "type": "string",
              "x-order": 2
            },
            "taxRegistrations": {
              "type": "object",
              "description": "Australian tax registrations for the party",
              "required": [
                "type",
                "value"
              ],
              "properties": {
                "type": {
                  "type": "string",
                  "enum": [
                    "ABN"
                  ],
                  "x-order": 1
                },
                "value": {
                  "type": "string",
                  "x-order": 2
                }
              },
              "additionalProperties": false,
              "x-order": 3
            },
            "contact": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string",
                  "x-order": 1
                },
                "phone": {
                  "type": "string",
                  "x-order": 2
                },
                "email": {
                  "type": "string",
                  "anyOf": [
                    {
                      "format": "email"
                    },
                    {
                      "const": ""
                    }
                  ],
                  "x-order": 3
                },
                "role": {
                  "type": "string",
                  "x-order": 4
                }
              },
              "additionalProperties": false,
              "x-order": 4
            },
            "address": {
              "title": "Address Definition",
              "description": "Standard address structure for DataShift canonical documents",
              "type": "object",
              "properties": {
                "addressId": {
                  "type": "string",
                  "x-order": 1
                },
                "addressee": {
                  "type": "string",
                  "x-order": 2
                },
                "street1": {
                  "type": "string",
                  "x-order": 3
                },
                "street2": {
                  "type": "string",
                  "x-order": 4
                },
                "city": {
                  "type": "string",
                  "x-order": 5
                },
                "state": {
                  "type": "string",
                  "x-order": 6
                },
                "postalCode": {
                  "type": "string",
                  "x-order": 7
                },
                "country": {
                  "type": "string",
                  "enum": [
                    "AU"
                  ],
                  "x-order": 8
                }
              },
              "required": [
                "street1",
                "city",
                "state",
                "postalCode",
                "country"
              ],
              "additionalProperties": false,
              "x-order": 5
            }
          },
          "required": [
            "id",
            "name"
          ],
          "additionalProperties": false,
          "x-order": 10
        },
        "billTo": {
          "title": "Address Definition",
          "description": "Billing destination supplied by the buyer.",
          "type": "object",
          "properties": {
            "addressId": {
              "type": "string",
              "x-order": 1
            },
            "addressee": {
              "type": "string",
              "x-order": 2
            },
            "street1": {
              "type": "string",
              "x-order": 3
            },
            "street2": {
              "type": "string",
              "x-order": 4
            },
            "city": {
              "type": "string",
              "x-order": 5
            },
            "state": {
              "type": "string",
              "x-order": 6
            },
            "postalCode": {
              "type": "string",
              "x-order": 7
            },
            "country": {
              "type": "string",
              "enum": [
                "AU"
              ],
              "x-order": 8
            }
          },
          "required": [
            "street1",
            "city",
            "state",
            "postalCode",
            "country"
          ],
          "additionalProperties": false,
          "x-order": 11
        },
        "shipTo": {
          "title": "Address Definition",
          "description": "Delivery destination for the ordered goods.",
          "type": "object",
          "properties": {
            "addressId": {
              "type": "string",
              "x-order": 1
            },
            "addressee": {
              "type": "string",
              "x-order": 2
            },
            "street1": {
              "type": "string",
              "x-order": 3
            },
            "street2": {
              "type": "string",
              "x-order": 4
            },
            "city": {
              "type": "string",
              "x-order": 5
            },
            "state": {
              "type": "string",
              "x-order": 6
            },
            "postalCode": {
              "type": "string",
              "x-order": 7
            },
            "country": {
              "type": "string",
              "enum": [
                "AU"
              ],
              "x-order": 8
            }
          },
          "required": [
            "street1",
            "city",
            "state",
            "postalCode",
            "country"
          ],
          "additionalProperties": false,
          "x-order": 12
        },
        "shipping": {
          "type": "object",
          "description": "Commercial freight charges and instructions.",
          "properties": {
            "amount": {
              "type": "number",
              "multipleOf": 0.01,
              "x-order": 1
            },
            "currency": {
              "title": "Currency Enumeration",
              "description": "ISO 4217 currency codes supported by DataShift canonical schemas",
              "type": "string",
              "enum": [
                "AUD"
              ],
              "x-order": 2
            },
            "carrier": {
              "type": "string",
              "x-order": 3
            },
            "route": {
              "type": "string",
              "description": "Shipping route method",
              "x-order": 4
            },
            "shippingInstructions": {
              "type": "string",
              "description": "Detailed shipping instructions",
              "x-order": 5
            },
            "buyerAcctNumber": {
              "type": "string",
              "x-order": 6
            },
            "incoTerms": {
              "type": "string",
              "enum": [
                "cfr",
                "cif",
                "cip",
                "cpt",
                "daf",
                "dap",
                "ddp",
                "ddu",
                "dpu",
                "deq",
                "des",
                "exw",
                "fas",
                "fca",
                "fob"
              ],
              "x-order": 7
            }
          },
          "additionalProperties": false,
          "x-order": 13
        },
        "lineItems": {
          "type": "array",
          "minItems": 1,
          "description": "Ordered product lines. DataShift manages uniqueLineKey for cross-document line correlation where needed.",
          "items": {
            "type": "object",
            "required": [
              "lineNumber",
              "supplierItemId",
              "buyerItemId",
              "quantity",
              "unitOfMeasure",
              "unitPrice",
              "currency",
              "lineAmountExTax",
              "lineAmountInclTax"
            ],
            "properties": {
              "lineNumber": {
                "type": "integer",
                "description": "Buyer line number from the purchase order.",
                "x-order": 1
              },
              "uniqueLineKey": {
                "type": "string",
                "description": "DataShift-managed stable line key used by DataShift connectors to correlate PO, POA, ASN, and INV lines.",
                "x-datashift-managed": true,
                "x-datashift-system": true,
                "x-order": 2
              },
              "supplierItemId": {
                "type": "string",
                "x-order": 3
              },
              "supplierItemAuxiliaryId": {
                "type": "string",
                "description": "Supplier's alternate/auxiliary part ID",
                "x-order": 4
              },
              "buyerItemId": {
                "type": "string",
                "x-order": 5
              },
              "description": {
                "type": "string",
                "x-order": 6
              },
              "quantity": {
                "type": "number",
                "multipleOf": 0.01,
                "description": "Ordered quantity for this line.",
                "x-order": 7
              },
              "unitOfMeasure": {
                "title": "REC20 Unit of Measure Codes",
                "description": "Unit of measure code for the ordered quantity.",
                "type": "string",
                "enum": [
                  "AY",
                  "BG",
                  "BL",
                  "BR",
                  "BLL",
                  "E2",
                  "BO",
                  "BX",
                  "BJ",
                  "BE",
                  "KA",
                  "CA",
                  "CG",
                  "CT",
                  "CQ",
                  "CS",
                  "CMT",
                  "CL",
                  "CH",
                  "MTQ",
                  "CY",
                  "DAY",
                  "DC",
                  "DZN",
                  "DR",
                  "EA",
                  "FOT",
                  "GRM",
                  "HUR",
                  "CEN",
                  "INH",
                  "JR",
                  "KGM",
                  "KMT",
                  "KT",
                  "LN",
                  "LK",
                  "LTR",
                  "MTR",
                  "TNE",
                  "MLT",
                  "MMT",
                  "MON",
                  "PK",
                  "PD",
                  "PL",
                  "PR",
                  "D97",
                  "C62",
                  "PG",
                  "LBR",
                  "RL",
                  "RO",
                  "SA",
                  "SE",
                  "SET",
                  "ST",
                  "SO",
                  "MTK",
                  "U3",
                  "MIL",
                  "TU",
                  "WEE"
                ],
                "x-order": 8
              },
              "unitPrice": {
                "type": "number",
                "x-order": 9
              },
              "currency": {
                "title": "Currency Enumeration",
                "description": "ISO 4217 currency code for line pricing.",
                "type": "string",
                "enum": [
                  "AUD"
                ],
                "x-order": 10
              },
              "lineAmountExTax": {
                "type": "number",
                "x-order": 11
              },
              "lineAmountInclTax": {
                "type": "number",
                "x-order": 12
              },
              "requestedDeliveryDate": {
                "type": "string",
                "format": "date-time",
                "x-order": 13
              },
              "priceBasisQuantityQuantity": {
                "type": "number",
                "description": "Price basis quantity",
                "x-order": 14
              },
              "priceBasisQuantityConversionFactor": {
                "type": "number",
                "description": "Price basis conversion factor",
                "x-order": 15
              },
              "priceBasisQuantityUnitOfMeasure": {
                "type": "string",
                "description": "Price basis unit of measure",
                "x-order": 16
              },
              "classificationDomain": {
                "type": "string",
                "description": "Product classification domain",
                "x-order": 17
              },
              "classificationCode": {
                "type": "string",
                "description": "Product classification code",
                "x-order": 18
              },
              "comments": {
                "type": "string",
                "description": "Line item specific comments",
                "x-order": 19
              }
            },
            "additionalProperties": false
          },
          "x-order": 14
        },
        "orderTotals": {
          "type": "object",
          "required": [
            "subtotal",
            "taxAmount",
            "totalAmount",
            "currency"
          ],
          "properties": {
            "subtotal": {
              "type": "number",
              "x-order": 1
            },
            "taxAmount": {
              "type": "number",
              "x-order": 2
            },
            "totalAmount": {
              "type": "number",
              "x-order": 3
            },
            "currency": {
              "title": "Currency Enumeration",
              "description": "ISO 4217 currency codes supported by DataShift canonical schemas",
              "type": "string",
              "enum": [
                "AUD"
              ],
              "x-order": 4
            }
          },
          "additionalProperties": false,
          "description": "Order-level subtotal, tax, and total amounts.",
          "x-order": 15
        },
        "extrinsics": {
          "type": "object",
          "description": "Partner-specific extension fields that are not part of the canonical core contract.",
          "additionalProperties": {
            "x-additionalPropertiesName": "extensionField",
            "description": "Partner-specific extension value."
          },
          "x-order": 16
        }
      },
      "additionalProperties": false,
      "description": "Business payload for the purchase order.",
      "x-order": 5
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "docType": "PO",
      "correlationId": "8d359a0f-3e5a-4d36-a87c-f2748b1d6b43",
      "timestamp": "2026-05-16T00:00:00Z",
      "metadata": {
        "sourceLanguage": "cxml",
        "sourceVersion": "1.2.067",
        "payloadId": "po-example-10001",
        "userAgent": "Example Supplier Gateway"
      },
      "data": {
        "poNumber": "PO-10001",
        "poVersion": "1",
        "operation": "new",
        "orderDate": "2026-05-16T00:00:00Z",
        "requestedDeliveryDate": "2026-05-23T00:00:00Z",
        "buyer": {
          "id": "BUYER-AU",
          "name": "Example Buyer Pty Ltd",
          "taxRegistrations": {
            "type": "ABN",
            "value": "12345678901"
          }
        },
        "supplier": {
          "id": "SUPPLIER-AU",
          "name": "Example Supplier Pty Ltd",
          "taxRegistrations": {
            "type": "ABN",
            "value": "98765432109"
          }
        },
        "billTo": {
          "addressee": "Example Buyer Accounts",
          "street1": "1 Market Street",
          "city": "Sydney",
          "state": "NSW",
          "postalCode": "2000",
          "country": "AU"
        },
        "shipTo": {
          "addressee": "Example Distribution Centre",
          "street1": "10 Warehouse Road",
          "city": "Melbourne",
          "state": "VIC",
          "postalCode": "3000",
          "country": "AU"
        },
        "lineItems": [
          {
            "lineNumber": 1,
            "uniqueLineKey": "PO-10001-1",
            "supplierItemId": "SUP-001",
            "buyerItemId": "BUY-001",
            "description": "Example product",
            "quantity": 12,
            "unitOfMeasure": "EA",
            "unitPrice": 25,
            "currency": "AUD",
            "lineAmountExTax": 300,
            "lineAmountInclTax": 330
          }
        ],
        "orderTotals": {
          "subtotal": 300,
          "taxAmount": 30,
          "totalAmount": 330,
          "currency": "AUD"
        },
        "extrinsics": {
          "department": "Operations"
        }
      }
    }
  ]
}