Tools and Methods
UN/CEFACT semantic models such as the Core Component Library are essentially the semantic dictionary that is used to create standard EDIFACT documents and XML schema. Web platform APIs will have a different granularity than traditional EDIFACT documents but can nevertheless be built upon the same semantic dictionary (which is published as a CSV file).
This suite of specifications defines a repeatable methodology to import UN/CEFACT semantics, model web API resources, then generate and publish consistent reference APIs and JSON-LD definitions. This will allow business subject matter experts and/or information modellers to quickly and consistently generate high quality API specifications that leverage existing semantic libraries.
We hope that the value of these specifications will not be limited to UN/CEFACT project teams. The specifications should be re-usable by any design team that needs to develop REST API specifications that leverage some existing library of definitions.
Overview of Methodology Specifications.
The diagram below shows the relationships between the methodology specifications (dark blue), the semantic library inputs (light blue), the outputs (green) and implementer systems (grey).
A UN/CEFACT business expert would use conformant modelling tools as follows.
- Import reference libraries such as UN/CEFACT RDM.
- Define web resources and their state lifecycles using simple UML class and state-chart diagrams.
- Link relevant semantic definitions from the imported RDMs to the web resources.
- Generate Open API 3.0 reference specifications and publish them to any platform that is readily accessible to web developers.
A web developer that is charged with implementing web APIs that comply with UN/CEFACT standards would use the published specifications as follows.
- Import the Open API 3.0 reference specification into their preferred web development tool.
- Implement an API in accordance with the specification, including any non-breaking extensions.
- Run the open source test harness against their implementation and publish the conformance report.
Model Interchange Specification
A standard JSON structure/schema for the representation of semantic library content and API models. This is used to
- import library content into any conformant modelling tool, and to
- interchange API models between conformant modelling tools.
A DSL (domain specific language) approach is preferred here because it will be simpler and more stable than XMI (interchange standard for UML tools) and will allow non-UML based tools to participate equally in the market.
UML Profile Specification
When the modelling tool is UML based (not all tools will be) then a simple UML profile that defines a consistent approach to modelling web resources in UML is needed. The profile would most likely include
- A UML class diagram profile for web resources, verbs, paths, and associated definitions.
- A UML state chart profile for web resource state lifecycles and events.
Open API3.0 NDR & Conformance Rules
Naming & Design Rules for the generation of Open API 3.0 reference specifications from the models. This specification will also define conformance rules that can be implemented in a test harness that can be used to verify that any implementation API is a conformant implementation of the reference specification.
Ssupported by an open source testing tool that can assess any actual API implementation against the corresponding UN/CEFACT reference API specification. The rules would allow (but report) non-breaking extensions and would deny (and alert) breaking changes. A non-breaking change is one where a conformant API consumer is not impacted by the extensions.
JSON-LD NDR & Conformance Rules
Similar to the above but for the generation of schema.org style JSON-LD definitions. Unlike API specifications that define specific structures (nouns) and actions (verbs), mostly for transactional purposes, the JSON-LD output would be used to support consistent semantics for snippets of data such as might be generated by IoT devices or granular trade data pipeline services.
Using Conformant Tools
Tools the conform to the specifications in this section can be used to import reference libraries and generate both API specifications and JSON-LD linked data schema.