JSON semantic format (JSON-NTV)

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

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

  • 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. Requirements Language

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

JsonType, JsonText, JsonName, JsonValue, JsonObject, JsonMember, JsonElement, JsonArray, JsonNumber, JsonString, JsonFalse, JsonNull, JsonTrue:

These terms are defined as type, text, name, value, object, member, element, 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.¶

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¶

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¶

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.3. NTVtype and Namespace

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

; representation of NtvType and Namespace (LongName)

NTVtypeLongName     = NamespaceParentLongName NTVtypeName

NamespaceLongName   = NamespaceParentLongName NamespaceName
NamespaceParentLongName = NamespaceLongName

NamespaceName   = [ ["$"] JsonString "." ]      ; REQ2 REQ3
NTVtypeName     = ["$"] JsonString              ; REQ3

3.1. JsonNTV format

The JsonNTV format is the JSON representation of an NTV entity (JsonValue) as 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

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¶

This format allows full compatibility with existing JSON structures:¶

• a JsonNumber, JsonString, JsonNull or JsonBoolean is the representation of a Vsingle entity,¶
• a JsonObject with a single member is the representation of an NVsingle or TVsingle entity,¶
• a JsonArray is the representation of a Vlist entity,¶
• a JsonObject without a single member is the representation of a Vlist entity composed with unnamed entities.¶

Note :¶

• 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]
    ; REQ5 REQ6

NTVname = JsonString

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

For NTVsingle entities:¶

• REQ5:

  If JsonNTVtype is not "json", JsonSepType is identical to singleSep joined with JsonNTVtype,¶

  else if JsonNTVvalue is not a JsonArray and not a JsonUnnamed, JsonSepType is empty,¶

  else JsonSepType is identical to singleSep.¶

For NTVlist entities:¶

• REQ6:

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

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

; JSON representation of NtvType (JsonNTVtype)

JsonNTVtype = [ NTVtypeLongName / relativeNTVtypeLongName ]
    ; REQ7

relativeNTVtypeLongName = *NamespaceName NTVtypeName
    ; REQ7

The corresponding rules are as follows:¶

• REQ7:

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

; JSON representation of NTVvalue (JsonNTVvalue)

JsonNTVvalue       = JsonNTVsingleValue / JsonNTVlistValue

JsonNTVsingleValue = NTVsingleValue
JsonNTVlistValue   = JsonNTVarrayValue / JsonNTVobjectValue
    ; REQ8

JsonNTVarrayValue  = beginArray ListJsonNTVvalue endArray
ListJsonNTVvalue   = [JsonNTV  *( vSep JsonNTV )]
JsonNTVobjectValue = beginObject ListJsonNTVmember endObject
ListJsonNTVmember  = [JsonNTVMember *( vSep JsonNTVMember)]

NTVsingleValue     = JsonValue

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

• REQ8:

  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¶

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

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

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

9.1. Normative References

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

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

9.2. Informative References

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

A.1. Json

Json NTVtype have a generic NTVtype : "json"¶

A.2. Numbers

A.3. Datation

Datation NTVtype have a generic NTVtype : "dat"¶

A.4. Period and Duration

A.5. 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).¶

A.6. Structured data

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

A.7. Normalized String

Keywords are not defined as Normalized String (eg. "id", "mandatory", "units"), they can be used as custom NTVtype (eg. "$id", "$mandatory", "$units")¶

A.8. 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 NTVtype and Namespace.¶

A.9. Custom NTVtype and Namespace

Custom NTVtype and Namespace can be created in any Namespace.¶

Table 10 below presents some examples of custom NTVtype.¶