Draft vocabulary introducing multiple JSON serialization modes for the OASIS Business Document Naming and Design Rules (BDNDR)

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

Fellow UBL TC members,

Per the ad-hoc meeting on JSON syntax held earlier today, I was 
tasked with drafting some language for discussion.

It was posited in the meeting that we might support multiple modes of 
JSON serialization, each with features suitable for different data 
scenarios. Common principles in naming would span all scenarios so as 
to promote ease of understanding of instances of different modes. A 
community of JSON users would select the mode most appropriate to 
their requirements, balancing performance against features as required.

I wracked my brain trying to divine appropriate names and I'm not 
necessarily happy with what I have come up with. Please provide any 
suggestions to improve on what I've drafted below. You know how I can 
be too wordy.

And, of course, if I have overlooked any technical aspect of the 
proposed modes, please correct me.

Implementing this new proposal in the OASIS Business Document Naming 
and Design Rules will require generating in each of the JSON 
committee notes a parallel set of JSON schemas to the ones already created.

I'm prepared to do this work, but I only want to do it once, so I 
would like us all to agree on both the approaches we take and the 
names and descriptions we ascribe to these approaches.

Kenneth, would you please add a discussion item of this proposal for 
me on the agenda in the NDRSC slot? Thanks.

. . . . . . Ken

Ref: 
https://docs.oasis-open.org/ubl/Business-Document-NDR/v1.1/csd03/Business-Document-NDR-v1.1-csd03.html#S-JSON-VALIDATION-ARTEFACTS

Replace old CSD03 6.1 with the following CSD04WD01 6.1 and 6.2, 
renumbering the subsequent sections. Technical changes will need to 
be added to the subsequent sections once we have agreement on the 
generalities described here.

6 JSON validation artefacts

6.1 JSON serialization modes

6.1.1 JSON serialization mode overview

Recognizing there are different applications of the use of JSON 
syntax in different programming and data scenarios, these NDR for 
JSON have evolved to embrace the concept of three serialization modes 
of CCTS information into JSON serialized syntax: legacy mode, schema 
mode, and instance mode.

Users can assess which serialization mode meets their information 
requirements in a particular scenario. Each serialization mode is 
built on the same conventions for naming, so as to promote 
familiarity across the use of all modes. The modes are not directly 
interchangeable as each exhibit unique properties in the 
serialization that have impacts on JSON validation.

6.1.2 JSON legacy-mode serialization

The JSON legacy-mode serialization protects a given serialization of 
an instance of CCTS content from future changes in cardinality.

In this mode, the JSON array structure of object structures is used 
in the serialization of each and every BIE in a document instance, 
regardless of the declared cardinality in the CCTS model. This is 
reflected in the JSON legacy schema for the CCTS model.

Any given legacy JSON instance is guaranteed to be JSON-schema-valid 
to the current and all future JSON legacy schemas. This is due to the 
backward-compatibility of future CCTS models.

These NDR specify the creation of legacy-mode JSON schemas to be used 
to validate instances following legacy-mode serialization.

6.1.3 JSON schema-mode serialization

The JSON schema-mode serialization presents a given serialization of 
an instance of CCTS according to the current version of the CCTS 
model, respecting the declared cardinality found in the model.

In this mode, the JSON array structure is used in the serialization 
only for those BIE constructs with an unbounded maximum cardinality. 
The JSON array structure is not used for the serialization of any BIE 
construct with a maximum cardinality of 1. The JSON object structure 
is used for the serialization of any BIE construct with a maximum 
cardinality of 1. This is reflected in the JSON version schema for 
the CCTS model.

Any given version JSON instance is guaranteed to be schema-valid only 
to the current JSON version schema and not necessarily to any future 
JSON version schema. This is due to the possibility that a future 
version of the CCTS model may have increased the upper bound of the 
cardinality of any given BIE. Such would change the serialization 
from a single object structure to an array structure of object 
structures, and so the future JSON version schema would not 
successfully validate the older JSON serialization.

These NDR specify the creation of schema-mode JSON version schemas to 
be used to validate instances following schema-mode serialization.

6.1.4 JSON instance-mode serialization

The JSON instance-mode serialization is the most parsimonious of the 
three serialization modes. A string value is used for the content of 
a BBIE that does not have any supplementary components associated 
with the content. An object structure is used for the content of a 
singleton BBIE that does have supplementary components associated 
with the content. An object structure is used for the content of a 
singleton ASBIE. An array construct of object constructs is used for 
an adjacent sequence of like-named BBIEs and for an adjacent sequence 
of like-named ASBIEs.

These NDR do not specify any creation of instance-mode JSON schemas 
to be used for validation purposes. It is up to the ingesting 
application to determine the structural validity and content of a 
given construct on-the-fly.

6.2 JSON validation artefacts overview

These NDR provide for expressing the semantic model of an information 
bundle as two sets of JSON Schema [JSON Schema] artefacts that 
support the definition and validation of the structure and content of 
JSON documents in support of legacy-mode serialization and 
schema-mode serialization..

These rules do not require these artefacts to be located in any 
particular directory structure.


--
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$125 (5 hours free) |
Essays (UBL, XML, etc.) http://www.linkedin.com/today/author/gkholman |