Draft response to JSON comment from Australia

["G. Ken Holman" <gkholman@CraneSoftwrights.com>]

Fellow UBL TC members,

The JSON task group has drafted below a response to the comment 
received (with thanks!) from the AusDigital project of the Digital 
Business Council REST/JSON technical working group:

  https://lists.oasis-open.org/archives/ubl-comment/201705/msg00007.html

... regarding:

  http://docs.oasis-open.org/ubl/UBL-2.1-JSON/v1.0/UBL-2.1-JSON-v1.0.html

At our next meeting I will ask the TC if it accepts this response 
below as suitable to be posted to the comment list as a formal 
disposition of the comment.

Thanks for taking the time to review it.

. . . . . . . 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:

  http://ausdigital.org/specs/ausdigital-syn/2.0/#ccts-texttype
  "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:

  http://docs.oasis-open.org/ubl/UBL-2.1-JSON/v1.0/cnd02/UBL-2.1-JSON-v1.0-cnd02.html#S-BBIE-EXPRESSION
   "Note":[{"TextContent":"Test","LanguageIdentifier":"en"},
           {"TextContent":"Tester","LanguageIdentifier":"fr"}]

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:

  http://docs.oasis-open.org/ubl/UBL-Governance/v1.0/cn01/UBL-Governance-v1.0-cn01.html#S-PRESERVING-BACKWARD-COMPATIBILITY
  "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.


--
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) |