RDM2API
other
Project Details
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: 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. The dark blue boxes on the architecture diagram below highlight the specific work items in this work package. Project purpose
Project scope
- 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.
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
