diff --git a/docs/_static/i18n.csv b/docs/_static/i18n.csv index 26a6bd93..150e918e 100644 --- a/docs/_static/i18n.csv +++ b/docs/_static/i18n.csv @@ -14,7 +14,7 @@ sector,Project sector,False, purpose,Project purpose,True, additionalClassifications,Additional classifications,False, additionalClassifications,Classification,False, -additionalClassifications/scheme,Scheme,True, +additionalClassifications/scheme,Scheme,False, additionalClassifications/id,ID,True, additionalClassifications/description,Description,True, additionalClassifications/uri,URI,False, diff --git a/docs/conf.py b/docs/conf.py index b2b5876a..4df3c67b 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -42,6 +42,7 @@ 'sphinxcontrib.jsonschema', 'sphinxcontrib.opencontracting', 'sphinxcontrib.opendataservices', + 'sphinx_design', ] # Add any paths that contain templates here, relative to this directory. @@ -85,8 +86,6 @@ smartquotes = False # MyST configuration. -# Disable dollarmath, which uses MathJax for a string like: "If Alice has $100 and Bob has $1..." -# https://myst-parser.readthedocs.io/en/latest/using/intro.html#sphinx-configuration-options myst_enable_extensions = ['linkify'] myst_heading_anchors = 6 myst_heading_slug_func = make_id diff --git a/docs/examples/example.json b/docs/examples/example.json index 66b78c1e..2ae5e1db 100644 --- a/docs/examples/example.json +++ b/docs/examples/example.json @@ -169,6 +169,13 @@ "id": "XX1234", "uri": "https://government-organisation.register.gov.uk/records/XX1234" }, + "additionalIdentifiers": [ + { + "scheme": "GB-GOV", + "legalName": "Motorways UK", + "id": "ABCDE" + } + ], "address": { "postalCode": "LL55 4NY", "countryName": "United Kingdom", @@ -401,7 +408,8 @@ "period": { "startDate": "2018-01-07T00:00:00Z", "endDate": "2018-01-07T00:00:00Z" - } + }, + "value": {} }, { "id": "2", @@ -448,7 +456,8 @@ "period": { "startDate": "2018-01-07T00:00:00Z", "endDate": "2018-01-07T00:00:00Z" - } + }, + "value": {} }, { "id": "2", @@ -481,32 +490,28 @@ ], "contractingProcesses": [ { - "id": "ocds-a1b1c1-a410a80d-adc8-11e6-9901-0019b9f3037b", + "id": "ocds-a1b1c1-c9b14c18-adc8-11e6-9901-0019b9f3037b", "summary": { - "ocid": "ocds-a1b1c1-a410a80d-adc8-11e6-9901-0019b9f3037b", - "externalReference": "2016-SMP-M75-J4_J5-design", + "ocid": "ocds-a1b1c1-c9b14c18-adc8-11e6-9901-0019b9f3037b", + "externalReference": "2016-SMP-M75-J4_J5-construction", "nature": [ - "design" + "construction" ], - "title": "Smart Motorway Design M75 J4-5", - "description": "Design of Smart Motorway upgrade M75 J4-5", + "title": "Smart Motorways Programme - Construction - Package 3 - M75 J8 - 10", + "description": "Collaborative Delivery Framework (CDF) - Lot 3B - Construction £10 to £50m", "status": "closed", "tender": { "procurementMethod": "limited", "procurementMethodDetails": "Restricted procedure", "costEstimate": { - "amount": 2000000, + "amount": 33000000, "currency": "GBP" }, - "numberOfTenderers": 2, + "numberOfTenderers": 1, "tenderers": [ { - "name": "A1 Expert Smart Moto Design", - "id": "GB-COH-11111111" - }, - { - "name": "Motorway Design Services PLC", - "id": "GB-COH-12345678" + "name": "Concrete Motorways Construction", + "id": "GB-COH-33333333" } ], "procuringEntity": { @@ -520,25 +525,25 @@ }, "suppliers": [ { - "name": "A1 Expert Smart Moto Design", - "id": "GB-COH-11111111" + "name": "Concrete Motorways Construction", + "id": "GB-COH-33333333" } ], "contractValue": { - "amount": 1950000, + "amount": 29000000, "currency": "GBP" }, "contractPeriod": { - "startDate": "2016-06-01T00:00:00Z", - "endDate": "2017-07-07T00:00:00Z" + "startDate": "2017-07-07T00:00:00Z", + "endDate": "2018-07-01T00:00:00Z" }, "finalValue": { - "amount": 1950000, + "amount": 35250000, "currency": "GBP" }, "transactions": [ { - "id": "ocds-a1b1c1-a410a80d-adc8-11e6-9901-0019b9f3037b-00001-1", + "id": "ocds-a1b1c1-c9b14c18-adc8-11e6-9901-0019b9f3037b-00001-1", "source": "https://openspending.org/motorways-uk-spending/", "date": "2017-08-07T00:00:00Z", "value": { @@ -550,76 +555,160 @@ "name": "Motorways UK" }, "payee": { - "id": "GB-COH-11111111", - "name": "A1 Expert Smart Moto Design" + "name": "Concrete Motorways Construction", + "id": "GB-COH-33333333" }, "uri": "https://openspending.org/motorways-uk-spending/transaction/xyz123" } ], "documents": [ { - "id": "a1b1c1-tender-doc-001", - "documentType": "tenderNotice", - "title": "M72 improvements at J4-5: Tender Notice", - "description": "A tender notice for the design of improvements to M75 J4-5", - "url": "https://example.com/Published/a1b1c1-design-001.html", - "datePublished": "2015-12-10T16:45:00Z", + "id": "a1b1c1-construction-excavation-report", + "documentType": "physicalProgressReport", + "title": "Report on construction excavation", + "description": "A report on the construction at Junction 5 where excavation damaged a watercourse.", + "url": "https://example.com/Published/a1b1c1-construction-monitoring.html", + "datePublished": "2018-02-01T00:00:00Z", + "dateModified": "2018-02-11T00:00:00Z", + "format": "text/html", + "language": "en", + "accessDetails": "Register for document access.", + "author": "Motorways UK" + }, + { + "id": "a1b1c1-construction-completion", + "documentType": "completionCertificate", + "title": "Completion certificate for construction at M75 J4-5 upgrade", + "description": "Completion certificate for the construction upgrading motorway M75 Junctions 4-5.", + "url": "https://example.com/Published/a1b1c1-construction-completion.html", + "datePublished": "2018-12-10T00:00:00Z", "format": "text/html", + "language": "en", + "accessDetails": "Register for document access.", "author": "Motorways UK" } + ], + "modifications": [ + { + "id": "m27-4-5-construction-modification-001", + "date": "2018-04-01T15:15:00Z", + "description": "Construction extended for 5 months", + "rationale": "Excavation damaged a watercourse. Construction extended for repairs.", + "type": "duration", + "releaseID": "ocds-a1b1c1-c9b14c18-adc8-11e6-9901-0019b9f3037b-cdfpc3b005", + "oldContractPeriod": { + "startDate": "2017-07-07T00:00:00Z", + "endDate": "2018-07-01T00:00:00Z" + }, + "newContractPeriod": { + "startDate": "2017-07-07T00:00:00Z", + "endDate": "2018-12-01T00:00:00Z" + } + }, + { + "id": "m27-4-5-construction-modification-002", + "date": "2018-04-01T15:15:00Z", + "description": "Construction scope extended to include repairing a watercourse", + "rationale": "Excavation damaged a watercourse. Construction scope extended for repairs.", + "type": "scope", + "releaseID": "ocds-a1b1c1-c9b14c18-adc8-11e6-9901-0019b9f3037b-cdfpc3b0015" + }, + { + "id": "m27-4-5-construction-modification-003", + "date": "2018-04-01T15:15:00Z", + "description": "Contract value increased from 29000000 to 35250000 to include repairing a watercourse", + "rationale": "Excavation damaged a watercourse. Construction budget extended for repairs.", + "type": "value", + "releaseID": "ocds-a1b1c1-c9b14c18-adc8-11e6-9901-0019b9f3037b-cdfpc3b0015", + "oldContractValue": { + "amount": 29000000, + "currency": "GBP" + }, + "newContractValue": { + "amount": 35250000, + "currency": "GBP" + } + } ] }, "releases": [ { - "id": "ocds-cdf-pc10008", - "date": "2016-04-01T00:00:00Z", + "id": "ocds-a1b1c1-c9b14c18-adc8-11e6-9901-0019b9f3037b-cdfpc3b0011", + "date": "2015-09-16T15:12:32Z", "tag": [ "tender" ], - "url": "https://www.example.com/releases/ocds-cdf-pc10008.json" + "url": "https://example.com/Published/releases/5553-b55.json" }, { - "id": "ocds-cdf-pc10009", - "date": "2016-06-01T15:49:19Z", + "id": "ocds-a1b1c1-c9b14c18-adc8-11e6-9901-0019b9f3037b-cdfpc3b0012", + "date": "2015-12-16T15:15:00Z", "tag": [ "award" ], - "url": "https://www.example.com/releases/ocds-cdf-pc10009.json" + "url": "https://example.com/Published/releases/5553-b56.json" }, { - "id": "ocds-cdf-pc10010", - "date": "2017-08-17T00:00:00Z", + "id": "ocds-a1b1c1-c9b14c18-adc8-11e6-9901-0019b9f3037b-cdfpc3b0013", + "date": "2015-12-16T15:15:00Z", + "tag": [ + "contract" + ], + "url": "https://example.com/Published/releases/5553-b57.json" + }, + { + "id": "ocds-a1b1c1-c9b14c18-adc8-11e6-9901-0019b9f3037b-cdfpc3b0014", + "date": "2015-12-16T15:15:00Z", + "tag": [ + "implementation" + ], + "url": "https://example.com/Published/releases/5553-b58.json" + }, + { + "id": "ocds-a1b1c1-c9b14c18-adc8-11e6-9901-0019b9f3037b-cdfpc3b0015", + "date": "2018-04-01T15:15:00Z", + "tag": [ + "implementationUpdate" + ], + "url": "https://example.com/Published/releases/5553-b59.json" + }, + { + "id": "ocds-a1b1c1-c9b14c18-adc8-11e6-9901-0019b9f3037b-cdfpc3b0016", + "date": "2018-12-10T09:15:00Z", "tag": [ - "implementation", "contractTermination" ], - "url": "https://www.example.com/releases/ocds-cdf-pc10010.json" + "url": "https://example.com/Published/releases/5553-b60.json" } ] }, { - "id": "ocds-a1b1c1-370ad85a-097f-4b8c-adf8-09d840c7c48b", + "id": "ocds-a1b1c1-a410a80d-adc8-11e6-9901-0019b9f3037b", "summary": { - "ocid": "ocds-a1b1c1-370ad85a-097f-4b8c-adf8-09d840c7c48b", - "externalReference": "2016-SMP-M75-J4_J5-supervision", + "ocid": "ocds-a1b1c1-a410a80d-adc8-11e6-9901-0019b9f3037b", + "externalReference": "2016-SMP-M75-J4_J5-design", "nature": [ - "supervision" + "design" ], - "title": "Commercial Management and Assurance for the Motorways Upgrade Programme M75 J4-5", - "description": "Specialist Professional and Technical Services Framework: Commercial Management and Assurance for the Motorways Upgrade Programme M75 J4-5", + "title": "Smart Motorway Design M75 J4-5", + "description": "Design of Smart Motorway upgrade M75 J4-5", "status": "closed", "tender": { "procurementMethod": "limited", - "procurementMethodDetails": "Framework", + "procurementMethodDetails": "Restricted procedure", "costEstimate": { - "amount": 5000000, + "amount": 2000000, "currency": "GBP" }, - "numberOfTenderers": 1, + "numberOfTenderers": 2, "tenderers": [ { - "name": "Expert Motorway Supervisors", - "id": "GB-COH-22222222" + "name": "A1 Expert Smart Moto Design", + "id": "GB-COH-11111111" + }, + { + "name": "Motorway Design Services PLC", + "id": "GB-COH-12345678" } ], "procuringEntity": { @@ -633,92 +722,86 @@ }, "suppliers": [ { - "name": "Expert Motorway Supervisors", - "id": "GB-COH-22222222" + "name": "A1 Expert Smart Moto Design", + "id": "GB-COH-11111111" } ], "contractValue": { - "amount": 4900000, + "amount": 1950000, "currency": "GBP" }, "contractPeriod": { - "startDate": "2017-02-24T00:00:00Z", - "endDate": "2018-10-10T00:00:00Z" + "startDate": "2016-06-01T00:00:00Z", + "endDate": "2017-07-07T00:00:00Z" }, "finalValue": { - "amount": 4900000, + "amount": 1950000, "currency": "GBP" }, "documents": [ { - "id": "a1b1c1-spats-2-033-completion", - "documentType": "completionCertificate", - "title": "Completion Certificate for supervision", - "description": "A completion certificate for Expert Motorway Supervisors supervision of M75 J4-5", - "url": "https://example.com/Published/a1b1c1-spats-2-033-completion.html", - "datePublished": "2018-12-10T16:45:00Z", - "format": "text/html" + "id": "a1b1c1-tender-doc-001", + "documentType": "tenderNotice", + "title": "M72 improvements at J4-5: Tender Notice", + "description": "A tender notice for the design of improvements to M75 J4-5", + "url": "https://example.com/Published/a1b1c1-design-001.html", + "datePublished": "2015-12-10T16:45:00Z", + "format": "text/html", + "author": "Motorways UK" } ] }, "releases": [ { - "id": "ocds-a1b1c1-spats-2-033e", - "date": "2017-03-02T17:14:37Z", + "id": "ocds-cdf-pc10008", + "date": "2016-04-01T00:00:00Z", "tag": [ "tender" ], - "url": "https://example.com/releases/ex-a1b1c1--033e.json" + "url": "https://www.example.com/releases/ocds-cdf-pc10008.json" }, { - "id": "ocds-a1b1c1-spats-2-033f", - "date": "2017-05-02T17:14:37Z", + "id": "ocds-cdf-pc10009", + "date": "2016-06-01T15:49:19Z", "tag": [ "award" ], - "url": "https://example.com/releases/ex-a1b1c1--033f.json" - }, - { - "id": "ocds-a1b1c1-spats-2-033g", - "date": "2017-07-02T17:14:37Z", - "tag": [ - "implementation" - ], - "url": "https://example.com/Published/releases/ex-a1b1c1--033g.json" + "url": "https://www.example.com/releases/ocds-cdf-pc10009.json" }, { - "id": "ocds-a1b1c1-spats-2-033h", - "date": "2018-12-10T14:45:00Z", + "id": "ocds-cdf-pc10010", + "date": "2017-08-17T00:00:00Z", "tag": [ + "implementation", "contractTermination" ], - "url": "https://example.com/releases/ex-a1b1c1--033h.json" + "url": "https://www.example.com/releases/ocds-cdf-pc10010.json" } ] }, { - "id": "ocds-a1b1c1-c9b14c18-adc8-11e6-9901-0019b9f3037b", + "id": "ocds-a1b1c1-370ad85a-097f-4b8c-adf8-09d840c7c48b", "summary": { - "ocid": "ocds-a1b1c1-c9b14c18-adc8-11e6-9901-0019b9f3037b", - "externalReference": "2016-SMP-M75-J4_J5-construction", + "ocid": "ocds-a1b1c1-370ad85a-097f-4b8c-adf8-09d840c7c48b", + "externalReference": "2016-SMP-M75-J4_J5-supervision", "nature": [ - "construction" + "supervision" ], - "title": "Smart Motorways Programme - Construction - Package 3 - M75 J8 - 10", - "description": "Collaborative Delivery Framework (CDF) - Lot 3B - Construction £10 to £50m", + "title": "Commercial Management and Assurance for the Motorways Upgrade Programme M75 J4-5", + "description": "Specialist Professional and Technical Services Framework: Commercial Management and Assurance for the Motorways Upgrade Programme M75 J4-5", "status": "closed", "tender": { "procurementMethod": "limited", - "procurementMethodDetails": "Restricted procedure", + "procurementMethodDetails": "Framework", "costEstimate": { - "amount": 33000000, + "amount": 5000000, "currency": "GBP" }, "numberOfTenderers": 1, "tenderers": [ { - "name": "Concrete Motorways Construction", - "id": "GB-COH-33333333" + "name": "Expert Motorway Supervisors", + "id": "GB-COH-22222222" } ], "procuringEntity": { @@ -732,140 +815,66 @@ }, "suppliers": [ { - "name": "Concrete Motorways Construction", - "id": "GB-COH-33333333" + "name": "Expert Motorway Supervisors", + "id": "GB-COH-22222222" } ], "contractValue": { - "amount": 29000000, + "amount": 4900000, "currency": "GBP" }, "contractPeriod": { - "startDate": "2017-07-07T00:00:00Z", - "endDate": "2018-07-01T00:00:00Z" + "startDate": "2017-02-24T00:00:00Z", + "endDate": "2018-10-10T00:00:00Z" }, "finalValue": { - "amount": 35250000, + "amount": 4900000, "currency": "GBP" }, "documents": [ { - "id": "a1b1c1-construction-excavation-report", - "documentType": "physicalProgressReport", - "title": "Report on construction excavation", - "description": "A report on the construction at Junction 5 where excavation damaged a watercourse.", - "url": "https://example.com/Published/a1b1c1-construction-monitoring.html", - "datePublished": "2018-02-01T00:00:00Z", - "dateModified": "2018-02-11T00:00:00Z", - "format": "text/html", - "language": "en", - "accessDetails": "Register for document access.", - "author": "Motorways UK" - }, - { - "id": "a1b1c1-construction-completion", + "id": "a1b1c1-spats-2-033-completion", "documentType": "completionCertificate", - "title": "Completion certificate for construction at M75 J4-5 upgrade", - "description": "Completion certificate for the construction upgrading motorway M75 Junctions 4-5.", - "url": "https://example.com/Published/a1b1c1-construction-completion.html", - "datePublished": "2018-12-10T00:00:00Z", - "format": "text/html", - "language": "en", - "accessDetails": "Register for document access.", - "author": "Motorways UK" - } - ], - "modifications": [ - { - "id": "m27-4-5-construction-modification-001", - "date": "2018-04-01T15:15:00Z", - "description": "Construction extended for 5 months", - "rationale": "Excavation damaged a watercourse. Construction extended for repairs.", - "type": "duration", - "releaseID": "ocds-a1b1c1-c9b14c18-adc8-11e6-9901-0019b9f3037b-cdfpc3b005", - "oldContractPeriod": { - "startDate": "2017-07-07T00:00:00Z", - "endDate": "2018-07-01T00:00:00Z" - }, - "newContractPeriod": { - "startDate": "2017-07-07T00:00:00Z", - "endDate": "2018-12-01T00:00:00Z" - } - }, - { - "id": "m27-4-5-construction-modification-002", - "date": "2018-04-01T15:15:00Z", - "description": "Construction scope extended to include repairing a watercourse", - "rationale": "Excavation damaged a watercourse. Construction scope extended for repairs.", - "type": "scope", - "releaseID": "ocds-a1b1c1-c9b14c18-adc8-11e6-9901-0019b9f3037b-cdfpc3b0015" - }, - { - "id": "m27-4-5-construction-modification-003", - "date": "2018-04-01T15:15:00Z", - "description": "Contract value increased from 29000000 to 35250000 to include repairing a watercourse", - "rationale": "Excavation damaged a watercourse. Construction budget extended for repairs.", - "type": "value", - "releaseID": "ocds-a1b1c1-c9b14c18-adc8-11e6-9901-0019b9f3037b-cdfpc3b0015", - "oldContractValue": { - "amount": 29000000, - "currency": "GBP" - }, - "newContractValue": { - "amount": 35250000, - "currency": "GBP" - } + "title": "Completion Certificate for supervision", + "description": "A completion certificate for Expert Motorway Supervisors supervision of M75 J4-5", + "url": "https://example.com/Published/a1b1c1-spats-2-033-completion.html", + "datePublished": "2018-12-10T16:45:00Z", + "format": "text/html" } ] }, "releases": [ { - "id": "ocds-a1b1c1-c9b14c18-adc8-11e6-9901-0019b9f3037b-cdfpc3b0011", - "date": "2015-09-16T15:12:32Z", + "id": "ocds-a1b1c1-spats-2-033e", + "date": "2017-03-02T17:14:37Z", "tag": [ "tender" ], - "url": "https://example.com/Published/releases/5553-b55.json" + "url": "https://example.com/releases/ex-a1b1c1--033e.json" }, { - "id": "ocds-a1b1c1-c9b14c18-adc8-11e6-9901-0019b9f3037b-cdfpc3b0012", - "date": "2015-12-16T15:15:00Z", + "id": "ocds-a1b1c1-spats-2-033f", + "date": "2017-05-02T17:14:37Z", "tag": [ "award" ], - "url": "https://example.com/Published/releases/5553-b56.json" - }, - { - "id": "ocds-a1b1c1-c9b14c18-adc8-11e6-9901-0019b9f3037b-cdfpc3b0013", - "date": "2015-12-16T15:15:00Z", - "tag": [ - "contract" - ], - "url": "https://example.com/Published/releases/5553-b57.json" + "url": "https://example.com/releases/ex-a1b1c1--033f.json" }, { - "id": "ocds-a1b1c1-c9b14c18-adc8-11e6-9901-0019b9f3037b-cdfpc3b0014", - "date": "2015-12-16T15:15:00Z", + "id": "ocds-a1b1c1-spats-2-033g", + "date": "2017-07-02T17:14:37Z", "tag": [ "implementation" ], - "url": "https://example.com/Published/releases/5553-b58.json" - }, - { - "id": "ocds-a1b1c1-c9b14c18-adc8-11e6-9901-0019b9f3037b-cdfpc3b0015", - "date": "2018-04-01T15:15:00Z", - "tag": [ - "implementationUpdate" - ], - "url": "https://example.com/Published/releases/5553-b59.json" + "url": "https://example.com/Published/releases/ex-a1b1c1--033g.json" }, { - "id": "ocds-a1b1c1-c9b14c18-adc8-11e6-9901-0019b9f3037b-cdfpc3b0016", - "date": "2018-12-10T09:15:00Z", + "id": "ocds-a1b1c1-spats-2-033h", + "date": "2018-12-10T14:45:00Z", "tag": [ "contractTermination" ], - "url": "https://example.com/Published/releases/5553-b60.json" + "url": "https://example.com/releases/ex-a1b1c1--033h.json" } ] } diff --git a/docs/guidance/example.md b/docs/guidance/example.md index b9507d96..68fe17a5 100644 --- a/docs/guidance/example.md +++ b/docs/guidance/example.md @@ -1,191 +1,31 @@ -# Worked example +# Examples -The [OC4IDS schema](../../reference/index) sets out the structure and format of an OC4IDS JSON file. +This page provides examples to help you understand and implement OC4IDS. There are two examples: -This worked example is a filled-in example OC4IDS JSON file representing a fictional, completed infrastructure project to upgrade a motorway in the UK. +## Worked example -The full OC4IDS JSON file for the worked example is [available to download](../examples/example.json). +The worked example is a JSON file that conforms to the [project package schema](../reference/package). It contains a single project that conforms to the [project schema](../reference/schema). You can view the complete worked example below or [download the JSON file](../examples/example.json). You can also view excerpts from the worked example alongside each sub-schema in the [schema reference documentation](../reference/schema). -```{tip} -You can also download a [blank example OC4IDS JSON file](../examples/blank.json) as a starting point for your implementation. -``` - -This page contains excerpts from the example JSON file, showing how key sections of the schema ought to be populated. - -## Overview - -An OC4IDS document is made up of a number of sections. These include: - -* **Project package** - a container for the data of multiple projects, as well as metadata about the publication. -* **Project data** - for each project including: - * **Project metadata** - contextual information about the project such as title, description, location and status. - * **Budget** - information about the projected costs or allocated budget for the project. - * **Parties** - information about the organizations and other participants involved in the project. - * **Documents** - documents and documentation relating to the project. - * **Contracting processes** - information about related contracting processes for different aspects of the project. - * **Completion** - information on the final scope, duration and costs for the project. +The worked example describes a fictional infrastructure project to upgrade a motorway in the UK with three related contracting processes. An example value is provided for each field in the schema, including: -## Sections +* [`forecasts`](project-schema.json,,forecasts) and [`metrics`](project-schema.json,,metrics) that describe planned and actual physical progress +* [`modifications`](project-schema.json,,metrics) that describe changes to the duration, scope and value of contracting processes +* [`completion`](project-schema.json,,completion) data, describing the final end date, value and scope of the project. -### Project package - -The project package serves as a container for the data of multiple projects, through its `projects` array. It also provides metadata concerning all the data it contains, including the publisher, schema version, data license and publication policy. - -```{jsoninclude} ../examples/example.json +```{jsoninclude} ../../docs/examples/example.json :jsonpointer: -:expand: publisher -:title: package +:title: Worked example ``` -#### License - -The `license` field ought to contain a link to the license that applies to the data in the package. Further information about licensing can be found in the [OCDS licensing guidance](https://standard.open-contracting.org/1.1/en/implementation/licensing/). - -#### Publication policy +## Blank example -The `publicationPolicy` field ought to contain a link to a data user guide. For more information about what to include in a publication policy, refer to [Data user guide](data_user_guide). +The blank example is a JSON file that conforms to the structure of the [project schema](../reference/schema). You can view the blank example below or [download the JSON file](../examples/blank.json). Field values are replaced with either: -### Project information +* Empty strings (`""`) or empty arrays (`[]`) +* The type of the field, e.g. "string" or "array" +* The name of the codelist referenced by the field, e.g. "string from currency codelist" -A project package can contain information about multiple infrastructure projects. Each infrastructure project is represented as an entry in the `projects` array. The example contains information about one infrastructure project. - -```{jsoninclude} ../examples/example.json +```{jsoninclude} ../../docs/examples/blank.json :jsonpointer: -:expand: projects -:exclude: version, uri, publishedDate, publisher, license, publicationPolicy -:title: projects -``` - -Each project object contains the following sections: - -#### Project metadata - -This section provides contextual information about the infrastructure project, including: - -* `id` for the project identifier. To make the project identifier globally unique, a project identifier prefix needs to be added to a local identifier for the project. Project identifier prefixes are assigned by the OC4IDS Helpdesk. For more information on project identifiers, refer to the [project identifiers guidance](identifiers.md#project-identifier-prefixes). - -* `status` from the [Project Status codelist](../reference/codelists.md#projectstatus). In this example, the project status is 'completed'. - -* `type` from the [Project Type codelist](../reference/codelists.md#projecttype). In this example, the project type is 'expansion'. - -* `sector` from the [Project Sector codelist](../reference/codelists.md#projectsector). In this example, the sector is 'transport.road', the parent sector 'transport' is also included in the sector list, in line with the guidance in the schema. - -* one or more `relatedProjects`, to reference other projects that are related to the same set of infrastructure assets, as [outlined in the schema reference](../reference/schema.md#relatedproject). In the relatedProject example below, a reference is made to the original project that initially constructed the motorway junctions, which are now being upgraded by this project. - -* one or more `locations`, which can be expressed in a variety of ways as [outlined in the schema reference](../reference/schema.md#location). In this example, one location is given: a motorway junction, using a point location, a gazetteer entry and an address. - -```{jsoninclude} ../examples/example.json -:jsonpointer: /projects/0/relatedProjects -:title: relatedProject -``` - -```{jsoninclude} ../examples/example.json -:jsonpointer: /projects/0/locations -:expand: geometry, gazetteer, address -:title: location -``` - -#### Budget and budget breakdown - -The `budget` section can be used to provide the overall budget for the project, and its `budgetBreakdown` array can be used to provide a breakdown of the budget by period and/or funding source. - -In the budget example below, the overall budget for the infrastructure project covers 3 years and is broken down into amounts per year, with £10,000,000 allocated in 2016 – as highlighted in the budgetBreakdown example. - - ```{jsoninclude} ../examples/example.json -:jsonpointer: /projects/0/budget -:expand: amount -:title: budget -``` - - ```{jsoninclude} ../examples/example.json -:jsonpointer: /projects/0/budget/budgetBreakdown/0 -:expand: amount, period, sourceParty -:title: budgetBreakdown -``` - -#### Parties (organizations) - -The `parties` array is used to provide details about organizations involved in the infrastructure project and their roles. Organization references elsewhere in the data refer back to entries in this section. - -In the party example below, details are given about the fictional Motorways UK entity, which is referred to from the `sourceParty` section in the `budgetBreakdown` example above, using the `name` and `id` from the entry in the `parties` array. - -```{jsoninclude} ../examples/example.json -:jsonpointer: /projects/0/parties/0 -:expand: address, contactPoint, roles -:title: party -``` - -#### Public authority - -The `publicAuthority` field indicates the project owner: the unit, body or department within a government that is tendering and contracting the project. It refers to an entry in the `parties` array, as described above. - -```{jsoninclude} ../examples/example.json -:jsonpointer: /projects/0/publicAuthority -:title: publicAuthority -``` - -#### Documents - -The `documents` array is used to provide information and links to documents and documentation relating to the infrastructure project. During different phases of the project, different document types are expected. - -In the document example below, an environmental impact assessment is provided. The `documentType` field is used to categorize the document against the [Document Type codelist](../reference/codelists.md#documenttype). - -```{jsoninclude} ../examples/example.json -:jsonpointer: /projects/0/documents/1 -:expand: address, contactPoint, roles -:title: document -``` - -#### Forecasts and metrics - -Publish structured data on planned and actual physical and financial progress using `Metric` objects in the `forecasts` (planned progress) and `metrics` (actual progress) arrays. Refer to the [implementation progress reports documentation](../cost/index.md#implementation-progress-reports) for further detail. - -In the example below, you can compare the planned `forecasts/observations` for 75% of physical progress completed with the actual `metrics/observations` for 75% of physical progress completed (note the difference in `period`). - -```{jsoninclude} ../examples/example.json -:jsonpointer: /projects/0/forecasts/0/observations/1 -:expand: unit, period -:title: forecast_observation -``` - -```{jsoninclude} ../examples/example.json -:jsonpointer: /projects/0/metrics/0/observations/1 -:expand: unit, period -:title: metric_observation -``` - -#### Contracting processes - -The `contractingProcesses` array is used to provide information about each contracting process associated with the project, including summary information, a list of `modifications` and a list of OCDS `releases`. - -In the contractingProcess example below, information is given about a contracting process for the design of the motorway upgrade, with one related document in the `documents` array (a tender notice) and two related OCDS `releases` (one for the tender and one for the contract award). - -```{jsoninclude} ../examples/example.json -:jsonpointer: /projects/0/contractingProcesses/0 -:expand: summary, documents, releases -:title: contractingProcess -``` - -##### Modifications - -Each contracting process includes a `modifications` array which is used to list any changes to the duration, price, scope or other significant aspect of the contracting process. - -In the modification example below, a change in duration is shown, using the `oldContractPeriod` and `newContractPeriod` fields. - -```{jsoninclude} ../examples/example.json -:jsonpointer: /projects/0/contractingProcesses/2/summary/modifications/0 -:expand: oldContractPeriod, newContractPeriod -:title: modification -``` - -#### Completion - -The `completion` section provides final details of the scope, duration and cost for the project. - -Since in this example there were variations to related contracting processes, the `finalValue` of the project exceeds its original planned budget. - -```{jsoninclude} ../examples/example.json -:jsonpointer: /projects/0/completion -:expand: finalValue -:title: Completion +:title: Blank example ``` diff --git a/docs/reference/changelog.md b/docs/reference/changelog.md index 81af17e2..4ee6e05d 100644 --- a/docs/reference/changelog.md +++ b/docs/reference/changelog.md @@ -10,6 +10,7 @@ * [#355](https://github.com/open-contracting/infrastructure/pull/355) - use correct normative and non-normative keywords in documentation. * [#362](https://github.com/open-contracting/infrastructure/pull/362) - add guidance on publishing in your own language. * [#371](https://github.com/open-contracting/infrastructure/pull/371) - add link to field level mapping template tutorial. +* [#370](https://github.com/open-contracting/infrastructure/pull/370) - improve schema reference documentation and integrate worked example. ### Schema diff --git a/docs/reference/index.md b/docs/reference/index.md index 090289bc..2bf00abf 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -2,13 +2,13 @@ The Open Contracting for Infrastructure Data Standard (OC4IDS) provides a common approach for the disclosure of structured data on infrastructure projects and their related contracting processes. -OC4IDS comprises a schema file and codelist files, and reference documentation is available for the [schema](schema) and [codelists](codelists). +OC4IDS comprises a [schema](schema) and [codelists](codelists). The schema sets out the fields, structure, data types and validation rules for OC4IDS data. Some schema fields refer to codelists, to limit and standardize the possible values of the fields, in order to promote data interoperability. The schema can be explored using the [schema browser](browser) and can be [downloaded here](../../build/current_lang/project-schema.json). The schema is expressed using [JSON Schema, draft 4](https://tools.ietf.org/html/draft-zyp-json-schema-04). OC4IDS data must be published as part of a [project package](package), which serves as a container for data on multiple projects and adds important metadata about the data publication. -The OC4IDS schema reuses many of the building blocks from the Open Contracting Data Standard; these are introduced in the [Getting Started section of the OCDS documentation](https://standard.open-contracting.org/1.1/en/getting_started/). +The OC4IDS schema reuses many fields and structures from the [Open Contracting Data Standard](https://standard.open-contracting.org). ```{toctree} :maxdepth: 1 diff --git a/docs/reference/schema.md b/docs/reference/schema.md index b21b7c56..4f30ad1d 100644 --- a/docs/reference/schema.md +++ b/docs/reference/schema.md @@ -6,102 +6,700 @@ } -The tables below describe each of the fields and objects in OC4IDS. To see how they fit together, consult the [schema browser](browser). +This page presents the fields in the OC4IDS schema in tables with additional information in paragraphs. Required fields are indicated in the **Required** column. + +For fields that reference a sub-schema, a link is provided to a table with details of the sub-schema. To see how the fields and sub-schemas fit together, consult the [schema browser](browser). + +**Examples** are provided for each table, showing how to represent the fields in the table in JSON format. For more information on the examples, see [examples](../guidance/example). ## Project -```{jsonschema} ../../build/current_lang/project-schema.json +The top-level object in OC4IDS is a project. + +A project is defined as: + +> The development of a set of infrastructure assets in a specified location, generally the responsibility of a single procuring entity and budget authority: for example, a highway overpass or a university campus. + +A project's fields include: + + * Metadata, such as the project's `title`, `description` and `status`. + * Budget data, which describes the projected costs or allocated budget for the project. + * Data about the parties (organizations and other participants) involved in the project. + * Links to documents relating to the project, such as needs assessments and project evaluations. + * Data about contracting processes for different aspects of the project, such as design, construction and supervision. + * Completion data, such as the final scope, duration and costs for the project. + +Each project has the following fields. + +`````{tab-set} + +````{tab-item} Schema + +```{jsonschema} ../../schema/project-level/project-schema.json :include: -:collapse: period,assetLifetime,sector,additionalClassifications,locations,budget/amount,budget/budgetBreakdown,parties,documents,contractingProcesses,relatedProjects +:collapse: period,additionalClassifications,relatedProjects,assetLifetime,locations,budget/amount,budget/budgetBreakdown,forecasts,parties,publicAuthority,documents,contractingProcesses,metrics,completion/finalValue +:addtargets: ``` +```` -## ContractingProcess +````{tab-item} Examples -```{jsonschema} ../../build/current_lang/project-schema.json -:include: +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0 +:title: Project +``` + +```` + +````` + +## Sub-schemas + +This section lists each sub-schema in the OC4IDS schema. Sub-schemas are parts of the schema that are represented as objects in OC4IDS data. Some sub-schemas are referenced from multiple places in the schema. + +### ContractingProcess +`ContractingProcess` is defined as: + +```{field-description} ../../schema/project-level/project-schema.json /definitions/ContractingProcess +``` + +This sub-schema is referenced by the following properties: +* [`contractingProcesses`](project-schema.json,,contractingProcesses) + +Each `ContractingProcess` has the following fields: + +`````{tab-set} + +````{tab-item} Schema + +```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/ContractingProcess -:collapse: releases,summary +:collapse: id,summary,releases +:addtargets: ``` -## ContractingProcessSummary +```` -```{jsonschema} ../../build/current_lang/project-schema.json -:include: +````{tab-item} Examples + +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/contractingProcesses +:title: contractingProcesses +``` + +```` + +````` + +### ContractingProcessSummary +`ContractingProcessSummary` is defined as: + +```{field-description} ../../schema/project-level/project-schema.json /definitions/ContractingProcessSummary +``` + +This sub-schema is referenced by the following properties: +* [`ContractingProcess/summary`](project-schema.json,/definitions/ContractingProcess,summary) + +Each `ContractingProcessSummary` has the following fields: + +`````{tab-set} + +````{tab-item} Schema + +```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/ContractingProcessSummary -:collapse: documents +:collapse: ocid,externalReference,nature,title,description,status,suppliers,contractValue,contractPeriod,finalValue,documents,modifications,transactions +:addtargets: ``` -## LinkedRelease +```` -```{jsonschema} ../../build/current_lang/project-schema.json -:include: +````{tab-item} Examples + +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/contractingProcesses/0/summary +:title: contractingProcesses/0/summary +``` + +```` + +````` + +### LinkedRelease +`LinkedRelease` is defined as: + +```{field-description} ../../schema/project-level/project-schema.json /definitions/LinkedRelease +``` + +This sub-schema is referenced by the following properties: +* [`ContractingProcess/releases`](project-schema.json,/definitions/ContractingProcess,releases) + +Each `LinkedRelease` has the following fields: + +`````{tab-set} + +````{tab-item} Schema + +```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/LinkedRelease +:collapse: id,tag,date,url +:addtargets: ``` -## Components +```` -### Address +````{tab-item} Examples + +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/contractingProcesses/0/releases +:title: contractingProcesses/0/releases +``` -We use properties from schema.org and vCard for address components. In the event source data cannot be broken down into these parts, data SHOULD contain at least a streetAddress value and postal code. +```` -When working with data, users ought to be aware that addresses might not always be broken down using all the properties the specification provides. +````` -```{jsonschema} ../../build/current_lang/project-schema.json -:pointer: /definitions/Address -:include: -:collapse: +### Modification + +`Modification` is defined as: + +```{field-description} ../../schema/project-level/project-schema.json /definitions/Modification ``` -### BudgetBreakdown +This sub-schema is referenced by the following properties: +* [`ContractingProcessSummary/modifications`](project-schema.json,/definitions/ContractingProcessSummary,modifications) -A budget breakdown is provided through an array of `BudgetBreakdown` objects, each of which represents budget for a particular period, from a particular source, or a combination of the two. +Each `Modification` has the following fields: -See the [documentation of the OCDS Budget Breakdown extension](https://extensions.open-contracting.org/en/extensions/budget/master/) for more details of this data model. BudgetBreakdown can also be extended further to include budget classifications data following the pattern described in the [OCDS Budgets and Spend extension](https://extensions.open-contracting.org/en/extensions/budget_and_spend/master/). +`````{tab-set} -```{jsonschema} ../../build/current_lang/project-schema.json -:pointer: /definitions/BudgetBreakdown -:include: -:collapse: +````{tab-item} Schema + +```{jsonschema} ../../schema/project-level/project-schema.json +:pointer: /definitions/Modification +:collapse: id,date,description,rationale,type,releaseID,oldContractValue,newContractValue,oldContractPeriod,newContractPeriod +:addtargets: +``` + +```` + +````{tab-item} Examples + +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/contractingProcesses/0/summary/modifications +:title: contractingProcesses/0/summary/modifications +``` + +```` + +````` + +### Period + +Dates MUST be expressed using a full ISO 8601 date-time including a timezone. E.g.: + +> 2018-09-18T11:26:04+01:00 + +Where the source system does not contain time information, a judgment ought to be made as to the relevant time to attach (e.g. start of the day; end of the working day etc.). + +`Period` is defined as: + +```{field-description} ../../schema/project-level/project-schema.json /definitions/Period +``` + +This sub-schema is referenced by the following properties: +* [`period`](project-schema.json,,period) +* [`assetLifetime`](project-schema.json,,assetLifetime) +* [`ContractingProcessSummary/contractPeriod`](project-schema.json,/definitions/ContractingProcessSummary,contractPeriod) +* [`Modification/oldContractPeriod`](project-schema.json,/definitions/Modification,oldContractPeriod) +* [`Modification/newContractPeriod`](project-schema.json,/definitions/Modification,newContractPeriod) +* [`BudgetBreakdown/period`](project-schema.json,/definitions/BudgetBreakdown,period) +* [`Observation/period`](project-schema.json,/definitions/Observation,period) + +Each `Period` has the following fields: + +`````{tab-set} + +````{tab-item} Schema + +```{jsonschema} ../../schema/project-level/project-schema.json +:pointer: /definitions/Period +:collapse: startDate,endDate,maxExtentDate,durationInDays +:addtargets: +``` + +```` + +````{tab-item} Examples + +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/period +:title: period +``` + +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/assetLifetime +:title: assetLifetime +``` + +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/budget/budgetBreakdown/0/period +:title: budget/budgetBreakdown/0/period +``` + +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/forecasts/0/observations/0/period +:title: forecasts/0/observations/0/period +``` + +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/contractingProcesses/0/summary/contractPeriod +:title: contractingProcesses/0/summary/contractPeriod +``` + +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/contractingProcesses/0/summary/modifications/0/oldContractPeriod +:title: contractingProcesses/0/summary/modifications/0/oldContractPeriod +``` + +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/contractingProcesses/0/summary/modifications/0/newContractPeriod +:title: contractingProcesses/0/summary/modifications/0/newContractPeriod +``` + +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/metrics/0/observations/0/period +:title: metrics/0/observations/0/period ``` +```` + +````` + ### Classification -A classification consists of an identifier for the codelist (the `scheme`) and a code from that codelist (the `id`), and then a human-readable label for the classification (the `description`). +`Classification` is defined as: + +```{field-description} ../../schema/project-level/project-schema.json /definitions/Classification +``` + +This sub-schema is referenced by the following properties: +* [`additionalClassifications`](project-schema.json,,additionalClassifications) + +Each `Classification` has the following fields: -```{jsonschema} ../../build/current_lang/project-schema.json +`````{tab-set} + +````{tab-item} Schema + +```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/Classification -:include: -:collapse: +:collapse: scheme,id,description,uri +:addtargets: ``` -For example: +```` -```json -{ - "scheme":"COFOG", - "id":"05.2", - "description":"Waste water management" -} +````{tab-item} Examples + +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/additionalClassifications +:title: additionalClassifications +``` + +```` + +````` + +### Location + +`Location` is defined as: + +```{field-description} ../../schema/project-level/project-schema.json /definitions/Location +``` + +This sub-schema is referenced by the following properties: +* [`locations`](project-schema.json,,locations) + +Each `Location` has the following fields: + +`````{tab-set} + +````{tab-item} Schema + +```{jsonschema} ../../schema/project-level/project-schema.json +:pointer: /definitions/Location +:collapse: id,description,uri,address +:addtargets: +``` + +```` + +````{tab-item} Examples + +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/locations +:title: locations +``` + +```` + +````` + +### Value + +`Value` is defined as: + +```{field-description} ../../schema/project-level/project-schema.json /definitions/Value ``` +This sub-schema is referenced by the following properties: +* [`budget/amount`](project-schema.json,,budget/amount) +* [`completion/finalValue`](project-schema.json,,completion/finalValue) +* [`ContractingProcessSummary/tender/costEstimate`](project-schema.json,/definitions/ContractingProcessSummary,tender/costEstimate) +* [`ContractingProcessSummary/contractValue`](project-schema.json,/definitions/ContractingProcessSummary,contractValue) +* [`ContractingProcessSummary/finalValue`](project-schema.json,/definitions/ContractingProcessSummary,finalValue) +* [`Modification/oldContractValue`](project-schema.json,/definitions/Modification,oldContractValue) +* [`Modification/newContractValue`](project-schema.json,/definitions/Modification,newContractValue) +* [`BudgetBreakdown/amount`](project-schema.json,/definitions/BudgetBreakdown,amount) +* [`Observation/value`](project-schema.json,/definitions/Observation,value) +* [`Transaction/value`](project-schema.json,/definitions/Transaction,value) + +Each `Value` has the following fields: + +`````{tab-set} + +````{tab-item} Schema + +```{jsonschema} ../../schema/project-level/project-schema.json +:pointer: /definitions/Value +:collapse: amount,currency +:addtargets: +``` + +```` + +````{tab-item} Examples + +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/budget/amount +:title: budget/amount +``` + +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/budget/budgetBreakdown/0/amount +:title: budget/budgetBreakdown/0/amount +``` + +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/contractingProcesses/0/summary/tender/costEstimate +:title: contractingProcesses/0/summary/tender/costEstimate +``` + +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/contractingProcesses/0/summary/contractValue +:title: contractingProcesses/0/summary/contractValue +``` + +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/contractingProcesses/0/summary/finalValue +:title: contractingProcesses/0/summary/finalValue +``` + +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/contractingProcesses/0/summary/modifications/2/oldContractValue +:title: contractingProcesses/0/summary/modifications/0/oldContractValue +``` + +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/contractingProcesses/0/summary/modifications/2/newContractValue +:title: contractingProcesses/0/summary/modifications/0/newContractValue +``` + +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/contractingProcesses/0/summary/transactions/0/value +:title: contractingProcesses/0/summary/transactions/0/value +``` + +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/completion/finalValue +:title: completion/finalValue +``` + +```` + +````` + +### Organization + +`Organization` is defined as: + +```{field-description} ../../schema/project-level/project-schema.json /definitions/Organization +``` + +This sub-schema is referenced by the following properties: +* [`parties`](project-schema.json,,parties) + +Each `Organization` has the following fields: + +`````{tab-set} + +````{tab-item} Schema + +```{jsonschema} ../../schema/project-level/project-schema.json +:pointer: /definitions/Organization +:collapse: name,id,identifier,additionalIdentifiers,address,contactPoint,roles,people +:addtargets: +``` + +```` + +````{tab-item} Examples + +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/parties +:title: parties +``` + +```` + +````` + +### OrganizationReference + +`OrganizationReference` is defined as: + +```{field-description} ../../schema/project-level/project-schema.json /definitions/OrganizationReference +``` + +This sub-schema is referenced by the following properties: +* [`publicAuthority`](project-schema.json,,publicAuthority) +* [`ContractingProcessSummary/tender/tenderers`](project-schema.json,/definitions/ContractingProcessSummary,tender/tenderers) +* [`ContractingProcessSummary/tender/procuringEntity`](project-schema.json,/definitions/ContractingProcessSummary,tender/procuringEntity) +* [`ContractingProcessSummary/tender/administrativeEntity`](project-schema.json,/definitions/ContractingProcessSummary,tender/administrativeEntity) +* [`ContractingProcessSummary/suppliers`](project-schema.json,/definitions/ContractingProcessSummary,suppliers) +* [`BudgetBreakdown/sourceParty`](project-schema.json,/definitions/BudgetBreakdown,sourceParty) +* [`Transaction/payer`](project-schema.json,/definitions/Transaction,payer) +* [`Transaction/payee`](project-schema.json,/definitions/Transaction,payee) + +Each `OrganizationReference` has the following fields: + +`````{tab-set} + +````{tab-item} Schema + +```{jsonschema} ../../schema/project-level/project-schema.json +:pointer: /definitions/OrganizationReference +:collapse: name,id +:addtargets: +``` + +```` + +````{tab-item} Examples + +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/budget/budgetBreakdown/0/sourceParty +:title: budget/budgetBreakdown/0/sourceParty +``` + +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/publicAuthority +:title: publicAuthority +``` + +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/contractingProcesses/0/summary/tender/tenderers +:title: contractingProcesses/0/summary/tender/tenderers +``` + +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/contractingProcesses/0/summary/tender/procuringEntity +:title: contractingProcesses/0/summary/tender/procuringEntity +``` + +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/contractingProcesses/0/summary/tender/administrativeEntity +:title: contractingProcesses/0/summary/tender/administrativeEntity +``` + +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/contractingProcesses/0/summary/suppliers +:title: contractingProcesses/0/summary/suppliers +``` + +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/contractingProcesses/0/summary/transactions/0/payer +:title: contractingProcesses/0/summary/transactions/0/payer +``` + +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/contractingProcesses/0/summary/transactions/0/payee +:title: contractingProcesses/0/summary/transactions/0/payee +``` + +```` + +````` + +### Address + +The address sub-schema re-uses fields from schema.org and vCard. In the event source data cannot be broken down into these parts, data should contain at least a `streetAddress` and `postalCode`. + +When working with data, users ought to be aware that addresses might not always be broken down using all the fields the schema provides. + +`Address` is defined as: + +```{field-description} ../../schema/project-level/project-schema.json /definitions/Address +``` + +This sub-schema is referenced by the following properties: +* [`Location/address`](project-schema.json,/definitions/Location,address) +* [`Organization/address`](project-schema.json,/definitions/Organization,address) + +Each `Address` has the following fields: + +`````{tab-set} + +````{tab-item} Schema + +```{jsonschema} ../../schema/project-level/project-schema.json +:pointer: /definitions/Address +:collapse: streetAddress,locality,region,postalCode,countryName +:addtargets: +``` + +```` + +````{tab-item} Examples + +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/locations/0/address +:title: locations/0/address +``` + +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/parties/0/address +:title: parties/0/address +``` + +```` + +````` + ### ContactPoint -```{jsonschema} ../../build/current_lang/project-schema.json +`ContactPoint` is defined as: + +```{field-description} ../../schema/project-level/project-schema.json /definitions/ContactPoint +``` + +This sub-schema is referenced by the following properties: +* [`Organization/contactPoint`](project-schema.json,/definitions/Organization,contactPoint) + +Each `ContactPoint` has the following fields: + +`````{tab-set} + +````{tab-item} Schema + +```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/ContactPoint -:include: -:collapse: +:collapse: name,email,telephone,faxNumber,url +:addtargets: +``` + +```` + +````{tab-item} Examples + +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/parties/0/contactPoint +:title: parties/0/contactPoint +``` + +```` + +````` + +### BudgetBreakdown + +For more information about this sub-schema, see the [OCDS Budget Breakdown extension documentation](https://extensions.open-contracting.org/en/extensions/budget/master/). `BudgetBreakdown` can also be extended further to include budget classifications data following the pattern described in the [OCDS Budgets and Spend extension](https://extensions.open-contracting.org/en/extensions/budget_and_spend/master/). + +`BudgetBreakdown` is defined as: + +```{field-description} ../../schema/project-level/project-schema.json /definitions/BudgetBreakdown ``` +This sub-schema is referenced by the following properties: +* [`budget/budgetBreakdown`](project-schema.json,,budget/budgetBreakdown) + +Each `BudgetBreakdown` has the following fields: + +`````{tab-set} + +````{tab-item} Schema + +```{jsonschema} ../../schema/project-level/project-schema.json +:pointer: /definitions/BudgetBreakdown +:collapse: id,description,amount,approvalDate,uri,period,sourceParty +:addtargets: +``` + +```` + +````{tab-item} Examples + +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/budget/budgetBreakdown +:title: budget/budgetBreakdown +``` + +```` + +````` + ### Document -For each document the following structured information can be provided. +`Document` is defined as: -```{jsonschema} ../../build/current_lang/project-schema.json +```{field-description} ../../schema/project-level/project-schema.json /definitions/Document +``` + +This sub-schema is referenced by the following properties: +* [`documents`](project-schema.json,,documents) +* [`ContractingProcessSummary/documents`](project-schema.json,/definitions/ContractingProcessSummary,documents) + +Each `Document` has the following fields: + +`````{tab-set} + +````{tab-item} Schema + +```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/Document -:include: -:collapse: +:collapse: id,documentType,title,description,url,datePublished,dateModified,format,language,pageStart,pageEnd,accessDetails,author +:addtargets: +``` + +```` + +````{tab-item} Examples + +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/documents +:title: documents ``` +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/contractingProcesses/0/summary/documents +:title: contractingProcesses/0/summary/documents +``` + +```` + +````` + ### Identifier Use of stable official organization identifiers can help join up data between systems. @@ -110,103 +708,230 @@ Organization identifiers should be constructed by collecting an official company For example, if identifying a company in Colombia, look up its identifier in the [Unified Commercial and Social Registry](http://org-id.guide/list/CO-RUE) and use the list code `CO-RUE`. -```{jsonschema} ../../build/current_lang/project-schema.json +`Identifier` is defined as: + +```{field-description} ../../schema/project-level/project-schema.json /definitions/Identifier +``` + +This sub-schema is referenced by the following properties: +* [`Organization/identifier`](project-schema.json,/definitions/Organization,identifier) +* [`Organization/additionalIdentifiers`](project-schema.json,/definitions/Organization,additionalIdentifiers) + +Each `Identifier` has the following fields: + +`````{tab-set} + +````{tab-item} Schema + +```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/Identifier -:include: -:collapse: +:collapse: scheme,id,legalName,uri +:addtargets: ``` -### Location +```` -A project can have one or more locations. Locations can be expressed in a number of different ways, using one or more of: +````{tab-item} Examples -* A point location or geometry (e.g. trace of a road, or polygon giving the boundary of a site); -* A gazetteer entry (e.g. town name); -* An address. +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/parties/0/identifier +:title: parties/0/identifier +``` -```{jsonschema} ../../build/current_lang/project-schema.json -:pointer: /definitions/Location -:include: -:collapse: address +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/parties/0/additionalIdentifiers +:title: parties/0/additionalIdentifiers ``` -### Modification +```` -For each modification, the following structured information can be provided. +````` -```{jsonschema} ../../build/current_lang/project-schema.json -:pointer: /definitions/Modification -:include: -:collapse: +### RelatedProject + +`RelatedProject` is defined as: + +```{field-description} ../../schema/project-level/project-schema.json /definitions/RelatedProject ``` -### Organization +This sub-schema is referenced by the following properties: +* [`relatedProjects`](project-schema.json,,relatedProjects) -For each organization, provide as much structured data as you can. +Each `RelatedProject` has the following fields: -```{jsonschema} ../../build/current_lang/project-schema.json -:pointer: /definitions/Organization -:collapse: identifier,additionalIdentifiers,address,contactPoint +`````{tab-set} + +````{tab-item} Schema + +```{jsonschema} ../../schema/project-level/project-schema.json +:pointer: /definitions/RelatedProject +:collapse: id,scheme,identifier,relationship,title,uri +:addtargets: ``` -### OrganizationReference +```` -```{jsonschema} ../../build/current_lang/project-schema.json -:pointer: /definitions/OrganizationReference -:include: -:collapse: +````{tab-item} Examples + +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/relatedProjects +:title: relatedProjects ``` -### Period +```` -Dates MUST be expressed using a full ISO 8601 date-time including a timezone. E.g.: +````` -> 2018-09-18T11:26:04+01:00 +### Metric +`Metric` is defined as: -Where the source system does not contain time information, a judgment ought to be made as to the relevant time to attach (e.g. start of the day; end of the working day etc.). +```{field-description} ../../schema/project-level/project-schema.json /definitions/Metric +``` -```{jsonschema} ../../build/current_lang/project-schema.json -:pointer: /definitions/Period -:include: -:collapse: +This sub-schema is referenced by the following properties: +* [`forecasts`](project-schema.json,,forecasts) +* [`metrics`](project-schema.json,,metrics) + +Each `Metric` has the following fields: + +`````{tab-set} + +````{tab-item} Schema + +```{jsonschema} ../../schema/project-level/project-schema.json +:pointer: /definitions/Metric +:collapse: id,title,description,observations +:addtargets: +``` + +```` + +````{tab-item} Examples + +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/forecasts +:title: forecasts +``` + +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/metrics +:title: metrics +``` + +```` + +````` + +### Observation +`Observation` is defined as: + +```{field-description} ../../schema/project-level/project-schema.json /definitions/Observation +``` + +This sub-schema is referenced by the following properties: +* [`Metric/observations`](project-schema.json,/definitions/Metric,observations) + +Each `Observation` has the following fields: + +`````{tab-set} + +````{tab-item} Schema + +```{jsonschema} ../../schema/project-level/project-schema.json +:pointer: /definitions/Observation +:collapse: id,period,value,measure,notes +:addtargets: ``` +```` + +````{tab-item} Examples + +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/forecasts/0/observations +:title: forecasts/0/observations +``` + +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/metrics/0/observations +:title: metrics/0/observations +``` + +```` + +````` + ### Person Use this object when you need to disclose the details of people associated with, representing or working on behalf of an organization involved in the project. -```{jsonschema} ../../build/current_lang/project-schema.json +`Person` is defined as: + +```{field-description} ../../schema/project-level/project-schema.json /definitions/Person +``` + +This sub-schema is referenced by the following properties: +* [`Organization/people`](project-schema.json,/definitions/Organization,people) + +Each `Person` has the following fields: + +`````{tab-set} + +````{tab-item} Schema + +```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/Person -:include: -:collapse: +:collapse: id,name,jobTitle +:addtargets: ``` -### RelatedProject +```` -A reference to a project related to the same set of infrastructure assets as the current project. +````{tab-item} Examples -```{jsonschema} ../../build/current_lang/project-schema.json -:pointer: /definitions/RelatedProject -:include: -:collapse: +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/parties/0/people +:title: parties/0/people ``` +```` + +````` + ### Transaction A spending transaction related to a contracting process. -```{jsonschema} ../../build/current_lang/project-schema.json +`Transaction` is defined as: + +```{field-description} ../../schema/project-level/project-schema.json /definitions/Transaction +``` + +This sub-schema is referenced by the following properties: +* [`ContractingProcessSummary/transactions`](project-schema.json,/definitions/ContractingProcessSummary,transactions) + +Each `Transaction` has the following fields: + +`````{tab-set} + +````{tab-item} Schema + +```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/Transaction -:include: -:collapse: +:collapse: id,source,date,value,payer,payee,uri +:addtargets: ``` -### Value +```` -All values should be published along with their currency using the following structure. +````{tab-item} Examples -```{jsonschema} ../../build/current_lang/project-schema.json -:pointer: /definitions/Value -:include: -:collapse: +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/contractingProcesses/0/summary/transactions +:title: contractingProcesses/0/summary/transactions ``` + +```` + +````` + diff --git a/manage.py b/manage.py index 76a4170a..aa110415 100755 --- a/manage.py +++ b/manage.py @@ -16,6 +16,7 @@ from ocdskit.schema import add_validation_properties basedir = Path(__file__).resolve().parent +referencedir = basedir / 'docs' / 'reference' def get(url): @@ -163,6 +164,178 @@ def compare(actual, infra_list, ocds_list, prefix, suffix): sys.exit(f'{prefix} is missing {", ".join(removed)}: remove from infra_{suffix}?') +def get_definition_references(schema, defn, parents=None, project_schema=None, include_nested=True): + """ + Recursively generate a list of JSON pointers that reference a definition in JSON schema. + + :param schema: The JSON schema + :param defn: The name of the definition + :param parents: A list of the parents of schema + :param project_schema: The full project schema + :param include_nested: Whether to include nested references + """ + + references = [] + + if parents is None: + parents = [] + + if project_schema is None: + project_schema = schema + + if 'properties' in schema: + for key, value in schema['properties'].items(): + if value.get('type') == 'array' and '$ref' in value['items']: + if value['items']['$ref'] == f"#/definitions/{defn}": + references.append(parents + [key, '0']) + elif include_nested: + references.extend(get_definition_references( + project_schema['definitions'][value['items']['$ref'].split('/')[-1]], + defn, + parents + [key, '0'], + project_schema, include_nested)) + elif '$ref' in value: + if value['$ref'] == f"#/definitions/{defn}": + references.append(parents + [key]) + elif include_nested: + references.extend(get_definition_references( + project_schema['definitions'][value['$ref'].split('/')[-1]], + defn, + parents + [key], + project_schema, include_nested)) + elif 'properties' in value: + references.extend(get_definition_references(value, + defn, + parents + [key], + project_schema, + include_nested)) + + if 'definitions' in schema: + for key, value in schema['definitions'].items(): + references.extend(get_definition_references(value, defn, [key], project_schema, include_nested)) + + return references + + +def update_sub_schema_reference(schema): + """Update docs/reference/schema.md""" + + # Load schema reference + with (referencedir / 'schema.md').open() as f: + schema_reference = f.readlines() + + # Preserve content that appears before the generated reference content for each sub-schema + sub_schema_index = schema_reference.index("## Sub-schemas\n") + 3 + + for i in range(sub_schema_index, len(schema_reference)): + if schema_reference[i][:4] == "### ": + defn = schema_reference[i][4:-1] + + # Drop definitions that don't appear in the schema + if defn in schema["definitions"]: + schema["definitions"][defn]["content"] = [] + j = i+1 + + while j < len(schema_reference) and not schema_reference[j].startswith(f"`{defn}` is defined as:"): + schema["definitions"][defn]["content"].append(schema_reference[j]) + j = j+1 + + # Preserve introductory content up to and including the sentence below the ## Sub-schema heading + schema_reference = schema_reference[:sub_schema_index] + schema_reference.append("\n") + + # Generate standard reference content for each definition + for defn, definition in schema["definitions"].items(): + definition["content"] = definition.get("content", []) + + # Add heading + definition["content"].insert(0, f"### {defn}\n") + + # Add description + definition["content"].extend([ + f"`{defn}` is defined as:\n\n", + f"```{{field-description}} ../../schema/project-level/project-schema.json /definitions/{defn}\n", + "```\n\n" + ]) + + # Add a list of properties that reference this definition + definition["references"] = get_definition_references(schema, defn, include_nested=False) + definition["content"].append("This sub-schema is referenced by the following properties:\n") + + for ref in definition["references"]: + # noqa: Remove array indices because they do not appear in the HTML anchors generated by the json schema directive + ref = [part for part in ref if part != '0'] + + url = 'project-schema.json,' + + # Omit nested references + if ref[0] in schema['definitions']: + url += f"/definitions/{ref[0]},{'/'.join(ref[1:])}" + else: + url += f",{'/'.join(ref)}" + + definition["content"].append(f"* [`{'/'.join(ref)}`]({url})\n") + + # Add schema table + properties_to_collapse = [] + for key, value in definition['properties'].items(): + if value.get('type') != 'object': + properties_to_collapse.append(key) + + definition["content"].extend([ + f"\nEach `{defn}` has the following fields:\n\n", + "`````{tab-set}\n\n", + "````{tab-item} Schema\n\n", + "```{jsonschema} ../../schema/project-level/project-schema.json\n", + f":pointer: /definitions/{defn}\n", + f":collapse: {','.join(properties_to_collapse)}\n" + ":addtargets:\n" + "```\n\n", + "````\n\n", + "````{tab-item} Examples\n\n" + ]) + + # Paths that don't appear in the example data at all + paths_to_skip = ['forecasts/0/observations/0/value', 'metrics/0/observations/0/value'] + + # Add examples + definition["references"] = get_definition_references(schema, defn) + for ref in definition["references"]: + if ref[0] not in schema['definitions'] and '/'.join(ref) not in paths_to_skip: + if ref[-1] == '0': + ref.pop(-1) + + definition["content"].extend([ + "```{jsoninclude} ../../docs/examples/example.json\n", + f":jsonpointer: /projects/0/{'/'.join(ref)}\n", + f":title: {'/'.join(ref)}\n", + "```\n\n" + ]) + + definition["content"].extend([ + "````\n\n", + "`````\n\n" + ]) + + schema_reference.extend(definition["content"]) + + # Paths that don't appear in the example data, but for which there is an alternative + paths_to_replace = { + '/projects/0/contractingProcesses/0/summary/modifications/0/oldContractValue': ( + '/projects/0/contractingProcesses/0/summary/modifications/2/oldContractValue'), + '/projects/0/contractingProcesses/0/summary/modifications/0/newContractValue': ( + '/projects/0/contractingProcesses/0/summary/modifications/2/newContractValue') + } + + for key, value in paths_to_replace.items(): + index = schema_reference.index(f":jsonpointer: {key}\n") + del schema_reference[index] + schema_reference.insert(index, f":jsonpointer: {value}\n") + + with (referencedir / 'schema.md').open('w') as f: + f.writelines(schema_reference) + + @click.group() def cli(): pass @@ -171,11 +344,15 @@ def cli(): @cli.command() def pre_commit(): """ - Generate a CSV file of fields that can contain non-English text. + Update docs/reference/schema.md and _static/i8n.csv """ with (basedir / 'schema' / 'project-level' / 'project-schema.json').open() as f: schema = json.load(f) + # Update schema reference documentation + update_sub_schema_reference(schema) + + # Generate a CSV file of fields that can contain non-English text. _, rows = mapping_sheet(schema, include_codelist=True, include_deprecated=False) with (basedir / 'docs' / '_static' / 'i18n.csv').open('w') as f: diff --git a/pull_request_template.md b/pull_request_template.md index c23a1aa4..68526ca2 100644 --- a/pull_request_template.md +++ b/pull_request_template.md @@ -19,11 +19,8 @@ If there are changes to `project-schema.json` or `project-package-schema.json`: - [ ] `docs/examples/blank.json` - [ ] Run `./manage.py pre-commit` to update `docs/_static/i8n.csv` -If you added a new definition to the schema, update `docs/reference/schema.md`: - -- [ ] Add an entry to the components section -- [ ] Update the `:collapse:` parameter of the `jsonschema` directive for any schemas or sub-schemas that reference the new definition +If you added a new definition to the schema, run `./manage.py pre-commit`. If you added a new codelist: - - [ ] Add an entry to `docs/reference/codelists.md` \ No newline at end of file + - [ ] Add an entry to `docs/reference/codelists.md` diff --git a/requirements.txt b/requirements.txt index 2d57c869..38cf5586 100644 --- a/requirements.txt +++ b/requirements.txt @@ -5,6 +5,7 @@ sphinxcontrib-opencontracting==0.0.8 sphinxcontrib-opendataservices-jsonschema==0.5.1 sphinxcontrib-opendataservices==0.5.0 +sphinx-design # Build jsonref