JSON semantic format (JSON-NTV)
draft-thomy-json-ntv-02
| Document | Type | Active Internet-Draft (individual) | |
|---|---|---|---|
| Author | THOMY Philippe | ||
| Last updated | 2023-12-19 | ||
| RFC stream | (None) | ||
| Intended RFC status | (None) | ||
| Formats | |||
| Stream | Stream state | (No stream defined) | |
| Consensus boilerplate | Unknown | ||
| RFC Editor Note | (None) | ||
| IESG | IESG state | I-D Exists | |
| Telechat date | (None) | ||
| Responsible AD | (None) | ||
| Send notices to | (None) |
draft-thomy-json-ntv-02
Internet Engineering Task Force P. THOMY
Internet-Draft Loco-labs
Intended status: Informational 19 December 2023
Expires: 21 June 2024
JSON semantic format (JSON-NTV)
draft-thomy-json-ntv-02
Abstract
This document describes a set of simple rules for unambiguously and
concisely encoding semantic data into JSON Data Interchange Format.
These rules are based on an NTV (Named and Typed Values) data
structure applicable to any simple or complex data.
The JSON-NTV format is its JSON translation.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on 21 June 2024.
Copyright Notice
Copyright (c) 2023 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents (https://trustee.ietf.org/
license-info) in effect on the date of publication of this document.
Please review these documents carefully, as they describe your rights
and restrictions with respect to this document. Code Components
extracted from this document must include Revised BSD License text as
described in Section 4.e of the Trust Legal Provisions and are
provided without warranty as described in the Revised BSD License.
THOMY Expires 21 June 2024 [Page 1]
Internet-Draft JSON semantic format (JSON-NTV) December 2023
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Presentation . . . . . . . . . . . . . . . . . . . . . . 3
1.2. Key design features . . . . . . . . . . . . . . . . . . . 4
1.3. Conventions Used in This Document . . . . . . . . . . . . 5
2. NTV structure . . . . . . . . . . . . . . . . . . . . . . . . 6
2.1. NTV layers . . . . . . . . . . . . . . . . . . . . . . . 6
2.2. NTV entities . . . . . . . . . . . . . . . . . . . . . . 7
2.2.1. NTVsingle . . . . . . . . . . . . . . . . . . . . . . 7
2.2.2. NTVlist . . . . . . . . . . . . . . . . . . . . . . . 8
2.3. NTVtype and Namespace . . . . . . . . . . . . . . . . . . 8
2.3.1. Namespace . . . . . . . . . . . . . . . . . . . . . . 9
2.3.2. NTVtype . . . . . . . . . . . . . . . . . . . . . . . 9
2.3.3. Representation . . . . . . . . . . . . . . . . . . . 10
3. JsonNTV . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.1. JsonNTV format . . . . . . . . . . . . . . . . . . . . . 11
3.2. JsonNTVname . . . . . . . . . . . . . . . . . . . . . . . 13
3.3. JsonNTVtype . . . . . . . . . . . . . . . . . . . . . . . 13
3.4. JsonNTVvalue . . . . . . . . . . . . . . . . . . . . . . 14
4. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 15
5. Parsing a JsonValue . . . . . . . . . . . . . . . . . . . . . 17
5.1. JSON decoding . . . . . . . . . . . . . . . . . . . . . . 17
5.2. NTV entity decoding . . . . . . . . . . . . . . . . . . . 18
5.3. NTVvalue decoding . . . . . . . . . . . . . . . . . . . . 19
5.4. NTVtype decoding . . . . . . . . . . . . . . . . . . . . 19
6. Properties . . . . . . . . . . . . . . . . . . . . . . . . . 19
6.1. NTV tree . . . . . . . . . . . . . . . . . . . . . . . . 19
6.2. NTV Pointer . . . . . . . . . . . . . . . . . . . . . . . 20
6.3. NTV Comparison . . . . . . . . . . . . . . . . . . . . . 20
6.4. NTV Canonical . . . . . . . . . . . . . . . . . . . . . . 21
6.5. JSON as a subtype of NTV . . . . . . . . . . . . . . . . 22
6.6. extended NTV structure . . . . . . . . . . . . . . . . . 22
6.7. nested NTVsingle entities . . . . . . . . . . . . . . . . 23
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 24
8. Security Considerations . . . . . . . . . . . . . . . . . . . 24
9. References . . . . . . . . . . . . . . . . . . . . . . . . . 24
9.1. Normative References . . . . . . . . . . . . . . . . . . 24
9.2. Informative References . . . . . . . . . . . . . . . . . 25
Appendix A. Global NTVtype and Namespace . . . . . . . . . . . . 26
A.1. Json . . . . . . . . . . . . . . . . . . . . . . . . . . 26
A.2. Numbers . . . . . . . . . . . . . . . . . . . . . . . . . 27
A.3. Binary encoding . . . . . . . . . . . . . . . . . . . . . 28
A.4. Datation . . . . . . . . . . . . . . . . . . . . . . . . 28
A.5. Period and Duration . . . . . . . . . . . . . . . . . . . 30
A.6. Location . . . . . . . . . . . . . . . . . . . . . . . . 30
A.7. Structured data . . . . . . . . . . . . . . . . . . . . . 31
A.8. Normalized String . . . . . . . . . . . . . . . . . . . . 32
THOMY Expires 21 June 2024 [Page 2]
Internet-Draft JSON semantic format (JSON-NTV) December 2023
A.9. Namespace . . . . . . . . . . . . . . . . . . . . . . . . 33
A.10. Custom NTVtype and Namespace . . . . . . . . . . . . . . 34
Appendix B. Complete ABNF notation . . . . . . . . . . . . . . . 34
Appendix C. JSON-NTV equivalence . . . . . . . . . . . . . . . . 36
Appendix D. Mapping NTVtypes . . . . . . . . . . . . . . . . . . 38
D.1. Table-Schema . . . . . . . . . . . . . . . . . . . . . . 38
D.2. JSON Schema . . . . . . . . . . . . . . . . . . . . . . . 39
D.3. JSON Schema . . . . . . . . . . . . . . . . . . . . . . . 41
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 42
Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 42
1. Introduction
1.1. Presentation
The semantic level of JSON or CSV shared data remains low. It is
often limited to the type of data defined in those exchange formats
(strings for CSV formats; numbers, strings, arrays and objects for
JSON formats).
JSON-NTV proposes to increase the semantic level of the JSON entities
[RFC8259] by adding two additional pieces of information to a JSON
entity :
* *name*: interpretation of the JSON value in human language or
detailed information or link to external information,
* *type*: interpretation of the JSON value in a data standard (eg.
GeoJSON, datetime), in a data catalog or in a software language.
The NTV entity is thus a triplet with a mandatory element (value) and
two additional elements (name, type).
_For example, Paris location can be represented by :_
- _a name : "paris",_
- _a type : geoJSON Point coordinates [RFC7946],_
- _a value : [2.3522, 48.8566]_
The easiest way to add that information into a JSON value is to use a
JSON object with a single member. The first term is the additional
elements using the syntax JSON-ND [JSON-ND]. The second term is the
JSON value.
_The JSON value of the previous example is:_
_{ "paris:point" : [2.3522, 48.8566] }_
THOMY Expires 21 June 2024 [Page 3]
Internet-Draft JSON semantic format (JSON-NTV) December 2023
With this approach, two NTV entities are defined :
* *a primitive entity* which is not composed of any other entity,
* *a structured entity* which is an ordered sequence of NTV
entities.
as well as two JSON formats depending on the presence of the
additional elements :
* *simple format* when name and type are not present
* *named format* when name or type is present
_Example (entity composed of two other primitive entities):_
_{ "cities::point": [[2.3522, 48.8566], [4.8357, 45.7640]] }
simple format for primitive entities_
_{"cities::point": {"paris":[2.3522, 48.8566], "lyon":[4.8357,
45.7640]}} named format for primitive entities_
A JSON-NTV generator produces a JSON value from a NTV entity and vice
versa a JSON-NTV parser transforms a JSON value into a NTV entity.
The document [NTV-TAB] presents a variation of this format for
tabular and multidimensional data.
The conversion between NTV entity and native entity is outside the
scope of this note.
1.2. Key design features
The format is focused on simplicity, lightness and web usage.
The key features of this format are the following:
* *JSON as the base format*
- JSON is simple and readable as simple text
- JSON supports rich structure including nesting and basic types
- JSON is web-native and very widely used and supported
- JSON format has binary representation (eg. CBOR format)
* *high semantic level of data*
THOMY Expires 21 June 2024 [Page 4]
Internet-Draft JSON semantic format (JSON-NTV) December 2023
- wide variety of data typing
- tree-like and customisable data typing
* *compatibility with existing formats*
- All JSON data is a JsonNTV data
- All NTVtypes are standard types
* *compatibility with any type of platform*
- types and structures are independent of software and hardware
platforms
- the NTV concept is applicable to all types of "jsonable" data
* *reversibility*
- the NTV entity coming from a JSON value is identical to the NTV
entity from which the JSON value comes
- the JSON representation of an NTV entity is the same as the
JSON value used to construct the NTV entity
* *tree structure*
- all NTV entities are trees
- tree properties are applicable to NTV entities
1.3. Conventions Used in This Document
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP
14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here.
This document also uses the following terms:
*JsonText, JsonMember, JsonElement :*
These terms are defined as text, member, element in the JSON
grammar [RFC8174].
THOMY Expires 21 June 2024 [Page 5]
Internet-Draft JSON semantic format (JSON-NTV) December 2023
*JsonValue, JsonObject, JsonArray, JsonNumber, JsonString,
JsonFalse, JsonNull, JsonTrue:*
These terms correspond to entities whose representation is defined
as value, object, array, number, string, false, null, true in the
JSON grammar [RFC8174].
*JsonPrimitive:*
A JsonNumber, JsonString, JsonFalse, JsonTrue or JsonNull.
*JsonUnnamed:*
A JsonObject without a single member.
*JsonNamed:*
A JsonObject with a single member.
*NTVsingle, NTVlist:*
NTVlist and NTVsingle entities can be abbreviated as:
* NVsingle : entity with default NTVtype "json",
* NVlist : entity without NTVtype,
* TVsingle, TVlist : entity without NTVname,
* Vsingle, Vlist : NVsingle or NVlist without NTVname.
2. NTV structure
2.1. NTV layers
NTV and JsonNTV structures are defined as shown in Figure 1:
* NTV is a data triplet (NTVname, NTVtype, NTVvalue) that contains
all the information needed to build the native entity.
* JsonNTV is the JsonValue of the NTV entity. JsonNTV is used to
build an interchangeable JsonText
+--------+ JSON load +-------+ NTV load +-------+ to_obj +------+
| |---------->| |--------->| NTV |--------->|native|
|JsonText| |JsonNTV| |triplet| |entity|
| |<----------| |<---------| |<---------| |
+--------+ JSON dump +-------+ NTV dump +-------+ from_obj +------+
Figure 1: NTV layers
_Example:_
THOMY Expires 21 June 2024 [Page 6]
Internet-Draft JSON semantic format (JSON-NTV) December 2023
* _Native layer_
new_year_2022 = datetime.date(2022, 01, 01) _is a Python
variable "new_year_2022" corresponding to a datetime object_
* _NTV layer_
("new_year_2022", "date", "2022-01-01") _is a triplet_
* _JsonNTV layer_
{ "new_year_2022:date" : "2022-01-01" } _is a JsonValue_
* _JsonText layer_
'{"new_year_2022:date":"2022-01-01"}' _is a JsonString_
2.2. NTV entities
Two categories of entities (one primitive and one structured) are
defined:
* *NTVsingle* for the primitive entity,
* *NTVlist* for an ordered sequence of NTV entities
An NTV entity is therefore a tree where the leaves nodes are the
NTVsingle entities and where the inner nodes are the NTVlist entities
2.2.1. NTVsingle
The data triplet of NTVsingle entities is composed by:
* *NTVsingleValue*: This NTVvalue is the JSON representation
(JsonValue) of the main content of the NTV entity,
* *NTVsingleType*: This NTVtype defines the type of entity and the
conversion rules between the native entity and the NTV entity.
The default NTVtype (defaultNTVtype) is the "json" NTVtype.
* *NTVname*: The NTVname is an additional textual information
(JsonString)
THOMY Expires 21 June 2024 [Page 7]
Internet-Draft JSON semantic format (JSON-NTV) December 2023
*In other words, any entity that has on the one hand a function of
encoding it into a JsonValue and on the other hand a function of
creating from a JsonValue can be taken into account. This approach
is very general because the majority of computer objects are defined
by a list of parameters (e.g. *args in python) and/or a list of key/
values (e.g. **kwargs in python) which simply translate into a
JsonArray or a JsonObject.*
The consistency between NTVsingleValue and NTVsingleType is outside
the scope of this note.
2.2.2. NTVlist
The data triplet of NTVlist entities is composed by:
* *NTVlistValue*: This NTVvalue is an ordered sequence of included
NTV entities.
* *NTVlistType*: This NTVtype is a Namespace or a NTVtype to apply
to the NTV entities included. This NTVlistType avoids including a
NTVtype (if NTVtype) or reduces the length (if Namespace) in the
JSON representation (JsonNTV) of the included NTV entities. The
default NTVtype (defaultNTVtype) is "None".
* *NTVname*: The NTVname is an additional textual information
(JsonString)
_Example of equivalent JSON representations:_
_where NTVlistType is None for the global NTVlist_
_[ { ":point" : [2.3522, 48.8566]}, {":point" : [4.8357,
45.7640]} ]_
_where NTVlistType is "point" for the global NTVlist_
_{ "::point" : [ [2.3522, 48.8566], [4.8357, 45.7640] ] }_
_If JsonValue is { "::dat" : ["2022-01-28T18-23-54", {":point": [1.1,
2.2] ] } }, the parsers deduce that the first NTVvalue has a "dat"
NTVtype and the second a "point" NTVtype._
2.3. NTVtype and Namespace
NTVtype is defined in a nested structure called Namespace.
THOMY Expires 21 June 2024 [Page 8]
Internet-Draft JSON semantic format (JSON-NTV) December 2023
This structuring of type makes it possible to reference any type of
data that has a JSON representation and to consolidate all the shared
data structures within the same tree of types.
2.3.1. Namespace
A Namespace is defined by a name (NamespaceName) and a Namespace
parent (NamespaceParent). The NamespaceName is unique in the
NamespaceParent.
Root node in the Namespace tree is the GlobalNamespace.
REQ1: NamespaceParent of GlobalNamespace is None.
2.3.2. NTVtype
A NTVtype is defined by a name (NTVtypeName) and a Namespace parent
(NamespaceParent). The NTVtype is unique in the NamespaceParent.
NTVtype and the rules to encode or decode NTVvalues MUST be
understood by data producers and data consumers. So NTVtype and
rules associated have to be defined in a specification shared by a
large community. On the other hand, it must be possible for everyone
to share data according to their own data structure.
There are therefore two categories of NTVtype:
* custom NTVtype (and Namespace) which can be created by anyone
without control,
* shared NTVtype (and Namespace) that are defined in a single,
shared repository. Each 'shared' Namespace or NTVtype is uniquely
managed.
For shared NTVtype, three sub-categories are defined (None, Simple,
Generic).
* The "None" NTVtype is used with NTVlist as defaultNTVtype.
* Simple NTVtype is associated to conversion rules between a native
entity and a NTV entity.
* Generic NTVtype is equivalent to a set of Simple NTVtype. This
indicates that parsers use associated simple NTVtype to decode the
JsonNTVvalue.
_Example:_
THOMY Expires 21 June 2024 [Page 9]
Internet-Draft JSON semantic format (JSON-NTV) December 2023
_"dat" is the generic NTVtypeName for "datetime" and "timeposix"_
_If a JSONvalue is { "::dat" : ["2022-01-28T18-23-54", 123456.78]
}, the parser deduces that the first entity has a "datetime"
NTVtypeName and the second a "timeposix" NTVtypeName._
2.3.3. Representation
A Namespace is defined by a string followed by a point
(NamespaceName).
A NTVtype is defined by a string (NTVtypeName).
The representation of a Namespace (NamespaceLongName) is composed by
all the nested NamespaceName.
The representation of a NTVtype (NTVtypeLongName) is composed by the
NamespaceLongName and the NTVtypeName.
The NTVtypeLongName is defined in Figure 2, which uses ABNF from
[RFC5234].
; representation of NtvType and Namespace (LongName)
NTVtypeLongName = NamespaceParentLongName NTVtypeName
NamespaceLongName = NamespaceParentLongName NamespaceName
NamespaceParentLongName = NamespaceLongName
NamespaceName = [ ["$"] JsonString "." ] ; REQ2 REQ3
NTVtypeName = ["$"] JsonString ; REQ3
Figure 2: JsonNTVtype - ABNF
The corresponding rules are as follows:
REQ2: NamespaceName and NamespaceLongName of GlobalNamespace are
empty.
REQ3: NTVtype (or Namespace) has 'custom' category if NTVtypeName
(or NamespaceName) begins with '$' or NTVtypeParent has
'custom' category
_Example for a representation of an NTVtype defined in two nested
Namespace in the global Namespace:_
_"ns1.ns2.type"_
THOMY Expires 21 June 2024 [Page 10]
Internet-Draft JSON semantic format (JSON-NTV) December 2023
_where:_
_"ns1." is a NamespaceName of a Namespace defined in the global
Namespace,_
_"ns2." is a NamespaceName of a Namespace defined in the "ns1"
Namespace,_
_"type" is a NTVtypeName of a NTVtype defined in the "ns2"
Namespace_
_Example of custom categories:_
_If "fr." is the name of a Namespace attached to the global
Namespace and containing the Namespace 'BAN' and the NTVtype
'dep', then:_
- _"fr.dep" is a name of a shared NTVtype,_
- _"fr.$test" is a name of a custom NTVtype,_
- _"fr.$example.one" is a name of a custom NTVtype_
- _"fr.BAN.$test" is a name of a custom NTVtype_
3. JsonNTV
3.1. JsonNTV format
The JsonNTV format is the JSON representation of an NTV entity
(JsonValue). This JsonValue is converted in JsonText with a Json
generator. The JsonNTV format is defined in Figure 3, which uses
ABNF from [RFC5234].
THOMY Expires 21 June 2024 [Page 11]
Internet-Draft JSON semantic format (JSON-NTV) December 2023
; JSON representation of NTV entities (JsonNTV)
JsonNTV = JsonNTVnamed / JsonNTVsimple ; REQ5
JsonNTVnamed = beginObject JsonNTVMember endObject
JsonNTVsimple = JsonNTVvalue / ArrayValue ; REQ6
ArrayValue = beginArray JsonNTVvalue endArray
JsonNTVMember = JsonNTVname nSep JsonNTVvalue
; Extract of JSON grammar used in this document
beginArray = ws "[" ws
beginObject = ws "{" ws
endArray = ws "]" ws
endObject = ws "}" ws
nSep = ws ":" ws
vSep = ws "," ws
ws = *( %x20 / %x09 / %x0A / %x0D )
JsonValue = JsonValue ; indicates that rule is defined in RFC8259
JsonString = JsonString ; indicates that rule is defined in RFC8259
Figure 3: JsonNTV - ABNF
The JsonNTV format is built with the NTVname, NTVvalue and the
JsonNTVtype.
Two JsonNTV formats are defined:
* named format (if NTVname or JsonType is not an empty string):
_{ JsonNTVname : JsonNTVvalue }_
* simple format (if NTVname and JsonType are empty string):
_JsonNTVvalue_
The corresponding rules are as follows:
REQ4: If JsonNTVname is empty, simple format is used
REQ5: If JsonNTVname is empty and JsonNTVvalue is a JsonObject
with a single member, ArrayValue is used
_Note :_
THOMY Expires 21 June 2024 [Page 12]
Internet-Draft JSON semantic format (JSON-NTV) December 2023
* _JsonNTV : 21, { ":" : 21 } and { ":json" : 21 } represent the
same Vsingle entity,_
3.2. JsonNTVname
JsonNTVname is the concatenation of NTVname and JsonSepType.
JsonSepType is composed with the separator singleSep or listSep and
the JsonNTVtype.
JsonNTVname and JsonSepType are defined in Figure 4, which uses ABNF
from [RFC5234].
; JSON representation of NTVname and NTVtype (JsonNTVname)
JsonNTVname = NTVname JsonSepType
JsonSepType = [singleSep [JsonNTVtype]]/[listSep JsonNTVtype]
; REQ7 REQ8
NTVname = JsonString
singleSep = ":" ; NTVsingle separator
listSep = "::" ; NTVlist separator
Figure 4: JsonNTVname - ABNF
For NTVsingle entities:
REQ6: If JsonNTVtype is not "json", JsonSepType is identical to
singleSep joined with JsonNTVtype,
else if JsonNTVvalue is not a JsonArray and not a
JsonObject, JsonSepType is empty,
else JsonSepType is identical to singleSep.
For NTVlist entities:
REQ7: If JsonNTVtype is not empty, JsonSepType is identical to
listSep joined with JsonNTVtype
else JsonSepType is empty.
3.3. JsonNTVtype
The JSON representation of a NTVtype (JsonNTVtype) is a compact
representation of the NTVtype in the context of the NTVtypeParent.
THOMY Expires 21 June 2024 [Page 13]
Internet-Draft JSON semantic format (JSON-NTV) December 2023
The JsonNTVtype is defined in Figure 5, which uses ABNF from
[RFC5234].
; JSON representation of NtvType (JsonNTVtype)
JsonNTVtype = [ NTVtypeLongName / relativeNTVtypeLongName ]
; REQ9
relativeNTVtypeLongName = *NamespaceName NTVtypeName
; REQ9
Figure 5: JsonNTVtype - ABNF
The corresponding rules are as follows:
REQ8: if NTVtype is identical to NTVtypeParent, JsonNTVtype is
empty,
else if NTVtypeParent is a Namespace and if NTVtype is
including in NTVtypeParent, JsonNTVtype is the
NTVtypeLongName relative to the NTVtypeParent.
else JsonNTVtype is the NTVtypeLongName
_Example:_
_If "fr." is the name of a Namespace attached to the global
Namespace and containing the NTVtype 'dep', then:_
- _{ "::fr." : { "department1:dep": "name1", "department2:dep":
"name2" } } is a valid JsonNTV representation._
3.4. JsonNTVvalue
The JsonNTVvalue is the JsonValue representation of NTVvalue as
defined in Figure 6, which uses ABNF from [RFC5234].
THOMY Expires 21 June 2024 [Page 14]
Internet-Draft JSON semantic format (JSON-NTV) December 2023
; JSON representation of NTVvalue (JsonNTVvalue)
JsonNTVvalue = JsonNTVsingleValue / JsonNTVlistValue
JsonNTVsingleValue = NTVsingleValue
JsonNTVlistValue = JsonNTVarrayValue / JsonNTVobjectValue
; REQ10
JsonNTVarrayValue = beginArray ListJsonNTVvalue endArray
ListJsonNTVvalue = [JsonNTV *( vSep JsonNTV )]
JsonNTVobjectValue = beginObject ListJsonNTVmember endObject
ListJsonNTVmember = [JsonNTVMember *( vSep JsonNTVMember)]
NTVsingleValue = JsonValue
Figure 6: JsonNTVvalue - ABNF
For a NTVsingle, JsonNTVvalue is the NTVvalue.
For a NTVlist, JsonNTValue has two representations:
* a JsonArray where JsonElements are the JsonNTV of included NTV
entities,
* a JsonObject where the JsonMembers are the JsonMembers of the
JsonNTV of included NTV entities.
The corresponding rules are as follows:
REQ9: if NTVlistValue has more than one NTV entities and if all
NTVname are different and not empty, JsonNTVobject is used,
else JsonNTVarray is used
_Example:_
_{ ":point" : [2.3522, 48.8566], ":point" : [4.8357, 45.7640] } is
not a valid JsonNTV_
4. Examples
Examples of JsonNTV representation of NTV entities:
*Vsingle :*
_"lyon"_
_52.5_
THOMY Expires 21 June 2024 [Page 15]
Internet-Draft JSON semantic format (JSON-NTV) December 2023
_{ ":" : [4.8357, 45.7640] }_
*NVsingle :*
_{ "city" : "paris" }_
_{ "paris:" : [4.8357, 45.7640] }_
*TVsingle:*
_{ ":point" : [4.8357, 45.7640] }_
*NTVsingle:*
_{ "paris:point" : [2.3522, 48.8566] }_
_{ "paris:ntv" : { "coordinate:point" : [4.8357, 45.7640] } }_
*Vlist (composed with JsonArray):*
_[4, 45]_
_["paris"]_
_[ [2.3522, 48.8566], {"lyon" : [4.8357, 45.7640]} ]_
_[ { ":point" : [2.3522, 48.8566]}, {":point" : [4.8357, 45.7640]}
]_
_[]_
*Vlist (composed with JsonObject) :*
_{ "name": "white", "firstname":"walter", "surname":"heisenberg"
}_
_{ "paris:point" : [2.3522, 48.8566] , "lyon" : "france"}_
_{ "paris" : [2.3522, 48.8566], "" : [4.8357, 45.7640]}_
_{ }_
*NVlist :*
_{ "simple list": [4, 45.7]}_
_{ "cities": [{":point": [2.3522, 48.8566]}, {":point": [4.8357,
45.7640]}]}_
THOMY Expires 21 June 2024 [Page 16]
Internet-Draft JSON semantic format (JSON-NTV) December 2023
*TVlist :*
_{ "::point": [[2.3522, 48.8566], {"lyon" : [4.8357, 45.7640]} ]
}_
_{ "::dat": [ "2022-01-28T18-23-54Z", "2022-01-28", 1234.78 ] }_
*NTVlist :*
_{ "cities::point": [[2.3522, 48.8566], {"lyon": [4.8357,
45.7640]}] }_
_{ "generic date::dat": [ "2022-01-28T18-23-54Z", "2022-01-28",
1234.78]}_
_{ "various::point": [ [2.3, 48.8], { ":date": "2022-01-28"},
{":json": 25 }, { "another NTVlist::json": [1,2,3]} ]}_
*NTVlist and NVlist (composed with JsonObject) :*
_{ "cities::point": { "paris": [2.352, 48.856], "lyon": [4.835,
45.764]}}_
_{ "cities": {"paris:point": [2.3522, 48.8566] , "lyon":
"france"}}_
5. Parsing a JsonValue
JsonValue is parsed according to JSON structure (from root to
leaves).
Several steps are considered:
* JSON decoding
* NTV entity decoding
* NTVvalue decoding
* NTVtype decoding
5.1. JSON decoding
This part is not detailed and consists of:
* exploit the JSON structure to identify JsonNTVname and
JsonNTVvalue,
THOMY Expires 21 June 2024 [Page 17]
Internet-Draft JSON semantic format (JSON-NTV) December 2023
* extract the following data from the JsonNTVname string:
JsonNTVtype, NTVname and singleSep or listSep
5.2. NTV entity decoding
The NTV entity is inferred from the JSON structure of JsonValue or
JsonNTVvalue:
PARS1: The tables Table 1 and Table 2 define the entity
identification rules (NTVsingle or NTVlist)
+===============+=============+
| JsonValue | NTV entity |
+===============+=============+
| JsonPrimitive | Vsingle |
+---------------+-------------+
| JsonUnnamed | Vlist |
+---------------+-------------+
| JsonArray | Vlist |
+---------------+-------------+
| JsonNamed | see Table 2 |
+---------------+-------------+
Table 1: Decoding JsonValue
+===========+===============+=============================+
| Separator | JsonNTVvalue | NTV entity |
+===========+===============+=============================+
| None | JsonPrimitive | NVsingle |
+-----------+---------------+-----------------------------+
| None | JsonNamed | NVsingle |
+-----------+---------------+-----------------------------+
| None | JsonUnnamed | NVlist |
+-----------+---------------+-----------------------------+
| None | JsonArray | NVlist |
+-----------+---------------+-----------------------------+
| ":" | JsonValue | TVsingle or NTVSingle |
+-----------+---------------+-----------------------------+
| "::" | JsonUnnamed | NVlist or TVlist or NTVlist |
+-----------+---------------+-----------------------------+
| "::" | JsonArray | NVlist or TVlist or NTVlist |
+-----------+---------------+-----------------------------+
Table 2: Decoding JsonNTVvalue
THOMY Expires 21 June 2024 [Page 18]
Internet-Draft JSON semantic format (JSON-NTV) December 2023
5.3. NTVvalue decoding
The NTVvalue is inferred from the JsonNTVvalue:
PARS2: The NTVvalue of NTVsingle is the JsonNTVvalue.
PARS3: The NTVvalue of NTVlist is the list of NTV entities parsed
for each JsonElement or JsonMember including in the
JsonNTVvalue.
5.4. NTVtype decoding
NTVtype is inferred from the JsonNTVtype:
PARS4: If JsonNTVtype is a valid NTVtypeLongName NTVtype is the
decoded JsonNTVtype,
else NTVtype is "json" NTVtype if concatened
ParentNTVtypeLongName with JsonNTVtype is empty,
else NTVtype is the decoded of concatenation of
ParentNTVtypeLongName with JsonNTVtype if it is a valid
NTVtypeLongName,
else NTVtype is the defaultNTVtype
The [JSON-NTV] repository gives some examples of NTV usage.
6. Properties
6.1. NTV tree
An NTV entity is a tree where the leaf nodes are the NTVsingle
entities and where the inner nodes are the NTVlist entities.
Therefore the tree property are applicable:
* tree indicators can be calculate:
- breadth : number of NTVsingle entities (leaves)
- size : number of NTV entities (nodes)
- height : length of the longest downward path to a leaf
* An ordering list of nodes can be defined to explore the tree for
example according to the DFS pre-ordering algorithm[DFS] (this
order is the same as the order in a JsonValue ),
THOMY Expires 21 June 2024 [Page 19]
Internet-Draft JSON semantic format (JSON-NTV) December 2023
6.2. NTV Pointer
A NTV Pointer is a string syntax for identifying a specific NTV
entity within a NTV tree.
The syntax defined for JSON Pointer [RFC6901] (json-pointer,
reference-token) is transposable to NTV Pointer (ntv-pointer,
reference-token):
* The ntv-pointer is a Unicode string containing a sequence of zero
or more reference-tokens, each prefixed by a '/'.
* The reference-token is the NTVname if it exists otherwise the
zero-based index of the NTV entity in the NTVvalue list.
The ntv-pointer is equal to the json-pointer of the JsonNTV
representation in most cases except :
* if the JsonNTV is a JsonObject with a single member where the
value is a JsonPrimitive,
* - if the JsonNTV contains a JsonArray containing a JsonObject with
a single member where the value is a JsonPrimitive
6.3. NTV Comparison
Three levels of equality are defined.
*Strict equality:*
Two NTV entities are strictly equals if :
- the NTVname are identical
- the NTVtypes are identical
- the NTVvalue are identical
o if the NTVvalue is a list of NTV entities, each NTV entity
has to be identical
o if the NTVvalue is a JSONvalue, the JSONvalues have to be
identical
*Structural equality:*
Two NTV entities are structurally equals if :
THOMY Expires 21 June 2024 [Page 20]
Internet-Draft JSON semantic format (JSON-NTV) December 2023
- the NTVname are identical
- the NTVtypes of NTVsingle are identical
- the NTVvalue are structurally identical:
o if the NTVvalue is a list of NTV entities, each NTV entity
has to be structurally identical
o if the NTVvalue is a JSONvalue, the JSONvalues have to be
identical
_Example of structural equality (JsonNTV representation):_
_{"::int32": [10, 20] } and [{":int32": 10}, {":int32": 20}]_
*Semantic equality:*
Two NTV entities are semantically equals if :
- the NTVname are identical
- the NTVvalue are semantically identical:
o if the NTVvalue is a list of NTV entities, each NTV entity
has to be semantically identical
o if the NTVvalue is a JSONvalue, the native entity associated
to the JSONvalue have to be identical
_Example of semantic equality (JsonNTV representation):_
_{":datetime": "2011-11-04T10:05:23+00:00" } and {":datetime":
"2011-11-04T11:05:23+01:00"}_
6.4. NTV Canonical
The NTVtype of the NTVlist entities is only useful for constructing
the JSON representation (two NTVlists with two different NTVtypes are
equal according to the structural equality criteria).
A canonical (single) format is chosen to facilitate sharing and
analysis of NTV and JsonNTV data. It is defined by setting a value
for the NTVtype of an NTVlist entity.
The rule is as follows:
THOMY Expires 21 June 2024 [Page 21]
Internet-Draft JSON semantic format (JSON-NTV) December 2023
REQ10: If an included entity is an NTVlist with an empty NTVtype,
its NTVtype is empty
If all included entities have an NTVtype 'json', its
NTVtype is empty.
In other cases, the NTVtype is the same as that of the
first included entity.
This rule is simple to implement and allows you to have a compact
JsonNTV format (another more complex choice would have been to take
the most frequent NTVtype among the included entities).
6.5. JSON as a subtype of NTV
The Appendix C shows that there is an equivalence between Json
entities (JsonArray, JsonObject, JsonNumber, JsonString, JsonFalse,
JsonTrue or JsonNull) and the corresponding NTV entities called JNTV
(resp. NTVarray, NTVobject, NTVnumber, NTVstring, NTVfalse, NTVtrue
, NTVnull).
JNTV entities have several properties:
* JNTV and JSON structures are substitutable with respect to
functions associated with Json structures (e.g. generation of the
JsonText format),
* Strict equality or Structural equality between two JNTV entities
are equivalent to equality between JsonNTV representations
* JNTV are canonical NTV entity
* NTV Pointer of JNTV are identical to Json Pointer of JsonNTV
representations
6.6. extended NTV structure
The NTVvalue of NTV entities are JsonValue. In the extended NTV
structure, NTVvalue can be every kind of data.
With this structure, the NTV representation is a "json like" data
where:
* JsonNTVvalue is always NTVvalue,
* JsonNTVtype is optional (if NTVtype can be deduced from the
NTVvalue),
THOMY Expires 21 June 2024 [Page 22]
Internet-Draft JSON semantic format (JSON-NTV) December 2023
* JsonNTVname is optional (if NTVname can be deduced from the
NTVvalue).
_Examples of extended NTV representation:_
_{ "python date" : [ datetime.date(2022, 1, 18),
datetime.date(2023, 1, 12) ] }_
_this "json like" structure can be converted in JsonNTV format:_
_{ "python date::date" : [ "2022-01-18", "2023-01-12" ] }_
6.7. nested NTVsingle entities
As defined in Section 2.2.1 an entity with Json representation can be
taken into account.
Appendix A defines usual NTVtypes (e.g. date, coordinate, email) but
also NTVtypes associated to structured data (e.g. dataset, NTV data,
custom format):
The example in Figure 7 is the representation of a NTVlist with three
NTVsingle:
* "dataset" is a NTVsingle build with a 'tab' structure (NTVdataset
defined in [NTV-TAB]). This NTVdataset includes in 'field2' an
NTV structure,
* "ntvdata" is a NTVsingle build with a 'ntv' structure. This
structure includes an other NTV structure,
* "sensor" is a NTVsingle build with a custom structure. This
structure includes a NTVdataset.
THOMY Expires 21 June 2024 [Page 23]
Internet-Draft JSON semantic format (JSON-NTV) December 2023
ex_list = {
"structure": {
"dataset:tab":{
"field1": [1,2,3],
"field2": [4,5,{":ntv": {"min": 6, "max": 7}]
},
"ntvdata:ntv":{
"equinox:date": "2024-03-20",
"paris:point": [2.35, 48.85],
"other data:ntv": {"val1": 1, "val2": 2}
},
"sensor:$sensor": [
8.51, 3.5, 4.2,
{":tab": [[1,2,3,4], [5,6,7,8]]}
]
}
}
Figure 7: Nested NTVsingle
Nested NTVsingle is treated as simple NTVsingle and can be used with
extended NTV structures.
7. IANA Considerations
No IANA actions are required :
Any JsonValue is a JsonNTVValue and conversely, any JsonNTVvalue
is a JsonValue.
Thus, any JSON data may or may not be treated as JsonNTV data, so
there is no need to create a specific MIME media type for JsonNTV.
All properties of the MIME media type "application/json" are
applicable.
8. Security Considerations
The format used for NTV data exchanges is the JSON format. So, all
the security considerations of [RFC8259] apply.
The NTV structure provides no cryptographic integrity protection of
any kind.
9. References
9.1. Normative References
THOMY Expires 21 June 2024 [Page 24]
Internet-Draft JSON semantic format (JSON-NTV) December 2023
[RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data
Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006,
<https://www.rfc-editor.org/info/rfc4648>.
[RFC7946] Butler, H., Daly, M., Doyle, A., Gillies, S., Hagen, S.,
and T. Schaub, "The GeoJSON Format", RFC 7946,
DOI 10.17487/RFC7946, August 2016,
<https://www.rfc-editor.org/info/rfc7946>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", STD 68, RFC 5234,
DOI 10.17487/RFC5234, January 2008,
<https://www.rfc-editor.org/info/rfc5234>.
[RFC6901] Bryan, P., Ed., Zyp, K., and M. Nottingham, Ed.,
"JavaScript Object Notation (JSON) Pointer", RFC 6901,
DOI 10.17487/RFC6901, April 2013,
<https://www.rfc-editor.org/info/rfc6901>.
[RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
Interchange Format", STD 90, RFC 8259,
DOI 10.17487/RFC8259, December 2017,
<https://www.rfc-editor.org/info/rfc8259>.
[RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet:
Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002,
<https://www.rfc-editor.org/info/rfc3339>.
[RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
RFC 7950, DOI 10.17487/RFC7950, August 2016,
<https://www.rfc-editor.org/info/rfc7950>.
9.2. Informative References
[DFS] "Wikipedia", "Depth-first search algorithm",
<https://en.wikipedia.org/wiki/Depth-first_search>.
[NTV-TAB] Thomy, P., "NTV tabular format (NTV-TAB)", 2023,
<https://datatracker.ietf.org/doc/draft-thomy-ntv-tab/>.
THOMY Expires 21 June 2024 [Page 25]
Internet-Draft JSON semantic format (JSON-NTV) December 2023
[JSON-ND] Kleidon, G., "JSON-ND", 2020,
<https://github.com/glenkleidon/JSON-ND>.
[JSON-NTV] Thomy, P., "JSON-NTV", 2022,
<https://github.com/loco-philippe/NTV#readme>.
[OLC] "Google", "Open Location Code", 2016,
<https://github.com/google/open-location-code>.
[W3C_TAB] "W3C", "Recommendation : Model for Tabular Data and
Metadata on the Web", 17 December 2015,
<https://www.w3.org/TR/2015/REC-tabular-data-model-
20151217/>.
[ISO_3166-1_alpha-2]
"ISO", "Codes for the representation of names of countries
and their subdivisions - Part 1: Country code", 2020,
<https://www.iso.org/standard/72482.html>.
[TABLE_SCHEMA]
"Frictionless", "Table Schema specification", 5 October
2021, <https://specs.frictionlessdata.io/table-
schema/#types-and-formats>.
[JSON_SCHEMA]
"JSON Schema", "JSON Schema validation", 16 June 2022,
<https://json-schema.org/draft/2020-12/json-schema-
validation>.
Appendix A. Global NTVtype and Namespace
The structure of NTVtype by Namespace makes it possible to have
NTVtype or Namespace corresponding to recognized standards at the
global level.
A standard NTVtype / Namespace is a NTVtype / Namespace defined in
the Global Namespace.
The standard NTVtype and Namespace are listed below.
A.1. Json
Json NTVtype have a generic NTVtype : "json"
THOMY Expires 21 June 2024 [Page 26]
Internet-Draft JSON semantic format (JSON-NTV) December 2023
+=======================+=======================+==================+
| NTVtypeName (generic) | NTVvalue | example NTVvalue |
+=======================+=======================+==================+
| json | generic NTVtype | |
+-----------------------+-----------------------+------------------+
| number (json) | JsonNumber [RFC8259] | 10 |
+-----------------------+-----------------------+------------------+
| boolean (json) | JsonBoolean [RFC8259] | "true" |
+-----------------------+-----------------------+------------------+
| null (json) | JsonNull [RFC8259] | "null" |
+-----------------------+-----------------------+------------------+
| string (json) | JsonString [RFC8259] | "value" |
+-----------------------+-----------------------+------------------+
| array (json) | JsonArray [RFC8259] | [1.1, 2.2] |
+-----------------------+-----------------------+------------------+
| object (json) | JsonObject [RFC8259] | {"value1": 1, |
| | | "value2": 2} |
+-----------------------+-----------------------+------------------+
Table 3: Json NTVtype
A.2. Numbers
+===========================+======================+================+
| NTVtypeName | NTVvalue | comment |
+===========================+======================+================+
| int | JsonNumber [RFC8259] | integer |
+---------------------------+----------------------+----------------+
| int8, int16, | JsonNumber [RFC8259] | signed integer |
| int32, int64 | | |
+---------------------------+----------------------+----------------+
| uint8, uint16, | JsonNumber [RFC8259] | unsigned |
| uint32, uint64 | | integer |
+---------------------------+----------------------+----------------+
| decimal64 | JsonNumber [RFC8259] | decimal |
| | | floating point |
+---------------------------+----------------------+----------------+
| float | JsonNumber [RFC8259] | binary |
| | | floating point |
+---------------------------+----------------------+----------------+
| float16, | JsonNumber [RFC8259] | binary |
| float32, float64 | | floating point |
+---------------------------+----------------------+----------------+
Table 4: Numbers NTVtype
THOMY Expires 21 June 2024 [Page 27]
Internet-Draft JSON semantic format (JSON-NTV) December 2023
A.3. Binary encoding
+=============+===========================+========================+
| NTVtypeName | NTVvalue | comment |
+=============+===========================+========================+
| bit | binary digit | string "0" or "1" |
+-------------+---------------------------+------------------------+
| binary | bit string | string of bit array |
+-------------+---------------------------+------------------------+
| base16 | base16 encoding [RFC4648] | string of hexadecimal |
| | | array |
+-------------+---------------------------+------------------------+
| base32 | base32 encoding [RFC4648] | string of |
| | | duotrigesimal array |
+-------------+---------------------------+------------------------+
| base64 | base64 encoding [RFC4648] | string of |
| | | tetrasexagesimal array |
+-------------+---------------------------+------------------------+
Table 5: Binary NTVtype
A.4. Datation
Datation NTVtype have a generic NTVtype : "dat"
THOMY Expires 21 June 2024 [Page 28]
Internet-Draft JSON semantic format (JSON-NTV) December 2023
+===========+========================+============================+
|NTVtypeName|NTVvalue | example NTVvalue |
|(generic) | | |
+===========+========================+============================+
|year |fullyear [RFC3339] | 1998 |
+-----------+------------------------+----------------------------+
|month |month [RFC3339] | 10 |
+-----------+------------------------+----------------------------+
|yearmonth |year + month (ISO8601-1)| 1998-10 |
+-----------+------------------------+----------------------------+
|day |mday [RFC3339] day of | 21 |
| |month | |
+-----------+------------------------+----------------------------+
|wday |wday [RFC3339] day of | 7 |
| |week | |
+-----------+------------------------+----------------------------+
|yday |yday [RFC3339] day of | 360 |
| |year | |
+-----------+------------------------+----------------------------+
|week |week [RFC3339] | 38 |
+-----------+------------------------+----------------------------+
|hour |hour [RFC3339] | 20 |
+-----------+------------------------+----------------------------+
|minute |minute [RFC3339] | 18 |
+-----------+------------------------+----------------------------+
|second |second [RFC3339] | 54 |
+-----------+------------------------+----------------------------+
|dat |generic NTVtype | |
+-----------+------------------------+----------------------------+
|date (dat) |date [RFC3339] | "2022-01-28"" |
+-----------+------------------------+----------------------------+
|time (dat) |timespec-base [time- | "T18:23:54", "18:23", |
| |fraction][RFC3339] | "T18" |
+-----------+------------------------+----------------------------+
|timetz |timespec-base [time- | "T18:23:54+0400" |
|(dat) |fraction] time- | |
| |zone[RFC3339] | |
+-----------+------------------------+----------------------------+
|datetime |iso-date-time (without | "2022-01-28T18-23-54" |
|(dat) |time-zone)[RFC3339] | |
+-----------+------------------------+----------------------------+
|datetimetz |iso-date-time (with | "2022-01-28T18-23-54+0400" |
|(dat) |time-zone)[RFC3339] | |
+-----------+------------------------+----------------------------+
Table 6: Datation NTVtype
THOMY Expires 21 June 2024 [Page 29]
Internet-Draft JSON semantic format (JSON-NTV) December 2023
A.5. Period and Duration
+=============+===========+=====================================+
| NTVtypeName | NTVvalue | example NTVvalue |
+=============+===========+=====================================+
| duration | duration | "P3Y6M4DT12H30M5S" |
| | [RFC3339] | |
+-------------+-----------+-------------------------------------+
| timearray | JsonArray | [dat1, dat2] |
| | | |
| | | _dat1, dat2 have "dat" NTVtypeName_ |
+-------------+-----------+-------------------------------------+
| period | period | "2022-01-01 / 2022-01-30" |
| | [RFC3339] | |
| | | "2022-01-01 / P3Y6M4DT12H30M5S" |
+-------------+-----------+-------------------------------------+
Table 7: Period and Duration NTVtype
A.6. Location
Location NTVtype have a generic NTVtype : "loc".
The CRS (Coordinate Reference Systems) is geographic, using the World
Geodetic System 1984 (WGS 84) datum, with longitude and latitude
units of decimal degrees (EPSG:4326).
+===============+=================+===============================+
| NTVtypeName | NTVvalue | example NTVvalue |
| (generic) | | |
+===============+=================+===============================+
| loc | generic NTVtype | |
+---------------+-----------------+-------------------------------+
| point (loc) | Point | [ 5.12, 45.256 ] _(lon, lat)_ |
| | coordinates | |
| | [RFC7946] | |
+---------------+-----------------+-------------------------------+
| pointstr | Point | "5.12, 45.256" _(lon, lat)_ |
| (loc) | coordinates | |
| | (string) | |
+---------------+-----------------+-------------------------------+
| pointobj | Point | {"lon": 5.12, "lat": 45.256} |
| (loc) | coordinates | |
| | (object) | |
+---------------+-----------------+-------------------------------+
| multipoint | MultiPoint | [pt1, pt2, pt3] |
| | coordinates | |
| | [RFC7946] | _ptx has "point" NTVtypeName_ |
THOMY Expires 21 June 2024 [Page 30]
Internet-Draft JSON semantic format (JSON-NTV) December 2023
+---------------+-----------------+-------------------------------+
| line (loc) | LineString | [pt1, pt2, pt3] |
| | coordinates | |
| | [RFC7946] | _ptx has "point" NTVtypeName_ |
+---------------+-----------------+-------------------------------+
| multiline | MultiLineString | [li1, li2, li3] |
| | coordinates | |
| | [RFC7946] | _lix has "line" NTVtypeName_ |
+---------------+-----------------+-------------------------------+
| polygon (loc) | Polygon | [rg1, rg2, rg3] |
| | coordinates | |
| | [RFC7946] | _rgx has "line" NTVtypeName |
| | | (ring)_ |
+---------------+-----------------+-------------------------------+
| multipolygon | MultiPolygon | [pl1, pl2, pl3] |
| (loc) | coordinates | |
| | [RFC7946] | _plx has "polygon" |
| | | NTVtypeName_ |
+---------------+-----------------+-------------------------------+
| geometry | Geometry | point, line or polygon |
| (loc) | coordinates | |
| | [RFC7946] | coordinates |
+---------------+-----------------+-------------------------------+
| multigeometry | MultiGeometry | [geo1, geo2, geo3] |
| (loc) | coordinates | |
| | [RFC7946] | _geox is point, line, polygon |
| | | or geometry_ |
+---------------+-----------------+-------------------------------+
| box (loc) | box coordinates | [ -10.0, -10.0, 10.0, 10.0 ] |
| | [RFC7946] | |
+---------------+-----------------+-------------------------------+
| geojson (loc) | geoJSON object | {"type": "point", |
| | [RFC7946] | "coordinates": [40.0, 0.0]} |
+---------------+-----------------+-------------------------------+
| codeolc (loc) | Open Location | "8FW4V75V+8F6" |
| | Code [OLC] | |
+---------------+-----------------+-------------------------------+
Table 8: Location NTVtype
A.7. Structured data
+=============+==================+
| NTVtypeName | NTVvalue |
+=============+==================+
| row | row [W3C_TAB] |
+-------------+------------------+
| field | column [W3C_TAB] |
THOMY Expires 21 June 2024 [Page 31]
Internet-Draft JSON semantic format (JSON-NTV) December 2023
+-------------+------------------+
| tab | table [W3C_TAB] |
+-------------+------------------+
| ntv | JsonNTV |
+-------------+------------------+
Table 9: Structured NTVtype
The data structure associated to this NTVtypeName are defined in
specific document.
A.8. Normalized String
+===========+===================+===================================+
|NTVtypeName| NTVvalue | example NTVvalue |
+===========+===================+===================================+
|uri | URI (RFC3986) | "https://www.ietf.org/rfc/ |
| | | rfc3986.txt" |
| | | |
| | | "geo:13.4125,103.86673" |
| | | (RFC5870) |
| | | |
| | | "info:eu-repo/dai/nl/12345" |
| | | |
| | | "mailto:John.Doe@example.com" |
| | | |
| | | "tel:+1-201-555-0123" (RFC3966) |
+-----------+-------------------+-----------------------------------+
|uriref | URI-reference | "www.example.com/questions/3456/ |
| | (RFC3986) | my-document" |
+-----------+-------------------+-----------------------------------+
|iri | internationalized | "http://www.example.org/D%FCrst" |
| | URI (RFC3987) | |
+-----------+-------------------+-----------------------------------+
|iriref | IRI-reference | "www.example.org/D%FCrst" |
| | (RFC3987) | |
+-----------+-------------------+-----------------------------------+
|uritem | URI-template | "{+x,hello,y}" |
| | (RFC6570) | |
+-----------+-------------------+-----------------------------------+
|uuid | UUID (RFC4122) | "f81d4fae-7dec- |
| | | 11d0-a765-00a0c91e6bf6" |
+-----------+-------------------+-----------------------------------+
|email | address (RFC5322) | "John Doe |
| | | <jdoe@machine.example>" |
+-----------+-------------------+-----------------------------------+
|idnemail | internationalized | |
| | adress (RFC6531) | |
THOMY Expires 21 June 2024 [Page 32]
Internet-Draft JSON semantic format (JSON-NTV) December 2023
+-----------+-------------------+-----------------------------------+
|hostname | Host Names | "en.wikipedia.org" |
| | (RFC1123) | |
+-----------+-------------------+-----------------------------------+
|idnhostname| internationalized | |
| | Host Names | |
| | (RFC5890) | |
+-----------+-------------------+-----------------------------------+
|jpointer | JSON pointer | "/foo/0" |
| | (RFC6901) | |
+-----------+-------------------+-----------------------------------+
|rjpointer | relative JSON | "1/nested/objects" |
| | pointer (I-D) | |
+-----------+-------------------+-----------------------------------+
|regex | regular | "[Ss]mith\\\\b" |
| | expression (ECMA | |
| | 262) | |
+-----------+-------------------+-----------------------------------+
|ipv4 | IPv4 address | "192.168.1.1" |
| | (RFC2673) | |
+-----------+-------------------+-----------------------------------+
|ipv6 | IPv6 address | "2001:0db8:85a3:0000:00 |
| | (RFC2373) | |
| | | 00:8a2e:0370:7334" |
+-----------+-------------------+-----------------------------------+
|file | file-hier-part | "///path/to/file" |
| | (RFC8089) | |
| | | "//host.example.com/path/to/ |
| | | file" |
+-----------+-------------------+-----------------------------------+
Table 10: Structured NTVtype
Keywords are not defined as Normalized String (eg. "id", "mandatory",
"units"), they can be used as custom NTVtype (eg. "$id",
"$mandatory", "$units")
A.9. Namespace
The global Namespace includes Namespaces for countries, dependent
territories and special areas as defined in [ISO_3166-1_alpha-2]
The JsonNamespace for those Namespace is composed by the two digits
of the country following by a dot.
_Example :_
_"fr." is the France JsonNamespace_
THOMY Expires 21 June 2024 [Page 33]
Internet-Draft JSON semantic format (JSON-NTV) December 2023
_"un." is The United Nations JsonNamespace_
Each Namespace defines a list of included NTVtype and Namespace.
A.10. Custom NTVtype and Namespace
Custom NTVtype and Namespace can be created in any Namespace.
Table 11 below presents some examples of custom NTVtype.
+================+=========================================+
| JsonNTVtype | comment or JsonNTV example |
+================+=========================================+
| "$id" | defined in the global Namespace |
| | |
| | eg. { ":$id": 5426849" } |
+----------------+-----------------------------------------+
| "$iata" | IATA airport code |
| | |
| | eg. {"Paris Nord:$iata": "CDG"} |
+----------------+-----------------------------------------+
| "$uic.station" | UIC station code |
| | |
| | eg. {"Nantes station:$uic.station" : |
| | "8748100"} |
+----------------+-----------------------------------------+
| "fr.$city" | NTVtype "city" in "fr." Namespace |
| | |
| | eg. {":fr.$city" : "Paris"} |
+----------------+-----------------------------------------+
| "$schemaorg." | "schemaorg" catalog |
| | |
| | eg. { ":$schemaorg.propertyID": "NO2" } |
| | |
| | { ":$schemaorg.unitText": "mg/m3"} |
+----------------+-----------------------------------------+
| "$darwincore." | "darwincore" catalog |
| | |
| | eg. { ":$darwincore.acceptedNameUsage": |
| | "Tamias minimus" } |
+----------------+-----------------------------------------+
Table 11: Examples of custom NTVtype
Appendix B. Complete ABNF notation
THOMY Expires 21 June 2024 [Page 34]
Internet-Draft JSON semantic format (JSON-NTV) December 2023
; representation of NtvType and Namespace (LongName)
NTVtypeLongName = NamespaceParentLongName NTVtypeName
NamespaceLongName = NamespaceParentLongName NamespaceName
NamespaceParentLongName = NamespaceLongName
NamespaceName = [ ["$"] JsonString "." ] ; REQ2 REQ3
NTVtypeName = ["$"] JsonString ; REQ3
; JSON representation of NTV entities (JsonNTV)
JsonNTV = JsonNTVnamed / JsonNTVsimple ; REQ5
JsonNTVnamed = beginObject JsonNTVMember endObject
JsonNTVsimple = JsonNTVvalue / ArrayValue ; REQ6
ArrayValue = beginArray JsonNTVvalue endArray
JsonNTVMember = JsonNTVname nSep JsonNTVvalue
; Extract of JSON grammar used in this document
beginArray = ws "[" ws
beginObject = ws "{" ws
endArray = ws "]" ws
endObject = ws "}" ws
nSep = ws ":" ws
vSep = ws "," ws
ws = *( %x20 / %x09 / %x0A / %x0D )
JsonValue = JsonValue ; indicates that rule is defined in RFC8259
JsonString = JsonString ; indicates that rule is defined in RFC8259
; JSON representation of NTVname and NTVtype (JsonNTVname)
JsonNTVname = NTVname JsonSepType
JsonSepType = [singleSep [JsonNTVtype]]/[listSep JsonNTVtype]
; REQ7 REQ8
NTVname = JsonString
singleSep = ":" ; NTVsingle separator
listSep = "::" ; NTVlist separator
; JSON representation of NtvType (JsonNTVtype)
JsonNTVtype = [ NTVtypeLongName / relativeNTVtypeLongName ]
; REQ9
THOMY Expires 21 June 2024 [Page 35]
Internet-Draft JSON semantic format (JSON-NTV) December 2023
relativeNTVtypeLongName = *NamespaceName NTVtypeName
; REQ9
; JSON representation of NTVvalue (JsonNTVvalue)
JsonNTVvalue = JsonNTVsingleValue / JsonNTVlistValue
JsonNTVsingleValue = NTVsingleValue
JsonNTVlistValue = JsonNTVarrayValue / JsonNTVobjectValue
; REQ10
JsonNTVarrayValue = beginArray ListJsonNTVvalue endArray
ListJsonNTVvalue = [JsonNTV *( vSep JsonNTV )]
JsonNTVobjectValue = beginObject ListJsonNTVmember endObject
ListJsonNTVmember = [JsonNTVMember *( vSep JsonNTVMember)]
NTVsingleValue = JsonValue
Figure 8: Collected ABNF grammar
Appendix C. JSON-NTV equivalence
This Appendix shows that we can associate with each JsonValue an NTV
entity whose JSON representation (JsonNtv) is identical to the
JsonValue.
To do this, let's call NTVarray, NTVobject, NTVnumber, NTVstring,
NTVfalse, NTVtrue, NTVnull the entities defined below.
* Json primitives
An NTVprimitive entity (resp. NTVnumber, NTVstring, NTVfalse,
NTVtrue or NTVnull) is a Vsingle entity whose NTVvalue is a
JsonPrimitive (resp. JsonNumber, JsonString, JsonFalse,
JsonTrue or JsonNull).
For example, the NTVstring entity associated with the
JsonString "foo" has the following attributes:
o NTVname: empty,
o NTVtype: "json",
o NTVvalue: "foo".
Given the NTV rules, the JsonNtv is equal to the NTVvalue and
therefore the JsonPrimitive. Conversely, an NTV parser
converts a JsonPrimitive into the corresponding NTVprimitive.
THOMY Expires 21 June 2024 [Page 36]
Internet-Draft JSON semantic format (JSON-NTV) December 2023
* Json Array
The NTVarray entity is the Vlist entity composed of the NTV
entities associated with the JsonElements of the JsonArray.
For example, for a JsonArray composed of the JsonNumber
represented by 25 and the JsonArray represented by [1,2], the
NTVarray has the following attributes:
o NTVname: None
o NTVtype: None
o NTVvalue: composed of NTVnumber 25 and the NTVarray
corresponding to the JsonArray [1,2]
As before, taking into account the NTV rules, the JsonNtv is
equal to the json representation of the NTVvalue which is
identical to the JsonArray.
Conversely, an NTV parser converts a JsonArray into the
corresponding NTVarray.
* JsonObject
Let's call NTVmember the NTV entity associated with the
JsonObject corresponding to a JsonMember (key/val). This
JsonObject has the representation {key: val}.
If val is a Json Primitive, NTVmember is an NVsingle:
o NTVname:key
o NTVtype: "json"
o NTVvalue: val
If val is a JsonArray or JsonObject, NTVmember is an NVlist:
o NTVname:key
o NTVtype: None
o NTVvalue: composed of NTV entities associated with the
elements of the JsonArray (or members of the JsonObject)
THOMY Expires 21 June 2024 [Page 37]
Internet-Draft JSON semantic format (JSON-NTV) December 2023
The NTVobject entity is the Vlist entity composed of the
NTVmember entities associated with the JsonMembers of the
JsonObject.
For example, for a JsonObject composed of the JsonMember
represented by "foo": 25 and the JsonMember represented by
"bar": [1,2], the NTVObject will be:
o NTVname: None
o NTVtype: None
o NTVvalue: composed of NVsingle (NTVname: "foo", NTVtype:
"json", NTVvalue: 25) and NVlist (NTVname: "bar", NTVtype:
None, NTVvalue: composed of NTVnumber 1 and NTVnumber 2).
Similarly to the JsonArray, given the NTV rules, the JsonNtv is
equal to the json representation of the NTVvalue which is
identical to the JsonObject.
Conversely, an NTV parser converts a JsonObject into the
corresponding NTVObject.
Thus, for all Json entities, we have an equivalence with an NTV
entity
Appendix D. Mapping NTVtypes
This Appendix presents the mapping between NTVtypes and the types
defined in Data schemas or Data languages.
D.1. Table-Schema
The mapping concerns Table Schema types and formats [TABLE_SCHEMA].
Parsable and pattern formats (datation) and topojson (location) are
not included
+===========+====================================+==============+
| type | format | NTVtype |
+===========+====================================+==============+
| string | default | string |
+-----------+------------------------------------+--------------+
| string | email | email |
+-----------+------------------------------------+--------------+
| string | uri | uri |
+-----------+------------------------------------+--------------+
| string | binary (base64 string) | base64 |
+-----------+------------------------------------+--------------+
THOMY Expires 21 June 2024 [Page 38]
Internet-Draft JSON semantic format (JSON-NTV) December 2023
| string | uuid | uuid |
+-----------+------------------------------------+--------------+
| number | default | number |
+-----------+------------------------------------+--------------+
| integer | default | int |
+-----------+------------------------------------+--------------+
| boolean | default | boolean |
+-----------+------------------------------------+--------------+
| object | default (json) | json |
+-----------+------------------------------------+--------------+
| array | default (json array) | array |
+-----------+------------------------------------+--------------+
| date | default (date ISO8601) | date |
+-----------+------------------------------------+--------------+
| time | default (time ISO8601) | time |
+-----------+------------------------------------+--------------+
| datetime | default (datetime ISO8601 in UTC) | datetime |
+-----------+------------------------------------+--------------+
| year | default | year |
+-----------+------------------------------------+--------------+
| yearmonth | default | yearmonth |
+-----------+------------------------------------+--------------+
| duration | default (lexical duration ISO8601) | duration |
+-----------+------------------------------------+--------------+
| geopoint | default (string "lon, lat") | pointstr |
+-----------+------------------------------------+--------------+
| geopoint | array (array [lon, lat]) | point |
+-----------+------------------------------------+--------------+
| geopoint | object (eg {"lon": 90, "lat": 45}) | pointobj |
+-----------+------------------------------------+--------------+
| geojson | default (geojson spec) | geojson |
+-----------+------------------------------------+--------------+
| -any- | -any- | $xxx (custom |
| | | type) |
+-----------+------------------------------------+--------------+
Table 12: Table-Schema types
D.2. JSON Schema
The mapping concerns JSON-schema [JSON_SCHEMA] primitive types,
defined formats and String-Encoded data .
THOMY Expires 21 June 2024 [Page 39]
Internet-Draft JSON semantic format (JSON-NTV) December 2023
+=================+=======================+=============+
| type | format | NTVtype |
+=================+=======================+=============+
| string | | string |
+-----------------+-----------------------+-------------+
| string | date-time | datetime |
+-----------------+-----------------------+-------------+
| string | time | time |
+-----------------+-----------------------+-------------+
| string | date | date |
+-----------------+-----------------------+-------------+
| string | duration | duration |
+-----------------+-----------------------+-------------+
| string | email | email |
+-----------------+-----------------------+-------------+
| string | idn-email | idnemail |
+-----------------+-----------------------+-------------+
| string | hostname | hostname |
+-----------------+-----------------------+-------------+
| string | idn-hostname | idnhostname |
+-----------------+-----------------------+-------------+
| string | ipv4 | ipv4 |
+-----------------+-----------------------+-------------+
| string | ipv6 | ipv6 |
+-----------------+-----------------------+-------------+
| string | uuid | uuid |
+-----------------+-----------------------+-------------+
| string | uri | uri |
+-----------------+-----------------------+-------------+
| string | uri-reference | uriref |
+-----------------+-----------------------+-------------+
| string | uri-template | uritem |
+-----------------+-----------------------+-------------+
| string | iri | iri |
+-----------------+-----------------------+-------------+
| string | iri-reference | iriref |
+-----------------+-----------------------+-------------+
| string | json-pointer | jpointer |
+-----------------+-----------------------+-------------+
| string | relative-json-pointer | rjpointer |
+-----------------+-----------------------+-------------+
| string | regex | regex |
+-----------------+-----------------------+-------------+
| number | | number |
+-----------------+-----------------------+-------------+
| integer | | int |
+-----------------+-----------------------+-------------+
| boolean | | boolean |
THOMY Expires 21 June 2024 [Page 40]
Internet-Draft JSON semantic format (JSON-NTV) December 2023
+-----------------+-----------------------+-------------+
| object | | object |
+-----------------+-----------------------+-------------+
| array | | array |
+-----------------+-----------------------+-------------+
| contentEncoding | base64 | base64 |
+-----------------+-----------------------+-------------+
| contentEncoding | base32 | base32 |
+-----------------+-----------------------+-------------+
| contentEncoding | base16 | base16 |
+-----------------+-----------------------+-------------+
| contentEncoding | binary | binary |
+-----------------+-----------------------+-------------+
| null | | null |
+-----------------+-----------------------+-------------+
Table 13: JSON Schema types
D.3. JSON Schema
The mapping concerns YANG build-in types defined [RFC7950].
Enumeration, leafref, identityref, instance-identifier, union are not
included.
THOMY Expires 21 June 2024 [Page 41]
Internet-Draft JSON semantic format (JSON-NTV) December 2023
+===========+===========+==========+
| type | NTVtype | comments |
+===========+===========+==========+
| boolean | boolean | |
+-----------+-----------+----------+
| decimal64 | decimal64 | |
+-----------+-----------+----------+
| empty | null | |
+-----------+-----------+----------+
| int8 | int8 | |
+-----------+-----------+----------+
| int16 | int16 | |
+-----------+-----------+----------+
| int32 | int32 | |
+-----------+-----------+----------+
| int64 | int64 | |
+-----------+-----------+----------+
| uint8 | uint8 | |
+-----------+-----------+----------+
| uint16 | uint16 | |
+-----------+-----------+----------+
| uint32 | uint32 | |
+-----------+-----------+----------+
| uint64 | uint64 | |
+-----------+-----------+----------+
| string | string | |
+-----------+-----------+----------+
| bit | bit | |
+-----------+-----------+----------+
| binary | binary | |
+-----------+-----------+----------+
Table 14: YANG types
Acknowledgements
TBD
Contributors
TBD
Author's Address
THOMY Expires 21 June 2024 [Page 42]
Internet-Draft JSON semantic format (JSON-NTV) December 2023
Philippe THOMY
Loco-labs
476 chemin du gaf de Famian
84 500 BOLLENE
France
Email: philippe@loco-labs.io
URI: https://github.com/loco-philippe/NTV/blob/main/README.md
THOMY Expires 21 June 2024 [Page 43]