{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://docs.datashift.com.au/edi/schemas/v1/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":"2.0.0","type":"object","required":["docType","correlationId","timestamp","metadata","data"],"properties":{"docType":{"description":"Canonical document type. For advance shipping notices this value is ASN.","x-order":1},"correlationId":{"type":"string","format":"uuid","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-order":3},"metadata":{"type":"object","required":["sourceLanguage","sourceVersion"],"properties":{"sourceLanguage":{"type":"string","enum":["json","cxml"],"x-order":1},"sourceVersion":{"type":"string","x-order":2}},"additionalProperties":false,"description":"Public source metadata retained for integration troubleshooting.","x-order":4},"data":{"type":"object","required":["dispatchAdviceNumber","noticeDate","shipmentDate","carrier","shipFrom","shipTo","lineItems"],"properties":{"dispatchAdviceNumber":{"type":"string","description":"Supplier-assigned shipment or dispatch advice identifier.","x-order":1},"operation":{"type":"string","enum":["new","update","delete"],"default":"new","description":"Whether this is a new shipment notice, an update, or a cancellation","x-order":2},"noticeDate":{"type":"string","format":"date-time","description":"Date and time the supplier created the shipment notice.","x-order":3},"shipmentDate":{"type":"string","format":"date-time","description":"Date and time the goods left the supplier.","x-order":4},"deliveryDate":{"type":"string","format":"date-time","description":"Expected delivery date and time.","x-order":5},"requestedDeliveryDate":{"type":"string","format":"date-time","description":"Buyer's originally requested delivery date","x-order":6},"shipmentType":{"type":"string","enum":["actual","planned"],"description":"Whether this is an actual shipment or a planned/estimated one","x-order":7},"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":8},"serviceLevel":{"type":"string","description":"Level of shipping service (e.g., overnight, ground, express)","x-order":9},"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":10},"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":11},"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":12},"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":13},"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","fis"],"description":"International Commercial Terms","x-order":1},"fobPoint":{"type":"string","x-order":2},"description":{"type":"string","x-order":3}},"additionalProperties":false,"x-order":14},"shipFrom":{"description":"Shipment origin.","x-order":15},"shipTo":{"description":"Shipment destination.","x-order":16},"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","format":"email","x-order":3},"phone":{"type":"string","x-order":4}},"additionalProperties":false},"x-order":17},"comments":{"type":"string","maxLength":2000,"description":"Human-readable notes about this shipment","x-order":18},"reason":{"type":"string","enum":["return"],"description":"Reason for shipment if not a standard delivery (e.g., return)","x-order":19},"lineItems":{"type":"array","minItems":1,"description":"Authoritative shipped line data. Packages reference these lines; they do not replace them.","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":"Stable DataShift line key from the original purchase order. This must reference the original line's uniqueLineKey found in the PurchaseOrder document for proper correlation. If the original document did not provide a uniqueLineKey, an exception will be raised during processing, forcing the user to manually correlate the line or update the shipment notice with the correct uniqueLineKey.","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":{"description":"UN/ECE REC20 unit of measure code","x-order":9},"poNumber":{"type":"string","description":"Purchase order number this shipped line fulfils.","x-order":10},"countryOfOrigin":{"type":"string","description":"Country where the item was manufactured","x-order":11},"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":12},"serialNumbers":{"type":"array","items":{"type":"string"},"description":"Serial numbers for individually serialised items","x-order":13}},"additionalProperties":false},"x-order":20},"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","x-order":2},"quantity":{"type":"number","multipleOf":0.01,"description":"Quantity of this line item packed in this carton","x-order":3},"unitOfMeasure":{"description":"Unit of measure for the quantity — must match the parent line item's unitOfMeasure","x-order":4}},"additionalProperties":false},"x-order":7}},"additionalProperties":false},"x-order":21},"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":22},"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":23}},"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.2.067"},"data":{"dispatchAdviceNumber":"ASN-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":{"name":"Example Supplier Warehouse"},"shipTo":{"name":"Example Distribution Centre"},"lineItems":[{"lineNumber":1,"uniqueLineKey":"PO-10001-1","supplierItemId":"SUP-001","buyerItemId":"BUY-001","quantity":6,"unitOfMeasure":"EA","poNumber":"PO-10001"}],"packages":[{"packageId":"CARTON-1","sscc":"193123456789012345","lineReferences":[{"uniqueLineKey":"PO-10001-1","quantity":6,"unitOfMeasure":"EA"}]}],"extrinsics":{"warehouseWave":"WAVE-42"}}}]}