| 1 | {
|
| 2 | "$version": "3.0.0",
|
| 3 | "$id": "logistics.parcel.tracking",
|
| 4 | "$title": "Parcel Tracking",
|
| 5 | "$description": "This data schema is a large-scale example, not a real-world reusable template",
|
| 6 | "$additionalProperties": false,
|
| 7 | "$oky": {
|
| 8 | "trackingNumber|@ # ~$TrackingNumber~|Unique parcel identifier": "PKG-2025-ABC12345",
|
| 9 | "barcode|@ {10,50}|Scannable barcode value": "420941259400111899223373657800",
|
| 10 | "status|@ ($PARCEL_STATUS)|Current parcel status": "IN_TRANSIT",
|
| 11 | "priority|@ ($PRIORITY)|Shipping priority level": "STANDARD",
|
| 12 | "serviceType|@ ($SERVICE_TYPE)|Type of delivery service": "EXPRESS",
|
| 13 | "sender|@ |Sender information": "&Contact",
|
| 14 | "recipient|@ |Recipient information": "&Contact",
|
| 15 | "origin|@ |Origin facility": "&Facility",
|
| 16 | "destination|@ |Destination facility": "&Facility",
|
| 17 | "currentLocation|? |Current parcel location": "&Location",
|
| 18 | "parcelDetails|@|Physical characteristics of the parcel": {
|
| 19 | "weight|@ (0.01..1000)|Weight in kilograms": 2.5,
|
| 20 | "dimensions|@|Parcel dimensions in centimeters": {
|
| 21 | "length|@ (1..300)": 30,
|
| 22 | "width|@ (1..200)": 20,
|
| 23 | "height|@ (1..200)": 15
|
| 24 | },
|
| 25 | "volumetricWeight|?(>0)|Calculated volumetric weight": 1.8,
|
| 26 | "packageType|@ ($PACKAGE_TYPE)|Type of packaging": "BOX",
|
| 27 | "fragile|@|Fragile content indicator": false,
|
| 28 | "hazardous|@|Hazardous material indicator": false,
|
| 29 | "hazmatClass|?($HAZMAT_CLASS)|Hazardous material classification": "CLASS_3",
|
| 30 | "declaredValue|?(>=0)|Declared value for insurance": "150.00",
|
| 31 | "currency|($CURRENCY)|Currency code (ISO 4217)": "EUR",
|
| 32 | "$requiredIfExist declaredValue": ["currency"],
|
| 33 | "description|@ {1,500}|Content description": "Electronic components",
|
| 34 | "itemCount|(>=1)|Number of items in parcel": 3,
|
| 35 | "$requiredIf hazardous(true)": [
|
| 36 | "hazmatClass"
|
| 37 | ],
|
| 38 | "$forbiddenIfNot hazardous(true)": [
|
| 39 | "hazmatClass"
|
| 40 | ]
|
| 41 | },
|
| 42 | "shipping|@|Shipping and scheduling information": {
|
| 43 | "shippedAt|~$DateTime~|Timestamp when parcel was shipped": "2025-01-15T09:30:00Z",
|
| 44 | "estimatedDelivery|? ~$DateTime~ (%ShippedBeforeEstimated)|Estimated delivery timestamp": "2025-01-18T18:00:00Z",
|
| 45 | "actualDelivery|? ~$DateTime~ (%ShippedBeforeActual)|Actual delivery timestamp": "2025-01-17T14:23:00Z",
|
| 46 | "deliveryWindow|?|Preferred delivery time window": {
|
| 47 | "start|@ ~$Time~": "09:00:00",
|
| 48 | "end|@ ~$Time~ (%DeliveryWindowValid)": "18:00:00"
|
| 49 | },
|
| 50 | "deliveryInstructions|? {1,500}|Special delivery instructions": "Leave at front door if no answer",
|
| 51 | "signatureRequired|@|Signature required on delivery": true,
|
| 52 | "ageVerificationRequired|@|Age verification required": false,
|
| 53 | "minimumAge|?(18..99)|Minimum age for delivery": 21,
|
| 54 | "insuranceAmount|?(>=0)|Insurance coverage amount": "200.00",
|
| 55 | "$requiredIf ageVerificationRequired(true)": [
|
| 56 | "minimumAge"
|
| 57 | ],
|
| 58 | "$forbiddenIfNot ageVerificationRequired(true)": [
|
| 59 | "minimumAge"
|
| 60 | ]
|
| 61 | },
|
| 62 | "trackingEvents|@ [1,*] -> !|Chronological list of tracking events": [
|
| 63 | "&TrackingEvent"
|
| 64 | ],
|
| 65 | "customsInfo|?|Customs and international shipping details": {
|
| 66 | "customsStatus|@ ($CUSTOMS_STATUS)|Current customs status": "CLEARED",
|
| 67 | "hsCode|? ~$HsCode~|Harmonized System code": "8471.30.01",
|
| 68 | "countryOfOrigin| ($COUNTRY)|Country of origin (ISO 3166-1 alpha-2)": "CN",
|
| 69 | "exportDeclarationNumber|? {5,30}|Export declaration reference": "EX2025001234",
|
| 70 | "importDeclarationNumber|? {5,30}|Import declaration reference": "IM2025005678",
|
| 71 | "customsValue| (>=0)": 120.5,
|
| 72 | "dutyAmount|?(>=0)|Customs duty amount": "15.00",
|
| 73 | "taxAmount|?(>=0)|Tax amount": "24.00",
|
| 74 | "dutiesPaidBy|($DUTIES_PAYER)|Party responsible for duties": "RECIPIENT",
|
| 75 | "$requiredIf customsStatus('CLEARED','HELD','REJECTED')": [
|
| 76 | "countryOfOrigin",
|
| 77 | "customsValue"
|
| 78 | ]
|
| 79 | },
|
| 80 | "delivery|?|Delivery completion details": {
|
| 81 | "deliveredAt|@ ~$DateTime~|Delivery timestamp": "2025-01-17T14:23:00Z",
|
| 82 | "deliveredTo|@ {2,100}|Person who received the parcel": "John Smith",
|
| 83 | "deliveryMethod|@ ($DELIVERY_METHOD)|How the parcel was delivered": "HANDED_TO_RESIDENT",
|
| 84 | "signatureUrl|? ~$Uri~|URL to signature image": "https://tracking.example.com/signatures/sig_abc123.png",
|
| 85 | "photoProofUrl|? ~$Uri~|URL to delivery photo": "https://tracking.example.com/photos/del_abc123.jpg",
|
| 86 | "deliveryNotes|? {1,500}|Additional delivery notes": "Received by household member",
|
| 87 | "attemptCount|(>=1)|Number of delivery attempts": 1,
|
| 88 | "rating|?(1..5)|Customer satisfaction rating": 5,
|
| 89 | "feedback|? {1,1000}|Customer feedback": "Fast and professional delivery"
|
| 90 | },
|
| 91 | "failedDelivery|?|Failed delivery details": {
|
| 92 | "failedAt|@ ~$DateTime~|Failure timestamp": "2025-01-17T14:23:00Z",
|
| 93 | "failureReason|@ ($FAILURE_REASON)|Reason for failed delivery": "RECIPIENT_UNAVAILABLE",
|
| 94 | "attemptCount|@ (>=1)|Number of attempts made": 1,
|
| 95 | "nextAttemptScheduled|? ~$DateTime~ (%NextAttemptAfterFailed)|Next scheduled attempt": "2025-01-18T10:00:00Z",
|
| 96 | "heldAtFacility|? |Facility where parcel is held": "&Facility",
|
| 97 | "customerNotified|@|Whether customer was notified": true,
|
| 98 | "notificationMethod|?($NOTIFICATION_TYPE)": "SMS"
|
| 99 | },
|
| 100 | "returns|?|Return shipment information": {
|
| 101 | "isReturn|@|Indicates if this is a return shipment": true,
|
| 102 | "originalTrackingNumber|? ~$TrackingNumber~|Original shipment tracking number": "PKG-2025-XYZ98765",
|
| 103 | "returnReason|?($RETURN_REASON)|Reason for return": "WRONG_ITEM",
|
| 104 | "returnAuthorization|? {5,50}|Return merchandise authorization number": "RMA-2025-00123",
|
| 105 | "returnRequestedAt|? ~$DateTime~|When return was requested": "2025-01-20T10:00:00Z",
|
| 106 | "returnLabel|?|Return shipping label details": {
|
| 107 | "labelUrl|@ ~$Uri~": "https://labels.example.com/return_abc123.pdf",
|
| 108 | "validUntil|@ ~$Date~": "2025-02-15"
|
| 109 | },
|
| 110 | "$requiredIf isReturn(true)": [
|
| 111 | "originalTrackingNumber",
|
| 112 | "returnReason",
|
| 113 | "returnAuthorization"
|
| 114 | ],
|
| 115 | "$forbiddenIfNot isReturn(true)": [
|
| 116 | "originalTrackingNumber",
|
| 117 | "returnReason",
|
| 118 | "returnAuthorization",
|
| 119 | "returnRequestedAt",
|
| 120 | "returnLabel"
|
| 121 | ]
|
| 122 | },
|
| 123 | "billing|?|Billing and payment information": {
|
| 124 | "invoiceNumber|@ {5,30}|Invoice reference number": "INV-2025-00456",
|
| 125 | "shippingCost|@ (>=0)": 12.99,
|
| 126 | "insuranceCost|?(>=0)": 2.5,
|
| 127 | "handlingFee|?(>=0)": "1.00",
|
| 128 | "fuelSurcharge|?(>=0)": 0.75,
|
| 129 | "totalCost|@ (%TotalCostValid)": 17.24,
|
| 130 | "currency|($CURRENCY)": "EUR",
|
| 131 | "paymentStatus|@ ($PAYMENT_STATUS)": "PAID",
|
| 132 | "paidAt|? ~$DateTime~": "2025-01-15T08:45:00Z",
|
| 133 | "paymentMethod|?($PAYMENT_METHOD)": "CREDIT_CARD",
|
| 134 | "$requiredIf paymentStatus('PAID')": [
|
| 135 | "paidAt",
|
| 136 | "paymentMethod"
|
| 137 | ],
|
| 138 | "$forbiddenIfNot paymentStatus('PAID','PARTIAL_REFUND')": [
|
| 139 | "paidAt"
|
| 140 | ]
|
| 141 | },
|
| 142 | "notifications|[*] -> !|Notification preferences and history": [
|
| 143 | {
|
| 144 | "type|@ # ($NOTIFICATION_TYPE)": "EMAIL",
|
| 145 | "destination|@ # {5,200}|Email or phone number": "john.smith@example.com",
|
| 146 | "events|@ [1,*] -> ($NOTIFICATION_EVENT)!|Events to notify": [
|
| 147 | "SHIPPED",
|
| 148 | "OUT_FOR_DELIVERY",
|
| 149 | "DELIVERED"
|
| 150 | ],
|
| 151 | "enabled|@": true,
|
| 152 | "lastSentAt|? ~$DateTime~": "2025-01-17T08:00:00Z"
|
| 153 | }
|
| 154 | ],
|
| 155 | "metadata|@|Additional metadata": {
|
| 156 | "createdAt|@ ~$DateTime~": "2025-01-15T08:30:00Z",
|
| 157 | "updatedAt|@ ~$DateTime~ (%CreatedBeforeUpdated)": "2025-01-17T14:25:00Z",
|
| 158 | "createdBy|@ {2,100}": "shipping-api",
|
| 159 | "source|($SOURCE_SYSTEM)": "WEB_ORDER",
|
| 160 | "orderReference|? {1,50}|Related order number": "ORD-2025-78901",
|
| 161 | "customerReference|? {1,50}|Customer's reference": "PO-2025-ABC",
|
| 162 | "tags|[0,10] -> {2,30}!": [
|
| 163 | "priority",
|
| 164 | "fragile"
|
| 165 | ],
|
| 166 | "notes|[*] -> {1,500}": [
|
| 167 | "Customer requested morning delivery"
|
| 168 | ]
|
| 169 | },
|
| 170 | "$requiredIf status('DELIVERED')": [
|
| 171 | "delivery"
|
| 172 | ],
|
| 173 | "$requiredIf status('FAILED_DELIVERY')": [
|
| 174 | "failedDelivery"
|
| 175 | ],
|
| 176 | "$requiredIf serviceType('INTERNATIONAL')": [
|
| 177 | "customsInfo"
|
| 178 | ],
|
| 179 | "$forbiddenIfNot status('DELIVERED')": [
|
| 180 | "delivery"
|
| 181 | ],
|
| 182 | "$forbiddenIfNot status('FAILED_DELIVERY')": [
|
| 183 | "failedDelivery"
|
| 184 | ]
|
| 185 | },
|
| 186 | "$defs": {
|
| 187 | "Contact": {
|
| 188 | "name|@ {2,100}|Full name": "John Smith",
|
| 189 | "company|? {2,200}|Company name": "Tech Solutions Ltd",
|
| 190 | "email|@ ~$Email~": "john.smith@example.com",
|
| 191 | "phone|@ ~$Phone~|Phone with country code": "+33612345678",
|
| 192 | "alternatePhone|? ~$Phone~": "+33698765432",
|
| 193 | "address|@ ": "&Address",
|
| 194 | "taxId|? {5,30}|Tax identification number": "FR12345678901"
|
| 195 | },
|
| 196 | "Address": {
|
| 197 | "street1|@ {2,200}|Street address line 1": "123 Main Street",
|
| 198 | "street2|? {2,200}|Street address line 2": "Building A, Floor 3",
|
| 199 | "city|@ {2,100}": "Paris",
|
| 200 | "state|? {2,100}|State or province": "Île-de-France",
|
| 201 | "postalCode|@ {2,20}": "75001",
|
| 202 | "country|@ ($COUNTRY)|ISO 3166-1 alpha-2 country code": "FR",
|
| 203 | "coordinates|?|GPS coordinates": {
|
| 204 | "latitude|@ (-90..90)": 48.8566,
|
| 205 | "longitude|@ (-180..180)": 2.3522
|
| 206 | },
|
| 207 | "addressType|($ADDRESS_TYPE)": "RESIDENTIAL",
|
| 208 | "accessCode|? {1,20}|Building access code": "A1234",
|
| 209 | "floor|? {1,20}": "3",
|
| 210 | "apartment|? {1,20}": "Suite 301"
|
| 211 | },
|
| 212 | "Facility": {
|
| 213 | "facilityId|@ # {3,50}": "FAC-PAR-001",
|
| 214 | "name|@ {2,200}": "Paris Distribution Center",
|
| 215 | "type|@ ($FACILITY_TYPE)": "DISTRIBUTION_CENTER",
|
| 216 | "address|@ ": "&Address",
|
| 217 | "timezone|@ {2,50}": "Europe/Paris",
|
| 218 | "operatingHours|?": {
|
| 219 | "open|@ ~$Time~": "06:00:00",
|
| 220 | "close|@ ~$Time~ (%OperatingHoursValid)": "22:00:00"
|
| 221 | },
|
| 222 | "contactPhone|? ~$Phone~": "+33140123456"
|
| 223 | },
|
| 224 | "Location": {
|
| 225 | "facilityId|? {3,50}": "FAC-PAR-001",
|
| 226 | "facilityName|? {2,200}": "Paris Distribution Center",
|
| 227 | "city|@ {2,100}": "Paris",
|
| 228 | "country|@ ($COUNTRY)": "FR",
|
| 229 | "coordinates|?": {
|
| 230 | "latitude|@ (-90..90)": 48.8566,
|
| 231 | "longitude|@ (-180..180)": 2.3522
|
| 232 | },
|
| 233 | "locationType|($LOCATION_TYPE)": "SORTING_FACILITY",
|
| 234 | "lastScanAt|@ ~$DateTime~": "2025-01-16T15:30:00Z"
|
| 235 | },
|
| 236 | "TrackingEvent": {
|
| 237 | "eventId|@ # ~$Uuid~|Unique event identifier": "550e8400-e29b-41d4-a716-446655440000",
|
| 238 | "timestamp|@ ~$DateTime~|When the event occurred": "2025-01-16T15:30:00Z",
|
| 239 | "eventCode|@ ($EVENT_CODE)|Event type code": "ARRIVED_AT_FACILITY",
|
| 240 | "status|@ ($PARCEL_STATUS)|Resulting parcel status": "IN_TRANSIT",
|
| 241 | "description|@ {5,500}|Human-readable event description": "Package arrived at Paris Distribution Center",
|
| 242 | "location|@ ": "&Location",
|
| 243 | "performedBy|?|Staff member or system that recorded the event": {
|
| 244 | "employeeId|@ {3,50}": "EMP-12345",
|
| 245 | "name|@ {2,100}": "Marie Dupont",
|
| 246 | "role|{2,50}": "Warehouse Operator"
|
| 247 | },
|
| 248 | "scanType|?($SCAN_TYPE)": "ARRIVAL_SCAN",
|
| 249 | "exceptionCode|?($EXCEPTION_CODE)|Exception reason if applicable": "NONE",
|
| 250 | "exceptionDetails|? {1,500}": "No exceptions",
|
| 251 | "proofUrl|? ~$Uri~|URL to proof of event": "https://tracking.example.com/scans/scan_abc123.jpg",
|
| 252 | "$requiredIfNot exceptionCode('NONE')": [
|
| 253 | "exceptionDetails"
|
| 254 | ]
|
| 255 | }
|
| 256 | },
|
| 257 | "$format": {
|
| 258 | "TrackingNumber": "^PKG-[0-9]{4}-[A-Z0-9]{8,12}$",
|
| 259 | "Phone":"^\\+[0-9]{7,15}$",
|
| 260 | "HsCode":"^[0-9]{4}(\\.[0-9]{2}(\\.[0-9]{2})?)?$"
|
| 261 | },
|
| 262 | "$compute": {
|
| 263 | "ShippedBeforeEstimated": "estimatedDelivery == null || shippedAt <= estimatedDelivery",
|
| 264 | "ShippedBeforeActual": "actualDelivery == null || shippedAt <= actualDelivery",
|
| 265 | "DeliveryWindowValid": "start < end",
|
| 266 | "CreatedBeforeUpdated": "updatedAt >= createdAt",
|
| 267 | "OperatingHoursValid": "open < close",
|
| 268 | "TotalCostValid": "totalCost >= 0 && totalCost == shippingCost + (insuranceCost ?? 0) + (handlingFee ?? 0) + (fuelSurcharge ?? 0)",
|
| 269 | "NextAttemptAfterFailed": "nextAttemptScheduled == null || nextAttemptScheduled > failedAt"
|
| 270 | },
|
| 271 | "$nomenclature": {
|
| 272 | "PARCEL_STATUS": "LABEL_CREATED,PICKED_UP,IN_TRANSIT,OUT_FOR_DELIVERY,DELIVERED,FAILED_DELIVERY,RETURNED,HELD_AT_FACILITY,CUSTOMS_HOLD,LOST,DAMAGED,CANCELLED",
|
| 273 | "PRIORITY": "ECONOMY,STANDARD,EXPRESS,OVERNIGHT,SAME_DAY",
|
| 274 | "SERVICE_TYPE": "STANDARD,EXPRESS,OVERNIGHT,SAME_DAY,FREIGHT,INTERNATIONAL,RETURNS",
|
| 275 | "PACKAGE_TYPE": "ENVELOPE,SMALL_BOX,MEDIUM_BOX,LARGE_BOX,BOX,PALLET,TUBE,BAG,CUSTOM",
|
| 276 | "HAZMAT_CLASS": "CLASS_1,CLASS_2,CLASS_3,CLASS_4,CLASS_5,CLASS_6,CLASS_7,CLASS_8,CLASS_9",
|
| 277 | "CUSTOMS_STATUS": "NOT_REQUIRED,PENDING,IN_REVIEW,CLEARED,HELD,REJECTED",
|
| 278 | "DUTIES_PAYER": "SENDER,RECIPIENT,THIRD_PARTY",
|
| 279 | "DELIVERY_METHOD": "HANDED_TO_RESIDENT,LEFT_AT_DOOR,LEFT_WITH_NEIGHBOR,DELIVERED_TO_MAILBOX,DELIVERED_TO_LOCKER,DELIVERED_TO_PICKUP_POINT,HANDED_TO_CONCIERGE,SAFE_PLACE",
|
| 280 | "FAILURE_REASON": "RECIPIENT_UNAVAILABLE,ADDRESS_NOT_FOUND,ACCESS_DENIED,REFUSED,BUSINESS_CLOSED,WEATHER,VEHICLE_ISSUE,OTHER",
|
| 281 | "RETURN_REASON": "WRONG_ITEM,DAMAGED,DEFECTIVE,NOT_AS_DESCRIBED,CHANGED_MIND,DUPLICATE_ORDER,LATE_DELIVERY,OTHER",
|
| 282 | "PAYMENT_STATUS": "PENDING,PAID,FAILED,REFUNDED,PARTIAL_REFUND",
|
| 283 | "PAYMENT_METHOD": "CREDIT_CARD,DEBIT_CARD,BANK_TRANSFER,PAYPAL,INVOICE,CASH_ON_DELIVERY,PREPAID",
|
| 284 | "NOTIFICATION_TYPE": "EMAIL,SMS,PUSH,WEBHOOK",
|
| 285 | "NOTIFICATION_EVENT": "LABEL_CREATED,SHIPPED,IN_TRANSIT,OUT_FOR_DELIVERY,DELIVERED,FAILED_DELIVERY,EXCEPTION,CUSTOMS_UPDATE",
|
| 286 | "SOURCE_SYSTEM": "WEB_ORDER,MOBILE_APP,API,RETAIL_POS,MARKETPLACE,MANUAL",
|
| 287 | "FACILITY_TYPE": "WAREHOUSE,DISTRIBUTION_CENTER,SORTING_FACILITY,PICKUP_POINT,LOCKER,RETAIL_STORE,AIRPORT_HUB,PORT",
|
| 288 | "LOCATION_TYPE": "ORIGIN_FACILITY,SORTING_FACILITY,DISTRIBUTION_CENTER,LOCAL_DEPOT,DELIVERY_VEHICLE,PICKUP_POINT,CUSTOMS",
|
| 289 | "ADDRESS_TYPE": "RESIDENTIAL,COMMERCIAL,PO_BOX,PICKUP_POINT,LOCKER",
|
| 290 | "COUNTRY":"AT,BE,BG,CH,CY,CZ,DE,DK,EE,ES,FI,FR,GB,GR,HR,HU,IE,IT,LT,LU,LV,MT,NL,NO,PL,PT,RO,SE,SI,SK,US,CA,MX,BR,AR,CL,CO,CN,JP,KR,IN,SG,HK,TW,TH,VN,AE,SA,IL,TR,MA,TN,EG,ZA,AU,NZ",
|
| 291 | "CURRENCY":"USD,EUR,CNY,JPY,GBP,CHF,CAD,AUD,HKD,SGD",
|
| 292 | "EVENT_CODE": "LABEL_CREATED,PICKED_UP,ARRIVED_AT_FACILITY,DEPARTED_FACILITY,IN_TRANSIT,CUSTOMS_CLEARANCE_START,CUSTOMS_CLEARED,CUSTOMS_HELD,OUT_FOR_DELIVERY,DELIVERY_ATTEMPTED,DELIVERED,FAILED_DELIVERY,HELD_AT_FACILITY,RETURNED_TO_SENDER,DAMAGED,LOST,CANCELLED",
|
| 293 | "SCAN_TYPE": "PICKUP_SCAN,ARRIVAL_SCAN,DEPARTURE_SCAN,DELIVERY_SCAN,EXCEPTION_SCAN,CUSTOMS_SCAN,RETURN_SCAN",
|
| 294 | "EXCEPTION_CODE": "NONE,ADDRESS_ISSUE,RECIPIENT_UNAVAILABLE,REFUSED,DAMAGED_IN_TRANSIT,CUSTOMS_ISSUE,WEATHER_DELAY,VEHICLE_ISSUE,SECURITY_HOLD,INCORRECT_ADDRESS,ACCESS_ISSUE"
|
| 295 | }
|
| 296 | }
|
| 297 | |