OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

ubl-comment message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: Re: [ubl-comment] feedback on the OASIS UBL JSON representation

Thank you, Mike, for the question, but I am unclear as to whom it is officially directed. You have addressed me personally, but you have sent the message to the UBL Public Comment List which normally triggers a formal response from the committee. The Public Comment List is not meant for back-and-forth threaded discussions.

Please confirm if you meant to request a formal response from the committee, or if this was inadvertent.

Meanwhile, I can offer my personal response given that you have addressed me. I see the committee's response as narrowly focused on the comments from Australia relative to choices the committee has made for the JSON serialization of CCTS relative to the existing XML serialization of CCTS. As indicated, the choices made by the committee support an intermediary access point to transliterate between the two UBL syntaxes without any semantic interpretation or translation of the content. I see this as crucial in an intermediary so that there is no influence by the intermediary on the semantic interpretation available to the recipient. As long as the intermediary is doing transliteration rather than translation, the information remains uncontaminated for the recipient to interpret. The choice of XML/JSON syntax becomes irrelevant because the information is only being transliterated and not translated. The receiver receives all the information the sender sends even if it was sent in a different syntax, because the one UBL semantic model is being used for both. The UBL semantic model is chosen by the stakeholders as best representing the information desired to be exchanged by those stakeholders. That the model is expressed using CCTS and the two serializations are serializations of CCTS (and not serializations of UBL) the transliteration between the two syntaxes is possible without semantic understanding of the UBL.

I personally interpret your question quite differently. The standards you cite are all syntax serializations of differing semantic models that were developed independently by stakeholders with differing scenarios, requirements and objectives. I question the probability of semantic-free transliteration and I anticipate semantic-aware translation would be required to address the impedance between them all, and between them and UBL. How effective such a translation would be would have to be measured by each group of stakeholders looking for interoperability between the many semantic models. It is an age-old problem in data exchange standards. Even if one of the models provides a lingua-franca suitable to accommodate them all individually, that doesn't address the situation where a mandatory semantic in one model needs be satisfied by an instance of a different model that does not include that mandatory item. And so a gap analysis of the interoperability between any two models needs to be developed, and ways of addressing those gaps determined by the stakeholders.

And so my personal answer to your question is "no" ... the information the committee included in the paragraph is not addressing the interoperability between differing semantic models. That information is limited to two differing syntax serializations of a single semantic model. And so I think relative to your question an access point providing *translation* between an endpoint's choice of syntax and a network's choice of syntax imposed on the access point would, necessarily, involve semantic interpretation.

Please indicate as a reply to the Public Comment List whether or not your question was a formal submission to the UBL Technical Committee requiring a formal response. For informal discussions, I recommend posting to the UBL Dev mailing list where many participants can provide input through threaded submissions. The UBL Dev list would also get wider readership for a richer discussion.

Thanks, again, for your interest in our work.

. . . . . . Ken

At 2017-05-28 09:56 -0400, Michael Onder wrote:

Does the info in the below paragraph fit with the interopability we are tr8ying to achieve between freaight data exchange standards, like EDIFACT, GS1, ANSI X12 etc.?

Any semantic interoperability is subject to the semantic interpretation of applications acting on the different choice of syntax. Accordingly, our choices in JSON expression support semantic-free transliteration. This would accommodate a process, such as one supported by an Access Provider on a network, to transliterate between XML and JSON syntaxes without knowledge of the underlying semantics.


Michael P. Onder
9751 Rehanek Ct.
Burke VA 22015
7036443867 HOME
7035984950 CELL

On May 28, 2017 8:44 AM, "G. Ken Holman" <<mailto:gkholman@cranesoftwrights.com>gkholman@cranesoftwrights.com> wrote: Thank you, again, Steve, for your project's considered formal feedback to the UBL Technical Committee regarding our specification for a JSON alternative representation for UBL.

The technical committee has prepared the agreed-upon response below to address the points that were raised. At the end you will find our invitation for you to continue the dialogue on this topic. Please let us know if you think anything was overlooked.

. . . . . . . Ken

Regarding "the primary goal of an OASIS UBL JSON specification should be to remain developer friendly so that it is usable just like any other JSON based APIs on the web", in fact, this was not the Technical Committee's primary goal by choice. From section 1.1 Overview the specification states "intent is only to convey in syntax the information content reflecting the same abstract model of the UN/CEFACT Core Component Technical Specification 2.01 [CCTS] with which the document model was designed. Accordingly, and in parallel to an application's use of XML syntax, the JSON syntax used is generic in nature and is neither streamlined nor optimized for any particular application's objectives. As one would undertake the unmarshalling of XML syntax into internal application data structures suitable for processing, one must also undertake the unmarshalling of JSON interchange syntax into whatever internal application data structures (or other JSON representations) of the content that are suitable for the task at hand."

And so, the intention of the JSON Alternative Representation is to specify a syntax suitable for interchanging data between different applications, while it is expected that APIs will be streamlined and optimized for the objectives of particular applications. Thus it is not considered in the committee's purview to presume any particular aspect of UBL semantics would be better expressed using a less generic choice of JSON constructs suitable for interchange. We note that the OASIS Business Document Naming and Design Rules (BDNDR) is not used just for UBL but can be used for any business vocabulary designed with CCTS constructs. Thus, the syntactic choices in BDNDR are based on CCTS principles of granularity and cardinality, not on UBL nor any other semantic interpretation of the information expressed using CCTS.

Regarding "must be possible to transform XML <-> JSON so that semantic interoperability is still feasible even when one party supports JSON and the other XML.", machine transliteration between JSON and XML without semantic awareness is critical to blinkered syntax interoperability. Choices made must allow information to be round-tripped losslessly without needing to know the underlying meaning or customized expression of any particular construct.

Any semantic interoperability is subject to the semantic interpretation of applications acting on the different choice of syntax. Accordingly, our choices in JSON expression support semantic-free transliteration. This would accommodate a process, such as one supported by an Access Provider on a network, to transliterate between XML and JSON syntaxes without knowledge of the underlying semantics.

A quick review of an example AusDigial approach to the JSON expression of CCTS for UBL reveals a case in point of presuming semantic concepts in expression:

  "JSON representation SHALL NOT specify language for every string
   data element. Instead it will use the UBL document level language
   indicator "Language":"EN" using ISO 639-1 language codes"

Upon receipt of a UBL document following the BDNDR expression of a JSON CCTS text field, an AusDigital-compliant process can choose what to do with an example as follows, which would not be possible to be round-tripped back to XML:


Regarding "Processing code is a mess", we cite our above response that the format for interchange is expected to be interpreted and translated into a format suitable for processing, in particular, the kind of expected processing for the semantics of the information. Such assumptions can be tailored and tuned to the recipient's expectations, without the sender having to know the assumptions a priori.

Regarding "Potential data loss", future backward compatibility is not explicitly covered in BDNDR because BDNDR does not impose such constraints. However, the UBL use of BDNDR does impose such constraints, and these are enumerated in detail to enforce future backward compatibility as described in our UBL Governance document:

  "Therefore any proposed changes to existing elements should be as follows:
   - from optional singular to optional multiple
   - from mandatory singular to mandatory multiple
   - from mandatory singular to optional singular
   - from mandatory singular to optional multiple
   - from mandatory multiple to optional multiple"

Each of the examples cited in your comment appear to avoided by the constraints UBL imposes in its use of BDNDR.

Regarding "Namespace URI properties", it is acknowledged such have not a lot of use in JSON beyond identification of the dictionary of semantics behind the labels (which your users could presumably assume to be UBL), but are critical to the blinkered syntax interoperability of BDNDR between XML and JSON. Without the preservation of this information from XML, an Access Point wouldn't be able to recreate the XML without knowing the JSON to be UBL. As BDNDR would easily be used for non-UBL information such as medical health records, border control records, or, really, any interchange document, each JSON expression would need to carry with it the suite of namespaces applicable to the XML expression of CCTS as described by BDNDR.

Moreover, the suggested cited JSON approach of a single "$id" URI would not accommodate the need for multiple URIs supporting round-trip blinkered transliteration.

The UBL TC welcomes your feedback regarding these observations to your comments.

We hope these comments reflect your continuing ability to express UBL documents internally in your applications using JSON following your own AusDigital conventions, provided that whatever interface is used to the outside world when exchanging JSON files would support through interpretation and translation the existing BDNDR conventions tailored for the blinkered interchange of CCTS-based documents.

At 2017-05-11 06:35 +1000, Steve Capell wrote:
Hi Chet

I acknowledge that the attached email is the substance of our contribution

Although there are a further 6 links at the bottom of the principles section. What about those?

Steven Capell
Mob: 0410 437854

On 11 May 2017, at 12:29 am, Chet Ensign <<mailto:chet.ensign@oasis-open.org><mailto:chet.ensign@oasis-open.org>chet.ensign@oasis-open.org> wrote:

Hi Steven,

I'm Chet Ensign, the person in charge of helping the TC's do their work within the OASIS rules. My thanks too for the detailed review and comments.

One of the details of the rules is that contributions cannot be made via links. Feedback must be in or attached to the message itself. No need to spend time on why unless you'd like to know. I'm just writing to ask if you can confirm that the following text is the content of the contribution:

--- Begin content ---

OASIS UBL JSON Specification Review

OASIS has <<https://www.oasis-open.org/news/announcements/ubl-2-1-json-alternate-representation-v1-0-and-business-document-naming-and-desig>https://www.oasis-open.org/news/announcements/ubl-2-1-json-alternate-representation-v1-0-and-business-document-naming-and-desig>released a specification for a JSON version of the UBL document library. The purpose of this page is to privide formal feedback to the technical committtee.

We have tested the specification and have encountered some difficulties that we would like to share - together with proposed improvements.


JSON has seen significant uptake accross the web over the last decade - to the extent that the vast majority of new services are provided as REST/JSON APIs, usually with some form of OAuth2 based authentication. The reason is that it's simple and developer freindly and yet powerful enough for most needs.

We would imagine that the rationale for the OASIS technical committee to develop a JSON representation of UBL is so that UBL can ride the JSON adoption wave and thereby extend it's reach and adoption. In that case, the primary goal of an OASIS UBL JSON specification should be to remain developer freindly so that it is usuable just like any other JSON based APIs on the web. We would suggest that there are two strategic goals for a JSON representation: Â Â * That it must be developer freindly so that UBL get uptake in the REST/JSON world. Â Â * That it must be possible to transform XML <-> JSON so that semantic interoperability is still feasible even when one party supports JSON and the other XML.

We started with those goals and found that there is an inevitable choice that must be made:   * You can design a simple transformation (XML <-> JSON) but you'll end up with complex and un-freindly JSON. Or   * You can design a more complex transformation in order to get a simpler and more developer freindly JSON.

Since the transformation need only be designed once (and can be made freely avaialble) but dealing with complex JSON will impact every developer that attempts to use it, we chose the latter option. This public repository hosts our version of the UBL JSON syntax specification.   * Our <<http://ausdigital.org/specs/ausdigital-syn/2.0/>http://ausdigital.org/specs/ausdigital-syn/2.0/>JSON Syntax Specification   * Some <<https://github.com/ausdigital/ausdigital-bill/tree/master/resources/ausdigital-syn/2.0/samples/Invoice>https://github.com/ausdigital/ausdigital-bill/tree/master/resources/ausdigital-syn/2.0/samples/Invoice>UBL JSON sample invoice documents   * The <<http://ausdigital.org/docson.html#https://raw.githubusercontent.com/ausdigital/ausdigital-bill/master/resources/ausdigital-syn/2.0/spec/Invoice.json>http://ausdigital.org/docson.html#https://raw.githubusercontent.com/ausdigital/ausdigital-bill/master/resources/ausdigital-syn/2.0/spec/Invoice.json>browsable JSON invoice Schema   * The <<https://github.com/ausdigital/ausdigital-bill/tree/master/resources/ausdigital-syn/1.0/samples/Invoice>https://github.com/ausdigital/ausdigital-bill/tree/master/resources/ausdigital-syn/1.0/samples/Invoice>XML versions of the same documents   * The <<http://testpoint.io/syn>http://testpoint.io/syn>lossless transformation API   * A <<http://ausdigital.org/specs/ausdigital-bill/1.0/>http://ausdigital.org/specs/ausdigital-bill/1.0/>semantic specification that works with both XML and JSON versions

Some Specific Feedback from our Developers

About the OASIS UBL JSON representation.

Processing code is a mess:

To get IdentifierContent you need to go through 5 loops:


If to define properties as objects when maxOccurs="1", you will need only 1 loop:


Of course, you can always access items but their index without loop if you know that maxItems = 1:


But to know this you need to go to json schema and check.

This is very likely that a lot of developers will generate POJOs from json schema and they will get a bunch of classes, where each property is a List.

Potential data loss

The main idea of the specification:
Future versions of UBL may raise the cardinality of any given object and so this approach is future-proof to revisions. This approach is also consistent and is used without thought of cardinality and so should be easier for the programmer (if a little verbose). Although a change in cardinality does not apply to the Document ABIE, the array notation is used for consistency with ASBIE expressions using arrays.

It works for cardinality changes in different UBL versions, but only partially.

For example, in UBL-Invoice-2.1.xsd:

<xsd:element ref="cac:InvoicePeriod" minOccurs="0" maxOccurs="unbounded"/>

And let's assume in UBL-Invoice-2.2.xsd maxOccurs changes from "unbound" to "1":

<xsd:element ref="cac:InvoicePeriod" minOccurs="0" maxOccurs="1"/>

In this case in JSON schema UBL 2.1:

"InvoicePeriod": {
        "title": "Invoice. Invoice_ Period. Period",
        "description": "A period to which the Invoice applies.",
        "items": {
        "$ref": "../common/UBL-CommonAggregateComponents-2.1.json#/definitions/InvoicePeriod"
        "minItems": 1,
        "additionalProperties": false,
        "type": "array"

And in 2.2:

"InvoicePeriod": {
        "title": "Invoice. Invoice_ Period. Period",
        "description": "A period to which the Invoice applies.",
        "items": {
        "$ref": "../common/UBL-CommonAggregateComponents-2.1.json#/definitions/InvoicePeriod"
        "maxItems": 1,
        "minItems": 1,
        "additionalProperties": false,
        "type": "array"

The good point is that property type hasn't been changed - it remains array. That means that no need to re-write code which is parsing JSON documents.

But if cardinality change is of the other type - increase maxOccurs.

For example:

<xsd:element ref="cac:OrderReference" minOccurs="0" maxOccurs="1"/>


"OrderReference": {
        "title": "Invoice. Order Reference",
    "description": "A reference to the Order with which this Invoice is associated.",
        "items": {
        "$ref": "../common/UBL-CommonAggregateComponents-2.1.json#/definitions/OrderReference"
        "maxItems": 1,
        "minItems": 1,
        "additionalProperties": false,
        "type": "array"

Let's assume maxOccurs is changed from "1" to "unbound":

<xsd:element ref="cac:OrderReference" minOccurs="0" maxOccurs="unbound"/>
In this case, we get for an array with unlimited number of or items:

"OrderReference": {
        "title": "Invoice. Order Reference",
    "description": "A reference to the Order with which this Invoice is associated.",
        "items": {
        "$ref": "../common/UBL-CommonAggregateComponents-2.1.json#/definitions/OrderReference"
        "minItems": 1,
        "additionalProperties": false,
        "type": "array"

Again, the type remains the same, so code, which is processing JSON will still be working. But here is the potential issue - all the items except first will be ignored, if a developer will not update processing logic, which is very likely as the code is working.

If increasing maxOccurs is not a valid case for newer versions, it is highly recommended to defined properties with maxOccurs="1" as objects and not as arrays.

Namespace URI properties

Although they are optional still they do not make much sense and likely will not be processed as they do not add anything to validation against json schemas. Lets to schema references the standard JSON way rather than a UBL specific way:

It would be good to add recommendation for using json schemas according to <<http://json-schema.org/latest/json-schema-core.html#rfc.section.9>http://json-schema.org/latest/json-schema-core.html#rfc.section.9>http://json-schema.org/latest/json-schema-core.html#rfc.section.9

--- end content ---

Thanks very much for confirming.

Best regards,

/chet ensign

On Tue, May 9, 2017 at 10:25 PM, steve capell <<mailto:steve.capell@gmail.com><mailto:steve.capell@gmail.com>steve.capell@gmail.com> wrote:
Dear working group,
As the REST/JSON technical working group that is part of the Australian e-invoicing initiative led by the digital business council in conjunction with the australian tax office, we would like to offer this feedback on the OASIS UBL JSON representation.


<<http://ausdigital.org>http://ausdigital.org><http://ausdigital.org>ausdigital.org specifications are licensed under <<https://www.gnu.org/licenses/gpl-3.0.en.html>https://www.gnu.org/licenses/gpl-3.0.en.html>GPL3 and governed in accordance with <<http://www.digistan.org/spec:1/COSS>http://www.digistan.org/spec:1/COSS>COSS
Kind regards,
Steven Capell
Chair, REST/JSON technical working group
Digital Business Council


Chet Ensign
Director of Standards Development and TC Administration
OASIS: Advancing open standards for the information society

Primary: <tel:%2B1%20973-996-2298>+1 973-996-2298
Mobile: <tel:%2B1%20201-341-1393>+1 201-341-1393

Contact info, blog, articles, etc. <http://www.CraneSoftwrights.com/o/>http://www.CraneSoftwrights.com/o/ |
Check our site for free XML, XSLT, XSL-FO and UBL developer resources |
Streaming hands-on XSLT/XPath 2 training class @ US$45 (5 hours free) |

This publicly archived list offers a means to provide input to the
OASIS Universal Business Language (UBL) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: <mailto:ubl-comment-subscribe@lists.oasis-open.org>ubl-comment-subscribe@lists.oasis-open.org Unsubscribe: <mailto:ubl-comment-unsubscribe@lists.oasis-open.org>ubl-comment-unsubscribe@lists.oasis-open.org List help: <mailto:ubl-comment-help@lists.oasis-open.org>ubl-comment-help@lists.oasis-open.org List archive: <http://lists.oasis-open.org/archives/ubl-comment/>http://lists.oasis-open.org/archives/ubl-comment/ Feedback License: <http://www.oasis-open.org/who/ipr/feedback_license.pdf>http://www.oasis-open.org/who/ipr/feedback_license.pdf List Guidelines: <http://www.oasis-open.org/maillists/guidelines.php>http://www.oasis-open.org/maillists/guidelines.php Committee: <http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=ubl>http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=ubl
Join OASIS: <http://www.oasis-open.org/join/>http://www.oasis-open.org/join/

Contact info, blog, articles, etc. http://www.CraneSoftwrights.com/o/ |
Check our site for free XML, XSLT, XSL-FO and UBL developer resources |
Streaming hands-on XSLT/XPath 2 training class @ US$45 (5 hours free) |

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]