NTV.json_ntv
JSON-NTV Package
Created on Fri Dec 24 15:21:14 2021
@author: philippe@loco-labs.io
This package contains the following classes:
-
NTV.json_ntv.ntv.NtvSingle
NTV.json_ntv.ntv.NtvList
NTV.json_ntv.ntv.Ntv
(abstract class)
Note: pandas connector is in another package ntv-pandas.ntv_pandas.pandas_ntv_connector
0 - Abstract
Today, the semantic level of shared data remains low. It is very often limited to the type of data defined in the exchange formats (strings for CSV formats; numbers, strings, arrays and objects for JSON formats).
The proposed consists of adding a type and a name to the data exchanged (see also the JSON-NTV specification).
With this evolution any data, whatever its semantic level, can be identified, shared and interpreted in a consistent way. The implementation of a type with a nested structure facilitates its appropriation. Finally, compatibility with existing JSON structures allows progressive deployment.
1 - NTV structure
The constructed entities (called NTV for named typed value) are therefore a triplet with one mandatory element (the value in JSON format) and two optional elements (name, type). >
For example, the location of Paris can be represented by:
- a name: "Paris",
- a type: the coordinates of a point according to the GeoJSON format,
- a value: [ 2.3522, 48.8566]
The easiest way to add this information is to use a JSON-object with a single member using the syntax JSON-ND for the first term of the member and the JSON-value for the second term of the member. >
For the example above, the JSON representation is:
{ "paris:point" : [2.3522, 48.8566] }
With this approach, three NTV entities are defined:
- a primitive entity which is not composed of any other entity (NTV-single),
- two structured entities: an unordered collection of NTV entities (NTV-set) and an ordered sequence of NTV entities (NTV-list).
as well as two JSON formats:
- simple format when the name and the type are not present (this is the usual case of CSV data),
- named format when the name or type is present (see example above for an NTV-single entity and below for a structured entity). >
Example of an entity composed of two other entities:
{ "cities::point": [[2.3522, 48.8566], [4.8357, 45.7640]] }
for an NTV-list entity{ "cities::point": { "paris":[2.3522, 48.8566], "lyon":[4.8357, 45.7640] } }
for an NTV-set entityNote: This syntax can also be used for CSV file headers
The type incorporates a notion of namespaces
that can be nested.
For example, the type: "ns1.ns2.type" means that:
- ns1. is a namespace defined in the global namespace,
- ns2. is a namespace defined in the ns1 namespace.,
- type is defined in the ns2 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.
1# -*- coding: utf-8 -*- 2""" 3***JSON-NTV Package*** 4 5Created on Fri Dec 24 15:21:14 2021 6 7@author: philippe@loco-labs.io 8 9This package contains the following classes: 10 11- `NTV.json_ntv.namespace` : 12 - `NTV.json_ntv.namespace.Namespace` 13 - `NTV.json_ntv.namespace.NtvType` 14 15 16- `NTV.json_ntv.ntv` : 17 - `NTV.json_ntv.ntv.NtvSingle` 18 - `NTV.json_ntv.ntv.NtvList` 19 - `NTV.json_ntv.ntv.Ntv` (abstract class) 20 21- `NTV.json_ntv.ntv_patch` : 22 23 - `NTV.json_ntv.ntv_patch.NtvOp` 24 - `NTV.json_ntv.ntv_patch.NtvPatch` 25 26- `NTV.json_ntv.ntv_comment` : 27 28 - `NTV.json_ntv.ntv_comment.NtvComment` 29 30- `NTV.json_ntv.ntv_util` : 31 32 - `NTV.json_ntv.ntv_util.NtvTree` 33 - `NTV.json_ntv.ntv_util.NtvJsonEncoder` 34 - `NTV.json_ntv.ntv_util.NtvError` 35 - `NTV.json_ntv.ntv_util.NtvConnector` (abstract class) 36 37- `NTV.json_ntv.ntv_connector` : 38 39 - `NTV.json_ntv.ntv_connector.NfieldConnec` 40 - `NTV.json_ntv.ntv_connector.SfieldConnec` 41 - `NTV.json_ntv.ntv_connector.NdatasetConnec` 42 - `NTV.json_ntv.ntv_connector.SdatasetConnec` 43 - `NTV.json_ntv.ntv_connector.MermaidConnec` 44 - `NTV.json_ntv.ntv_connector.CborConnec` 45 - `NTV.json_ntv.ntv_connector.ShapelyConnec` 46 47Note: pandas connector is in another package `ntv-pandas.ntv_pandas.pandas_ntv_connector` 48 49# 0 - Abstract 50 51Today, the semantic level of shared data remains low. It is very often limited 52to the type of data defined in the exchange formats (strings for CSV formats; 53numbers, strings, arrays and objects for JSON formats). 54 55The proposed consists of adding a type and a name to the data exchanged (see also the 56[JSON-NTV specification](https://github.com/loco-philippe/NTV/blob/main/documentation/JSON-NTV-standard.pdf)). 57 58With this evolution any data, whatever its semantic level, can be identified, 59shared and interpreted in a consistent way. 60The implementation of a type with a nested structure facilitates its appropriation. 61Finally, compatibility with existing JSON structures allows progressive deployment. 62 63# 1 - NTV structure 64 65The constructed entities (called NTV for *named typed value*) are therefore a triplet 66 with one mandatory element (the value in JSON format) and two optional elements (name, type). 67> 68> *For example, the location of Paris can be represented by:* 69> - *a name: "Paris",* 70> - *a type: the coordinates of a point according to the GeoJSON format,* 71> - *a value: [ 2.3522, 48.8566]* 72 73The easiest way to add this information is to use a JSON-object with a single member 74 using the syntax [JSON-ND](https://github.com/glenkleidon/JSON-ND) for the first 75 term of the member and the JSON-value for the second term of the member. 76> 77> *For the example above, the JSON representation is:* 78> *```{ "paris:point" : [2.3522, 48.8566] }```* 79 80With this approach, three NTV entities are defined: 81- a primitive entity which is not composed of any other entity (NTV-single), 82- two structured entities: an unordered collection of NTV entities (NTV-set) and 83 an ordered sequence of NTV entities (NTV-list). 84 85as well as two JSON formats: 86- simple format when the name and the type are not present (this is the usual case of CSV data), 87- named format when the name or type is present (see example above for an NTV-single 88entity and below for a structured entity). 89> 90> *Example of an entity composed of two other entities:* 91> - *```{ "cities::point": [[2.3522, 48.8566], [4.8357, 45.7640]] }``` for an NTV-list entity* 92> - *```{ "cities::point": { "paris":[2.3522, 48.8566], "lyon":[4.8357, 45.7640] } }``` 93for an NTV-set entity* 94> 95> *Note: This syntax can also be used for CSV file headers* 96 97The type incorporates a notion of `namespaces` that can be nested. 98> *For example, the type: "ns1.ns2.type" means that:* 99> - *ns1. is a namespace defined in the global namespace,* 100> - *ns2. is a namespace defined in the ns1 namespace.,* 101> - *type is defined in the ns2 namespace.* 102 103This structuring of type makes it possible to reference any type of data that has 104 a JSON representation and to consolidate all the shared data structures within the 105 same tree of types. 106 107 108""" 109from json_ntv.namespace import Namespace, NtvType, str_type, relative_type, agreg_type 110from json_ntv.ntv_patch import NtvOp, NtvPatch 111from json_ntv.ntv_comment import NtvComment 112from json_ntv.ntv import Ntv, NtvSingle, NtvList 113from json_ntv.ntv_util import NtvTree, NtvJsonEncoder, NtvConnector, NtvError 114#from json_ntv.pandas_ntv_connector import DataFrameConnec, SeriesConnec, read_json, to_json, as_def_type 115from json_ntv.ntv_connector import from_csv, to_csv 116from json_ntv.ntv_connector import MermaidConnec, CborConnec, ShapelyConnec 117from json_ntv.ntv_connector import NfieldConnec, SfieldConnec 118from json_ntv.ntv_connector import NdatasetConnec, SdatasetConnec 119 120#print('package :', __package__)