Leap JSON Response v1.0

Status

This page represents version 1.0 of the Leap JSON Response specification. New versions of Leap JSON will always be backward compatible; using a never remove, only add strategy.

To request changes to the specification or report an error please contact support.

Response Format

This section describes the structure of a Leap JSON Response document, which is identified by the media-type: application/vnd.leap+json. Leap JSON documents are defined in JavaScript Object Notation (JSON). Conventions related to this document and definitions of client/server responsibilities related to Leap JSON are discussed in the Leap JSON introduction document.

Unless otherwise noted, objects defined by this specification should not contain any additional members. Client and server implementations must ignore members not recognized by this specification.

Top-level Reserved Property Names

A document MAY include the following attributes:

Name	Type	Extra
apiVersion	String	Represents the desired version of the service API in a request, and the version of the service API that’s served in the response. apiVersion SHOULD always be present.
context	String	Echo-back data, set by the client and returned by the server.  Used for asynchronous and batch situations. Optional, and only present if sent in the request.
id	String	A server supplied identifier for the response, regardless of whether it is successful or unsuccessful.  id is used to correlate to events and server logs. Optional.
lang	String	A server supplied identifier for the response, echoing back the language code indicated in the request. If sent, only the I18N information, where defined, for the language code specified shall be returned. Optional, and only present if sent in  the request.
data	Object	Container object for data returned by the service in the case of a successful operation which, in turn, returns data.  This object contains many elements, itself, which are indicated later in this specification. *See note regarding mutual exclusivity below.
error	Object	Container object for the error returned by the service in the case of an unsuccessful operation.  This object contains many elements, itself, which are indicated later in this specification.  *See note regarding mutual exclusivity below.
method	String	Specifies the operation to perform, or that has been performed, on the data.
selfLink	String	A reference to a link which can be used to get more information about the details of this request and response. Optional.

data Object Reserved Property Names

Name	Type	Parent	Extra
kind	String	data	Serves as a guide to what type of information this particular object stores. Kind MAY exist at the data object level, items object (see below), or any level where understanding the type of data in an object is important.  kind SHOULD BE the first property in an object, when used.
totalItems	Number	data	Indicates the range of the items array (below).
updated	String	data	Indicates the date/time (RFC 3339) the data was requested. This may, then, be used by the client to determine if data refresh is necessary.
metadata	Object	data	Optional object array which describes the data contained in the items array. See metadata elements (below).
items	Array	data	An array of an unspecified object. SHOULD be the last element in the data object.

High-Level Example of Response

{
  "id": "uniquerequestID",
  "apiVersion": "1.0",
  "context": "contextString",
  "selfLink": "/linkToResultsEventStore/uniquerequestID",
  "data": {
    "kind": "delivery",
    "updated": "2018-02-04T19:29:54.001Z",
    "totalItems": 1,
    "metadata": [
      {
        //metadata object (below) here
      }
    ],
    "items": [
      {
        //item object (below) here
      }
    ]
}

metadata Array Object Property Names

Name	Type	Parent	Extra
kind	String	metadata	The kind of data item being described. name SHOULD match an element in the associated item object.
type	String	metadata	The data type associated with this element.
byteLength	Integer	metadata	The name of the data item being described. name SHOULD match an element in the associated item.
i18nID	String	metadata	Unique, server-internal, internationalization identifier associated with name.
i18nLangText	Array<Object>	metadata	Internationalization text tag associated with name.
lang	String	i18nLangText	ISO 639 language code for internationalization.
text	String	i18nLangText	Internationalized text.

metadata Array Example

"metadata": [
    {
      "kind": "WOrdNumber",
      "type": "string",
      "i18nID": "I18N_WORDER",
      "byteLenth": 20,
      "i18nLangText": [
        {
          "lang": "en",
          "text": "Work Order"
        },
        {
          "lang": "de",
          "text": "Arbeitsauftrag"
        }
      ]
    }
  ]

item Array Object Property Names

The item array, other than any properties listed below, is dependent on the application object definition and thus not part of this specification.  In other words, beyond any reserved properties indicated below, the definition of the items array is application-specific.  While the object described in the data.items array MAY contain any object or element consistent with the JSON standard, a flat structure is generally recommended.

Support for hierarchical objects, within JSON, is supported, but the use of the relationships array to define relationships, external to the items data has some advantages and potential performance benefits. 

"items": [
    {
      "deliveryId": "12312312",
      "carCod": "UPS",
      "shipmentDateTime": "2018-06-04T12:00:00.000Z",
      "clientId": "CLI1232",
      "customerNumber": "CST010322",
      "customerName": "My Mart",
      "addressLine1": "123 Main St",
      "addressLine2": "",
      "addressCity": "Winchester",
      "addressStProv": "TX",
      "addressPostalCode": "77345",
      "palletCount": 2
    }
  ]

Relationship Property Names within Items Objects

Name	Type	Parent	Extra
relationships	Array<Object>	items	Indication of relationships. Optional.
kind	String	relationships	Relates the link to the item element with the same name.
type	String	relationships	Specifies the type of link.  Enumeration of types, as of the time of this document’s create is:  [“self”, “collection”]
link	Object	relationships	Container object for related reference
href	String	link	Specifies the actual link url.  If related to the same base namespace, including feature group and feature, it may include the notation ~/ to indicate this.
desc	Array<Object>	link	Optional array of language descriptions for tool tips or other use cases.
lang	String	desc	ISO 639 language code for internationalization.
text	String	desc	Internationalized text.

"relationships": [
    {
      "kind": "delivery",
      "type": "self",
      "link": {
        "href": "~/delivery/12312312"
      }
    },
    {
      "kind": "carCod",
      "type": "self",
      "link": {
        "href": "~/carrierCodes/12312312"
      }
    },
    {
      "kind": "palletCount",
      "type": "collection",
      "link": {
        "href": "~/shippableInventory/12312312"
      }
    }
  ]

error Object Reserved Property Names

Name	Type	Parent	Extra
errorCode	Integer	error	The actual error code encountered.  While this property value MAY represent the HTTP response code, an actual application error SHOULD be returned here.
errorText	Array<Object>	error	An array of language-specific error text messages
lang	String	errorText	ISO 639 language code for internationalization.
text	String	errorText	Internationalized text.
developerInformation	Object	error	An object holding more detailed information regarding the error.
domain	String	developerInformation	The domain of the error.  Usually, Feature group/feature.
location	String	developerInformation	Location of the error.  Usually, module, execution route or framework element.
developerMessage	String	developerInformation	Detailed message aimed at aiding developers and support to identify the source of an issue.
vendorDetails	Object	developerInformation	Object holding any low-level, vendor specific information.
vendorID	String	vendorDetails	Implementation provider’s (vendor) Vendor ID.
vendorErrorCode	Integer	vendorDetails	Error code from the vendor implementation.
vendorErrorMessage	String	vendorDetails	Error message from the vendors implementation.

Success and Error Examples

{
  "id": "uniquerequestID",
  "apiVersion": "1.0",
  "context": "contextString",
  "selfLink": "/linkToResultsEventStore/uniquerequestID",
  "error": {
    "errorCode": 5443,
    "errorText": [
      {
        "lang": "en",
        "text": "Invalid Request - Invalid Shipment Identifier"
      }
    ]
  }
}

{
  "id": "uniquerequestID",
  "apiVersion": "1.0",
  "context": "contextString",
  "selfLink": "/linkToResultsEventStore/uniquerequestID",
  "error": {
    "errorCode": 400,
    "errorText": [
      {
        "lang": "en",
        "text": "Invalid Request - Shipping date incorrect for shipment"
      },
      {
        "lang": "de",
        "text": "Ungültige Lieferung - Das Versanddatum ist für den Versand nicht korrekt"
      }
    ],
    "developerInformation": {
      "domain": "facilityExecution/shipping",
      "location": "rateService",
      "developerMessage": "Shipdate should be greater than or equal to the facility's current date",
      "vendorDetails": {
          "vendorID": "wherewerks",
          "vendorErrorMessage": "Shipdate incorrect. ShipDate = 20180307 CurrentDate = 20180312",
          "vendorErrorCode": 1000027
      }
    }
  }
}

{
  "id": "uniquerequestID",
  "apiVersion": "1.0",
  "context": "contextString",
  "selfLink": "/linkToResultsEventStore/uniquerequestID",
  "data": {
    "kind": "delivery",
    "updated": "2018-02-04T19:29:54.001Z",
    "totalItems": 1,
    "metadata": [
      {
        "kind": "deliveryId",
        "type": "string",
        "i18nID": "I18N_DELIVERYID",
        "byteLenth": 20,
        "i18nLangText": [
          {
            "lang": "en",
            "text": "Delivery"
          }
        ]
      },
      {
        "kind": "carCod",
        "type": "string",
        "i18nID": "I18N_CARRIERCODE",
        "byteLenth": 10,
        "i18nLangText": [
          {
            "lang": "en",
            "text": "Carrier"
          }
        ]
      },
      {
        "kind": "shipmentDateTime",
        "type": "string",
        "i18nID": "I18N_SHIPDATE",
        "byteLenth": 30,
        "i18nLangText": [
          {
            "lang": "en",
            "text": "Carrier Pickup Date"
          }
        ]
      },
      {
        "kind": "palletCount",
        "type": "number",
        "i18nID": "I18N_SHIPPALLETCOUNT",
        "byteLenth": 10,
        "i18nLangText": [
          {
            "lang": "en",
            "text": "Number of Pallets"
          }
        ]
      }
    ],
    "items": [
      {
        "deliveryId": "12312312",
        "carCod": "UPS",
        "shipmentDateTime": "2018-06-04T12:00:00.000Z",
        "addressPostalCode": "77345",
        "palletCount": 2,
        "relationships": [
          {
            "kind": "delivery",
            "type": "self",
            "link": {
              "href": "~/delivery/12312312",
              "name": [
                {
                  "lang": "en"
                },
                {
                  "text": "Delivery"
                }
              ]
            }
          },
          {
            "kind": "carCod",
            "type": "self",
            "link": {
              "href": "~/carrierCodes/12312312",
              "name": [
                {
                  "lang": "en"
                },
                {
                  "text": "Carrier Selected"
                }
              ]
            }
          },
          {
            "kind": "palletCount",
            "type": "collection",
            "link": {
              "href": "~/shippableInventory/12312312",
              "name": [
                {
                  "lang": "en"
                },
                {
                  "text": "Shipment Inventory"
                }
              ]
            }
          }
        ]
      }
    ]
  }
}