]> Loco-labs

476 chemin du gaf de Famian BOLLENE 84 500 FR philippe@loco-labs.io https://github.com/loco-philippe/NTV/blob/main/README.md

General Internet Engineering Task Force JSON semantic data interchange format ABNF 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.  

Introduction

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 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 ,
  • 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 . The second term is the JSON value.

• The JSON value of the previous example is:
  • { "paris:point" : [2.3522, 48.8566] }

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

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

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

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 .

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.

 

NTV structure

NTV layers NTV and JsonNTV structures are defined as shown in :

• 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

NTV layers | |--------->| NTV |--------->|native| |JsonText| |JsonNTV| |triplet| |entity| | |<----------| |<---------| |<---------| | +--------+ JSON dump +-------+ NTV dump +-------+ from_obj +------+ ]]>

Example:

• 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

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

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.

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.

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.

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.

• 1. NamespaceParent of GlobalNamespace is None.

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.

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 , which uses ABNF from .

DataType and Namespace names - ABNF

The corresponding rules are as follows:

• 1. NamespaceName and NamespaceLongName of GlobalNamespace are empty.
  2. 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

 

JsonNTV

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 , which uses ABNF from .

JsonNTV - ABNF

The JsonNTV format is built with the NTVname, NTVvalue and the JsonNTVtype. Two JsonNTV formats are defined:

• named format:
  • { JsonNTVname : JsonNTVvalue }
• simple format:
  • JsonNTVvalue

The corresponding rule is as follows:

• 1. If JsonNTVname is empty, simple format is used else named format is used

Note :

• JsonNTV : 21, { ":" : 21 } and { ":json" : 21 } represent the same Vsingle entity.
• If JsonNTVvalue is a JsonObject with a single member, the JsonNTVname is not empty.

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 , which uses ABNF from .

JsonNTVname - ABNF

For NTVsingle entities:

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

• 1. If NTVtype is a DataType, listSep is present in JsonSepType else listSep is not present.

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 , which uses ABNF from .

JsonNTVtype - ABNF

The corresponding rules are as follows:

• 1. 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 NTVtypeRelativeName (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 DataType 'dep', then:
  • { "::fr." : { "department1:dep": "name1", "department2:dep": "name2" } } is a valid JsonNTV representation.

JsonNTVvalue The JsonNTVvalue is the JsonValue representation of NTVvalue as defined in , which uses ABNF from .

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:

• 1. NTVlist with multiple NTV entities : if all JsonNTVname of NTV entities are different and not empty, JsonNTVobjectValue is used else JsonNTVarrayValue is used
  2. NTVlist with single NTV entity : if JsonNTVname of the NTVlist is not empty JsonNTVobjectValue is used else JsonNTVarrayValue is used

Example:

• { ":point" : [2.3522, 48.8566], ":point" : [4.8357, 45.7640] } is not a valid JsonNTV

 

Examples Examples of JsonNTV representation of NTV entities: Vsingle :

• "lyon"
• 52.5
• { ":" : [4.8357, 45.7640] }

NVsingle :

• { "city" : "paris" }
• { "paris:" : [4.8357, 45.7640] }

TVsingle:

• { ":point" : [4.8357, 45.7640] }
• { ":string[fr]" : "Paris est un belle ville" }

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

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

 

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

JSON decoding This part is not detailed and consists of:

• exploit the JSON structure to identify JsonNTVname and JsonNTVvalue,
• extract the following data from the JsonNTVname string: JsonNTVtype, NTVname and singleSep or listSep

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

• 1. The tables and define the entity identification rules (NTVsingle or NTVlist)

Decoding JsonValue

JsonValue	NTV entity
JsonPrimitive	Vsingle
JsonUnnamed	Vlist
JsonArray	Vlist
JsonNamed	see

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

NTVvalue decoding The NTVvalue is inferred from the JsonNTVvalue:

• 1. The NTVvalue of NTVsingle is the JsonNTVvalue.
  2. The NTVvalue of NTVlist is the list of NTV entities parsed for each JsonElement or JsonMember including in the JsonNTVvalue.

NTVtype decoding NTVtype is inferred from the JsonNTVtype:

• 1. If JsonNTVtype is a valid NTVtypeLongName : NTVtype is the decoded JsonNTVtype, else if concatened ParentNTVtypeLongName with JsonNTVtype is empty : NTVtype is "json", else if the decoded of concatenation of ParentNTVtypeLongName with JsonNTVtype is a valid NTVtypeLongName : NTVtype is it, else NTVtype is the defaultNTVtype

The repository gives some examples of NTV usage.

 

Properties

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 (this order is the same as the order in a JsonValue ),

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

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
    • if the NTVvalue is a list of NTV entities, each NTV entity has to be identical
    • if the NTVvalue is a JSONvalue, the JSONvalues have to be identical

Structural equality:

• Two NTV entities are structurally equals if :
  • the NTVname are identical
  • the NTVtypes of NTVsingle are identical
  • the NTVvalue are structurally identical:
    • if the NTVvalue is a list of NTV entities, each NTV entity has to be structurally identical
    • 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:
    • if the NTVvalue is a list of NTV entities, each NTV entity has to be semantically identical
    • 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"}

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:

• 1. NTVtype is empty, if an included entity is an NTVlist with an empty NTVtype, NTVtype is empty, if all included entities have an NTVtype 'json', NTVtype is the common Namespace, if the common Namespace is not the GlobalNamespace, 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).

JSON as a subtype of NTV The 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

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),
• 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" ] }

nested NTVsingle entities As defined in an entity with Json representation can be taken into account. 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 is the representation of a NTVlist with three NTVsingle:

• "dataset" is a NTVsingle build with a 'tab' structure (NTVdataset defined in ). 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.

Nested NTVsingle

Nested NTVsingle is treated as simple NTVsingle and can be used with extended NTV structures.

 

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.

Security Considerations The format used for NTV data exchanges is the JSON format. So, all the security considerations of apply. The NTV structure provides no cryptographic integrity protection of any kind.

  References Normative References Informative References "Wikipedia" "Google" "W3C" "ISO" "Frictionless" "JSON Schema"  

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.

Json Json DataType have a generic DataType : "json" Json DataType

DataTypeName (generic)	NTVvalue	example NTVvalue
json	generic DataType
number (json)	JsonNumber	10
boolean (json)	JsonBoolean	"true"
null (json)	JsonNull	"null"
string (json)	JsonString	"value"
array (json)	JsonArray	[1.1, 2.2]
object (json)	JsonObject	{"value1": 1, "value2": 2}

Numbers Numbers DataType

DataTypeName	NTVvalue	comment
int	JsonNumber	integer
int8, int16, int32, int64	JsonNumber	signed integer
uint8, uint16, uint32, uint64	JsonNumber	unsigned integer
decimal64	JsonNumber	decimal floating point
float	JsonNumber	binary floating point
float16, float32, float64	JsonNumber	binary floating point

Binary encoding Binary DataType

DataTypeName	NTVvalue	comment
bit	binary digit	string "0" or "1"
binary	bit string	string of bit array
base16	base16 encoding	string of hexadecimal array
base32	base32 encoding	string of duotrigesimal array
base64	base64 encoding	string of tetrasexagesimal array

Datation Datation DataType have a generic DataType : "dat" Datation DataType

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

Period and Duration Period and Duration DataType

DataTypeName	NTVvalue	example NTVvalue
duration	duration	"P3Y6M4DT12H30M5S"
timearray	JsonArray	[dat1, dat2]dat1, dat2 have "dat" DataTypeName
period	period	"2022-01-01 / 2022-01-30""2022-01-01 / P3Y6M4DT12H30M5S"

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

DataTypeName (generic)	NTVvalue	example NTVvalue
loc	generic DataType
point (loc)	Point coordinates	[ 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	[pt1, pt2, pt3]ptx is "point" NTVvalue
line (loc)	LineString coordinates	[pt1, pt2, pt3]ptx is "point" NTVvalue
multiline	MultiLineString coordinates	[li1, li2, li3]lix is "line" NTVvalue
polygon (loc)	Polygon coordinates	[rg1, rg2, rg3]rgx is "line" NTVvalue (ring)
multipolygon (loc)	MultiPolygon coordinates	[pl1, pl2, pl3]plx is "polygon" NTVvalue
geometry	Geometry coordinates	"point", "line" or "polygon"NTVvalue
multigeometry	MultiGeometry coordinates	[geo1, geo2, geo3]geox is "geometry" NTVvalue
box (loc)	box coordinates	[ -10.0, -10.0, 10.0, 10.0 ]
geojson (loc)	geoJSON object	{"type": "point", "coordinates": [40.0, 0.0]}
codeolc (loc)	Open Location Code	"8FW4V75V+8F6"

Structured data Structured DataType

DataTypeName	NTVvalue
row	row
field	column
tab	table
ndarray	multidimensional array
xndarray	labelled multidimensional array
xdataset	coordinated multidimensional array
ntv	JsonNTV
sch	Schema

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

Normalized String 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:0000: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")

Namespace The global Namespace includes Namespaces for countries, dependent territories and special areas as defined in 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.

Custom DataType and Namespace Custom DataType and Namespace can be created in any Namespace. below presents some examples of custom DataType. Examples of custom DataType

JsonDataType	comment or JsonNTV example
"$id"	defined in the global Namespaceeg. { ":$id": 5426849" }
"$iata"	IATA airport codeeg. {"Paris Nord:$iata": "CDG"}
"$uic.station"	UIC station codeeg. {"Nantes station:$uic.station" : "8748100"}
"fr.$city"	DataType "city" in "fr." Namespaceeg. {":fr.$city" : "Paris"}
"$schemaorg."	"schemaorg" catalogeg. { ":$schemaorg.propertyID": "NO2" } { ":$schemaorg.unitText": "mg/m3"}
"$darwincore."	"darwincore" catalogeg. { ":$darwincore.acceptedNameUsage": "Tamias minimus" }

Complete ABNF notation

Collected ABNF grammar

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:
    • NTVname: empty,
    • NTVtype: "json",
    • 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.
• 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:
    • NTVname: None
    • NTVtype: None
    • 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:
    • NTVname:key
    • NTVtype: "json"
    • NTVvalue: val
  • If val is a JsonArray or JsonObject, NTVmember is an NVlist:
    • NTVname:key
    • NTVtype: None
    • NTVvalue: composed of NTV entities associated with the elements of the JsonArray (or members of the JsonObject)
  • 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:
    • NTVname: None
    • NTVtype: None
    • 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

Mapping DataTypes This Appendix presents the mapping between DataTypes and the types defined in Data schemas or Data languages.

Table-Schema The mapping concerns Table Schema types and formats . Parsable and pattern formats (datation) and topojson (location) are not included 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)

JSON Schema The mapping concerns JSON-schema primitive types, defined formats and String-Encoded data . 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

YANG The mapping concerns YANG build-in types defined. Enumeration, leafref, identityref, instance-identifier, union are not included. 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