Merge pull request #106 from Open-Telecoms-Data/example-updates

Example updates

docs/_static/jsonschema.css

@@ -0,0 +1,3 @@
+.wy-table-responsive table td {
+    white-space: normal !important;
+}

docs/_static/renderjson.css

@@ -1,11 +1,11 @@
-pre.renderjson { overflow: scroll; font-size:smaller; border: 1px solid grey;}
+pre.renderjson { overflow: scroll; font-size:smaller; border: 1px solid #e1e4e5; padding: 12px; background-color: #eeffcc;}
 .renderjson a { text-decoration: none; }
-.renderjson .disclosure { color: crimson; font-size: 150%; }
+.renderjson .disclosure { color: grey; font-size: 150%; }
 .renderjson .syntax { color: grey; }
-.renderjson .string { color: darkred; }
+.renderjson .string { color: #4070a0; }
 .renderjson .number { color: darkcyan; }
 .renderjson .boolean { color: blueviolet; }
-.renderjson .key    { color: darkblue; }
+.renderjson .key    { color: #062873; font-weight: bold;}
 .renderjson .keyword { color: blue; }
-.renderjson .object.syntax { color: lightseagreen; }
-.renderjson .array.syntax  { color: orange; }
+.renderjson .object.syntax { color: grey; }
+.renderjson .array.syntax  { color: grey; }

docs/_static/renderjson.js

@@ -185,7 +185,7 @@ var module;
     //Added by timgdavies
     renderjson.set_default_open = function(node_list) { renderjson.default_open = node_list ? node_list : [] ; return renderjson; };
 
-    renderjson.set_icons('⊕', '⊖');
+    renderjson.set_icons('▹', '▾');
     renderjson.set_show_by_default(false);
     renderjson.set_sort_objects(false);
     renderjson.set_max_string_length("none");

docs/_templates/layout.html

@@ -1,3 +1,3 @@
 {% extends "!layout.html" %}
-{% set css_files = css_files + ["_static/renderjson.css"] %}
+{% set css_files = css_files + ["_static/renderjson.css", "_static/jsonschema.css"] %}
 {% set script_files = script_files + ["_static/renderjson.js", "_static/json-example-format.js"] %}

docs/guidance/publication.md

@@ -52,7 +52,7 @@ To meet the widest range of use cases, you ought to publish data in all three fo
 :::{tab-item} JSON to GeoJSON
 The standard repository's [`manage.py`](https://github.com/Open-Telecoms-Data/open-fibre-data-standard/blob/main/manage.py) file provides a command-line interface for transforming OFDS data from JSON to GeoJSON format.
 
-To convert a network to GeoJSON format:
+To convert a network package to GeoJSON format:
 
 * Clone the [repository](https://github.com/Open-Telecoms-Data/open-fibre-data-standard)
 * Create a virtual environment:
@@ -68,7 +68,7 @@ pip install -r requirements.txt
 * Run the following command:
 
 ```bash
-./manage.py convert-to-geojson network.json
+./manage.py convert-to-geojson network-package.json
 ```
 
 :::
@@ -109,15 +109,17 @@ The preferred approach is to publish embedded nodes and links in `.nodes` and `.
 
 :::{tab-item} Embedded data
 The following example shows a network with embedded nodes and links:
-```{jsoninclude} ../../examples/json/network-embedded.json
-:jsonpointer:
+```{jsoninclude} ../../examples/json/network-package.json
+:jsonpointer: /networks/0
+:expand: nodes,links
 ```
 :::
 
 :::{tab-item} References to endpoints
 The following example shows a network with references to separate endpoints for nodes and links:
 ```{jsoninclude} ../../examples/json/network-separate-endpoints.json
-:jsonpointer:
+:jsonpointer: /networks/0
+:expand: relatedResources
 ```
 :::
 
@@ -145,15 +147,16 @@ The preferred approach is to publish embedded nodes and links. If your network i
 
 :::{tab-item} Embedded data
 The following example shows a network with embedded nodes and links:
-```{jsoninclude} ../../examples/json/network-embedded.json
-:jsonpointer:
+```{jsoninclude} ../../examples/json/network-package.json
+:jsonpointer: /networks/0
 ```
 :::
 
 :::{tab-item} References to files
 The following example shows a network with references to separate files for nodes and links:
 ```{jsoninclude} ../../examples/json/network-separate-files.json
-:jsonpointer:
+:jsonpointer: /networks/0
+:expand: relatedResources
 ```
 :::
 

docs/reference/identifiers.md

@@ -32,8 +32,8 @@ To ensure that an organisation's `.identifier` is globally unique, it has two co
 
 :::{tab-item} Example
 The following example shows the `.identifier` for an organisation registered at Ghana's Registrar General's Department, the scheme code for which is [GH-RGD](https://org-id.guide/list/GH-RGD):
-```{jsoninclude} ../../examples/json/network.json
-:jsonpointer: /organisations/0/identifier
+```{jsoninclude} ../../examples/json/network-package.json
+:jsonpointer: /networks/0/organisations/0/identifier
 ```
 :::
 

docs/reference/publication_formats.md

@@ -43,15 +43,17 @@ Click on schema elements to expand the tree, or use the '+' icon to expand all e
 
 :::{tab-item} Small file example
 The following example shows a network package containing two networks:
-```{jsoninclude} ../../examples/json/network-package.json
+```{jsoninclude} ../../examples/json/multiple-networks.json
 :jsonpointer:
+:expand: networks
 ```
 :::
 
 :::{tab-item} API response example
 The following example shows a network package containing two networks with URLs for the next and previous pages of results.
 ```{jsoninclude} ../../examples/json/api-response.json
 :jsonpointer:
+:expand: networks,pages
 ```
 :::
 
@@ -90,13 +92,15 @@ Publish separate GeoJSON [feature collections](https://datatracker.ietf.org/doc/
 The following example shows a GeoJSON feature collection containing nodes:
 ```{jsoninclude} ../../examples/geojson/nodes.geojson
 :jsonpointer:
+:expand: features
 ```
 :::
 
 :::{tab-item} Links feature collection
 The following example shows a GeoJSON feature collection containing links:
 ```{jsoninclude} ../../examples/geojson/links.geojson
 :jsonpointer:
+:expand: features
 ```
 :::
 
@@ -108,6 +112,7 @@ The following example shows a GeoJSON feature collection containing features fro
 
 ```{jsoninclude} ../../examples/geojson/multiple-networks.geojson
 :jsonpointer:
+:expand: features
 ```
 
 For data published via a paginated API, you should add a top-level `pages` object to the feature collection to provide URLs for the next and previous pages of results:

docs/reference/schema.md

@@ -43,8 +43,8 @@ In addition to the above sections, there are several top-level metadata fields:
 
 :::{tab-item} Example
 ```{eval-rst} 
-.. jsoninclude:: ../../examples/json/network.json
-   :jsonpointer:
+.. jsoninclude:: ../../examples/json/network-package.json
+   :jsonpointer: /networks/0
    :title: Example
 ```
 :::
@@ -111,8 +111,8 @@ Each `Node` has the following fields:
 
 :::{tab-item} Example
 ```{eval-rst} 
-.. jsoninclude:: ../../examples/json/network.json
-   :jsonpointer: /nodes
+.. jsoninclude:: ../../examples/json/network-package.json
+   :jsonpointer: /networks/0/nodes
    :title: Example
 ```
 :::
@@ -148,8 +148,9 @@ Each `Link` has the following fields:
 
 :::{tab-item} Example
 ```{eval-rst} 
-.. jsoninclude:: ../../examples/json/network.json
-   :jsonpointer: /links
+.. jsoninclude:: ../../examples/json/network-package.json
+   :jsonpointer: /networks/0/links
+   :title: Example
 ```
 :::
 
@@ -173,8 +174,8 @@ Each `Phase` has the following fields:
 
 :::{tab-item} Example
 ```{eval-rst} 
-.. jsoninclude:: ../../examples/json/network.json
-   :jsonpointer: /phases
+.. jsoninclude:: ../../examples/json/network-package.json
+   :jsonpointer: /networks/0/phases
    :title: Example
 ```
 :::
@@ -203,8 +204,8 @@ Each `Organisation` has the following fields:
 
 :::{tab-item} Example
 ```{eval-rst} 
-.. jsoninclude:: ../../examples/json/network.json
-   :jsonpointer: /organisations
+.. jsoninclude:: ../../examples/json/network-package.json
+   :jsonpointer: /networks/0/organisations
    :title: Example
 ```
 :::
@@ -233,8 +234,8 @@ Each `Contract` has the following fields:
 
 :::{tab-item} Example
 ```{eval-rst} 
-.. jsoninclude:: ../../examples/json/network.json
-   :jsonpointer: /contracts
+.. jsoninclude:: ../../examples/json/network-package.json
+   :jsonpointer: /networks/0/contracts
    :title: Example
 ```
 :::
@@ -259,12 +260,12 @@ Each `Geometry` has the following fields:
 
 :::{tab-item} Example
 ```{eval-rst} 
-.. jsoninclude:: ../../examples/json/network.json
-   :jsonpointer: /nodes/0/location
+.. jsoninclude:: ../../examples/json/network-package.json
+   :jsonpointer: /networks/0/nodes/0/location
    :title: Node
 
-.. jsoninclude:: ../../examples/json/network.json
-   :jsonpointer: /links/0/route
+.. jsoninclude:: ../../examples/json/network-package.json
+   :jsonpointer: /networks/0/links/0/route
    :title: Link
 ```
 :::
@@ -289,8 +290,8 @@ Each `OrganisationReference` has the following fields:
 
 :::{tab-item} Example
 ```{eval-rst} 
-.. jsoninclude:: ../../examples/json/network.json
-   :jsonpointer: /links/0/physicalInfrastructureProvider
+.. jsoninclude:: ../../examples/json/network-package.json
+   :jsonpointer: /networks/0/links/0/physicalInfrastructureProvider
    :title: Example
 ```
 :::
@@ -314,8 +315,8 @@ Each `PhaseReference` has the following fields:
 
 :::{tab-item} Example
 ```{eval-rst} 
-.. jsoninclude:: ../../examples/json/network.json
-   :jsonpointer: /contracts/0/relatedPhases
+.. jsoninclude:: ../../examples/json/network-package.json
+   :jsonpointer: /networks/0/contracts/0/relatedPhases
    :title: Example
 ```
 :::
@@ -340,8 +341,8 @@ Each `Address` has the following fields:
 
 :::{tab-item} Example
 ```{eval-rst} 
-.. jsoninclude:: ../../examples/json/network.json
-   :jsonpointer: /nodes/0/address
+.. jsoninclude:: ../../examples/json/network-package.json
+   :jsonpointer: /networks/0/nodes/0/address
    :title: Example
 ```
 :::
@@ -365,8 +366,8 @@ Each `Value` has the following fields:
 
 :::{tab-item} Example
 ```{eval-rst} 
-.. jsoninclude:: ../../examples/json/network.json
-   :jsonpointer: /contracts/0/value
+.. jsoninclude:: ../../examples/json/network-package.json
+   :jsonpointer: /networks/0/contracts/0/value
    :title: Example
 ```
 :::
@@ -391,8 +392,8 @@ Each `Document` has the following fields:
 
 :::{tab-item} Example
 ```{eval-rst} 
-.. jsoninclude:: ../../examples/json/network.json
-   :jsonpointer: /contracts/0/documents
+.. jsoninclude:: ../../examples/json/network-package.json
+   :jsonpointer: /networks/0/contracts/0/documents
    :title: Example
 ```
 :::
@@ -417,8 +418,8 @@ Each `Identifier` has the following fields:
 
 :::{tab-item} Example
 ```{eval-rst} 
-.. jsoninclude:: ../../examples/json/network.json
-   :jsonpointer: /organisations/0/identifier
+.. jsoninclude:: ../../examples/json/network-package.json
+   :jsonpointer: /networks/0/organisations/0/identifier
    :title: Example
 ```
 :::
@@ -460,8 +461,8 @@ Each `CoordinateReferenceSystem` has the following fields:
 
 :::{tab-item} Example
 ```{eval-rst} 
-.. jsoninclude:: ../../examples/json/network.json
-   :jsonpointer: /crs
+.. jsoninclude:: ../../examples/json/network-package.json
+   :jsonpointer: /networks/0/crs
    :title: Example
 ```
 :::
@@ -491,11 +492,11 @@ Each `RelatedResourceReference` has the following fields:
 :::{tab-item} Example
 ```{eval-rst} 
 .. jsoninclude:: ../../examples/json/network-separate-endpoints.json
-   :jsonpointer: /relatedResources
+   :jsonpointer: /networks/0/relatedResources
    :title: Pagination
 
 .. jsoninclude:: ../../examples/json/network-separate-files.json
-   :jsonpointer: /relatedResources
+   :jsonpointer: /networks/0/relatedResources
    :title: Streaming
 ```
 :::
@@ -516,13 +517,12 @@ Each `FibreTypeDetails` has the following fields:
 :pointer: /definitions/FibreTypeDetails
 :collapse: description
 ```
-```
 :::
 
 :::{tab-item} Example
 ```{eval-rst} 
-.. jsoninclude:: ../../examples/json/network.json
-   :jsonpointer: /links/0/fibreTypeDetails
+.. jsoninclude:: ../../examples/json/network-package.json
+   :jsonpointer: /networks/0/links/0/fibreTypeDetails
    :title: Example
 ```
 :::
@@ -547,13 +547,12 @@ Each `DeploymentDetails` has the following fields:
 :pointer: /definitions/DeploymentDetails
 :collapse: description
 ```
-```
 :::
 
 :::{tab-item} Example
 ```{eval-rst} 
-.. jsoninclude:: ../../examples/json/network.json
-   :jsonpointer: /links/0/deploymentDetails
+.. jsoninclude:: ../../examples/json/network-package.json
+   :jsonpointer: /networks/0/links/0/deploymentDetails
    :title: Example
 ```
 :::
@@ -582,10 +581,11 @@ Each `CapacityDetails` has the following fields:
 
 :::{tab-item} Example
 ```{eval-rst} 
-.. jsoninclude:: ../../examples/json/network.json
-   :jsonpointer: /links/0/capacityDetails
+.. jsoninclude:: ../../examples/json/network-package.json
+   :jsonpointer: /networks/0/links/0/capacityDetails
    :title: Example
 ```
 :::
 
 ::::
+