Project Details

Project Identifier
Bureau Decision #
#1907014; #1912058; #2003088; #2006001, #2009042; #2101080, #2101085, #2102092, #2112055, #2201058
Project Proposal Status


Project Page


Supporting VC
Project Lead
HoD Support
Submitted date
Draft Development Completion
Publication Date

Project purpose

To define a standard methodology that can be used to produce high quality OpenAPI specifications and JSON-LD dictionaries from existing UN/CEFACT semantic library content, particularly the Reference Data Models (RDM).  The methodology will be complete and proven successful when users can:

  • Re-use our semantics: UN/CEFACT library content (RDM) can be imported into any conformant modelling tool or semantic tool.
  • Model consistently: API Resource / Event models and JSON-LD dictionaries can be created in any conformant modelling tool and easily mapped to the imported RDM definitions.
  • Publish specifications: API reference specifications (Including Open API3.0 and JSON-LD) can be generated from the modelling tool and published to open platforms such as Github.
  • Test conformance of their implementations. Actual API implementations can be tested against the reference specifications and a conformance report generated.

We will know this work is successful when the world wide community of web developers are actively using UN/CEFACT semantic standards in their Trade & Transport system Web APIs.

Project scope

The dark blue boxes on the architecture diagram below highlight the specific work items in this work package.

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.
  • Generate JSON-LD dictionaries for use by any semantic processor


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.

Project Deliverables

The project deliverables are:

  • Deliverable 1
    • Guideline on Model interchange. A simple and standard JSON structure/schema for the interchange of 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.
  • Deliverable 2
    • Guideline on Open API UML Profile.  A simple UML profile that defines a consistent approach to modelling web resources in UML.  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.
  • Deliverable 3
    • Guideline on Open API3.0 NDR and interface conformance rules.  Serialisation rules for the generation of Open API 3.0 specifications from models. A set of testable rules, supported 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
  • Deliverable 4
    • Guideline on JSON-LD NDR and dictionary conformance rules.  Serialisation Rules for the generation of JSON-LD dictionaries from models. A set of testable rules supported by an open source testing tool that can assess any JSON-LD snippet for conformance against the UN/CEFACT JSON-LD dictionary. 

Exit Criteria

The exit criteria will be:

  • For Deliverable 1
    • Guideline ready for publication
  • For Deliverable 2
    • Guideline ready for publication
  • For Deliverable 3
    • Guideline ready for publication
  • For Deliverable 4
    • Guideline ready for publication

Project Team Membership and Required Functional Expertise

Membership is open to UN/CEFACT experts with broad knowledge in the area of:

  • Information Modelling
  • REST API Design
  • UML

In addition, Heads of Delegations may invite technical experts from their constituency to participate in the work. Experts are expected to contribute to the work based solely on their expertise and to comply with the UN/CEFACT Code of Conduct and Ethics.

Geographical Focus

The geographical focus is global.

Initial Contributions

The following contributions are submitted as part of this proposal. It is understood that these contributions are only for consideration by the Project Team and that other participants may submit additional contributions in order to ensure that as much information as possible is obtained from those with expertise and a  material interest in the project. It is also understood that the Project Team may choose to adopt one or more of these contributions “as is”.

List any initial contributions:

  • edi3.org tools & methods specifications.

Resource Requirements

No additional secretariat resources will required.

Project Leadership

Proposed co-lead (deliverables 1 & 2) Steven Capell

Proposed co-lead (deliverables 3) Andreas Pelekies

Proposed co-lead (deliverables 4) Nis Jespersen

Project Proposal Files

  File Modified
PNG File image2019-6-21_16-26-19.png Jun 21, 2019 by Malik
PDF File 190617-3a ISCO ProjectProposal_RDM2API v2.pdf Jun 21, 2019 by Malik