These Guidelines have been established to assist developers by providing a basic set of rules for creating JavaScript Object Notation (JSON) messages based on the WCO Data Model. The Guidelines include a definition of what the final JSON message should look like.
The WCO DM is composed of three building blocks. The first block is the ‘business process’, which clarifies the specific context in which the WCO DM is implemented. The next is the ‘semantic’ block, which lays down conceptual definitions of the WCO DM data object. The semantic block is divided into two sub-blocks, namely the ‘data library’ which acts as a data dictionary where all data objects – including classes and data elements – are defined; and the ‘information model’ which clarifies the relationship between one data object and another, as well as the cardinality and granularity of the respective data objects. The third block is concerned with electronic messages, i.e., the objects that actually transmitted in a data exchange process.
The construct of the WCO DM’s electronic message format is fully controlled by the semantic block, ensuring the consistency of the message content regardless of the message format being used to carry the information.
The WCO supports several prominent message formats for implementing the WCO DM. The WCO electronic message format guidelines ensure the proper level of conformity between the electronic message and its conceptual semantic basis.
Use of the JSON message format for implementing the WCO DM is now supported, taking into account the various advantages offered by this message format. The JSON electronic format is ubiquitous on the World Wide Web (i.e. the internet) and is used by many web services. By design, JSON messages are relatively lightweight, thus helping to increase the efficiency of electronic message processing. At the same time, the JSON format is considered to be ‘clean’, and therefore readable by humans.
JSON was created in the early 2000s to be minimal, portable and textual. As a subset of JavaScript (a web browser scripting language), JSON is widely used for public Application Programming Interfaces (APIs). The JSON message format was standardized in 2013 as ECMA-404 , and published in 2017 as RFC8259 by the Internet Engineering Task Force (IETF). JSON is commonly associated with REST services, especially for APIs published on the World Wide Web. Although the REST architecture for APIs allows for any format, JSON provides a more flexible message format that increases the speed of communication. It is useful when developing web or mobile applications where fast, compact and convenient serialization of data is required.
The high-level characteristics of the JSON message format include the following:
• a piece of information (object) is wrapped by a pair of curly braces “{}”
• a piece of data is represented as a key – value pair. The key and value of the data are separated by a colon “:”
• A list (array) is wrapped by a pair of square brackets “[]”
• Data elements are separated by commas “,”
{"arrivalDateTime":{}}
{"journeyId": {}}
{"id": {}}
{"name": {}}
{"typeCode": {}}
{"grossWeightMeasure":{"content": 100000, "unitCode": "KGM"}}
{"issueDateTime":
{"content": "20071011090000CET", "formatCode": "304"}
}
{
"declaration":
{
"consignment":
{
"consignmentItem":
{
"commodity": {}
}
}
}
}
{
"address":
{
"cityName": {"content":"Brussels"},
"countryCode": {"content":"BE"},
"countrySubDivisionID":,
"countrySubDivisionName":,
"line": {},
"postCodeID": {"content":"1210"}
}
},
becomes
{
"address":
{
"cityName": {"content":"Brussels"},
"countryCode": {"content":"BE"},
"postCodeID": {"content":"1210"}
}
},
{
"amendment":
{
"changeReasonCode": {},
"pointer":
{
"documentSectionCode":,
"sequenceNumberic":,
"tagID": ,
}
}
},
becomes
{
"amendment":
{"changeReasonCode": {}}
}
A sample segment for a CRI message with the basic rules applied is shown in Appendix I of these Guidelines.
The CDT governs how the information must be represented. In other words, the CDT describes the data type of a data element. CDT translates into two possible ways to represent the data type:
JSON Example with Complex Type
{
"goodsMeasure":
{
"grossWeightMeasure":{"content": 100000, "unitCode": "KGM"}
}
}
JSON Example with Simple Type
{
"goodsMeasure":
{
"grossWeightMeasure":100000
}
}
{
"declaration":
{
"id": {"content": "CRI0745557", "schemeId": ""},
"issueDateTime": {"content": "20071011090000CET", "formatCode": "304"},
"goodsMeasure":
{
"grossWeightMeasure":{"content": 100000, "unitCode": "KGM"}
},
"borderTransportMeans":
{
"arrivalLocation":{
"arrivalDateTime":{"content": "20230111090000CET", "formatCode": "304"}
},
"departureLocation":{
"departureDateTime":{"content": "2023011590000CET", "formatCode": "304"}
},
"builtYear":{"content": "2010", "formatCode": "602"},
"id": {"content": "9365790", "schemeId": ""},
"journeyId": {"content": "4550", "schemeId": ""},
"name": {"content": "ABC General", "languageId": "EN"},
"registrationNationalityCode": {"content": "BE", "listId": "98"},
"scheduledConveyanceId": {"content": "8645663", "schemeId": ""},
"stayId": {"content": "07353415", "schemeId": ""},
"crewMember":
{
"id": { "content": "K04587446", "schemeId": ""}
},
"master":
{
"id": { "content": "H00456688999", "schemeId": ""},
"name": { "content": "Alice", "languageId": ""},
"personData":
{
"birthDateTime": { "content": "20071011090000CET", "formatCode": "304"}
}
},
"carrier":
{
"id": { "content": "554688-001", "schemeId": ""},
"name": { "content": "ABC LTD", "languageId": ""}
}
}
}
}