{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://docs.datashift.com.au/edi/contracts/releases/1.0.6/schemas/advance-shipping-notice.schema.json",
  "title": "Advance Ship Notice (ASN) Canonical Schema",
  "description": "Public canonical Advance Shipping Notice contract used to describe goods shipped against one or more purchase orders.",
  "version": "1.0.6",
  "type": "object",
  "required": [
    "docType",
    "correlationId",
    "timestamp",
    "metadata",
    "data"
  ],
  "properties": {
    "docType": {
      "const": "ASN",
      "x-datashift-managed": true,
      "x-datashift-system": true,
      "description": "Canonical document type. For advance shipping notices this value is ASN.",
      "x-order": 1
    },
    "correlationId": {
      "type": "string",
      "format": "uuid",
      "x-datashift-managed": true,
      "x-datashift-system": true,
      "description": "Stable UUID used to trace this shipment notice through fulfilment and invoice workflows.",
      "x-order": 2
    },
    "timestamp": {
      "type": "string",
      "format": "date-time",
      "description": "UTC timestamp indicating when DataShift created the canonical shipment notice.",
      "x-datashift-managed": true,
      "x-datashift-system": true,
      "x-order": 3
    },
    "metadata": {
      "type": "object",
      "description": "Public source metadata retained for integration troubleshooting.",
      "required": [
        "sourceLanguage",
        "sourceVersion",
        "userAgent"
      ],
      "properties": {
        "sourceLanguage": {
          "type": "string",
          "enum": [
            "json",
            "cxml"
          ],
          "x-order": 1
        },
        "sourceVersion": {
          "const": "1.0.6",
          "description": "Canonical schema version used to create this document",
          "x-order": 2
        },
        "payloadId": {
          "type": "string",
          "description": "Original cXML payload ID",
          "x-order": 3
        },
        "userAgent": {
          "const": "DataShift Edge v1",
          "description": "DataShift Edge version that generated the canonical document",
          "x-order": 4
        }
      },
      "additionalProperties": false,
      "x-order": 4
    },
    "data": {
      "type": "object",
      "required": [
        "dispatchAdviceNumber",
        "poNumber",
        "noticeDate",
        "shipmentDate",
        "carrier",
        "shipFrom",
        "shipTo",
        "lineItems"
      ],
      "properties": {
        "dispatchAdviceNumber": {
          "type": "string",
          "description": "Supplier-assigned shipment or dispatch advice identifier.",
          "x-order": 1
        },
        "poNumber": {
          "type": "string",
          "description": "Primary purchase order number this shipment fulfils.",
          "x-order": 2
        },
        "operation": {
          "type": "string",
          "enum": [
            "new",
            "update",
            "delete"
          ],
          "default": "new",
          "description": "Whether this is a new shipment notice, an update, or a cancellation",
          "x-order": 3
        },
        "noticeDate": {
          "type": "string",
          "format": "date-time",
          "description": "Date and time the supplier created the shipment notice.",
          "x-order": 4
        },
        "shipmentDate": {
          "type": "string",
          "format": "date-time",
          "description": "Date and time the goods left the supplier.",
          "x-order": 5
        },
        "deliveryDate": {
          "type": "string",
          "format": "date-time",
          "description": "Expected delivery date and time.",
          "x-order": 6
        },
        "requestedDeliveryDate": {
          "type": "string",
          "format": "date-time",
          "description": "Buyer's originally requested delivery date",
          "x-order": 7
        },
        "shipmentType": {
          "type": "string",
          "enum": [
            "actual",
            "planned"
          ],
          "description": "Whether this is an actual shipment or a planned/estimated one",
          "x-order": 8
        },
        "fulfillmentType": {
          "type": "string",
          "enum": [
            "partial",
            "complete"
          ],
          "description": "Whether this shipment fulfils all or part of the referenced order.",
          "x-enum-descriptions": {
            "partial": "The shipment fulfils part of the referenced order.",
            "complete": "The shipment fulfils the referenced order in full."
          },
          "x-order": 9
        },
        "serviceLevel": {
          "type": "string",
          "description": "Level of shipping service (e.g., overnight, ground, express)",
          "x-order": 10
        },
        "documentReference": {
          "type": "object",
          "description": "Reference to previous ship notice (required for operation=update/delete)",
          "properties": {
            "documentId": {
              "type": "string",
              "x-order": 1
            },
            "payloadId": {
              "type": "string",
              "x-order": 2
            }
          },
          "additionalProperties": false,
          "x-order": 11
        },
        "poReferences": {
          "type": "array",
          "description": "References to purchase orders being fulfilled by this shipment",
          "items": {
            "type": "object",
            "required": [
              "poNumber"
            ],
            "properties": {
              "poNumber": {
                "type": "string",
                "x-order": 1
              },
              "poVersion": {
                "type": "string",
                "x-order": 2
              },
              "documentId": {
                "type": "string",
                "x-order": 3
              },
              "payloadId": {
                "type": "string",
                "x-order": 4
              },
              "orderDate": {
                "type": "string",
                "format": "date-time",
                "x-order": 5
              }
            },
            "additionalProperties": false
          },
          "x-order": 12
        },
        "carrier": {
          "type": "object",
          "required": [
            "name"
          ],
          "description": "Carrier and service details for the shipment.",
          "properties": {
            "name": {
              "type": "string",
              "description": "Carrier company name",
              "x-order": 1
            },
            "identifiers": {
              "type": "array",
              "description": "Carrier identification codes",
              "items": {
                "type": "object",
                "required": [
                  "domain",
                  "value"
                ],
                "properties": {
                  "domain": {
                    "type": "string",
                    "enum": [
                      "SCAC",
                      "IATA",
                      "AAR",
                      "UIC",
                      "EAN",
                      "DUNS",
                      "companyName"
                    ],
                    "description": "Domain/type of identifier",
                    "x-order": 1
                  },
                  "value": {
                    "type": "string",
                    "x-order": 2
                  }
                },
                "additionalProperties": false
              },
              "x-order": 2
            },
            "serviceType": {
              "type": "string",
              "description": "Type of shipping service",
              "x-order": 3
            }
          },
          "additionalProperties": false,
          "x-order": 13
        },
        "shipmentIdentifiers": {
          "type": "array",
          "description": "Tracking numbers and shipment identifiers (consignment note, bill of lading, etc.)",
          "items": {
            "type": "object",
            "required": [
              "domain",
              "value"
            ],
            "properties": {
              "domain": {
                "type": "string",
                "enum": [
                  "trackingNumber",
                  "billOfLading",
                  "proNumber",
                  "airWaybill",
                  "containerNumber"
                ],
                "description": "Type of shipment identifier",
                "x-order": 1
              },
              "value": {
                "type": "string",
                "x-order": 2
              }
            },
            "additionalProperties": false
          },
          "x-order": 14
        },
        "termsOfDelivery": {
          "type": "object",
          "description": "Delivery terms and conditions",
          "properties": {
            "incoTerms": {
              "type": "string",
              "enum": [
                "cfr",
                "cif",
                "cip",
                "cpt",
                "daf",
                "dap",
                "ddp",
                "ddu",
                "dpu",
                "deq",
                "des",
                "exw",
                "fas",
                "fca",
                "fob"
              ],
              "description": "International Commercial Terms",
              "x-order": 1
            },
            "fobPoint": {
              "type": "string",
              "x-order": 2
            },
            "description": {
              "type": "string",
              "x-order": 3
            }
          },
          "additionalProperties": false,
          "x-order": 15
        },
        "shipFrom": {
          "title": "Address Definition",
          "description": "Shipment origin.",
          "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": 16
        },
        "shipTo": {
          "title": "Address Definition",
          "description": "Shipment destination.",
          "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": 17
        },
        "contacts": {
          "type": "array",
          "description": "Contact information for various roles",
          "items": {
            "type": "object",
            "required": [
              "role"
            ],
            "properties": {
              "role": {
                "type": "string",
                "enum": [
                  "shipFrom",
                  "shipTo",
                  "carrierCorporate",
                  "technicalSupport",
                  "customerService"
                ],
                "x-order": 1
              },
              "name": {
                "type": "string",
                "x-order": 2
              },
              "email": {
                "type": "string",
                "anyOf": [
                  {
                    "format": "email"
                  },
                  {
                    "const": ""
                  }
                ],
                "x-order": 3
              },
              "phone": {
                "type": "string",
                "x-order": 4
              }
            },
            "additionalProperties": false
          },
          "x-order": 18
        },
        "comments": {
          "type": "string",
          "maxLength": 2000,
          "description": "Human-readable notes about this shipment",
          "x-order": 19
        },
        "reason": {
          "type": "string",
          "enum": [
            "return"
          ],
          "description": "Reason for shipment if not a standard delivery (e.g., return)",
          "x-order": 20
        },
        "lineItems": {
          "type": "array",
          "minItems": 1,
          "description": "Authoritative shipped line data. Packages reference these lines; they do not replace them. DataShift manages uniqueLineKey correlation where needed.",
          "items": {
            "type": "object",
            "required": [
              "quantity"
            ],
            "properties": {
              "lineNumber": {
                "type": "integer",
                "description": "Line number from the purchase order being fulfilled.",
                "x-order": 1
              },
              "shipNoticeLineNumber": {
                "type": "integer",
                "description": "Sequence number of this line within the ship notice",
                "x-order": 2
              },
              "uniqueLineKey": {
                "type": "string",
                "description": "DataShift-managed stable line key from the original purchase order, used by internal connectors for cross-document correlation.",
                "x-datashift-managed": true,
                "x-datashift-system": true,
                "x-order": 3
              },
              "supplierItemId": {
                "type": "string",
                "description": "Supplier's part or item number",
                "x-order": 4
              },
              "buyerItemId": {
                "type": "string",
                "description": "Buyer's part or item number",
                "x-order": 5
              },
              "gtin": {
                "type": "string",
                "description": "GS1 Global Trade Item Number",
                "x-order": 6
              },
              "description": {
                "type": "string",
                "description": "Item description",
                "x-order": 7
              },
              "quantity": {
                "type": "number",
                "multipleOf": 0.01,
                "description": "Quantity shipped on this line.",
                "x-order": 8
              },
              "unitOfMeasure": {
                "title": "REC20 Unit of Measure Codes",
                "description": "UN/ECE REC20 unit of measure code",
                "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": 9
              },
              "countryOfOrigin": {
                "type": "string",
                "enum": [
                  "AU"
                ],
                "description": "Country where the item was manufactured",
                "x-order": 10
              },
              "batchInfo": {
                "type": "object",
                "description": "Lot or batch tracking information",
                "properties": {
                  "batchId": {
                    "type": "string",
                    "x-order": 1
                  },
                  "productionDate": {
                    "type": "string",
                    "format": "date",
                    "x-order": 2
                  },
                  "expirationDate": {
                    "type": "string",
                    "format": "date",
                    "x-order": 3
                  }
                },
                "additionalProperties": false,
                "x-order": 11
              },
              "serialNumbers": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Serial numbers for individually serialised items",
                "x-order": 12
              }
            },
            "additionalProperties": false
          },
          "x-order": 21
        },
        "packages": {
          "type": "array",
          "description": "Physical package or carton detail used for carton allocation and SSCC labelling.",
          "items": {
            "type": "object",
            "required": [
              "packageId"
            ],
            "properties": {
              "packageId": {
                "type": "string",
                "description": "Supplier or warehouse package identifier unique within this shipment.",
                "x-order": 1
              },
              "sscc": {
                "type": "string",
                "pattern": "^[0-9]{18}$",
                "description": "Serial Shipping Container Code for the carton or logistic unit.",
                "x-order": 2
              },
              "packagingCode": {
                "type": "string",
                "description": "Type of packaging (e.g., BOX, PAL, CTN)",
                "x-order": 3
              },
              "grossWeight": {
                "type": "object",
                "description": "Total weight of package including contents",
                "properties": {
                  "value": {
                    "type": "number",
                    "multipleOf": 0.001,
                    "x-order": 1
                  },
                  "unit": {
                    "type": "string",
                    "enum": [
                      "KG",
                      "LB",
                      "OZ",
                      "G"
                    ],
                    "x-order": 2
                  }
                },
                "additionalProperties": false,
                "x-order": 4
              },
              "netWeight": {
                "type": "object",
                "description": "Weight of contents only",
                "properties": {
                  "value": {
                    "type": "number",
                    "multipleOf": 0.001,
                    "x-order": 1
                  },
                  "unit": {
                    "type": "string",
                    "enum": [
                      "KG",
                      "LB",
                      "OZ",
                      "G"
                    ],
                    "x-order": 2
                  }
                },
                "additionalProperties": false,
                "x-order": 5
              },
              "dimensions": {
                "type": "object",
                "description": "Physical dimensions of the package",
                "properties": {
                  "length": {
                    "type": "number",
                    "multipleOf": 0.01,
                    "x-order": 1
                  },
                  "width": {
                    "type": "number",
                    "multipleOf": 0.01,
                    "x-order": 2
                  },
                  "height": {
                    "type": "number",
                    "multipleOf": 0.01,
                    "x-order": 3
                  },
                  "unit": {
                    "type": "string",
                    "enum": [
                      "CM",
                      "IN",
                      "M",
                      "FT"
                    ],
                    "x-order": 4
                  }
                },
                "additionalProperties": false,
                "x-order": 6
              },
              "lineReferences": {
                "type": "array",
                "description": "References to authoritative lineItems packed inside this package.",
                "items": {
                  "type": "object",
                  "required": [
                    "quantity"
                  ],
                  "anyOf": [
                    {
                      "required": [
                        "lineNumber"
                      ]
                    },
                    {
                      "required": [
                        "uniqueLineKey"
                      ]
                    }
                  ],
                  "properties": {
                    "lineNumber": {
                      "type": "integer",
                      "x-order": 1
                    },
                    "uniqueLineKey": {
                      "type": "string",
                      "description": "DataShift-managed line key from the original purchase order for internal connector correlation",
                      "x-datashift-managed": true,
                      "x-datashift-system": true,
                      "x-order": 2
                    },
                    "quantity": {
                      "type": "number",
                      "multipleOf": 0.01,
                      "description": "Quantity of this line item packed in this carton",
                      "x-order": 3
                    },
                    "unitOfMeasure": {
                      "title": "REC20 Unit of Measure Codes",
                      "description": "Unit of measure for the quantity — must match the parent line item's unitOfMeasure",
                      "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": 4
                    }
                  },
                  "additionalProperties": false
                },
                "x-order": 7
              }
            },
            "additionalProperties": false
          },
          "x-order": 22
        },
        "hazardInfo": {
          "type": "array",
          "description": "Hazardous materials information",
          "items": {
            "type": "object",
            "properties": {
              "unNumber": {
                "type": "string",
                "x-order": 1
              },
              "hazardClass": {
                "type": "string",
                "x-order": 2
              },
              "description": {
                "type": "string",
                "x-order": 3
              }
            },
            "additionalProperties": false
          },
          "x-order": 23
        },
        "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": 24
        }
      },
      "additionalProperties": false,
      "description": "Business payload for the shipment notice.",
      "x-order": 5
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "docType": "ASN",
      "correlationId": "cab103da-1713-4976-80c4-f1b47f62b523",
      "timestamp": "2026-05-16T02:00:00Z",
      "metadata": {
        "sourceLanguage": "cxml",
        "sourceVersion": "1.0.6",
        "payloadId": "asn-example-10001",
        "userAgent": "DataShift Edge v1"
      },
      "data": {
        "dispatchAdviceNumber": "ASN-10001",
        "poNumber": "PO-10001",
        "noticeDate": "2026-05-16T02:00:00Z",
        "shipmentDate": "2026-05-16T03:00:00Z",
        "deliveryDate": "2026-05-23T00:00:00Z",
        "fulfillmentType": "partial",
        "carrier": {
          "name": "Example Freight",
          "serviceType": "Road"
        },
        "shipFrom": {
          "addressee": "Example Supplier Warehouse",
          "street1": "20 Supplier Street",
          "city": "Adelaide",
          "state": "SA",
          "postalCode": "5000",
          "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",
            "quantity": 6,
            "unitOfMeasure": "EA"
          }
        ],
        "packages": [
          {
            "packageId": "CARTON-1",
            "sscc": "193123456789012345",
            "lineReferences": [
              {
                "uniqueLineKey": "PO-10001-1",
                "quantity": 6,
                "unitOfMeasure": "EA"
              }
            ]
          }
        ],
        "extrinsics": {
          "warehouseWave": "WAVE-42"
        }
      }
    }
  ]
}