diff --git a/docs/reference/publication_formats.md b/docs/reference/publication_formats.md index 1500e33..f760030 100644 --- a/docs/reference/publication_formats.md +++ b/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 +``` \ No newline at end of file diff --git a/examples/csv/contracts.csv b/examples/csv/contracts.csv new file mode 100644 index 0000000..c38ca6a --- /dev/null +++ b/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 diff --git a/examples/csv/contracts_documents.csv b/examples/csv/contracts_documents.csv new file mode 100644 index 0000000..30d0a9a --- /dev/null +++ b/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 diff --git a/examples/csv/contracts_relatedPhases.csv b/examples/csv/contracts_relatedPhases.csv new file mode 100644 index 0000000..bf38581 --- /dev/null +++ b/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 diff --git a/examples/csv/links.csv b/examples/csv/links.csv new file mode 100644 index 0000000..17d2cb0 --- /dev/null +++ b/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 diff --git a/examples/csv/networks.csv b/examples/csv/networks.csv new file mode 100644 index 0000000..9f8e656 --- /dev/null +++ b/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 diff --git a/examples/csv/nodes.csv b/examples/csv/nodes.csv new file mode 100644 index 0000000..8ee44e5 --- /dev/null +++ b/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 diff --git a/examples/csv/nodes_internationalConnections.csv b/examples/csv/nodes_internationalConnections.csv new file mode 100644 index 0000000..6546dcd --- /dev/null +++ b/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 diff --git a/examples/csv/organisations.csv b/examples/csv/organisations.csv new file mode 100644 index 0000000..04397ea --- /dev/null +++ b/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 diff --git a/examples/csv/phases.csv b/examples/csv/phases.csv new file mode 100644 index 0000000..48d54c3 --- /dev/null +++ b/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. diff --git a/examples/csv/phases_funders.csv b/examples/csv/phases_funders.csv new file mode 100644 index 0000000..acac887 --- /dev/null +++ b/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 diff --git a/examples/csv/relatedResources.csv b/examples/csv/relatedResources.csv new file mode 100644 index 0000000..ae29817 --- /dev/null +++ b/examples/csv/relatedResources.csv @@ -0,0 +1 @@ +id,relatedResources/0/href,relatedResources/0/rel diff --git a/examples/csv/template/contracts.csv b/examples/csv/template/contracts.csv new file mode 100644 index 0000000..4a20e6c --- /dev/null +++ b/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 diff --git a/examples/csv/template/contracts_documents.csv b/examples/csv/template/contracts_documents.csv new file mode 100644 index 0000000..30955bf --- /dev/null +++ b/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 diff --git a/examples/csv/template/contracts_relatedPhases.csv b/examples/csv/template/contracts_relatedPhases.csv new file mode 100644 index 0000000..b60910c --- /dev/null +++ b/examples/csv/template/contracts_relatedPhases.csv @@ -0,0 +1 @@ +id,contracts/0/id,contracts/0/relatedPhases/0/id,contracts/0/relatedPhases/0/name diff --git a/examples/csv/template/links.csv b/examples/csv/template/links.csv new file mode 100644 index 0000000..2f98ab1 --- /dev/null +++ b/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 diff --git a/examples/csv/template/networks.csv b/examples/csv/template/networks.csv new file mode 100644 index 0000000..31c4bbd --- /dev/null +++ b/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 diff --git a/examples/csv/template/nodes.csv b/examples/csv/template/nodes.csv new file mode 100644 index 0000000..3822065 --- /dev/null +++ b/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 diff --git a/examples/csv/template/nodes_internationalConnections.csv b/examples/csv/template/nodes_internationalConnections.csv new file mode 100644 index 0000000..8aed12d --- /dev/null +++ b/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 diff --git a/examples/csv/template/organisations.csv b/examples/csv/template/organisations.csv new file mode 100644 index 0000000..bd69c0d --- /dev/null +++ b/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 diff --git a/examples/csv/template/phases.csv b/examples/csv/template/phases.csv new file mode 100644 index 0000000..1b8927f --- /dev/null +++ b/examples/csv/template/phases.csv @@ -0,0 +1 @@ +id,phases/0/id,phases/0/name,phases/0/description diff --git a/examples/csv/template/phases_funders.csv b/examples/csv/template/phases_funders.csv new file mode 100644 index 0000000..302d9c6 --- /dev/null +++ b/examples/csv/template/phases_funders.csv @@ -0,0 +1 @@ +id,phases/0/id,phases/0/funders/0/id,phases/0/funders/0/name diff --git a/examples/csv/template/relatedResources.csv b/examples/csv/template/relatedResources.csv new file mode 100644 index 0000000..ae29817 --- /dev/null +++ b/examples/csv/template/relatedResources.csv @@ -0,0 +1 @@ +id,relatedResources/0/href,relatedResources/0/rel