Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Question on Naming Scheme Compatibility with JSONLD #4

Open
ChrisJMacdonald opened this issue Mar 2, 2023 · 4 comments
Open

Question on Naming Scheme Compatibility with JSONLD #4

ChrisJMacdonald opened this issue Mar 2, 2023 · 4 comments

Comments

@ChrisJMacdonald
Copy link

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,

@AP-G
Copy link
Contributor

AP-G commented Mar 2, 2023

First, a general remark: The JSON Schema (draft) publication follows the UN/CEFACT JSON Schema Naming and design rules (NDR) that can be found here:

https://unece.org/trade/trade-facilitation-and-e-businessuncefact/json-schema-naming-and-design-rules

This NDR assures that the ruleset of the underlying (reference) data model is respected according to the Core Component Technical Specification (CCTS). This is the foundation of all UN/CEFACT semantic data modelling work since decades.

Your question points out one significant topic. The data model originates from a process-based data modelling view. All relevant information is clustered according to its process relationship. For instance, all information that is needed for a contractual agreement is grouped under "...Agreement", all that is needed for delivery under "...Delivery" and all that is needed for payment under "...Settlement". So far, so good. Having these basic data classes, issues start to rise when it comes to message design or information exchange design.
Around 20 years ago, the first XML-based UN/CEFACT standard messages had been developed using these classes. From the data model perspective, for instance, the information about a seller, a buyer and the agreed on product price all fall under the "...Agreement" classes. So, the first messages only used this one (global) data type to model this information. Additional (human, but not computer readable) documentation defined, that for instance a price shall not be defined on message header level, and the seller shall not be changed on message line item (product) level.
This led to a lot of implementation issues in practice, as all of these rules had to be manually implemented by the developers. The XSD files just had the global data types allowing all of this information. So, it was decided to contextualise those classes for the real-life-implementation-needs. "Header" and "Line" was added to the contextualised classes. This way, the "...HeaderAgreement" did not offer the ability to change a product price any more and the "...LineAgreement" did not offer the ability to change the seller any more. The same is true for the "...Settlement"

The JSON Schema NDR takes all of these decisions into account. This is why there is more than one export variant available:

  1. JSON Schemas that represent the contextualised message data structures (snapshot)
  2. JSON Schemas that represent the contextualised domain specific data structures (subset) (e.g. Supply Chain, Multimodal Transport ...); So one level higher
  3. JSON Schemas that represent the complete library starting from the Buy-Ship-Pay-view and representing all levels of contextualisation (library)

Most of those decisions are (to my understanding) taken into account in the JSON LD vocabulary, but only as a one-in-all respesentation. At the same time, it looks like the JSON-LD, groups some of the classes. As a consequence it looks, like it "only" represents the uncontextualised, highest level. This means that all the business requirement knowledge, that is taken into account in the different contextualisations from real-life-requirements, gets a little bit "hidden" in the JSON LD vocabulary.
To me it looks like this happened to the "...Settlement". While the original CEFACT standard, the library, contextualises on purpose between "Header" and "Line", it looks like this differentiation is taken out in the JSON LD publication.
As a consequence, an implementer of the vocabulary must know about the requirements, that are not documented in the vocabulary itself.

Coming back to your original question. The "applicableTradeSettlement" in the vocabulary does not contain the contextualisation information the same way, as it is done in the CEFACT semantic library or the JSON schemas.
Looking at "...Agreement": You have to know that you must use for instance
https://vocabulary.uncefact.org/HeaderTradeAgreement
and
https://vocabulary.uncefact.org/LineTradeAgreement
instead. Everything is linked, but, at least to myself (and you according to your question), it is not so clear to identify the different contextualisations and when to use what.

So, the naming (for "Agreement") is the same, if you know what contextualisation to use. But for Settlement there seems to be a difference, indeed:
https://vocabulary.uncefact.org/specifiedLineTradeSettlement
https://vocabulary.uncefact.org/HeaderTradeSettlement

I hope, my long answer helps a bit. It may be valuable to put your issue in the JSON-LD repo as well / instead, as the JSON schemas here represent what is defined in "the UN/CEFACT standard". I would be happy to be pointed to the JSON LD Naming and Design Rules document, where all those rules are defined to be able to automate the needed mapping.

BR,
Andreas

@ChrisJMacdonald
Copy link
Author

Thank you very much for your detailed answer Andreas, gave me some great material to go away and familiarise myself with.
I agree that the Business Requirements may get a little bit hidden in the JSONLD spec. However, upon further looking it may be that this is just more hidden to the human reader rather than the information itself.
Using the Header vs Line issue to expand upon this, we can see that:
https://vocabulary.uncefact.org/applicableTradeSettlement is a property of type https://vocabulary.uncefact.org/HeaderTradeSettlement
and
https://vocabulary.uncefact.org/specifiedLineTradeSettlement is a property of type https://vocabulary.uncefact.org/LineTradeSettlement
So the context is retained through the mechanism of JSONLD.
I had also forwarded this issue onto the JSONLD Slack channel, and one response I got was

"there is some clean up happening when generating json-ld. Soon there will be more clean up (eg recognising that voyage is a valid subtype or transportMovement)"

So I'll follow up with them to see exactly how this clean up is functioning.

Cheers

@ChrisJMacdonald
Copy link
Author

For anyone who may see this in the future, The JSON LD Project has updated the names and brought them more in line with the JSON Schema. For example:

  • TradeTransaction is now https://vocabulary.uncefact.org/SupplyChainTradeTransaction
  • applicableTradeAgreement is now https://vocabulary.uncefact.org/applicableHeaderTradeAgreement
  • applicableTradeDelivery is now https://vocabulary.uncefact.org/applicableHeaderTradeDelivery

However, applicableTradeSettlement is still the same, so odd how it hasn't received the same treatment.

@AP-G
Copy link
Contributor

AP-G commented May 6, 2023

One additional comment on a possible difference between the JSON-LD vocab and JSON Schema:

The JSON schema exports reflect the complete library including all semantic (business requirement related) decisions.

One example: The document (message) level nearly never uses the highest level data types, as they contain not the right level of contextualisation. The highest level (here BSP) is the result of several decades of international cross-industy and administrative harmonisation. It assures that all the structures are consistent through all their usages and applications in each domain, sector, industry or country.
For instance, it assures that a Party, Consignment, Shipment, Movement, Event or TransportEquipment always contains the same semantic definitions and the same properties to be specified. And exactly this - harmonisation and interoperability is the main purpose of that level.
In practice this outer - or highest level gets contextualised and sub-setted for the specific business process requirements or industry requirements. This is the reason why all the differenct (domain) specific subset Reference Data Models exist:

  • CrossBorderManagement
  • MutlitModalTransport
  • Payment
  • SupplyChain
  • Sustainability (Track and Trace)
  • Certification
  • Tourism

So those subsets contain only parts of and maybe more specific parts of the BSP (restrictions on properties and codes, clearer definitions for the given context, document related message structures).

I am not sure if this level is reflected in the JSON-LD vocab in a comparable way. I would be happy to learn if and how this is reflected.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants