Internet-Draft JSON semantic format (JSON-NTV) May 2024
THOMY Expires 28 November 2024 [Page]
Workgroup:
Internet Engineering Task Force
Internet-Draft:
draft-thomy-json-ntv-03
Published:
Intended Status:
Informational
Expires:
Author:
P. THOMY
Loco-labs

JSON semantic format (JSON-NTV)

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 28 November 2024.

Table of Contents

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 :

The NTV entity is thus a triplet with a mandatory element (value) and two additional elements (name, type).

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.

With this approach, two NTV entities are defined :

as well as two JSON formats depending on the presence of the additional elements :

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:

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

Layer 1 JsonText JsonNTV native entity NTV triplet JSON load JSON dump NTV load NTV dump to_obj from_obj
Figure 1: NTV layers

Example:

2.2. NTV entities

Two categories of entities (one primitive and one structured) are defined:

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 is a DataType. It defines the type of entity and the conversion rules between the native entity and the NTV entity. The default NTVtype (defaultNTVtype) is the "json" DataType.
  • NTVname: The NTVname is an additional textual information (JsonString)

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 DataType to apply to the NTV entities included. This NTVlistType avoids including a NTVtype (if DataType) 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. DataType and Namespace

A DataType is defined in a nested structure called Namespace.

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

The DataType represents the semantic of a data and is structured in a flat classification. For example, "email" and "string" are two DataType.

A DataType is composed with a TypeBase and an optional TypeExtension. The TypeExtension defines an additional property. For example:

  • a "float" TypeBase may have a "kg" extension to indicate a unit.
  • a "string" TypeBase may have a "fr" extension to indicate a langage.

A DataType is defined by a name (DataTypeName) and a Namespace parent (NamespaceParent). The TypeBase of a DataType is unique in the NamespaceParent. The TypeExtension of a DataType is free.

TypeBase and the rules to encode or decode NTVvalues MUST be understood by data producers and data consumers. So TypeBase 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 TypeBase:

  • custom TypeBase (and Namespace) which can be created by anyone without control,
  • shared TypeBase (and Namespace) that are defined in a single, shared repository. Each 'shared' Namespace or TypeBase is uniquely managed.

For shared TypeBase, three sub-categories are defined (None, Simple, Generic).

  • The "None" TypeBase is used with NTVlist as defaultDataType.
  • Simple TypeBase is associated to conversion rules between a native entity and a NTV entity.
  • Generic TypeBase is equivalent to a set of Simple TypeBase. This indicates that parsers use associated simple TypeBase to decode the JsonNTVvalue.

Example:

  • "dat" is the generic TypeBaseName 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" TypeBaseName and the second a "timeposix" TypeBaseName.

2.3.3. Representation

A Namespace is defined by a string followed by a point (NamespaceName).

A DataType is defined by a string (DataTypeName) composed by the TypeBaseName and the TypeExtensionName.

The representation of a Namespace (NamespaceLongName) is composed by all the nested NamespaceName.

The representation of a DataType (DataTypeLongName) is composed by the NamespaceLongName and the DataTypeName.

The DataTypeLongName is defined in Figure 2, which uses ABNF from [RFC5234].


; representation of DataType and Namespace (Name and LongName)

DataTypeLongName  = NamespaceParentLongName DataTypeName

NamespaceLongName = NamespaceParentLongName NamespaceName
NamespaceParentLongName = NamespaceLongName

NamespaceName   = [ ["$"] JsonString "." ]      ; REQ2 REQ3
DataTypeName    = TypeBaseName ["[" TypeExtensionName "]"]
TypeBaseName    = ["$"] JsonString              ; REQ3
TypeExtensionName   = JsonString

Figure 2: DataType and Namespace names - ABNF

The corresponding rules are as follows:

  • REQ2:
    NamespaceName and NamespaceLongName of GlobalNamespace are empty.
    REQ3:
    DataType (or Namespace) has 'custom' category if DataTypeName (or NamespaceName) begins with '$' or NamespaceParent has 'custom' category

Example for a representation of a DataType defined in two nested Namespace in the global Namespace:

  • "ns1.ns2.type"
  • 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 DataTypeName of a DataType 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 DataType 'dep', then:

    • "fr.dep" is a name of a shared DataType,
    • "fr.$test" is a name of a custom DataType,
    • "fr.$example.one" is a name of a custom DataType
    • "fr.BAN.$test" is a name of a custom DataType

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


; JSON representation of NTV entities (JsonNTV)

JsonNTV        = JsonNTVnamed / JsonNTVsimple      ; REQ4

JsonNTVnamed   = beginObject JsonNTVMember endObject
JsonNTVsimple  = JsonNTVvalue

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:

The corresponding rule is as follows:

Note :

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)
    ; REQ5 REQ6

NTVname = JsonString

singleSep   = ":"      ; NTVsingle separator
listSep     = "::"     ; NTVlist separator

Figure 4: JsonNTVname - ABNF

For NTVsingle entities:

For NTVlist entities:

3.3. JsonNTVtype

The JSON representation of a NTVtype (JsonNTVtype) is a compact representation of the NTVtype in the context of the NTVtypeParent.

The JsonNTVtype is defined in Figure 5, which uses ABNF from [RFC5234].


; JSON representation of NTVType (JsonNTVtype)

JsonNTVtype = [ NTVtypeLongName / NTVtypeRelativeName ]
    ; REQ7

NTVtypeLongName = DataTypeLongName / NamespaceLongName
NTVtypeRelativeName = *NamespaceName (DataTypeName / NamespaceName)
    ; REQ7

Figure 5: JsonNTVtype - ABNF

The corresponding rules are as follows:

Example:

3.4. JsonNTVvalue

The JsonNTVvalue is the JsonValue representation of NTVvalue as defined in Figure 6, which uses ABNF from [RFC5234].


; JSON representation of NTVvalue (JsonNTVvalue)

JsonNTVvalue       = JsonNTVsingleValue / JsonNTVlistValue

JsonNTVsingleValue = NTVsingleValue
JsonNTVlistValue   = JsonNTVarrayValue / JsonNTVobjectValue
    ; REQ8 REQ9

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:

The corresponding rules are as follows:

Example:

4. Examples

Examples of JsonNTV representation of NTV entities:

Vsingle :

NVsingle :

TVsingle:

NTVsingle:

Vlist (composed with JsonArray):

Vlist (composed with JsonObject) :

NVlist :

TVlist :

NTVlist :

NTVlist and NVlist (composed with JsonObject) :

5. Parsing a JsonValue

JsonValue is parsed according to JSON structure (from root to leaves).

Several steps are considered:

5.1. JSON decoding

This part is not detailed and consists of:

5.2. NTV entity decoding

The NTV entity is inferred from the JSON structure of JsonValue or JsonNTVvalue:

Table 1: Decoding JsonValue
JsonValue NTV entity
JsonPrimitive Vsingle
JsonUnnamed Vlist
JsonArray Vlist
JsonNamed see Table 2
Table 2: Decoding JsonNTVvalue
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

5.3. NTVvalue decoding

The NTVvalue is inferred from the JsonNTVvalue:

5.4. NTVtype decoding

NTVtype is inferred from the JsonNTVtype:

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:

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 equal to the json-pointer of the JsonNTV representation in most cases except :

6.3. NTV Comparison

Three levels of equality are defined.

Strict equality:

Structural equality:

Semantic equality:

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:

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:

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:

Examples of extended NTV representation:

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:

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 :

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

[RFC4648]
Josefsson, S., "The Base16, Base32, and Base64 Data Encodings", RFC 4648, DOI 10.17487/RFC4648, , <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, , <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, , <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, , <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, , <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, , <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, , <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, , <https://www.rfc-editor.org/info/rfc3339>.
[RFC7950]
Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", RFC 7950, DOI 10.17487/RFC7950, , <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)", , <https://datatracker.ietf.org/doc/draft-thomy-ntv-tab/>.
[JSON-ND]
Kleidon, G., "JSON-ND", , <https://github.com/glenkleidon/JSON-ND>.
[JSON-NTV]
Thomy, P., "JSON-NTV", , <https://github.com/loco-philippe/NTV#readme>.
[OLC]
"Google", "Open Location Code", , <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", , <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 DataType and Namespace

The structure of DataType by Namespace makes it possible to have DataType or Namespace corresponding to recognized standards at the global level.

A standard DataType / Namespace is a DataType / Namespace defined in the Global Namespace.

The standard DataType and Namespace are listed below.

A.1. Json

Json DataType have a generic DataType : "json"

Table 3: Json DataType
DataTypeName (generic) NTVvalue example NTVvalue
json generic DataType
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}

A.2. Numbers

Table 4: Numbers DataType
DataTypeName NTVvalue comment
int JsonNumber [RFC8259] integer
int8, int16, int32, int64 JsonNumber [RFC8259] signed integer
uint8, uint16, uint32, uint64 JsonNumber [RFC8259] unsigned integer
decimal64 JsonNumber [RFC8259] decimal floating point
float JsonNumber [RFC8259] binary floating point
float16, float32, float64 JsonNumber [RFC8259] binary floating point

A.3. Binary encoding

Table 5: Binary DataType
DataTypeName 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

A.4. Datation

Datation DataType have a generic DataType : "dat"

Table 6: Datation DataType
DataTypeName (generic) NTVvalue example NTVvalue
year fullyear [RFC3339] 1998
month month [RFC3339] 10
yearmonth year + month (ISO8601-1) 1998-10
day mday [RFC3339] day of month 21
wday wday [RFC3339] day of week 7
yday yday [RFC3339] day of year 360
week week [RFC3339] 38
hour hour [RFC3339] 20
minute minute [RFC3339] 18
second second [RFC3339] 54
dat generic DataType
date (dat) date [RFC3339] "2022-01-28""
time (dat) timespec-base [time-fraction][RFC3339] "T18:23:54", "18:23", "T18"
timetz (dat) timespec-base [time-fraction] time-zone[RFC3339] "T18:23:54+0400"
datetime (dat) iso-date-time (without time-zone)[RFC3339] "2022-01-28T18-23-54"
datetimetz (dat) iso-date-time (with time-zone)[RFC3339] "2022-01-28T18-23-54+0400"

A.5. Period and Duration

Table 7: Period and Duration DataType
DataTypeName NTVvalue example NTVvalue
duration duration [RFC3339] "P3Y6M4DT12H30M5S"
timearray JsonArray

[dat1, dat2]

dat1, dat2 have "dat" DataTypeName

period period [RFC3339]

"2022-01-01 / 2022-01-30"

"2022-01-01 / P3Y6M4DT12H30M5S"

A.6. Location

Location DataType have a generic DataType : "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).

Table 8: Location DataType
DataTypeName (generic) NTVvalue example NTVvalue
loc generic DataType
point (loc) Point coordinates [RFC7946] [ 5.12, 45.256 ] (lon, lat)
pointstr (loc) Point coordinates (string) "5.12, 45.256" (lon, lat)
pointobj (loc) Point coordinates (object) {"lon": 5.12, "lat": 45.256}
multipoint MultiPoint coordinates [RFC7946]

[pt1, pt2, pt3]

ptx is "point" NTVvalue

line (loc) LineString coordinates [RFC7946]

[pt1, pt2, pt3]

ptx is "point" NTVvalue

multiline MultiLineString coordinates [RFC7946]

[li1, li2, li3]

lix is "line" NTVvalue

polygon (loc) Polygon coordinates [RFC7946]

[rg1, rg2, rg3]

rgx is "line" NTVvalue (ring)

multipolygon (loc) MultiPolygon coordinates [RFC7946]

[pl1, pl2, pl3]

plx is "polygon" NTVvalue

geometry Geometry coordinates [RFC7946]

"point", "line" or "polygon"

NTVvalue

multigeometry MultiGeometry coordinates [RFC7946]

[geo1, geo2, geo3]

geox is "geometry" NTVvalue

box (loc) box coordinates [RFC7946] [ -10.0, -10.0, 10.0, 10.0 ]
geojson (loc) geoJSON object [RFC7946] {"type": "point", "coordinates": [40.0, 0.0]}
codeolc (loc) Open Location Code [OLC] "8FW4V75V+8F6"

A.7. Structured data

Table 9: Structured DataType
DataTypeName NTVvalue
row row [W3C_TAB]
field column [W3C_TAB]
tab table [NTV-TAB]
ndarray multidimensional array [NTV-TAB]
xndarray labelled multidimensional array[NTV-TAB]
xdataset coordinated multidimensional array[NTV-TAB]
ntv JsonNTV
sch Schema

The data structure associated to this DataTypeName are defined in specific document.

A.8. Normalized String

Table 10: Structured DataType
DataTypeName NTVvalue example NTVvalue
unit Physical quantities "kg / s2"
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 (RFC3986) "www.example.com/questions/3456/my-document"
iri internationalized URI (RFC3987) "http://www.example.org/D%FCrst"
iriref IRI-reference (RFC3987) "www.example.org/D%FCrst"
uritem URI-template (RFC6570) "{+x,hello,y}"
uuid UUID (RFC4122) "f81d4fae-7dec-11d0-a765-00a0c91e6bf6"
email address (RFC5322) "John Doe <jdoe@machine.example>"
idnemail internationalized adress (RFC6531)
hostname Host Names (RFC1123) "en.wikipedia.org"
idnhostname internationalized Host Names (RFC5890)
jpointer JSON pointer (RFC6901) "/foo/0"
rjpointer relative JSON pointer (I-D) "1/nested/objects"
regex regular expression (ECMA 262) "[Ss]mith\\\\b"
ipv4 IPv4 address (RFC2673) "192.168.1.1"
ipv6 IPv6 address (RFC2373)

"2001:0db8:85a3:0000:00

00:8a2e:0370:7334"

file file-hier-part (RFC8089)

"///path/to/file"

"//host.example.com/path/to/file"

Keywords are not defined as Normalized String (eg. "id", "mandatory", "units"), they can be used as custom DataType (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
  • "un." is The United Nations JsonNamespace

Each Namespace defines a list of included DataType and Namespace.

A.10. Custom DataType and Namespace

Custom DataType and Namespace can be created in any Namespace.

Table 11 below presents some examples of custom DataType.

Table 11: Examples of custom DataType
JsonDataType 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"

DataType "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" }

Appendix B. Complete ABNF notation


; representation of DataType and Namespace (Name and LongName)

DataTypeLongName  = NamespaceParentLongName DataTypeName

NamespaceLongName = NamespaceParentLongName NamespaceName
NamespaceParentLongName = NamespaceLongName

NamespaceName   = [ ["$"] JsonString "." ]      ; REQ2 REQ3
DataTypeName    = TypeBaseName ["[" TypeExtensionName "]"]
TypeBaseName    = ["$"] JsonString              ; REQ3
TypeExtensionName   = JsonString

; JSON representation of NTV entities (JsonNTV)

JsonNTV        = JsonNTVnamed / JsonNTVsimple      ; REQ4

JsonNTVnamed   = beginObject JsonNTVMember endObject
JsonNTVsimple  = JsonNTVvalue

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)
    ; REQ5 REQ6

NTVname = JsonString

singleSep   = ":"      ; NTVsingle separator
listSep     = "::"     ; NTVlist separator

; JSON representation of NTVType (JsonNTVtype)

JsonNTVtype = [ NTVtypeLongName / NTVtypeRelativeName ]
    ; REQ7

NTVtypeLongName = DataTypeLongName / NamespaceLongName
NTVtypeRelativeName = *NamespaceName (DataTypeName / NamespaceName)
    ; REQ7

; JSON representation of NTVvalue (JsonNTVvalue)

JsonNTVvalue       = JsonNTVsingleValue / JsonNTVlistValue

JsonNTVsingleValue = NTVsingleValue
JsonNTVlistValue   = JsonNTVarrayValue / JsonNTVobjectValue
    ; REQ8 REQ9

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.

Thus, for all Json entities, we have an equivalence with an NTV entity

Appendix D. Mapping DataTypes

This Appendix presents the mapping between DataTypes 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

Table 12: Table-Schema types
type format DataType
string default string
string email email
string uri uri
string binary (base64 string) base64
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)

D.2. JSON Schema

The mapping concerns JSON-schema [JSON_SCHEMA] primitive types, defined formats and String-Encoded data .

Table 13: JSON Schema types
type format DataType
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
object object
array array
contentEncoding base64 base64
contentEncoding base32 base32
contentEncoding base16 base16
contentEncoding binary binary
null null

D.3. YANG

The mapping concerns YANG [RFC7950] build-in types defined. Enumeration, leafref, identityref, instance-identifier, union are not included.

Table 14: YANG types
type DataType 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

Acknowledgements

TBD

Contributors

TBD

Author's Address

Philippe THOMY
Loco-labs
476 chemin du gaf de Famian
84 500 BOLLENE
France