### ***JSON-NTV (named and typed value) <img src="https://loco-philippe.github.io/ES/json-ntv.PNG" alt="json-NTV" style="float:right;width:233px;height:64px;"> : a semantic format for interoperability***
*JSON-NTV is a universal representation format. It allows the sharing and conversion of any type of data.*
*The NTV format is part of the [Environmental Sensing Project](https://github.com/loco-philippe/Environmental-Sensing#readme)*
For more information, see the [user guide](https://loco-philippe.github.io/NTV/documentation/user_guide.html) or the [github repository](https://github.com/loco-philippe/NTV).
# What is NTV ?
The semantic level of shared JSON (or CSV) data (e.g. Open Data) remains low, which makes automated reuse difficult.
JSON-NTV proposes to enrich it to obtain a real interoperable exchange format.
## NTV format
The NTV format consists of representing data by three attributes: a name, a type and a value. This representation is common in programming languages (for example a variable with Python typing is defined by `age: int = 25`), however the JSON format represents data with only a value or a key:value pair.
The JSON-NTV extension consists of including the type in the name to associate it with a value (for example `{'age:int': 25}` is the JSON representation of the NTV triplet ('age', 'int' , 25 ) ).
This approach makes it possible to reversibly represent any simple or complex data by a JSON structure (high interoperability).
## Examples
```python
In [1]: from shapely.geometry import Point
from datetime import date
from pprint import pprint
In [2]: pprint(Ntv.obj(21).expand())
Out[2]: {'name': '', 'type': 'json', 'value': 21}
In [3]: pprint(Ntv.obj({"paris:point": [2.3, 48.9] }).expand())
Out[3]: {'name': 'paris', 'type': 'point', 'value': [2.3, 48.9]}
In [4]: pprint(Ntv.obj({"cities::point": [[2.3, 48.9], [4.8, 45.8] }).expand())
Out[4]: {'name': 'cities',
'type': 'point',
'value': [{'name': '', 'type': 'point', 'value': [2.3, 48.9]},
{'name': '', 'type': 'point', 'value': [4.8, 45.8]}]}
In [5]: pprint(Ntv.obj({"paris:point": [2.3, 48.9], "start:date": "2023-08-03", "measurement": 45.8}).expand())
Out[5]: {'name': '',
'type': '',
'value': [{'name': 'paris', 'type': 'point', 'value': [2.3, 48.9]},
{'name': 'start', 'type': 'date', 'value': '2023-08-03'},
{'name': 'measurement', 'type': 'json', 'value': 45.8}]}
```
> *Note: This typing syntax can also be used for CSV file headers*
## NTV structure
With this approach, two NTV entities are defined:
- a primitive entity which is not composed of any other entity (NTV-single),
- a structured entity which is 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 (e.g. `25`),
- named format when the name or type is present ((e.g. `{'age': 25}` or `{':int': 25}`)).
The type incorporates a notion of `namespace` that can be nested.
> *For example, the type: `ns1.ns2.type_a` means that:*
>
> - *`ns1.` is a namespace defined in the global namespace,*
> - *`ns2.` is a namespace defined in the `ns1.` namespace.,*
> - *`type_a` is defined in the `ns2.` namespace.*
The type can be extended with additional data.
> *For example, the type: `float[kg]` means that:*
>
> - *`float` is a main type of the data,*
> - *`kg` is an additional type (e.g. an unit),*
> - *`float[kg]` may represent a Quantity.*
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.
## NTV uses
Several variations and use cases of the NTV format are defined:
- Tabular and multidimensional data exchange format (e.g. open-data)
- Compact, reversible and semantic pandas-JSON interface
- Comment and change management of JSON data
- visualization of JSON or NTV tree
- JSON data editor
- data validation (value conformity to the Datatype)
## NTV and JSON
The flowchart below explain how to convert and exchange native entities through NTV and JSON format.
```mermaid
flowchart LR
text["#10240;#10240;JSON#10240;#10240;\ntext"]
val["#10240;JSON-NTV#10240;\nvalue"]
ntv["#10240;#10240;#10240;NTV#10240;#10240;#10240;\nentity"]
nat["#10240;native#10240;\nentity"]
text--->|JSON load|val
val--->|JSON dump|text
val--->|NTV from JSON|ntv
ntv--->|from NTV|nat
ntv--->|NTV to JSON|val
nat--->|to NTV|ntv
```
The conversion between native entity and JSON-text is reversible (lossless round trip).
```python
In [6]: loc_and_date = {'newyear': date(2023, 1, 2), 'Paris': Point(2.3, 48.9)}
json_loc_date = Ntv.obj(loc_and_date).to_obj(encoded=True)
print(json_loc_date, type(json_loc_date))
Out[6]: {"newyear:date": "2023-01-02", "Paris:point": [2.3, 48.9]} <class 'str'>
In [7]: Ntv.obj(json_loc_date).to_obj(format='obj') == loc_and_date
Out[7]: True
```
*Properties :*
- each NTV object has a unique JSON representation
- each JSON data corresponds to a unique NTV entity
- an NTV entity is a tree where each node is an NTV entity and each leaf an NTV-Single entity
- an NTV entity is a neutral representation (independent of a software or hardware platform)
Raw data
{
"_id": null,
"home_page": "https://github.com/loco-philippe/NTV/blob/main/README.md",
"name": "json-ntv",
"maintainer": null,
"docs_url": null,
"requires_python": "<4,>=3.7",
"maintainer_email": null,
"keywords": "JSON-NTV, semantic JSON, development, environmental data",
"author": "Philippe Thomy",
"author_email": "philippe@loco-labs.io",
"download_url": "https://files.pythonhosted.org/packages/77/87/6812d0f5159d612bf590348dee14d11ef0b06c6eb76044fea3656041b889/json_ntv-1.4.0.tar.gz",
"platform": null,
"description": "### ***JSON-NTV (named and typed value) <img src=\"https://loco-philippe.github.io/ES/json-ntv.PNG\" alt=\"json-NTV\" style=\"float:right;width:233px;height:64px;\"> : a semantic format for interoperability***\r\n\r\n*JSON-NTV is a universal representation format. It allows the sharing and conversion of any type of data.*\r\n\r\n*The NTV format is part of the [Environmental Sensing Project](https://github.com/loco-philippe/Environmental-Sensing#readme)*\r\n\r\nFor more information, see the [user guide](https://loco-philippe.github.io/NTV/documentation/user_guide.html) or the [github repository](https://github.com/loco-philippe/NTV).\r\n\r\n# What is NTV ?\r\n\r\nThe semantic level of shared JSON (or CSV) data (e.g. Open Data) remains low, which makes automated reuse difficult.\r\n\r\nJSON-NTV proposes to enrich it to obtain a real interoperable exchange format.\r\n \r\n## NTV format\r\n\r\nThe NTV format consists of representing data by three attributes: a name, a type and a value. This representation is common in programming languages (for example a variable with Python typing is defined by `age: int = 25`), however the JSON format represents data with only a value or a key:value pair.\r\n\r\nThe JSON-NTV extension consists of including the type in the name to associate it with a value (for example `{'age:int': 25}` is the JSON representation of the NTV triplet ('age', 'int' , 25 ) ).\r\n\r\nThis approach makes it possible to reversibly represent any simple or complex data by a JSON structure (high interoperability).\r\n\r\n## Examples\r\n\r\n```python\r\nIn [1]: from shapely.geometry import Point\r\n from datetime import date\r\n from pprint import pprint\r\n\r\nIn [2]: pprint(Ntv.obj(21).expand())\r\nOut[2]: {'name': '', 'type': 'json', 'value': 21}\r\n\r\nIn [3]: pprint(Ntv.obj({\"paris:point\": [2.3, 48.9] }).expand())\r\nOut[3]: {'name': 'paris', 'type': 'point', 'value': [2.3, 48.9]}\r\n\r\nIn [4]: pprint(Ntv.obj({\"cities::point\": [[2.3, 48.9], [4.8, 45.8] }).expand())\r\nOut[4]: {'name': 'cities',\r\n 'type': 'point',\r\n 'value': [{'name': '', 'type': 'point', 'value': [2.3, 48.9]},\r\n {'name': '', 'type': 'point', 'value': [4.8, 45.8]}]}\r\n\r\nIn [5]: pprint(Ntv.obj({\"paris:point\": [2.3, 48.9], \"start:date\": \"2023-08-03\", \"measurement\": 45.8}).expand())\r\nOut[5]: {'name': '',\r\n 'type': '',\r\n 'value': [{'name': 'paris', 'type': 'point', 'value': [2.3, 48.9]},\r\n {'name': 'start', 'type': 'date', 'value': '2023-08-03'},\r\n {'name': 'measurement', 'type': 'json', 'value': 45.8}]}\r\n```\r\n\r\n> *Note: This typing syntax can also be used for CSV file headers*\r\n\r\n## NTV structure\r\n\r\nWith this approach, two NTV entities are defined:\r\n\r\n- a primitive entity which is not composed of any other entity (NTV-single),\r\n- a structured entity which is an ordered sequence of NTV entities (NTV-list).\r\n\r\nas well as two JSON formats:\r\n\r\n- simple format when the name and the type are not present (e.g. `25`),\r\n- named format when the name or type is present ((e.g. `{'age': 25}` or `{':int': 25}`)).\r\n\r\nThe type incorporates a notion of `namespace` that can be nested.\r\n\r\n> *For example, the type: `ns1.ns2.type_a` means that:*\r\n>\r\n> - *`ns1.` is a namespace defined in the global namespace,*\r\n> - *`ns2.` is a namespace defined in the `ns1.` namespace.,*\r\n> - *`type_a` is defined in the `ns2.` namespace.*\r\n\r\nThe type can be extended with additional data.\r\n\r\n> *For example, the type: `float[kg]` means that:*\r\n>\r\n> - *`float` is a main type of the data,*\r\n> - *`kg` is an additional type (e.g. an unit),*\r\n> - *`float[kg]` may represent a Quantity.*\r\n\r\nThis 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.\r\n\r\n## NTV uses\r\n\r\nSeveral variations and use cases of the NTV format are defined:\r\n\r\n- Tabular and multidimensional data exchange format (e.g. open-data)\r\n- Compact, reversible and semantic pandas-JSON interface\r\n- Comment and change management of JSON data\r\n- visualization of JSON or NTV tree\r\n- JSON data editor\r\n- data validation (value conformity to the Datatype)\r\n\r\n## NTV and JSON\r\n\r\nThe flowchart below explain how to convert and exchange native entities through NTV and JSON format.\r\n\r\n```mermaid\r\nflowchart LR\r\n text[\"#10240;#10240;JSON#10240;#10240;\\ntext\"]\r\n val[\"#10240;JSON-NTV#10240;\\nvalue\"]\r\n ntv[\"#10240;#10240;#10240;NTV#10240;#10240;#10240;\\nentity\"]\r\n nat[\"#10240;native#10240;\\nentity\"]\r\n text--->|JSON load|val\r\n val--->|JSON dump|text\r\n val--->|NTV from JSON|ntv\r\n ntv--->|from NTV|nat\r\n ntv--->|NTV to JSON|val\r\n nat--->|to NTV|ntv\r\n```\r\n\r\nThe conversion between native entity and JSON-text is reversible (lossless round trip).\r\n\r\n```python\r\nIn [6]: loc_and_date = {'newyear': date(2023, 1, 2), 'Paris': Point(2.3, 48.9)}\r\n json_loc_date = Ntv.obj(loc_and_date).to_obj(encoded=True)\r\n print(json_loc_date, type(json_loc_date))\r\nOut[6]: {\"newyear:date\": \"2023-01-02\", \"Paris:point\": [2.3, 48.9]} <class 'str'>\r\n\r\nIn [7]: Ntv.obj(json_loc_date).to_obj(format='obj') == loc_and_date\r\nOut[7]: True\r\n```\r\n\r\n*Properties :*\r\n\r\n- each NTV object has a unique JSON representation\r\n- each JSON data corresponds to a unique NTV entity\r\n- an NTV entity is a tree where each node is an NTV entity and each leaf an NTV-Single entity\r\n- an NTV entity is a neutral representation (independent of a software or hardware platform)\r\n",
"bugtrack_url": null,
"license": null,
"summary": "JSON-NTV a semantic format for interoperability",
"version": "1.4.0",
"project_urls": {
"Homepage": "https://github.com/loco-philippe/NTV/blob/main/README.md"
},
"split_keywords": [
"json-ntv",
" semantic json",
" development",
" environmental data"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "840c6386a9f334ad6930624a45e87df2bdc73d88f65c50d5262967643045d3f9",
"md5": "c0328456c6233e6bcbe305ed266c7c0f",
"sha256": "c4c3b1b90ca637625a0d26f10dc6023d1b033061f66ce3faaabbec619ca8c6a3"
},
"downloads": -1,
"filename": "json_ntv-1.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c0328456c6233e6bcbe305ed266c7c0f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.7",
"size": 41617,
"upload_time": "2024-05-07T09:39:41",
"upload_time_iso_8601": "2024-05-07T09:39:41.508560Z",
"url": "https://files.pythonhosted.org/packages/84/0c/6386a9f334ad6930624a45e87df2bdc73d88f65c50d5262967643045d3f9/json_ntv-1.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "77876812d0f5159d612bf590348dee14d11ef0b06c6eb76044fea3656041b889",
"md5": "044904d56d10e9d9c8429df91b29ab43",
"sha256": "279f0b774330aafc9a3fd2ec614491f6518f1368d384368d8d162db0e291b35d"
},
"downloads": -1,
"filename": "json_ntv-1.4.0.tar.gz",
"has_sig": false,
"md5_digest": "044904d56d10e9d9c8429df91b29ab43",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.7",
"size": 49508,
"upload_time": "2024-05-07T09:39:43",
"upload_time_iso_8601": "2024-05-07T09:39:43.409350Z",
"url": "https://files.pythonhosted.org/packages/77/87/6812d0f5159d612bf590348dee14d11ef0b06c6eb76044fea3656041b889/json_ntv-1.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-07 09:39:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "loco-philippe",
"github_project": "NTV",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "json-ntv"
}
JSON
