Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

RDM2API

other

Linktoparent

Project Details

Page properties
Domain
Project Identifier
Text Field
defaultexample: P1021
idpid
requiredtrue
P1079
Bureau Decision #
Text Field
defaultexample: P1021
idBureauDecision
requiredtrue
#1907014,; #1912058; #2003088; #2006001
Project Proposal Status

SP Page Status
dateMar 09, 2018 12:14
hidetrue
width25%
userMalik
statusofficial

Project Page

RDM2API

Supporting VC
Project Lead
HoD Support
Text Field
defaultexample: EU / US / UN
idHodSupport
requiredtrue
N/A
Status
Select2
defaultSelect the status for this project
idproject_status
requiredtrue
selectedIn development
  • Initiated
  • In development
  • Completed
Version
Text Field
defaultClick to set the version number
idversion_number
requiredtrue
2.0
Submitted date
Date Picker
defaultClick to set the submissions date
idsubmitted_date
requiredtrue
2019-05-06
Draft Development Completion
Date Picker
defaultDraft Development date
idDraft
2020-08-30
Publication Date
Date Picker
defaultExit date
idExit
2020-11-15
Excerpt

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

Attachments
oldfalse