Merge pull request #108 from Open-Telecoms-Data/csv

Add CSV format reference, examples and template

docs/reference/publication_formats.md

@@ -206,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
+```

examples/csv/contracts.csv

@@ -0,0 +1,2 @@
+id,contracts/0/id,contracts/0/title,contracts/0/description,contracts/0/type,contracts/0/value/amount,contracts/0/value/currency,contracts/0/dateSigned
+a096d627-72e1-4f9b-b129-951b1737bff4,1,NextGen Phase 1 Construction Contract,Contract for the construction of phase 1 of the NextGen network.,private,1537459500.00,GHS,2016-06-30

examples/csv/contracts_documents.csv

@@ -0,0 +1,2 @@
+id,contracts/0/id,contracts/0/documents/0/title,contracts/0/documents/0/description,contracts/0/documents/0/url,contracts/0/documents/0/format
+a096d627-72e1-4f9b-b129-951b1737bff4,1,NextGen Phase 1 Construction Contract,Signed contract.,http://example.com/contracts/nextgen-phase1-construction.pdf,application/pdf

examples/csv/contracts_relatedPhases.csv

@@ -0,0 +1,2 @@
+id,contracts/0/id,contracts/0/relatedPhases/0/id,contracts/0/relatedPhases/0/name
+a096d627-72e1-4f9b-b129-951b1737bff4,1,1,NextGen Phase 1

examples/csv/links.csv

@@ -0,0 +1,2 @@
+id,links/0/id,links/0/name,links/0/phase/id,links/0/phase/name,links/0/status,links/0/readyForServiceDate,links/0/start,links/0/end,links/0/directed,links/0/route/type,links/0/route/coordinates,links/0/physicalInfrastructureProvider/id,links/0/physicalInfrastructureProvider/name,links/0/networkProvider/id,links/0/networkProvider/name,links/0/supplier/id,links/0/supplier/name,links/0/transmissionMedium,links/0/deployment,links/0/deploymentDetails/description,links/0/darkFibre,links/0/fibreType,links/0/fibreTypeDetails/description,links/0/fibreCount,links/0/fibreLength,links/0/technologies,links/0/capacity,links/0/capacityDetails/description,links/0/countries
+a096d627-72e1-4f9b-b129-951b1737bff4,1,Accra to Kumasi,1,NextGen Phase 1,operational,2018-01-01,1,2,False,LineString,"-0.173,5.626;-0.178,5.807;-0.112,5.971;-0.211,5.963;-0.321,6.170;-0.488,6.290;-0.560,6.421;-0.752,6.533;-0.867,6.607;-1.101,6.585;-1.304,6.623;-1.461,6.727;-1.628,6.713",GH-RGD-CS111111111,FibreCo,GH-RGD-CS222222222,FastWeb,GH-RGD-CS333333333,ProjectCo,fibre,belowGround,Buried in ducts,True,G.652,"CABLED STANDARD ENHANCED SINGLEMODE FIBRE ESMF, LOW WATER PEAK SINGLE MODE FIBRE G.652.D, OS2",24,276000,sdh,4.976,2xSTM-16,GH

examples/csv/networks.csv

@@ -0,0 +1,2 @@
+id,name,website,publisher/id,publisher/name,publisher/identifier/id,publisher/identifier/scheme,publisher/identifier/legalName,publisher/identifier/uri,publisher/country,publisher/roles,publisher/roleDetails,publisher/website,publisher/logo,publicationDate,collectionDate,crs/name,crs/uri,accuracy,accuracyDetails,language
+a096d627-72e1-4f9b-b129-951b1737bff4,Ghana Fibre Network,http://example.com/network,GH-RGD-CS111111111,FibreCo,CS111111111,GH-RGD,FibreCo Ghana Limited,https://example.com/companies/CS111111111,GH,,,https://www.example.com,https://www.example.com/logo.png,2022-01-01,2021-09-30,urn:ogc:def:crs:OGC::CRS84,http://www.opengis.net/def/crs/OGC/1.3/CRS84,250,Measured according to the US National Standard for Spatial Data Accuracy.,en

examples/csv/nodes.csv

@@ -0,0 +1,3 @@
+id,nodes/0/id,nodes/0/name,nodes/0/phase/id,nodes/0/phase/name,nodes/0/status,nodes/0/location/type,nodes/0/location/coordinates,nodes/0/address/streetAddress,nodes/0/address/locality,nodes/0/address/region,nodes/0/address/postalCode,nodes/0/address/country,nodes/0/type,nodes/0/accessPoint,nodes/0/power,nodes/0/technologies,nodes/0/physicalInfrastructureProvider/id,nodes/0/physicalInfrastructureProvider/name,nodes/0/networkProvider/id,nodes/0/networkProvider/name
+a096d627-72e1-4f9b-b129-951b1737bff4,1,Accra,1,NextGen Phase 1,operational,Point,-0.174;5.625,Boundary Rd,Shiashie,Accra,12345,GH,pop,True,True,ip,GH-RGD-CS111111111,FibreCo,GH-RGD-CS222222222,FastWeb
+a096d627-72e1-4f9b-b129-951b1737bff4,2,Kumasi,1,NextGen Phase 1,operational,Point,-1.628;6.711,Kejetia Road,Bantama,Kumasi,00000,GH,pop,True,True,ip,GH-RGD-CS111111111,FibreCo,GH-RGD-CS222222222,FastWeb

examples/csv/nodes_internationalConnections.csv

@@ -0,0 +1,2 @@
+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
+a096d627-72e1-4f9b-b129-951b1737bff4,1,,,Lomé,,TG

examples/csv/organisations.csv

@@ -0,0 +1,5 @@
+id,organisations/0/id,organisations/0/name,organisations/0/identifier/id,organisations/0/identifier/scheme,organisations/0/identifier/legalName,organisations/0/identifier/uri,organisations/0/country,organisations/0/roles,organisations/0/roleDetails,organisations/0/website,organisations/0/logo
+a096d627-72e1-4f9b-b129-951b1737bff4,GH-RGD-CS111111111,FibreCo,CS111111111,GH-RGD,FibreCo Ghana Limited,https://example.com/companies/CS111111111,GH,physicalInfrastructureProvider,FibreCo owns and maintains the physical infrastructure.,https://www.example.com,https://www.example.com/logo.png
+a096d627-72e1-4f9b-b129-951b1737bff4,GH-RGD-CS222222222,FastWeb,CS222222222,GH-RGD,FastWeb Ghana Limited,https://example.com/companies/CS222222222,GH,networkProvider,FastWeb provides wholesale services to service providers and dark fibre access to other network providers.,https://www.example.com,https://www.example.com/logo.png
+a096d627-72e1-4f9b-b129-951b1737bff4,GH-RGD-CS333333333,ProjectCo,CS333333333,GH-RGD,ProjectCo Ghana Limited,https://example.com/companies/CS333333333,GH,supplier,ProjectCo was responsible for the construction of phase 1 of the NextGen network.,https://www.example.com,https://www.example.com/logo.png
+a096d627-72e1-4f9b-b129-951b1737bff4,1,Ghana Infrastructure Investment Fund,,,,,GH,funder,The Ghana Infrastructure Investment Fund provided equity financing for the construction of phase 1 of the NextGen network.,https://www.example.com,https://www.example.com/logo.png

examples/csv/phases.csv

@@ -0,0 +1,2 @@
+id,phases/0/id,phases/0/name,phases/0/description
+a096d627-72e1-4f9b-b129-951b1737bff4,1,NextGen Phase 1,The first phase of the Ghana Fibre Network NextGen roll-out.

examples/csv/phases_funders.csv

@@ -0,0 +1,2 @@
+id,phases/0/id,phases/0/funders/0/id,phases/0/funders/0/name
+a096d627-72e1-4f9b-b129-951b1737bff4,1,1,Ghana Infrastructure Investment Fund

examples/csv/relatedResources.csv

@@ -0,0 +1 @@
+id,relatedResources/0/href,relatedResources/0/rel

examples/csv/template/contracts.csv

@@ -0,0 +1 @@
+id,contracts/0/id,contracts/0/title,contracts/0/description,contracts/0/type,contracts/0/value/amount,contracts/0/value/currency,contracts/0/dateSigned

examples/csv/template/contracts_documents.csv

@@ -0,0 +1 @@
+id,contracts/0/id,contracts/0/documents/0/title,contracts/0/documents/0/description,contracts/0/documents/0/url,contracts/0/documents/0/format

examples/csv/template/contracts_relatedPhases.csv

@@ -0,0 +1 @@
+id,contracts/0/id,contracts/0/relatedPhases/0/id,contracts/0/relatedPhases/0/name

examples/csv/template/links.csv

@@ -0,0 +1 @@
+id,links/0/id,links/0/name,links/0/phase/id,links/0/phase/name,links/0/status,links/0/readyForServiceDate,links/0/start,links/0/end,links/0/directed,links/0/route/type,links/0/route/coordinates,links/0/physicalInfrastructureProvider/id,links/0/physicalInfrastructureProvider/name,links/0/networkProvider/id,links/0/networkProvider/name,links/0/supplier/id,links/0/supplier/name,links/0/transmissionMedium,links/0/deployment,links/0/deploymentDetails/description,links/0/darkFibre,links/0/fibreType,links/0/fibreTypeDetails/description,links/0/fibreCount,links/0/fibreLength,links/0/technologies,links/0/capacity,links/0/capacityDetails/description,links/0/countries

examples/csv/template/networks.csv

@@ -0,0 +1 @@
+id,name,website,publisher/id,publisher/name,publisher/identifier/id,publisher/identifier/scheme,publisher/identifier/legalName,publisher/identifier/uri,publisher/country,publisher/roles,publisher/roleDetails,publisher/website,publisher/logo,publicationDate,collectionDate,crs/name,crs/uri,accuracy,accuracyDetails,language

examples/csv/template/nodes.csv

@@ -0,0 +1 @@
+id,nodes/0/id,nodes/0/name,nodes/0/phase/id,nodes/0/phase/name,nodes/0/status,nodes/0/location/type,nodes/0/location/coordinates,nodes/0/address/streetAddress,nodes/0/address/locality,nodes/0/address/region,nodes/0/address/postalCode,nodes/0/address/country,nodes/0/type,nodes/0/accessPoint,nodes/0/power,nodes/0/technologies,nodes/0/physicalInfrastructureProvider/id,nodes/0/physicalInfrastructureProvider/name,nodes/0/networkProvider/id,nodes/0/networkProvider/name

examples/csv/template/nodes_internationalConnections.csv

@@ -0,0 +1 @@
+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

examples/csv/template/organisations.csv

@@ -0,0 +1 @@
+id,organisations/0/id,organisations/0/name,organisations/0/identifier/id,organisations/0/identifier/scheme,organisations/0/identifier/legalName,organisations/0/identifier/uri,organisations/0/country,organisations/0/roles,organisations/0/roleDetails,organisations/0/website,organisations/0/logo

examples/csv/template/phases.csv

@@ -0,0 +1 @@
+id,phases/0/id,phases/0/name,phases/0/description

examples/csv/template/phases_funders.csv

@@ -0,0 +1 @@
+id,phases/0/id,phases/0/funders/0/id,phases/0/funders/0/name

examples/csv/template/relatedResources.csv

@@ -0,0 +1 @@
+id,relatedResources/0/href,relatedResources/0/rel