These Guidelines have been established to assist developers by providing a basic set of rules for creating OpenAPI Documents based on the WCO Data Model (DM), with the aim of ensuring that the electronic messages specified based on the OpenAPI Document comply with the WCO DM. The Guidelines include a definition of what the final WCO DM compliant OpenAPI Document might look like.
The Guidelines are focused on the schema definition of OpenAPI; they do not address the OpenAPI service definitions.
The WCO DM building block is composed of three main layers. The first layer is the ‘business process’, which clarify the specific context in which the WCO DM is implemented. The next is the ‘semantic’ layer, which lays down conceptual definitions of the WCO DM data object. The semantic layer is divided into two sub-layers, 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 layer is concerned with electronic messages
The construct of the WCO DM’s electronic message format is fully controlled by the semantic layer, 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 and data exchange protocols for implementing the WCO DM. The WCO electronic message format/data exchange protocol guidelines ensure the proper level of conformity between the electronic message and its conceptual semantic basis.
Application Programming Interfaces (APIs) form the connecting glue between modern applications. Nearly every application contains APIs to connect with corporate data sources, third party data services or other applications. Creating an open description format for API services that is vendor-neutral, portable and open is critical to accelerating the vision of a truly connected world.
The purpose of the Open API Initiative (OAI) is to create an open approach to governing the specifications used for describing RESTful APIs. OAI is organized as a Linux Foundation Collaborative Project; it promotes APIs as a fundamental building block of modern software to address the challenges of standardizing and documenting the APIs that are driving the modern API economy. Such initiatives are critical to the success of interoperable and innovative ICT solutions.
OAI outlines the use of OpenAPI Specifications (OAS) – a widely adopted industry standard for describing modern APIs. OAS is a standard, language-agnostic interface to RESTful APIs, which allows both humans and computers to discover and understand a service’s capabilities without access to its source code.
The OAS standard provides that all definitions and descriptions of an API are contained in an OpenAPI Document (or a set of OpenAPI Documents), including a collection of OpenAPI Objects . While all these Objects contain comprehensive information to describe an API, including service interface specifications, the WCO DM model primarily covers those OpenAPI Objects that relate to data and schema definitions. Such data and schema definitions describe the API data input in the request body, or the API output in the response body. In this connection, the OAS defines its data objects using Data types, comprised of Primitive data types and Object data types.
The OAS Primitive data types are based on the data types supported by the JSON Schema Specification Wright Draft 00 .. OAS Primitive data types correspond to the WCO DM format representation for each WCO data element. OAS Primitives consist of the integer, number, string and Boolean data type, qualified with specific formats. Meanwhile, WCO DM format representation consists of alpha (a), numeric (n) or a combination of both, supplemented by the length of the data, either as a fixed or variable length. Mapping between OAS Primitive data types will be needed to determine how the WCO DM format representation can be represented in OAS Primitive type.
In addition to the Primitives, OAS also supports user-defined data types, represented with the Object data type. The Object data type is defined using a schema under the Component object that holds reusable objects for different aspects of OAS in the OAS Document. The OAS Object data type corresponds to all complex structures in the WCO DM Library represented by WCO DM classes and information packages (i.e. the Base, Derived and My Information Package).
All data nodes in the OAS data definition are represented by properties defining the data node. A property with a data type object could have a property called Properties to contain its children, creating a parent-child relationship. The UML Class Diagram could represent the structure of the parent-child relationship between different OAS data nodes, and could thus be directly mapped to the WCO DM UML Class Diagram.
The schema defining the OAS Object data type is composed of properties . In addition, OAS allows the use of extensions to the standardized properties. The extension properties are implemented as patterned fields that are always prefixed by “x-.” An extension property is used to hold essential WCO DM information, such as the WCO ID and WCO Position ID for direct reference to a particular WCO DM data object from an OAS data node.
OAS implementation of the WCO DM includes several properties, such as those shown below:
OAS properties | WCO DM equivalent | Remarks |
---|---|---|
Property name/key | WCO DM XML Tag name | OAS does not define a specific property name for identifying a property. |
Type | Reference to WCO DM classes/data elements | An OAS property with an Object data type corresponds to a WCO DM class; an OAS property with a Primitives data type corresponds to a WCO DM data element. |
Example | Data example to help understand the specifications of a property. | |
x-wcoid | WCO ID | OAS extension to indicate the WCO ID of a WCO DM data element/class. |
x- wcopi | WCO position ID | OAS extension to indicate the position ID of a WCO DM data element/class. |
An OpenAPI document could be represented in either JSON or YAML . The WCO DM supports the use of YAML for expressing a WCO DM using OpenAPI. The YAML website describes YAML as a human-friendly data serialization language suitable for all programming languages, but commonly used for configuration files and in applications where data is being stored or transmitted. YAML has a minimal syntax and uses indentation to indicate nesting and structure.
The general YAML notation characteristics include the following:
• a piece of data is represented as a key – value pair; the key is separated from the value by a colon (“:”)
• A list of information (array) is started by a dash, followed by a space (“-”).
The WCO Data Model is the only source for business rules, cardinalities, formats, core data types, code sets, class definitions and the message structure. The business rules set by the users, which define the subset, are the supplementary source.
The structure of the electronic message is included in field components, a root document object of the OpenAPI document. The component field is used to hold various schemas for the specifications. The root element of the schema would be the root WCO DM class for a particular message.
The key of the YAML data piece uses the WCO DM’s XML Tag name.
The key name of a composite data structure (i.e., class) is represented in lowerCamelCase
components:
schemas:
declaration:
components:
schemas:
declaration:
type: Object
properties:
issueDateTime:
components:
schemas:
declaration:
type:Object
x-wcoid: ‘42A’
x-wcopi: ‘0001D’
properties:
issueDateTime:
$ref: ‘#/components/schemas/dateTimeType’
x-wcoid: ‘D011’
x-wcopi: ‘0001D335’
The WCOPI entries could be found in the column “Unique Position ID” of the Base Information Package and Additional Information Package.
components:
schemas:
goodsLocation:
#...other details omitted
authorizationId:
components:
schemas:
seal:
#...other details omitted
id:
components:
schemas:
carrier:
#...other details omitted
name:
components:
schemas:
additionalDocument:
#...other details omitted
typeCode:
The WCO library of data elements includes column “XML Tag” to be used for the attribute’s key name.
schemas:
declaration:
type:Object
x-wcoid: "42A"
properties:
carrier:
$ref: ‘#/components/schemas/declaration.carrier’
x-wcoid: "18A"
x-wcopi: "0178D"
declaration.carrier:
type:Object
properties:
id:
$ref: ‘#/components/schemas/identifierType'
x-wcoid: "R012"
x-wcopi: "0178D99"
name:
$ref: ‘#/components/schemas/textType'
x-wcoid: "R011"
x-wcopi: "0178D98"
A sample OpenAPI Document for a Cargo Report Import message with the basic rules applied is shown in Appendix I to 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 differently in different message formats. For instance, the XML electronic message format represents CDT supplementary attributes as XML attributes.
<GoodsMeasure>
<GrossWeightMeasure unitCode=”KGM”>100000</GrossWeightMeasure >
</GoodsMeasure>
As for the OpenAPI document and JSON electronic message format, there are two possible ways to represent the data type:
{
"goodsMeasure":
{
"grossWeightMeasure":{"content": 100000, "unitCode": "KGM"}
}
}
{
"goodsMeasure":
{
"grossWeightMeasure":100000
}
}
Trait | Complex type | Simple type |
---|---|---|
Message size | Relatively bigger message size | Relatively compact and smaller message size (The omission of supplementary attributes of the CDT structure help reduces the overall size of the electronic message format) |
Data qualifier (e.g., unit measurement of weight, the currency of monetary amount) | Flexible data qualifier | No qualifier. (No qualifier could be provided in the electronic message. A fix or default qualifier could be added outside the electronic message specification, e.g., in the business rules. The default qualifier may be applicable in the case where, for example, the sender and recipient agree to use only one currency of a monetary amount, such as EUR Therefore, could be omitted)) |
The WCO DM CDT structure follows the UN/CEFACT’s CDT as specified in the Core Components Data Type Catalogue version 2.01, as found in the table below:
Name | Attribute Name | Tag Name | Simple Type |
---|---|---|---|
Amount. Type | Amount. content | content | decimal |
Amount. Type | Amount Currency. Identifier | currencyID | string |
Binary Object. Type | Binary Object. content | content | base64Binary |
Binary Object. Type | Binary Object. Format. Text | format | string |
Binary Object. Type | Binary Object. Mime. Code | mimeCode | string |
Binary Object. Type | Binary Object. Encoding. Code | encodingCode | string |
Binary Object. Type | Binary Object. Character Set. Code | characterSetCode | string |
Binary Object. Type | Binary Object. Uniform Resource. Identifier | uri | anyURI |
Binary Object. Type | Binary Object. Filename. Text | filename | string |
Code. Type | Code. content | content | string |
Code. Type | Code List. Identifier | listID | string |
Code. Type | Code List. Agency. Identifier | listAgencyID | string |
Code. Type | Code List. Agency Name. Text | listAgencyName | string |
Code. Type | Code List. Version. Identifier | listVersionID | string |
Code. Type | Code. Name. Text | name | string |
Code. Type | Code List. Name. Text | listName | string |
Code. Type | Language. Identifier | languageID | string |
Code. Type | Code List. Uniform Resource. Identifier | listURI | anyURI |
Code. Type | Code List Scheme. Uniform Resource. Identifier | listSchemeURI | anyURI |
Date Time. Type | Date Time. content | content | string |
Date Time. Type | Date Time. Format. Code | formatCode | string |
Identifier. Type | Identifier. content | content | string |
Identifier. Type | Identification Scheme. Identifier | schemeID | string |
Identifier. Type | Identification Scheme. Name. Text | schemeName | string |
Identifier. Type | Identification Scheme Agency. Identifier | schemeAgencyID | string |
Identifier. Type | Identification Scheme. Agency Name. Text | schemeAgencyName | string |
Identifier. Type | Identification Scheme. Version. Identifier | schemeVersionID | string |
Identifier. Type | Identification Scheme Data. Uniform Resource. Identifier | schemeDataURI | anyURI |
Identifier. Type | Identification Scheme. Uniform Resource. Identifier | schemeURI | anyURI |
Identifier. Type | Indicator. content | content | boolean |
Measure. Type | Measure. content | content | decimal |
Measure. Type | Measure Unit. Code | unitCode | string |
Numeric. Type | Numeric. content | content | decimal |
Quantity. Type | Quantity. content | content | decimal |
Quantity. Type | Quantity Unit. Code | unitCode | string |
Text. Type | Text. content | content | string |
Text. Type | Language. Identifier | languageID | string |
The primary objective of these Guidelines is to ensure that the electronic messages produced based on an OpenAPI Document composed by following the Guidelines comply with the WCO DM. Adherence to the rules specified in these Guidelines will help to ensure that the resulting electronic messages, in particular JSON, comply with the JSON Guidelines and therefore ensure interoperability between different IT systems.
It is possible to add additional fields/information to an OpenAPI Document beyond the rules prescribed by the Guidelines (e.g., examples, national data description, etc.), as long as the additional information will not have any impact on the format of the electronic messages produced based on the OpenAPI Document. In other words, the compliance of an OpenAPI Document is not measured against its conformity with the rules set out in the Guidelines, but by analyzing the validity – against the JSON Guidelines – of an electronic message produced based on the OpenAPI Document.
components:
schemas:
declaration:
type:Object
x-wcoid: 42A
x-wcopi: 0001D
properties:
id:
$ref: ‘#/components/schemas/identifierType'
x-wcoid: "D014"
x-wcopi: "0001D336"
issueDateTime:
$ref: ‘#/components/schemas/dateTimeType’
x-wcoid: "D011"
x-wcopi: "0001D335"
goodsMeasure:
$ref: ‘#/components/schemas/declaration.goodsMeasure'
x-wcoid: "65A"
x-wcopi: "2077D"
borderTransportMeans:
$ref: ‘#/components/schemas/declaration.borderTransportMeans’
x-wcoid: "15A"
x-wcopi: "0071D"
carrier:
$ref: ‘#/components/schemas/declaration.carrier’
x-wcoid: "18A"
x-wcopi: "0178D"
declaration.goodsMeasure:
type:Object
properties:
grossWeightMeasure:
$ref: ‘#/components/schemas/measureType’
x-wcoid: "131"
x-wcopi: "2077D343"
declaration.borderTransportMeans:
type:Object
properties:
arrivalLocation:
$ref: ‘#/components/schemas/declaration.borderTransportMeans.arrivalLocation
x-wcoid: "11C"
x-wcopi: "0074D"
departureLocation:
$ref: ‘#/components/schemas/declaration.borderTransportMeans. departureLocation’
x-wcoid: "98B"
x-wcopi: "0098D"
builtYear:
$ref: ‘#/components/schemas/dateTimeType’
x-wcoid: "268"
x-wcopi: "0071D615"
id:
$ref: ‘#/components/schemas/identifierType'
x-wcoid: "T006"
x-wcopi: "0071D597"
journeyId:
$ref: ‘#/components/schemas/identifierType'
x-wcoid: "149"
x-wcopi: "0071D608"
name:
$ref: ‘#/components/schemas/textType'
x-wcoid: "T005"
x-wcopi: "0071D459"
registrationNationalityCode:
$ref: ‘#/components/schemas/codeType'
x-wcoid: "T014"
x-wcopi: "0071D599"
scheduledConveyanceId:
$ref: ‘#/components/schemas/identifierType'
x-wcoid: "205"
x-wcopi: "0071D613"
stayId:
$ref: ‘#/components/schemas/identifierType'
x-wcoid: "010"
x-wcopi: "0071D614"
crewMember:
$ref: ‘#/components/schemas/declaration.borderTransportMeans.crewMember’
x-wcoid: "39A"
x-wcopi: "0091D"
master:
$ref: ‘#/components/schemas/declaration.borderTransportMeans.master’
x-wcoid: "87A"
x-wcopi: "0109D"
declaration.borderTransportMeans.arrivalLocation:
type:Object
properties:
arrivalDateTime:
$ref: ‘#/components/schemas/dateTimeType’
x-wcoid: "172"
x-wcopi: "0074D11440"
declaration.borderTransportMeans.departureLocation:
type:Object
properties:
departureDateTime:
$ref: ‘#/components/schemas/dateTimeType’
x-wcoid: "156"
x-wcopi: "0098D11441"
declaration.borderTransportMeans.crewMember’:
type:Object
properties:
id:
$ref: ‘#/components/schemas/identifierType'
x-wcoid: "R033"
x-wcopi: "0091D644"
declaration.borderTransportMeans.master:
type:Object
properties:
id:
$ref: ‘#/components/schemas/identifierType'
x-wcoid: "R017"
x-wcopi: "0109D671"
name:
$ref: ‘#/components/schemas/textType'
x-wcoid: "R016"
x-wcopi: "0109D670"
personData:
$ref: ‘#/components/schemas/declaration.borderTransportMeans.master.personData’
x-wcoid: "60C"
x-wcopi: "2072D"
declaration.borderTransportMeans.master.personData:
type:Object
properties:
birthDateTime:
$ref: ‘#/components/schemas/dateTimeType’
x-wcoid: "425"
x-wcopi: "2072D683"
declaration.carrier:
type:Object
properties:
id:
$ref: ‘#/components/schemas/identifierType'
x-wcoid: "R012"
x-wcopi: "0178D99"
name:
$ref: ‘#/components/schemas/textType'
x-wcoid: "R011"
x-wcopi: "0178D98"
dateTimeType:
type:Object
properties:
formatCode:
type: string
content:
type: string
measureType:
type:Object
properties:
unitCode:
type: string
content:
type: decimal
identifierType:
type:Object
properties:
schemeId:
type: string
content:
type: number
textType:
type:Object
properties:
languageId:
type: string
content:
type: string
codeType:
type:Object
properties:
listId:
type: string
content:
type: string
{
"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": ""}
}
}
}
}