Giter Club home page Giter Club logo

spec-jsonschema's Introduction

UN/CEFACT JSON Schema NDR Technical Specification

Multiple groups within UN/CEFACT wish to develop standard Application Programming Interfaces (APIs) as part of the set of technical deliverables from their project. The RDM2API project demonstrated that it is possible to go from the semantics of UN/CEFACT towards APIs. This project aims to develop a technical specification in order to move from Reference Data Model (RDM) based deliverables to a standardized API which retains the richness of information available in RDMs.

The JSON Schema NDR TS defines a standardised method to generate the UN/CEFACT data structures of the reference data models and their derived message structures as standardised JSON schema files. The https://github.com/uncefact/spec-JSONschema publishes the standardised JSON schema files as well as examples.

This repository serves as a test platform during the project phase. Subsequently, the final location for the publication of the UN/CEFACT standards will be specified. The generated JSON schema files will serve as standardised input for the JSON-LD project from the end of this project. In this way, conformity between these two formats will be ensured.

The JSON Schema NDR Technical Specification 1.0 from the UN/CEFACT website can be found here.

Content

In this repository there are two main publications of UN/CEFACT JSON schema artefacts:

  • The first variant in the JSONSchema2020-12 folder is based on JSON schema draft 2020-12 and fully supports OpenAPI 3.1.x.

  • The second variant in the Compatibility folder supports OpenAPI 3.0.x and therefore uses some older JSON schema concepts.

Use cases for extensions, restrictions and contextualisations of the publications can be found in the examples folder.

Contribution

We invite anyone in the global supply chain space (e.g. trade, transport, finance, agriculture, travel, …) to participate and contribute. Especially we are looking for active users in API development to drive quality requirements.

Note that you need to be a registered UN/CEFACT expert in order to formally contribute as Subject Matter Expert to this specification. 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 and the policy on Intellectual Property Rights.

To register please visit https://uncefact.unece.org/display/uncefactpublic/UNCEFACT+Expert+Registration and follow the registration process.

The official UN/CEFACT project page can be found at https://uncefact.unece.org/pages/viewpage.action?pageId=83591895

Chair of the project is Marek Laskowski. Project Lead is Jörg Walther. Editors are Andreas Pelekies @AndreasPvd and Gerhard Heemskerk @GerhardHNL.

Meetings

Sessions will be held regularly on Tuesdays from 10:00-11:00 Central European Time.

The standing agenda is to review open issues or other topics that can be found on the official UN/CEFACT project page.

Meeting minutes are shared on the project page.

spec-jsonschema's People

Contributors

andreaspvd avatar ap-g avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar

Forkers

kshychko ceebell

spec-jsonschema's Issues

Duplicate keys in UNECE-BSPContextCCL.json

There are duplicate keys in UNECE-BSPContextCCL.json:

'noteType' :

    "noteType": {
      "title": "Note. Details",
      "description": "A textual or coded description, such as a remark or additional information.",
      "uncefact:type": "AggregateBIE",
      "uncefact:cefactUNId": "UN01002519",
      "uncefact:cefactBusinessProcess": "In All Contexts",
      "type": "object",
      "properties": { ... },
      "$ref": "UNECE-BasicComponents.json#/$defs/extensibleType",
      "unevaluatedProperties": false
    }

and

    "noteType": {
      "title": "Specified_ Note. Details",
      "description": "A specified textual or coded description, such as a remark or additional information.",
      "uncefact:type": "AggregateBIE",
      "uncefact:cefactUNId": "UN01015368",
      "uncefact:cefactBusinessProcess": "In All Contexts",
      "type": "object",
      "properties": { ... },
      "$ref": "UNECE-BasicComponents.json#/$defs/extensibleType",
      "unevaluatedProperties": false
    }

'subordinateLocationType':

    "subordinateLocationType": {
      "title": "Subordinate Subordinate_ Location. Details",
      "description": "A physical location or place which is a subordinate location of a subordinate location.",
      "uncefact:type": "AggregateBIE",
      "uncefact:cefactUNId": "UN01004087",
      "uncefact:cefactBusinessProcess": "In All Contexts",
      "type": "object",
      "properties": { ... },
      "$ref": "UNECE-BasicComponents.json#/$defs/extensibleType",
      "unevaluatedProperties": false
    }

and

    "subordinateLocationType": {
      "title": "Subordinate_ Location. Details",
      "description": "A physical location or place which is a subordinate location of a location.",
      "uncefact:type": "AggregateBIE",
      "uncefact:cefactUNId": "UN01004092",
      "uncefact:cefactBusinessProcess": "In All Contexts",
      "type": "object",
       "properties": { ... },
      "$ref": "UNECE-BasicComponents.json#/$defs/extensibleType",
      "unevaluatedProperties": false
    }

Question about unqualified DateTimeType

Hi there
I'm creating this issue as a question, I don't have a lot of context as I found out about this from reading the PDF at at https://unece.org/sites/default/files/2022-09/API-TECH-SPEC_JSON_Schema_NDR_version1p0.pdf

In the PDF, the unqualified dateTimeType seems to suggest that it will be a string with the jsonschema date-time format whereas the examples in this repo seem to suggest that it will be an object with two string fields (content and an optional format).

I'm wondering if this is a change in direction or if one of the github/pdf are just out-of-date.

Decimal representations in uncefact - jsonschema

The regex for decimal strings in the schema is proposed as "^([+-]?(0?|[1-9][0-9]*)(\\.?\\d+))$"

This isn't compatible with json's numeric representations and isn't compatible with most languages' float/doule toString implementations which will use E notation when the exponent is large enough.

This is just a question on whether there'd be interest in expanding this regex to allow exponent notation. The reason is that it's a lot easier for users of this jsonschema to convert their json or domain data to the appropriate types.

With exponents supported it's a simple toString, without them a user needs to first use a library to get a full positional string - this creates some friction whenever converting number to strings that match the jsonschema.

(not sure if this spec is finalized or still in draft)

Include unit conversions

Hi,

Can the unit conversion details be added to the JSON Schema output, please?

We had this on the original Excel export, so it should be possible to include it on the JSON Schema too.

We need this to properly link from QUDT (big win!). Please ref w3c-ccg/traceability-vocab#536 (comment) on more details on these requirements.

Question on Naming Scheme Compatibility with JSONLD

Just a question,

In this Cross Industry Invoice, it includes the fields

"applicableHeaderTradeSettlement": {
                "specifiedTradeSettlementPaymentMeans": {
                    "payerPartyDebtorFinancialAccount": {
                        "typeCode": false
                    }
                }
}

And in the JSONLD Spec, also under uncefact, I believe the equivalent would be:
https://vocabulary.uncefact.org/applicableTradeSettlement
https://vocabulary.uncefact.org/specifiedPaymentMeans
https://vocabulary.uncefact.org/payerPartyFinancialAccount
https://vocabulary.uncefact.org/debtorFinancialAccountTypeCode

Which follow the same nested pattern.

Is there a reason for the subtle differences between the naming? Are we able to translate easily between names or is any standardisation happening between the JSON Schemas and the JSON LD Project.

Cheers,

JSONSchema representation for "YY-MM-DD"

The uncefact spec mandates using a jsonschema date for the "YYMMDD" format. It's not listed as one of the untdid2379JsonType types that requires an additional context.

This is consistent with the ccts->edifact mappings recommended here - https://unece.org/DAM/cefact/codesfortrade/CCTS/CCTS-DTCatalogueVersion3p1.pdf
For YYMMDD it declares "Map to semantically equivalent ISO representa-
tion without century truncation"

What I'd like to know is what the recommended approach is for choosing the century for a date that only specifies the decade. Different libraries to different things and it'd be good to make sure we're confirming to the unece instead of some arbitrary library.

EG: Libraries always choose the century based on the current date. However they don't all have the same rollover points depending on the current date. EG: Today some libraries might map centuries from 00-70 to the 20th century and 71-99 to the 19th, other libraries might choose 00-69.

What is the recommendation for how the CC should be created for YYMMDD dates?

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.