{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/dhl/json-schema/dhl-tracking-shipments-schema.json",
  "title": "TrackingShipments",
  "description": "Unified tracking response object",
  "x-generated": "2026-11-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/dhl-shipment-tracking-openapi.yml#/components/schemas/TrackingShipments",
  "type": "object",
  "properties": {
    "url": {
      "description": "A link to current page",
      "type": "string",
      "format": "uri"
    },
    "prevUrl": {
      "description": "A link to the previous page",
      "type": "string",
      "format": "uri"
    },
    "nextUrl": {
      "description": "A link to the next page",
      "type": "string",
      "format": "uri"
    },
    "firstUrl": {
      "description": "A link to the first page",
      "type": "string",
      "format": "uri"
    },
    "lastUrl": {
      "description": "A link to the last page",
      "type": "string",
      "format": "uri"
    },
    "shipments": {
      "description": "An array of unified tracking shipments",
      "type": "array",
      "items": {
        "$ref": "#/$defs/TrackingShipment"
      }
    },
    "possibleAdditionalShipmentsUrl": {
      "description": "An array of business services, where should be potentially shipment found",
      "type": "array",
      "items": {
        "type": "string",
        "format": "uri"
      }
    }
  },
  "$defs": {
    "Company": {
      "description": "A public business organization",
      "type": "object",
      "properties": {
        "@type": {
          "type": "string",
          "default": "Company"
        },
        "name": {
          "description": "The name of the person",
          "type": "string"
        },
        "organizationName": {
          "description": "The name of organization",
          "type": "string"
        },
        "address": {
          "$ref": "#/$defs/SecuredAddress"
        }
      },
      "required": [
        "@type"
      ]
    },
    "ControlledDataCode": {
      "type": "string",
      "enum": [
        "consignee-city",
        "servicepoint-facilityId",
        "servicepoint-url",
        "shipper-city",
        "signatory-name"
      ]
    },
    "CountryCode": {
      "description": "Code specifying the country using ISO 3166-1 alpha-2",
      "type": "string",
      "format": "country-code"
    },
    "DgfAirport": {
      "description": "DHL Global Forwarding Airport",
      "type": "object",
      "allOf": [
        {
          "$ref": "#/$defs/DgfLocation"
        }
      ],
      "properties": {
        "dgf:locationCode": {
          "description": "Airport of departure/destination in IATA code format",
          "type": "string"
        },
        "countryCode": {
          "$ref": "#/$defs/CountryCode"
        }
      }
    },
    "DgfLocation": {
      "description": "DHL Global Forwarding Location",
      "type": "object",
      "properties": {
        "dgf:locationName": {
          "description": "The name of the location",
          "type": "string"
        }
      }
    },
    "DgfRoute": {
      "description": "DHL Global Forwarding Route",
      "type": "object",
      "properties": {
        "dgf:vesselName": {
          "description": "Vessel Name for Ocean",
          "type": "string"
        },
        "dgf:voyageFlightNumber": {
          "description": "Voyage number for Ocean, Flight Carrier and Number for Air",
          "type": "string"
        },
        "dgf:airportOfDeparture": {
          "$ref": "#/$defs/DgfAirport"
        },
        "dgf:airportOfDestination": {
          "$ref": "#/$defs/DgfAirport"
        },
        "dgf:estimatedDepartureDate": {
          "description": "Flight Estimated Date and Time of Departure",
          "type": "string",
          "format": "iso8601-date-time"
        },
        "dgf:estimatedArrivalDate": {
          "description": "Flight Estimated Date and Time of Arrival",
          "type": "string",
          "format": "iso8601-date-time"
        },
        "dgf:placeOfAcceptance": {
          "$ref": "#/$defs/DgfLocation"
        },
        "dgf:portOfLoading": {
          "$ref": "#/$defs/DgfLocation"
        },
        "dgf:portOfUnloading": {
          "$ref": "#/$defs/DgfLocation"
        },
        "dgf:placeOfDelivery": {
          "$ref": "#/$defs/DgfLocation"
        }
      }
    },
    "Dimensions": {
      "description": "A measurable extent of a particular kind of delivery",
      "type": "object",
      "properties": {
        "height": {
          "$ref": "#/$defs/QuantitativeValue"
        },
        "length": {
          "$ref": "#/$defs/QuantitativeValue"
        },
        "width": {
          "$ref": "#/$defs/QuantitativeValue"
        }
      }
    },
    "EstimatedDeliveryTimeFrame": {
      "description": "A term when shipment is expected to arrive",
      "type": "object",
      "properties": {
        "estimatedFrom": {
          "description": "The start date of the estimated time frame",
          "format": "iso8601-date-time",
          "type": "string"
        },
        "estimatedThrough": {
          "description": "The end date of the estimated time frame",
          "format": "iso8601-date-time",
          "type": "string"
        }
      }
    },
    "Humidity": {
      "description": "Humidity measurement",
      "type": "object",
      "properties": {
        "value": {
          "description": "Humidity value",
          "type": "string"
        },
        "unit": {
          "description": "Unit of measurement",
          "type": "string",
          "enum": [
            "percentage"
          ]
        },
        "deviceId": {
          "description": "Sensor device id measured the humidity",
          "type": "string"
        }
      }
    },
    "Location": {
      "description": "location co-ordinates of shipment",
      "type": "object",
      "properties": {
        "lat": {
          "description": "Latitude value",
          "type": "number",
          "format": "float"
        },
        "lon": {
          "description": "Longitude value",
          "type": "number",
          "format": "float"
        }
      }
    },
    "Measurement": {
      "description": "Telemetry measurement details about shipment",
      "properties": {
        "timestamp": {
          "description": "Date and time when the telemetry data was created by the origin system",
          "type": "string",
          "format": "iso8601-date-time"
        },
        "deviceId": {
          "description": "Sensor device id measured the humidity",
          "type": "string"
        },
        "pieceIds": {
          "description": "piece ids of shipment",
          "type": "array",
          "items": {
            "$ref": "#/$defs/PieceId"
          }
        },
        "location": {
          "$ref": "#/$defs/Location"
        },
        "humidity": {
          "$ref": "#/$defs/Humidity"
        },
        "pressure": {
          "$ref": "#/$defs/Pressure"
        },
        "temperature": {
          "$ref": "#/$defs/Temperature"
        },
        "tilt": {
          "$ref": "#/$defs/Tilt"
        }
      }
    },
    "Organization": {
      "description": "A sensitive common organization or company",
      "type": "object",
      "properties": {
        "@type": {
          "type": "string",
          "default": "Organization"
        },
        "name": {
          "description": "The name of the person",
          "type": "string"
        },
        "organizationName": {
          "description": "The name of organization",
          "type": "string"
        },
        "address": {
          "$ref": "#/$defs/SecuredAddress"
        }
      },
      "required": [
        "@type"
      ]
    },
    "Person": {
      "description": "A person",
      "properties": {
        "@type": {
          "type": "string",
          "default": "Person"
        },
        "familyName": {
          "description": "Family name, the last name of a person",
          "type": "string"
        },
        "givenName": {
          "description": "Given name, the first name of a person",
          "type": "string"
        },
        "name": {
          "description": "The name of the person",
          "type": "string"
        },
        "address": {
          "$ref": "#/$defs/SecuredAddress"
        }
      },
      "required": [
        "@type"
      ]
    },
    "PersonEntity": {
      "description": "A real organization or personal entity, if type is not specified, a Organization implementation is used",
      "type": "object",
      "oneOf": [
        {
          "$ref": "#/$defs/UnknownEntity"
        },
        {
          "$ref": "#/$defs/Organization"
        },
        {
          "$ref": "#/$defs/Company"
        },
        {
          "$ref": "#/$defs/Person"
        }
      ]
    },
    "PieceId": {
      "description": "Identification of item or piece in the shipment",
      "type": "string"
    },
    "Pressure": {
      "description": "Pressure measurement",
      "type": "object",
      "properties": {
        "value": {
          "description": "Pressure value",
          "type": "string"
        },
        "unit": {
          "description": "Unit of measurement",
          "type": "string",
          "enum": [
            "pascal",
            "bar",
            "psi"
          ]
        },
        "deviceId": {
          "description": "Sensor device id measured the pressure",
          "type": "string"
        }
      }
    },
    "Product": {
      "description": "Offered product or service",
      "type": "object",
      "properties": {
        "deliveryMethodRemark": {
          "description": "Specific detail of product",
          "type": "string"
        },
        "productCode": {
          "type": "string"
        },
        "productName": {
          "description": "Business unit product or service",
          "type": "string"
        }
      }
    },
    "ProofOfDelivery": {
      "description": "An acknowledgment that an order successfully arrived at its intended destination",
      "type": "object",
      "properties": {
        "documentUrl": {
          "description": "The link to related electronic proof of delivery document",
          "format": "uri",
          "type": "string"
        },
        "signatureUrl": {
          "description": "The link to related electronic signature",
          "format": "uri",
          "type": "string"
        },
        "signed": {
          "$ref": "#/$defs/PersonEntity"
        },
        "timestamp": {
          "description": "Date and time of related proof of delivery document",
          "format": "iso8601-date-time",
          "type": "string"
        }
      }
    },
    "Provider": {
      "description": "The service provider, service operator, or service performer",
      "type": "object",
      "required": [
        "destinationProvider"
      ],
      "properties": {
        "destinationProvider": {
          "description": "The name of the provider organization handling the delivery in the destination country",
          "type": "string",
          "enum": [
            "acs-courier",
            "anpost",
            "bpost",
            "bring",
            "chronopost",
            "colis-prive",
            "econnect",
            "express",
            "fastway",
            "freight",
            "freight-fr",
            "freight-se",
            "hrvatska-posta",
            "magyar-posta",
            "oepag",
            "parcel-be",
            "parcel-bl",
            "parcel-cz",
            "parcel-de",
            "parcel-es",
            "parcel-iberia",
            "parcel-lu",
            "parcel-nl",
            "parcel-pl",
            "parcel-pt",
            "parcel-uk",
            "posta",
            "posta-slovenije",
            "posti",
            "poste-italiane",
            "ppl",
            "rapido",
            "relais-colis",
            "slovak-parcel-service",
            "speedy",
            "sps",
            "trans-o-flex",
            "urgent-cargus"
          ]
        }
      }
    },
    "QuantitativeValue": {
      "description": "A point value or interval for product characteristics and other purposes",
      "type": "object",
      "properties": {
        "unitText": {
          "description": "A string or text indicating the unit of measurement",
          "type": "string"
        },
        "value": {
          "description": "The value of the quantitative value or property value node",
          "type": "number"
        }
      }
    },
    "Reference": {
      "description": "An indication that refers to related shipment",
      "type": "object",
      "properties": {
        "@scope": {
          "$ref": "#/$defs/SecretScope"
        },
        "number": {
          "description": "A value of reference",
          "type": "string"
        },
        "type": {
          "$ref": "#/$defs/ReferenceType"
        }
      },
      "required": [
        "type"
      ]
    },
    "ReferenceType": {
      "description": "Type of reference",
      "type": "string",
      "enum": [
        "container-number",
        "customer-confirmation-number",
        "customer-reference",
        "domestic-consignment-id",
        "ecommerce-number",
        "housebill",
        "local-tracking-number",
        "masterbill",
        "payer-account-number",
        "receiver-account-number",
        "reference",
        "shipment-id",
        "shipper-account-number",
        "routing-code",
        "customer-order-number"
      ]
    },
    "ReturnFlag": {
      "description": "A flag whether the delivery is returned back to consignor",
      "type": "boolean",
      "default": false
    },
    "SecretScope": {
      "description": "A secret scope of protected or sensitive information",
      "type": "string",
      "enum": [
        "public",
        "secret",
        "sensitive"
      ]
    },
    "SecuredAddress": {
      "description": "The mailing address secured by policy",
      "properties": {
        "addressLocality": {
          "description": "Text specifying the name of the locality, for example a city",
          "type": "string"
        },
        "addressLocalityServicing": {
          "description": "Text specifying a detail of address locality",
          "type": "string"
        },
        "addressRegion": {
          "description": "Text specifying a detail of country",
          "type": "string"
        },
        "countryCode": {
          "$ref": "#/$defs/CountryCode"
        },
        "postalCode": {
          "description": "Text specifying the postal code for an address",
          "type": "string"
        },
        "streetAddress": {
          "description": "The street address expressed as free form text",
          "type": "string"
        },
        "addressLine": {
          "description": "Text specifying the addressLine, for example an apartment, suite, or floor number",
          "type": "string"
        }
      }
    },
    "SecuredPlace": {
      "description": "The location of object",
      "type": "object",
      "properties": {
        "address": {
          "$ref": "#/$defs/SecuredAddress"
        },
        "servicePoint": {
          "$ref": "#/$defs/ServicePoint"
        }
      }
    },
    "Service": {
      "description": "Service (provider) used to resolve this tracking number (id)",
      "type": "string",
      "enum": [
        "dgf",
        "dsc",
        "ecommerce",
        "ecommerce-apac",
        "ecommerce-europe",
        "ecommerce-ppl",
        "ecommerce-iberia",
        "express",
        "freight",
        "parcel-de",
        "parcel-nl",
        "parcel-pl",
        "parcel-uk",
        "post-de",
        "post-international",
        "sameday",
        "svb"
      ],
      "nullable": false,
      "x-enum-varnames": [
        "DGF",
        "DSC",
        "ECM",
        "ECP",
        "ECE",
        "PPL",
        "ECI",
        "XPR",
        "FRT",
        "PAD",
        "PAN",
        "PAP",
        "PUK",
        "PSD",
        "DPI",
        "SMD",
        "SVB"
      ]
    },
    "ServicePoint": {
      "properties": {
        "url": {
          "type": "string"
        },
        "label": {
          "type": "string"
        }
      }
    },
    "StatusCode": {
      "description": "Code of the status (high-level grouping statuses)",
      "type": "string",
      "enum": [
        "delivered",
        "failure",
        "pre-transit",
        "transit",
        "unknown"
      ]
    },
    "Temperature": {
      "description": "Temperature measurement",
      "type": "object",
      "properties": {
        "value": {
          "description": "Temperature value",
          "type": "string"
        },
        "unit": {
          "description": "Unit of measurement",
          "type": "string",
          "enum": [
            "celsius",
            "fahrenheit",
            "kelvin"
          ]
        },
        "deviceId": {
          "description": "Sensor device id measured the temperature",
          "type": "string"
        }
      }
    },
    "Tilt": {
      "description": "Tilt measurement",
      "type": "object",
      "properties": {
        "value": {
          "description": "Tilt value",
          "type": "string"
        },
        "unit": {
          "description": "Unit of measurement",
          "type": "string",
          "enum": [
            "degree",
            "radian"
          ]
        },
        "deviceId": {
          "description": "Sensor device id measured the tilt",
          "type": "string"
        }
      }
    },
    "TrackingShipment": {
      "description": "Unified tracking shipment",
      "type": "object",
      "properties": {
        "id": {
          "description": "Shipment identification tracking number",
          "type": "string"
        },
        "service": {
          "$ref": "#/$defs/Service"
        },
        "division": {
          "description": "The (sub)division of service provider that owns the shipment",
          "type": "string"
        },
        "origin": {
          "$ref": "#/$defs/SecuredPlace"
        },
        "destination": {
          "$ref": "#/$defs/SecuredPlace"
        },
        "status": {
          "$ref": "#/$defs/TrackingShipmentStatus"
        },
        "pickUpDate": {
          "description": "Shipment pickup date",
          "type": "string",
          "format": "iso8601-date-time"
        },
        "estimatedTimeOfDelivery": {
          "description": "Estimated time of delivery",
          "type": "string",
          "format": "iso8601-date-time"
        },
        "agreedDeliveryDate": {
          "description": "Agreed Delivery Date",
          "type": "string",
          "format": "iso8601-date-time"
        },
        "estimatedDeliveryTimeFrame": {
          "$ref": "#/$defs/EstimatedDeliveryTimeFrame"
        },
        "estimatedTimeOfDeliveryRemark": {
          "description": "Human-readable description of the estimated delivery time",
          "type": "string"
        },
        "serviceUrl": {
          "description": "Custom link to BU tracking service",
          "type": "string",
          "format": "uri"
        },
        "rerouteUrl": {
          "description": "Custom link to BU rerouting service, if available for the current status of the shipment",
          "type": "string",
          "format": "uri"
        },
        "returnFlag": {
          "$ref": "#/$defs/ReturnFlag"
        },
        "details": {
          "$ref": "#/$defs/TrackingShipmentDetails"
        },
        "events": {
          "description": "Historical list of events & timestamps",
          "type": "array",
          "items": {
            "$ref": "#/$defs/TrackingShipmentEvent"
          }
        }
      }
    },
    "TrackingShipmentDetails": {
      "description": "Shipment Details",
      "type": "object",
      "properties": {
        "product": {
          "$ref": "#/$defs/Product"
        },
        "provider": {
          "$ref": "#/$defs/Provider"
        },
        "receiver": {
          "$ref": "#/$defs/PersonEntity"
        },
        "sender": {
          "$ref": "#/$defs/PersonEntity"
        },
        "carrier": {
          "$ref": "#/$defs/PersonEntity"
        },
        "shipper": {
          "$ref": "#/$defs/PersonEntity"
        },
        "consignee": {
          "$ref": "#/$defs/PersonEntity"
        },
        "proofOfDelivery": {
          "$ref": "#/$defs/ProofOfDelivery"
        },
        "proofOfDeliverySignedAvailable": {
          "type": "boolean",
          "description": "\\'Yes\\' if signer identification is available"
        },
        "totalNumberOfPieces": {
          "description": "Total number of items or pieces in the shipment",
          "type": "integer",
          "format": "int32"
        },
        "pieceIds": {
          "description": "Ids of all the items or pieces in the shipment",
          "type": "array",
          "items": {
            "$ref": "#/$defs/PieceId"
          }
        },
        "weight": {
          "$ref": "#/$defs/QuantitativeValue"
        },
        "volume": {
          "$ref": "#/$defs/QuantitativeValue"
        },
        "loadingMeters": {
          "description": "A loading meter standard unit of measurement for transport by truck",
          "type": "number",
          "format": "float"
        },
        "dimensions": {
          "$ref": "#/$defs/Dimensions"
        },
        "references": {
          "description": "A list of indications that refers to related shipment",
          "type": "array",
          "items": {
            "$ref": "#/$defs/Reference"
          }
        },
        "valueAddedServices": {
          "$ref": "#/$defs/ValueAddedServices"
        },
        "controlledDataCodes": {
          "description": "Extra Controlled Access Data Codes",
          "type": "array",
          "items": {
            "$ref": "#/$defs/ControlledDataCode"
          }
        },
        "shipmentActivationDate": {
          "description": "Shipment Activation date",
          "type": "string",
          "format": "iso8601-date-time"
        },
        "dgf:routes": {
          "description": "DHL Global Forwarding routing Details",
          "type": "array",
          "items": {
            "$ref": "#/$defs/DgfRoute"
          }
        },
        "telemetry": {
          "description": "list of all sensor measurements from devices",
          "type": "array",
          "items": {
            "$ref": "#/$defs/Measurement"
          }
        }
      }
    },
    "TrackingShipmentEvent": {
      "description": "Shipment movement information",
      "type": "object",
      "allOf": [
        {
          "$ref": "#/$defs/TrackingShipmentStatus"
        },
        {
          "properties": {
            "pieceIds": {
              "description": "Ids of all the items or pieces in the shipment",
              "type": "array",
              "items": {
                "$ref": "#/$defs/PieceId"
              }
            }
          }
        }
      ]
    },
    "TrackingShipmentStatus": {
      "description": "High-level shipment status",
      "type": "object",
      "properties": {
        "timestamp": {
          "description": "A combination of date and time of day",
          "type": "string",
          "format": "iso8601-date-time"
        },
        "location": {
          "$ref": "#/$defs/SecuredPlace"
        },
        "statusCode": {
          "$ref": "#/$defs/StatusCode"
        },
        "status": {
          "description": "Short description of the status - title",
          "type": "string"
        },
        "statusDetailed": {
          "description": "Detailed status of the shipment",
          "type": "string"
        },
        "description": {
          "description": "Human-readable detailed description",
          "type": "string"
        },
        "remark": {
          "description": "Remark regarding the shipment status",
          "type": "string"
        },
        "nextSteps": {
          "description": "Description of the next steps",
          "type": "string"
        }
      },
      "required": [
        "timestamp",
        "statusCode"
      ]
    },
    "UnknownEntity": {
      "description": "Technical internal integration object, not intended for direct integration! Use Organization or Person please.",
      "properties": {
        "@type": {
          "type": "string",
          "default": "UnknownEntity"
        },
        "familyName": {
          "type": "string"
        },
        "givenName": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "organizationName": {
          "type": "string"
        },
        "address": {
          "$ref": "#/$defs/SecuredAddress"
        }
      },
      "required": [
        "@type"
      ]
    },
    "ValueAddedService": {
      "description": "End customer service",
      "type": "object",
      "properties": {
        "serviceType": {
          "type": "string",
          "enum": [
            "bulky",
            "pickup",
            "gogreen",
            "priority",
            "extraInsurance",
            "directInjection",
            "cashOnDelivery",
            "importFees"
          ]
        },
        "serviceCriteria": {
          "type": "string"
        },
        "serviceFlag": {
          "type": "boolean"
        }
      }
    },
    "ValueAddedServices": {
      "description": "Services I booked together with my Tracking details",
      "type": "object",
      "properties": {
        "services": {
          "description": "List of customer services",
          "type": "array",
          "items": {
            "$ref": "#/$defs/ValueAddedService"
          }
        }
      }
    }
  }
}