Add CSV format reference, examples and template

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:
@@ -201,3 +206,175 @@ This section has [open issues](https://github.com/Open-Telecoms-Data/open-fibre-
 
 This section describes how to publish data in CSV format.
 
+The CSV format has 10 tables, reflecting the structure of the [schema](schema.md). Arrays of objects in the schema are represented as separate tables:
+
+* [Networks](#table-structure)
+  * [Nodes](#nodes)
+    * [International connections](#international-connections)
+  * [Links](#links)
+  * [Phases](#phases)
+    * [Funders](#funders)
+  * [Organisations](#organisations)
+  * [Contracts](#contracts)
+    * [Documents](#documents)
+    * [Related phases](#related-phases)
+
+The field in the schema that each column represents is identified by the field's [JSON Pointer](https://tools.ietf.org/html/rfc6901). Rows in child tables are related to rows in parent tables using the parent object's `id` field.
+
+The following example shows a network with two nodes represented in JSON format and as tables. Note how the network's `.id` appears in both tables.
+
+::::{tab-set}
+
+:::{tab-item} JSON
+```{jsoninclude} ../../examples/json/network-package.json
+:jsonpointer: /networks/0
+:exclude: links,phases,organisations,contracts
+```
+:::
+
+:::{tab-item} Networks table
+```{csv-table-no-translate}
+:header-rows: 1
+:widths: auto
+:file: ../../examples/csv/networks.csv
+```
+:::
+
+:::{tab-item} Nodes table
+```{csv-table-no-translate}
+:header-rows: 1
+:widths: auto
+:file: ../../examples/csv/nodes.csv
+```
+:::
+
+::::
+
+### Table structure
+
+This section describes the structure of the tables in the CSV format and the relationship between the tables. Example CSV files and blank templates are provided for each table.
+
+The networks table is the main table. It is related to the following tables:
+
+* [Nodes](#nodes): one-to-many by `id`
+* [Links](#links): one-to-many by `id`
+* [Phases](#phases): one-to-many by `id`
+* [Organisations](#organisations): one-to-many by `id`
+* [Contracts](#contracts): one-to-many by `id`
+
+The fields in this table are listed below. You can also download an [example CSV file](../../examples/csv/networks.csv) or a [blank template](../../examples/csv/template/networks.csv) for this table.
+
+```{jsonschema} ../../schema/network-schema.json
+:include: id,name,website,publisher,publicationDate,collectionDate,crs,accuracy,accuracyDetails,language
+```
+
+#### Nodes
+
+This table is related to the following tables:
+
+* [Networks](#table-structure): many-to-one by `id`
+* [International connections](#international-connections): one-to-many by `nodes/0/id`
+
+The fields in this table are listed below. You can also download an [example CSV file](../../examples/csv/nodes.csv) or a [blank template](../../examples/csv/template/nodes.csv).
+
+```{jsonschema} ../../schema/network-schema.json
+:include: id,nodes/0/id,nodes/0/name,nodes/0/phase,nodes/0/status,nodes/0/location,nodes/0/address,nodes/0/type,nodes/0/accessPoint,nodes/0/power,nodes/0/technologies,nodes/0/physicalInfrastructureProvider,nodes/0/networkProvider
+```
+
+##### International connections
+
+This table is related to the following tables:
+
+* [Nodes](#nodes): many-to-one by `nodes/0/id`
+
+The fields in this table are listed below. You can also download an [example CSV file](../../examples/csv/nodes_internationalConnections.csv) or a [blank template](../../examples/csv/template/nodes_internationalConnections.csv).
+
+```{jsonschema} ../../schema/network-schema.json
+:include: id,nodes/0/id,nodes/0/internationalConnections/0/streetAddress,nodes/0/internationalConnections/0/locality,nodes/0/internationalConnections/0/region,nodes/0/internationalConnections/0/postalCode,nodes/0/internationalConnections/0/country
+```
+
+#### Links
+
+This table is related to the following tables:
+
+* [Networks](#table-structure): many-to-one by `id`
+
+The fields in this table are listed below. You can also download an [example CSV file](../../examples/csv/links.csv) or a [blank template](../../examples/csv/template/links.csv).
+
+```{jsonschema} ../../schema/network-schema.json
+:include: id,links/0/id,links/0/name,links/0/phase,links/0/status,links/0/readyForServiceDate,links/0/start,links/0/end,links/0/route,links/0/physicalInfrastructureProvider,links/0/networkProvider,links/0/supplier,links/0/transmissionMedium,links/0/deployment,links/0/deploymentDetails,links/0/darkFibre,links/0/fibreType,links/0/fibreTypeDetails,links/0/fibreCount,links/0/fibreLength,links/0/technologies,links/0/capacity,links/0/capacityDetails,links/0/countries,links/0/directed
+```
+
+#### Phases
+
+This table is related to the following tables:
+
+* [Networks](#table-structure): many-to-one by `id`
+* [Funders](#funders): one-to-many by `phases/0/id`
+
+The fields in this table are listed below. You can also download an [example CSV file](../../examples/csv/phases.csv) or a [blank template](../../examples/csv/template/phases.csv).
+
+```{jsonschema} ../../schema/network-schema.json
+:include: id,phases/0/name,phases/0/description
+```
+
+##### Funders
+
+This table is related to the following tables:
+
+* [Phases](#phases): many-to-one by `phase/0/id`
+
+The fields in this table are listed below. You can also download an [example CSV file](../../examples/csv/phases_funders.csv) or a [blank template](../../examples/csv/template/phases_funders.csv).
+
+```{jsonschema} ../../schema/network-schema.json
+:include: id,phases/0/id,phases/0/funders/0/id,phases/0/funders/0/name
+```
+
+#### Organisations
+
+This table is related to the following tables:
+
+* [Network](#table-structure): many-to-one by `id`
+
+The fields in this table are listed below. You can also download an [example CSV file](../../examples/csv/organisations.csv) or a [blank template](../../examples/csv/template/organisations.csv).
+
+```{jsonschema} ../../schema/network-schema.json
+:include: id,organisations/0/id,organisations/0/name,organisations/0/identifier,organisations/0/country,organisations/0/roles,organisations/0/roleDetails,organisations/0/website,organisations/0/logo
+```
+
+#### Contracts
+
+This table is related to the following tables:
+
+* [Network](#table-structure): many-to-one by `id`
+* [Documents](#documents): one-to-many by `contracts/0/id`
+
+The fields in this table are listed below. You can also download an [example CSV file](../../examples/csv/contracts.csv) or a [blank template](../../examples/csv/template/contracts.csv).
+
+```{jsonschema} ../../schema/network-schema.json
+:include: id,contracts/0/id,contracts/0/title,contracts/0/description,contracts/0/type,contracts/0/value,contracts/0/dateSigned
+```
+
+##### Documents
+
+This table is related to the following tables:
+
+* [Contracts](#contracts): many-to-one by `contracts/0/id`
+
+The fields in this table are listed below. You can also download an [example CSV file](../../examples/csv/contracts_documents.csv) or a [blank template](../../examples/csv/template/contracts_documents.csv).
+
+```{jsonschema} ../../schema/network-schema.json
+:include: id,contracts/0/id,contracts/0/documents/0/title,contracts/0/documents/0/description,contracts/0/documents/0/url,contracts/0/documents/0/format
+```
+
+##### Related phases
+
+This table is related to the following tables:
+
+* [Contracts](#contracts): many-to-one by `contracts/0/id`
+
+The fields in this table are listed below. You can also download an [example CSV file](../../examples/csv/contracts_relatedPhases.csv) or a [blank template](../../examples/csv/template/contracts_relatedPhases.csv).
+
+```{jsonschema} ../../schema/network-schema.json
+:include: id,contracts/0/id,contracts/0/relatedPhases/0/id,contracts/0/relatedPhases/0/name
+```