From d3b07939d5bd6e12ff93ed5c9eed49fa92ee5bf0 Mon Sep 17 00:00:00 2001 From: Duncan Dewhurst Date: Fri, 11 Nov 2022 15:52:03 +1300 Subject: [PATCH 01/24] requirements.txt: Upgrade sphinxcontrib-opendataservices --- requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/requirements.txt b/requirements.txt index 2eb3f04f..ec4284ce 100644 --- a/requirements.txt +++ b/requirements.txt @@ -6,7 +6,7 @@ sphinxcontrib-opencontracting==0.0.3 # https://github.com/OpenDataServices/sphinxcontrib-opendataservices-jsonschema/pull/41 # sphinxcontrib-opendataservices-jsonschema==0.5.0 -e git+https://github.com/jpmckinney/sphinxcontrib-opendataservices-jsonschema.git@upgrade-jsonref#egg=sphinxcontrib-opendataservices-jsonschema -sphinxcontrib-opendataservices==0.1.0 +sphinxcontrib-opendataservices==0.5.0 # Build jsonref From b9626d4ff4922b36a248a53e098425cb05c34a9d Mon Sep 17 00:00:00 2001 From: Duncan Dewhurst Date: Fri, 11 Nov 2022 15:52:33 +1300 Subject: [PATCH 02/24] manage.py: Add a pre-commit script to update schema reference docs --- manage.py | 149 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 148 insertions(+), 1 deletion(-) diff --git a/manage.py b/manage.py index 630c5847..a2728806 100755 --- a/manage.py +++ b/manage.py @@ -163,6 +163,149 @@ 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): + """ + Recursively generate a list of JSON pointers that reference a definition in JSON schema. + + :param schema: The JSON schema + :defn: The name of the definition + :parents: A list of the parents of schema + :project_schema: The full project schema + """ + + 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']) + else: + references.extend(get_definition_references(project_schema['definitions'][value['items']['$ref'].split('/')[-1]], defn, parents + [key, '0'], project_schema)) + elif '$ref' in value: + if value['$ref'] == f"#/definitions/{defn}": + references.append(parents + [key]) + else: + references.extend(get_definition_references(project_schema['definitions'][value['$ref'].split('/')[-1]], defn, parents + [key], project_schema)) + elif 'properties' in value: + references.extend(get_definition_references(value, defn, parents + [key], project_schema)) + + if 'definitions' in schema: + for key, value in schema['definitions'].items(): + references.extend(get_definition_references(value, defn, [key], project_schema)) + + 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}"): + while j < len(schema_reference) and not schema_reference[j].startswith("```{jsonschema}"): + 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", + "```{jsoninclude-quote} ../../schema/project-level/project-schema.json\n", + f":jsonpointer: /definitions/{defn}/description\n", + "```\n\n" + ]) + + # Add a list of properties that reference this definition + definition["references"] = get_definition_references(schema, defn) + definition["content"].append("This sub-schema is referenced by the following properties:\n") + + for ref in definition["references"]: + # 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'] + + # Ideally, these would be relative links - see https://github.com/OpenDataServices/sphinxcontrib-opendataservices/issues/43 + url = 'https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#project-schema.json,' + + # Omit nested references + if ref[0] in schema['definitions'] and len(ref) == 2: + url += '/definitions/' + elif len(ref) == 1: + url += ',' + else: + continue + + url += ','.join(ref) + definition["content"].append(f"* [`{'/'.join(ref)}`]({url})\n") + + # Add schema table + 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(definition['properties'].keys())}\n" + "```\n\n", + ":::\n\n", + ":::{tab-item} Examples\n\n" + ]) + + # Add examples + for ref in definition["references"]: + if ref[0] not in schema['definitions']: + if ref[-1] == '0': + ref.pop(-1) + + definition["content"].extend([ + "```{eval-rst}\n", + ".. 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"]) + + with (referencedir/ 'schema.md').open('w') as f: + f.writelines(schema_reference) + + @click.group() def cli(): pass @@ -171,11 +314,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: From 76400b5f66ba55945b86033d409306f25e67d997 Mon Sep 17 00:00:00 2001 From: Duncan Dewhurst Date: Fri, 11 Nov 2022 15:54:23 +1300 Subject: [PATCH 03/24] docs/examples: reorder contracting processes, add missing fields --- docs/examples/example.json | 383 +++++++++++++++++++------------------ docs/guidance/example.md | 4 +- 2 files changed, 197 insertions(+), 190 deletions(-) diff --git a/docs/examples/example.json b/docs/examples/example.json index 66b78c1e..ebe540df 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", @@ -481,32 +488,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 +523,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 +553,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 +720,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 +813,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 3abe4f6a..5cdc5e3e 100644 --- a/docs/guidance/example.md +++ b/docs/guidance/example.md @@ -161,7 +161,7 @@ The `contractingProcesses` array is used to provide information about each contr 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 +:jsonpointer: /projects/0/contractingProcesses/1 :expand: summary, documents, releases :title: contractingProcess ``` @@ -173,7 +173,7 @@ Each contracting process includes a `modifications` array which is used to list 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 +:jsonpointer: /projects/0/contractingProcesses/0/summary/modifications/0 :expand: oldContractPeriod, newContractPeriod :title: modification ``` From 389a54d22356f70e55a69a585cf3946eae029276 Mon Sep 17 00:00:00 2001 From: Duncan Dewhurst Date: Fri, 11 Nov 2022 15:54:56 +1300 Subject: [PATCH 04/24] docs/reference/schema.md: Refactor, add definitions and examples --- docs/reference/schema.md | 937 +++++++++++++++++++++++++++++++++++---- 1 file changed, 840 insertions(+), 97 deletions(-) diff --git a/docs/reference/schema.md b/docs/reference/schema.md index b21b7c56..e25ddb23 100644 --- a/docs/reference/schema.md +++ b/docs/reference/schema.md @@ -6,39 +6,539 @@ } -The tables below describe each of the fields and objects in OC4IDS. To see how they fit together, consult the [schema browser](browser). +This section presents each field in the 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). ## Project +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. + +Each project has the following fields: + ```{jsonschema} ../../build/current_lang/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 ``` -## ContractingProcess +## Sub-schemas -```{jsonschema} ../../build/current_lang/project-schema.json -:include: +This section lists each sub-schema in the OC4IDS schema. Some sub-schemas are referenced in multiple places in the schema. + +### ContractingProcess +`ContractingProcess` is defined as: + +```{jsoninclude-quote} ../../schema/project-level/project-schema.json +:jsonpointer: /definitions/ContractingProcess/description +``` + +This sub-schema is referenced by the following properties: +* [`contractingProcesses`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#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 ``` -## ContractingProcessSummary +::: -```{jsonschema} ../../build/current_lang/project-schema.json -:include: +:::{tab-item} Examples + +```{eval-rst} +.. jsoninclude:: ../../docs/examples/example.json + :jsonpointer: /projects/0/contractingProcesses + :title: contractingProcesses +``` + +::: + +:::: + +### ContractingProcessSummary +`ContractingProcessSummary` is defined as: + +```{jsoninclude-quote} ../../schema/project-level/project-schema.json +:jsonpointer: /definitions/ContractingProcessSummary/description +``` + +This sub-schema is referenced by the following properties: +* [`ContractingProcess/summary`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#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,tender,suppliers,contractValue,contractPeriod,finalValue,documents,modifications,transactions ``` -## LinkedRelease +::: -```{jsonschema} ../../build/current_lang/project-schema.json -:include: +:::{tab-item} Examples + +```{eval-rst} +.. jsoninclude:: ../../docs/examples/example.json + :jsonpointer: /projects/0/contractingProcesses/0/summary + :title: contractingProcesses/0/summary +``` + +::: + +:::: + +### LinkedRelease +`LinkedRelease` is defined as: + +```{jsoninclude-quote} ../../schema/project-level/project-schema.json +:jsonpointer: /definitions/LinkedRelease/description +``` + +This sub-schema is referenced by the following properties: +* [`ContractingProcess/releases`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#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 +``` + +::: + +:::{tab-item} Examples + +```{eval-rst} +.. jsoninclude:: ../../docs/examples/example.json + :jsonpointer: /projects/0/contractingProcesses/0/releases + :title: contractingProcesses/0/releases +``` + +::: + +:::: + +### Modification + +For each modification, the following structured information can be provided. + +`Modification` is defined as: + +```{jsoninclude-quote} ../../schema/project-level/project-schema.json +:jsonpointer: /definitions/Modification/description +``` + +This sub-schema is referenced by the following properties: +* [`ContractingProcessSummary/modifications`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#project-schema.json,/definitions/ContractingProcessSummary,modifications) + +Each `Modification` has the following fields: + +::::{tab-set} + +:::{tab-item} Schema + +```{jsonschema} ../../schema/project-level/project-schema.json +:pointer: /definitions/Modification +:collapse: id,date,description,rationale,type,releaseID,oldContractValue,newContractValue,oldContractPeriod,newContractPeriod +``` + +::: + +:::{tab-item} Examples + +```{eval-rst} +.. 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: + +```{jsoninclude-quote} ../../schema/project-level/project-schema.json +:jsonpointer: /definitions/Period/description +``` + +This sub-schema is referenced by the following properties: +* [`period`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#project-schema.json,,period) +* [`assetLifetime`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#project-schema.json,,assetLifetime) +* [`ContractingProcessSummary/contractPeriod`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#project-schema.json,/definitions/ContractingProcessSummary,contractPeriod) +* [`Modification/oldContractPeriod`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#project-schema.json,/definitions/Modification,oldContractPeriod) +* [`Modification/newContractPeriod`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#project-schema.json,/definitions/Modification,newContractPeriod) +* [`BudgetBreakdown/period`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#project-schema.json,/definitions/BudgetBreakdown,period) +* [`Observation/period`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#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 +``` + +::: + +:::{tab-item} Examples + +```{eval-rst} +.. jsoninclude:: ../../docs/examples/example.json + :jsonpointer: /projects/0/period + :title: period +``` + +```{eval-rst} +.. jsoninclude:: ../../docs/examples/example.json + :jsonpointer: /projects/0/assetLifetime + :title: assetLifetime +``` + +```{eval-rst} +.. jsoninclude:: ../../docs/examples/example.json + :jsonpointer: /projects/0/budget/budgetBreakdown/0/period + :title: budget/budgetBreakdown/0/period +``` + +```{eval-rst} +.. jsoninclude:: ../../docs/examples/example.json + :jsonpointer: /projects/0/forecasts/0/observations/0/period + :title: forecasts/0/observations/0/period +``` + +```{eval-rst} +.. jsoninclude:: ../../docs/examples/example.json + :jsonpointer: /projects/0/contractingProcesses/0/summary/contractPeriod + :title: contractingProcesses/0/summary/contractPeriod +``` + +```{eval-rst} +.. jsoninclude:: ../../docs/examples/example.json + :jsonpointer: /projects/0/contractingProcesses/0/summary/modifications/0/oldContractPeriod + :title: contractingProcesses/0/summary/modifications/0/oldContractPeriod +``` + +```{eval-rst} +.. jsoninclude:: ../../docs/examples/example.json + :jsonpointer: /projects/0/contractingProcesses/0/summary/modifications/0/newContractPeriod + :title: contractingProcesses/0/summary/modifications/0/newContractPeriod +``` + +```{eval-rst} +.. 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: + +```{jsoninclude-quote} ../../schema/project-level/project-schema.json +:jsonpointer: /definitions/Classification/description +``` + +This sub-schema is referenced by the following properties: +* [`additionalClassifications`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#project-schema.json,,additionalClassifications) + +Each `Classification` has the following fields: + +::::{tab-set} + +:::{tab-item} Schema + +```{jsonschema} ../../schema/project-level/project-schema.json +:pointer: /definitions/Classification +:collapse: scheme,id,description,uri +``` + +::: + +:::{tab-item} Examples + +```{eval-rst} +.. jsoninclude:: ../../docs/examples/example.json + :jsonpointer: /projects/0/additionalClassifications + :title: additionalClassifications +``` + +::: + +:::: + +### Location + +A project can have one or more locations. Locations can be expressed in a number of different ways, using one or more of: + +* 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. + +`Location` is defined as: + +```{jsoninclude-quote} ../../schema/project-level/project-schema.json +:jsonpointer: /definitions/Location/description +``` + +This sub-schema is referenced by the following properties: +* [`locations`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#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,geometry,gazetteer,uri,address +``` + +::: + +:::{tab-item} Examples + +```{eval-rst} +.. jsoninclude:: ../../docs/examples/example.json + :jsonpointer: /projects/0/locations + :title: locations +``` + +::: + +:::: + +### Value + +All values should be published along with their currency using the following structure. + +`Value` is defined as: + +```{jsoninclude-quote} ../../schema/project-level/project-schema.json +:jsonpointer: /definitions/Value/description +``` + +This sub-schema is referenced by the following properties: +* [`ContractingProcessSummary/contractValue`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#project-schema.json,/definitions/ContractingProcessSummary,contractValue) +* [`ContractingProcessSummary/finalValue`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#project-schema.json,/definitions/ContractingProcessSummary,finalValue) +* [`Modification/oldContractValue`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#project-schema.json,/definitions/Modification,oldContractValue) +* [`Modification/newContractValue`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#project-schema.json,/definitions/Modification,newContractValue) +* [`BudgetBreakdown/amount`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#project-schema.json,/definitions/BudgetBreakdown,amount) +* [`Observation/value`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#project-schema.json,/definitions/Observation,value) +* [`Transaction/value`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#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 +``` + +::: + +:::{tab-item} Examples + +```{eval-rst} +.. jsoninclude:: ../../docs/examples/example.json + :jsonpointer: /projects/0/budget/amount + :title: budget/amount +``` + +```{eval-rst} +.. jsoninclude:: ../../docs/examples/example.json + :jsonpointer: /projects/0/budget/budgetBreakdown/0/amount + :title: budget/budgetBreakdown/0/amount +``` + +```{eval-rst} +.. jsoninclude:: ../../docs/examples/example.json + :jsonpointer: /projects/0/contractingProcesses/0/summary/tender/costEstimate + :title: contractingProcesses/0/summary/tender/costEstimate +``` + +```{eval-rst} +.. jsoninclude:: ../../docs/examples/example.json + :jsonpointer: /projects/0/contractingProcesses/0/summary/contractValue + :title: contractingProcesses/0/summary/contractValue +``` + +```{eval-rst} +.. jsoninclude:: ../../docs/examples/example.json + :jsonpointer: /projects/0/contractingProcesses/0/summary/finalValue + :title: contractingProcesses/0/summary/finalValue +``` + +```{eval-rst} +.. jsoninclude:: ../../docs/examples/example.json + :jsonpointer: /projects/0/contractingProcesses/0/summary/transactions/0/value + :title: contractingProcesses/0/summary/transactions/0/value +``` + +```{eval-rst} +.. jsoninclude:: ../../docs/examples/example.json + :jsonpointer: /projects/0/completion/finalValue + :title: completion/finalValue +``` + +::: + +:::: + +### Organization + +For each organization, provide as much structured data as you can. + +`Organization` is defined as: + +```{jsoninclude-quote} ../../schema/project-level/project-schema.json +:jsonpointer: /definitions/Organization/description +``` + +This sub-schema is referenced by the following properties: +* [`parties`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#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 +``` + +::: + +:::{tab-item} Examples + +```{eval-rst} +.. jsoninclude:: ../../docs/examples/example.json + :jsonpointer: /projects/0/parties + :title: parties +``` + +::: + +:::: + +### OrganizationReference + +`OrganizationReference` is defined as: + +```{jsoninclude-quote} ../../schema/project-level/project-schema.json +:jsonpointer: /definitions/OrganizationReference/description ``` -## Components +This sub-schema is referenced by the following properties: +* [`publicAuthority`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#project-schema.json,,publicAuthority) +* [`ContractingProcessSummary/suppliers`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#project-schema.json,/definitions/ContractingProcessSummary,suppliers) +* [`BudgetBreakdown/sourceParty`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#project-schema.json,/definitions/BudgetBreakdown,sourceParty) +* [`Transaction/payer`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#project-schema.json,/definitions/Transaction,payer) +* [`Transaction/payee`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#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 +``` + +::: + +:::{tab-item} Examples + +```{eval-rst} +.. jsoninclude:: ../../docs/examples/example.json + :jsonpointer: /projects/0/budget/budgetBreakdown/0/sourceParty + :title: budget/budgetBreakdown/0/sourceParty +``` + +```{eval-rst} +.. jsoninclude:: ../../docs/examples/example.json + :jsonpointer: /projects/0/publicAuthority + :title: publicAuthority +``` + +```{eval-rst} +.. jsoninclude:: ../../docs/examples/example.json + :jsonpointer: /projects/0/contractingProcesses/0/summary/tender/tenderers + :title: contractingProcesses/0/summary/tender/tenderers +``` + +```{eval-rst} +.. jsoninclude:: ../../docs/examples/example.json + :jsonpointer: /projects/0/contractingProcesses/0/summary/tender/procuringEntity + :title: contractingProcesses/0/summary/tender/procuringEntity +``` + +```{eval-rst} +.. jsoninclude:: ../../docs/examples/example.json + :jsonpointer: /projects/0/contractingProcesses/0/summary/tender/administrativeEntity + :title: contractingProcesses/0/summary/tender/administrativeEntity +``` + +```{eval-rst} +.. jsoninclude:: ../../docs/examples/example.json + :jsonpointer: /projects/0/contractingProcesses/0/summary/suppliers + :title: contractingProcesses/0/summary/suppliers +``` + +```{eval-rst} +.. jsoninclude:: ../../docs/examples/example.json + :jsonpointer: /projects/0/contractingProcesses/0/summary/transactions/0/payer + :title: contractingProcesses/0/summary/transactions/0/payer +``` + +```{eval-rst} +.. jsoninclude:: ../../docs/examples/example.json + :jsonpointer: /projects/0/contractingProcesses/0/summary/transactions/0/payee + :title: contractingProcesses/0/summary/transactions/0/payee +``` + +::: + +:::: ### Address @@ -46,62 +546,167 @@ We use properties from schema.org and vCard for address components. In the event 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 +`Address` is defined as: + +```{jsoninclude-quote} ../../schema/project-level/project-schema.json +:jsonpointer: /definitions/Address/description +``` + +This sub-schema is referenced by the following properties: +* [`Location/address`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#project-schema.json,/definitions/Location,address) +* [`Organization/address`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#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 -:include: -:collapse: +:collapse: streetAddress,locality,region,postalCode,countryName +``` + +::: + +:::{tab-item} Examples + +```{eval-rst} +.. jsoninclude:: ../../docs/examples/example.json + :jsonpointer: /projects/0/locations/0/address + :title: locations/0/address +``` + +```{eval-rst} +.. jsoninclude:: ../../docs/examples/example.json + :jsonpointer: /projects/0/parties/0/address + :title: parties/0/address +``` + +::: + +:::: + +### ContactPoint + +`ContactPoint` is defined as: + +```{jsoninclude-quote} ../../schema/project-level/project-schema.json +:jsonpointer: /definitions/ContactPoint/description +``` + +This sub-schema is referenced by the following properties: +* [`Organization/contactPoint`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#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 +:collapse: name,email,telephone,faxNumber,url +``` + +::: + +:::{tab-item} Examples + +```{eval-rst} +.. jsoninclude:: ../../docs/examples/example.json + :jsonpointer: /projects/0/parties/0/contactPoint + :title: parties/0/contactPoint ``` +::: + +:::: + ### BudgetBreakdown 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. 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/). -```{jsonschema} ../../build/current_lang/project-schema.json -:pointer: /definitions/BudgetBreakdown -:include: -:collapse: +`BudgetBreakdown` is defined as: + +```{jsoninclude-quote} ../../schema/project-level/project-schema.json +:jsonpointer: /definitions/BudgetBreakdown/description ``` -### Classification +This sub-schema is referenced by the following properties: -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`). +Each `BudgetBreakdown` has the following fields: -```{jsonschema} ../../build/current_lang/project-schema.json -:pointer: /definitions/Classification -:include: -:collapse: -``` +::::{tab-set} -For example: +:::{tab-item} Schema -```json -{ - "scheme":"COFOG", - "id":"05.2", - "description":"Waste water management" -} +```{jsonschema} ../../schema/project-level/project-schema.json +:pointer: /definitions/BudgetBreakdown +:collapse: id,description,amount,uri,period,sourceParty ``` -### ContactPoint +::: -```{jsonschema} ../../build/current_lang/project-schema.json -:pointer: /definitions/ContactPoint -:include: -:collapse: +:::{tab-item} Examples + +```{eval-rst} +.. jsoninclude:: ../../docs/examples/example.json + :jsonpointer: /projects/0/budget/budgetBreakdown + :title: budget/budgetBreakdown ``` +::: + +:::: + ### Document For each document the following structured information can be provided. -```{jsonschema} ../../build/current_lang/project-schema.json +`Document` is defined as: + +```{jsoninclude-quote} ../../schema/project-level/project-schema.json +:jsonpointer: /definitions/Document/description +``` + +This sub-schema is referenced by the following properties: +* [`documents`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#project-schema.json,,documents) +* [`ContractingProcessSummary/documents`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#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 +``` + +::: + +:::{tab-item} Examples + +```{eval-rst} +.. jsoninclude:: ../../docs/examples/example.json + :jsonpointer: /projects/0/documents + :title: documents +``` + +```{eval-rst} +.. 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 +715,241 @@ 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: + +```{jsoninclude-quote} ../../schema/project-level/project-schema.json +:jsonpointer: /definitions/Identifier/description +``` + +This sub-schema is referenced by the following properties: +* [`Organization/identifier`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#project-schema.json,/definitions/Organization,identifier) +* [`Organization/additionalIdentifiers`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#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 ``` -### 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. +```{eval-rst} +.. 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 +```{eval-rst} +.. 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 + +A reference to a project related to the same set of infrastructure assets as the current project. + +`RelatedProject` is defined as: + +```{jsoninclude-quote} ../../schema/project-level/project-schema.json +:jsonpointer: /definitions/RelatedProject/description ``` -### Organization +This sub-schema is referenced by the following properties: +* [`relatedProjects`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#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 ``` -### OrganizationReference +::: -```{jsonschema} ../../build/current_lang/project-schema.json -:pointer: /definitions/OrganizationReference -:include: -:collapse: +:::{tab-item} Examples + +```{eval-rst} +.. 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.). +```{jsoninclude-quote} ../../schema/project-level/project-schema.json +:jsonpointer: /definitions/Metric/description +``` -```{jsonschema} ../../build/current_lang/project-schema.json -:pointer: /definitions/Period -:include: -:collapse: +This sub-schema is referenced by the following properties: +* [`forecasts`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#project-schema.json,,forecasts) +* [`metrics`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#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 ``` +::: + +:::{tab-item} Examples + +```{eval-rst} +.. jsoninclude:: ../../docs/examples/example.json + :jsonpointer: /projects/0/forecasts + :title: forecasts +``` + +```{eval-rst} +.. jsoninclude:: ../../docs/examples/example.json + :jsonpointer: /projects/0/metrics + :title: metrics +``` + +::: + +:::: + +### Observation +`Observation` is defined as: + +```{jsoninclude-quote} ../../schema/project-level/project-schema.json +:jsonpointer: /definitions/Observation/description +``` + +This sub-schema is referenced by the following properties: +* [`Metric/observations`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#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,unit,dimensions,notes +``` + +::: + +:::{tab-item} Examples + +```{eval-rst} +.. jsoninclude:: ../../docs/examples/example.json + :jsonpointer: /projects/0/forecasts/0/observations + :title: forecasts/0/observations +``` + +```{eval-rst} +.. 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: + +```{jsoninclude-quote} ../../schema/project-level/project-schema.json +:jsonpointer: /definitions/Person/description +``` + +This sub-schema is referenced by the following properties: +* [`Organization/people`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#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 ``` -### 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: +```{eval-rst} +.. 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: + +```{jsoninclude-quote} ../../schema/project-level/project-schema.json +:jsonpointer: /definitions/Transaction/description +``` + +This sub-schema is referenced by the following properties: +* [`ContractingProcessSummary/transactions`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#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 ``` -### 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: +```{eval-rst} +.. jsoninclude:: ../../docs/examples/example.json + :jsonpointer: /projects/0/contractingProcesses/0/summary/transactions + :title: contractingProcesses/0/summary/transactions ``` + +::: + +:::: + From 819f9b2d8e17599c5fac322413bc2e33f1df881b Mon Sep 17 00:00:00 2001 From: Duncan Dewhurst Date: Fri, 11 Nov 2022 16:11:33 +1300 Subject: [PATCH 05/24] docs/reference/schema.md: Use Sphinx Tabs for schema tables and examples --- docs/conf.py | 1 + docs/reference/schema.md | 240 +++++++++++++++++++-------------------- manage.py | 12 +- requirements.txt | 1 + 4 files changed, 128 insertions(+), 126 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index e5348452..dbd616e7 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -42,6 +42,7 @@ 'sphinxcontrib.jsonschema', 'sphinxcontrib.opencontracting', 'sphinxcontrib.opendataservices', + 'sphinx_tabs.tabs' ] # Add any paths that contain templates here, relative to this directory. diff --git a/docs/reference/schema.md b/docs/reference/schema.md index e25ddb23..d16dfa94 100644 --- a/docs/reference/schema.md +++ b/docs/reference/schema.md @@ -39,18 +39,18 @@ This sub-schema is referenced by the following properties: Each `ContractingProcess` has the following fields: -::::{tab-set} +`````{tabs} -:::{tab-item} Schema +````{tab} Schema ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/ContractingProcess :collapse: id,summary,releases ``` -::: +```` -:::{tab-item} Examples +````{tab} Examples ```{eval-rst} .. jsoninclude:: ../../docs/examples/example.json @@ -58,9 +58,9 @@ Each `ContractingProcess` has the following fields: :title: contractingProcesses ``` -::: +```` -:::: +````` ### ContractingProcessSummary `ContractingProcessSummary` is defined as: @@ -74,18 +74,18 @@ This sub-schema is referenced by the following properties: Each `ContractingProcessSummary` has the following fields: -::::{tab-set} +`````{tabs} -:::{tab-item} Schema +````{tab} Schema ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/ContractingProcessSummary :collapse: ocid,externalReference,nature,title,description,status,tender,suppliers,contractValue,contractPeriod,finalValue,documents,modifications,transactions ``` -::: +```` -:::{tab-item} Examples +````{tab} Examples ```{eval-rst} .. jsoninclude:: ../../docs/examples/example.json @@ -93,9 +93,9 @@ Each `ContractingProcessSummary` has the following fields: :title: contractingProcesses/0/summary ``` -::: +```` -:::: +````` ### LinkedRelease `LinkedRelease` is defined as: @@ -109,18 +109,18 @@ This sub-schema is referenced by the following properties: Each `LinkedRelease` has the following fields: -::::{tab-set} +`````{tabs} -:::{tab-item} Schema +````{tab} Schema ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/LinkedRelease :collapse: id,tag,date,url ``` -::: +```` -:::{tab-item} Examples +````{tab} Examples ```{eval-rst} .. jsoninclude:: ../../docs/examples/example.json @@ -128,9 +128,9 @@ Each `LinkedRelease` has the following fields: :title: contractingProcesses/0/releases ``` -::: +```` -:::: +````` ### Modification @@ -147,18 +147,18 @@ This sub-schema is referenced by the following properties: Each `Modification` has the following fields: -::::{tab-set} +`````{tabs} -:::{tab-item} Schema +````{tab} Schema ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/Modification :collapse: id,date,description,rationale,type,releaseID,oldContractValue,newContractValue,oldContractPeriod,newContractPeriod ``` -::: +```` -:::{tab-item} Examples +````{tab} Examples ```{eval-rst} .. jsoninclude:: ../../docs/examples/example.json @@ -166,9 +166,9 @@ Each `Modification` has the following fields: :title: contractingProcesses/0/summary/modifications ``` -::: +```` -:::: +````` ### Period @@ -195,18 +195,18 @@ This sub-schema is referenced by the following properties: Each `Period` has the following fields: -::::{tab-set} +`````{tabs} -:::{tab-item} Schema +````{tab} Schema ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/Period :collapse: startDate,endDate,maxExtentDate,durationInDays ``` -::: +```` -:::{tab-item} Examples +````{tab} Examples ```{eval-rst} .. jsoninclude:: ../../docs/examples/example.json @@ -256,9 +256,9 @@ Each `Period` has the following fields: :title: metrics/0/observations/0/period ``` -::: +```` -:::: +````` ### Classification @@ -275,18 +275,18 @@ This sub-schema is referenced by the following properties: Each `Classification` has the following fields: -::::{tab-set} +`````{tabs} -:::{tab-item} Schema +````{tab} Schema ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/Classification :collapse: scheme,id,description,uri ``` -::: +```` -:::{tab-item} Examples +````{tab} Examples ```{eval-rst} .. jsoninclude:: ../../docs/examples/example.json @@ -294,9 +294,9 @@ Each `Classification` has the following fields: :title: additionalClassifications ``` -::: +```` -:::: +````` ### Location @@ -317,18 +317,18 @@ This sub-schema is referenced by the following properties: Each `Location` has the following fields: -::::{tab-set} +`````{tabs} -:::{tab-item} Schema +````{tab} Schema ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/Location :collapse: id,description,geometry,gazetteer,uri,address ``` -::: +```` -:::{tab-item} Examples +````{tab} Examples ```{eval-rst} .. jsoninclude:: ../../docs/examples/example.json @@ -336,9 +336,9 @@ Each `Location` has the following fields: :title: locations ``` -::: +```` -:::: +````` ### Value @@ -361,18 +361,18 @@ This sub-schema is referenced by the following properties: Each `Value` has the following fields: -::::{tab-set} +`````{tabs} -:::{tab-item} Schema +````{tab} Schema ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/Value :collapse: amount,currency ``` -::: +```` -:::{tab-item} Examples +````{tab} Examples ```{eval-rst} .. jsoninclude:: ../../docs/examples/example.json @@ -416,9 +416,9 @@ Each `Value` has the following fields: :title: completion/finalValue ``` -::: +```` -:::: +````` ### Organization @@ -435,18 +435,18 @@ This sub-schema is referenced by the following properties: Each `Organization` has the following fields: -::::{tab-set} +`````{tabs} -:::{tab-item} Schema +````{tab} Schema ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/Organization :collapse: name,id,identifier,additionalIdentifiers,address,contactPoint,roles,people ``` -::: +```` -:::{tab-item} Examples +````{tab} Examples ```{eval-rst} .. jsoninclude:: ../../docs/examples/example.json @@ -454,9 +454,9 @@ Each `Organization` has the following fields: :title: parties ``` -::: +```` -:::: +````` ### OrganizationReference @@ -475,18 +475,18 @@ This sub-schema is referenced by the following properties: Each `OrganizationReference` has the following fields: -::::{tab-set} +`````{tabs} -:::{tab-item} Schema +````{tab} Schema ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/OrganizationReference :collapse: name,id ``` -::: +```` -:::{tab-item} Examples +````{tab} Examples ```{eval-rst} .. jsoninclude:: ../../docs/examples/example.json @@ -536,9 +536,9 @@ Each `OrganizationReference` has the following fields: :title: contractingProcesses/0/summary/transactions/0/payee ``` -::: +```` -:::: +````` ### Address @@ -558,18 +558,18 @@ This sub-schema is referenced by the following properties: Each `Address` has the following fields: -::::{tab-set} +`````{tabs} -:::{tab-item} Schema +````{tab} Schema ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/Address :collapse: streetAddress,locality,region,postalCode,countryName ``` -::: +```` -:::{tab-item} Examples +````{tab} Examples ```{eval-rst} .. jsoninclude:: ../../docs/examples/example.json @@ -583,9 +583,9 @@ Each `Address` has the following fields: :title: parties/0/address ``` -::: +```` -:::: +````` ### ContactPoint @@ -600,18 +600,18 @@ This sub-schema is referenced by the following properties: Each `ContactPoint` has the following fields: -::::{tab-set} +`````{tabs} -:::{tab-item} Schema +````{tab} Schema ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/ContactPoint :collapse: name,email,telephone,faxNumber,url ``` -::: +```` -:::{tab-item} Examples +````{tab} Examples ```{eval-rst} .. jsoninclude:: ../../docs/examples/example.json @@ -619,9 +619,9 @@ Each `ContactPoint` has the following fields: :title: parties/0/contactPoint ``` -::: +```` -:::: +````` ### BudgetBreakdown @@ -639,18 +639,18 @@ This sub-schema is referenced by the following properties: Each `BudgetBreakdown` has the following fields: -::::{tab-set} +`````{tabs} -:::{tab-item} Schema +````{tab} Schema ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/BudgetBreakdown :collapse: id,description,amount,uri,period,sourceParty ``` -::: +```` -:::{tab-item} Examples +````{tab} Examples ```{eval-rst} .. jsoninclude:: ../../docs/examples/example.json @@ -658,9 +658,9 @@ Each `BudgetBreakdown` has the following fields: :title: budget/budgetBreakdown ``` -::: +```` -:::: +````` ### Document @@ -678,18 +678,18 @@ This sub-schema is referenced by the following properties: Each `Document` has the following fields: -::::{tab-set} +`````{tabs} -:::{tab-item} Schema +````{tab} Schema ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/Document :collapse: id,documentType,title,description,url,datePublished,dateModified,format,language,pageStart,pageEnd,accessDetails,author ``` -::: +```` -:::{tab-item} Examples +````{tab} Examples ```{eval-rst} .. jsoninclude:: ../../docs/examples/example.json @@ -703,9 +703,9 @@ Each `Document` has the following fields: :title: contractingProcesses/0/summary/documents ``` -::: +```` -:::: +````` ### Identifier @@ -727,18 +727,18 @@ This sub-schema is referenced by the following properties: Each `Identifier` has the following fields: -::::{tab-set} +`````{tabs} -:::{tab-item} Schema +````{tab} Schema ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/Identifier :collapse: scheme,id,legalName,uri ``` -::: +```` -:::{tab-item} Examples +````{tab} Examples ```{eval-rst} .. jsoninclude:: ../../docs/examples/example.json @@ -752,9 +752,9 @@ Each `Identifier` has the following fields: :title: parties/0/additionalIdentifiers ``` -::: +```` -:::: +````` ### RelatedProject @@ -771,18 +771,18 @@ This sub-schema is referenced by the following properties: Each `RelatedProject` has the following fields: -::::{tab-set} +`````{tabs} -:::{tab-item} Schema +````{tab} Schema ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/RelatedProject :collapse: id,scheme,identifier,relationship,title,uri ``` -::: +```` -:::{tab-item} Examples +````{tab} Examples ```{eval-rst} .. jsoninclude:: ../../docs/examples/example.json @@ -790,9 +790,9 @@ Each `RelatedProject` has the following fields: :title: relatedProjects ``` -::: +```` -:::: +````` ### Metric `Metric` is defined as: @@ -807,18 +807,18 @@ This sub-schema is referenced by the following properties: Each `Metric` has the following fields: -::::{tab-set} +`````{tabs} -:::{tab-item} Schema +````{tab} Schema ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/Metric :collapse: id,title,description,observations ``` -::: +```` -:::{tab-item} Examples +````{tab} Examples ```{eval-rst} .. jsoninclude:: ../../docs/examples/example.json @@ -832,9 +832,9 @@ Each `Metric` has the following fields: :title: metrics ``` -::: +```` -:::: +````` ### Observation `Observation` is defined as: @@ -848,18 +848,18 @@ This sub-schema is referenced by the following properties: Each `Observation` has the following fields: -::::{tab-set} +`````{tabs} -:::{tab-item} Schema +````{tab} Schema ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/Observation :collapse: id,period,value,measure,unit,dimensions,notes ``` -::: +```` -:::{tab-item} Examples +````{tab} Examples ```{eval-rst} .. jsoninclude:: ../../docs/examples/example.json @@ -873,9 +873,9 @@ Each `Observation` has the following fields: :title: metrics/0/observations ``` -::: +```` -:::: +````` ### Person @@ -892,18 +892,18 @@ This sub-schema is referenced by the following properties: Each `Person` has the following fields: -::::{tab-set} +`````{tabs} -:::{tab-item} Schema +````{tab} Schema ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/Person :collapse: id,name,jobTitle ``` -::: +```` -:::{tab-item} Examples +````{tab} Examples ```{eval-rst} .. jsoninclude:: ../../docs/examples/example.json @@ -911,9 +911,9 @@ Each `Person` has the following fields: :title: parties/0/people ``` -::: +```` -:::: +````` ### Transaction @@ -930,18 +930,18 @@ This sub-schema is referenced by the following properties: Each `Transaction` has the following fields: -::::{tab-set} +`````{tabs} -:::{tab-item} Schema +````{tab} Schema ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/Transaction :collapse: id,source,date,value,payer,payee,uri ``` -::: +```` -:::{tab-item} Examples +````{tab} Examples ```{eval-rst} .. jsoninclude:: ../../docs/examples/example.json @@ -949,7 +949,7 @@ Each `Transaction` has the following fields: :title: contractingProcesses/0/summary/transactions ``` -::: +```` -:::: +````` diff --git a/manage.py b/manage.py index a2728806..4a43165f 100755 --- a/manage.py +++ b/manage.py @@ -271,14 +271,14 @@ def update_sub_schema_reference(schema): # Add schema table definition["content"].extend([ f"\nEach `{defn}` has the following fields:\n\n", - "::::{tab-set}\n\n", - ":::{tab-item} Schema\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(definition['properties'].keys())}\n" "```\n\n", - ":::\n\n", - ":::{tab-item} Examples\n\n" + "````\n\n", + "````{tab-item} Examples\n\n" ]) # Add examples @@ -296,8 +296,8 @@ def update_sub_schema_reference(schema): ]) definition["content"].extend([ - ":::\n\n", - "::::\n\n" + "````\n\n", + "`````\n\n" ]) schema_reference.extend(definition["content"]) diff --git a/requirements.txt b/requirements.txt index ec4284ce..d4b68ddf 100644 --- a/requirements.txt +++ b/requirements.txt @@ -7,6 +7,7 @@ sphinxcontrib-opencontracting==0.0.3 # sphinxcontrib-opendataservices-jsonschema==0.5.0 -e git+https://github.com/jpmckinney/sphinxcontrib-opendataservices-jsonschema.git@upgrade-jsonref#egg=sphinxcontrib-opendataservices-jsonschema sphinxcontrib-opendataservices==0.5.0 +sphinx-tabs # Build jsonref From 3dacc5bc84e5058940f092daa7a6eb92ca74e46b Mon Sep 17 00:00:00 2001 From: Duncan Dewhurst Date: Fri, 11 Nov 2022 16:33:37 +1300 Subject: [PATCH 06/24] manage.py: Fix lint errors --- manage.py | 274 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 141 insertions(+), 133 deletions(-) diff --git a/manage.py b/manage.py index 4a43165f..317ce9ca 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 / 'reference' def get(url): @@ -164,146 +165,153 @@ def compare(actual, infra_list, ocds_list, prefix, suffix): def get_definition_references(schema, defn, parents=None, project_schema=None): - """ - Recursively generate a list of JSON pointers that reference a definition in JSON schema. - - :param schema: The JSON schema - :defn: The name of the definition - :parents: A list of the parents of schema - :project_schema: The full project schema - """ - - 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']) - else: - references.extend(get_definition_references(project_schema['definitions'][value['items']['$ref'].split('/')[-1]], defn, parents + [key, '0'], project_schema)) - elif '$ref' in value: - if value['$ref'] == f"#/definitions/{defn}": - references.append(parents + [key]) - else: - references.extend(get_definition_references(project_schema['definitions'][value['$ref'].split('/')[-1]], defn, parents + [key], project_schema)) - elif 'properties' in value: - references.extend(get_definition_references(value, defn, parents + [key], project_schema)) - - if 'definitions' in schema: - for key, value in schema['definitions'].items(): - references.extend(get_definition_references(value, defn, [key], project_schema)) - - return references + """ + Recursively generate a list of JSON pointers that reference a definition in JSON schema. + + :param schema: The JSON schema + :defn: The name of the definition + :parents: A list of the parents of schema + :project_schema: The full project schema + """ + + 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']) + else: + references.extend(get_definition_references( + project_schema['definitions'][value['items']['$ref'].split('/')[-1]], + defn, + parents + [key, '0'], + project_schema)) + elif '$ref' in value: + if value['$ref'] == f"#/definitions/{defn}": + references.append(parents + [key]) + else: + references.extend(get_definition_references( + project_schema['definitions'][value['$ref'].split('/')[-1]], + defn, + parents + [key], + project_schema)) + elif 'properties' in value: + references.extend(get_definition_references(value, defn, parents + [key], project_schema)) + + if 'definitions' in schema: + for key, value in schema['definitions'].items(): + references.extend(get_definition_references(value, defn, [key], project_schema)) + + 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}"): - while j < len(schema_reference) and not schema_reference[j].startswith("```{jsonschema}"): - 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", - "```{jsoninclude-quote} ../../schema/project-level/project-schema.json\n", - f":jsonpointer: /definitions/{defn}/description\n", - "```\n\n" - ]) - - # Add a list of properties that reference this definition - definition["references"] = get_definition_references(schema, defn) - definition["content"].append("This sub-schema is referenced by the following properties:\n") - - for ref in definition["references"]: - # 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'] - - # Ideally, these would be relative links - see https://github.com/OpenDataServices/sphinxcontrib-opendataservices/issues/43 - url = 'https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#project-schema.json,' - - # Omit nested references - if ref[0] in schema['definitions'] and len(ref) == 2: - url += '/definitions/' - elif len(ref) == 1: - url += ',' - else: - continue - - url += ','.join(ref) - definition["content"].append(f"* [`{'/'.join(ref)}`]({url})\n") - - # Add schema table - 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(definition['properties'].keys())}\n" - "```\n\n", - "````\n\n", - "````{tab-item} Examples\n\n" - ]) - - # Add examples - for ref in definition["references"]: - if ref[0] not in schema['definitions']: - if ref[-1] == '0': - ref.pop(-1) - - definition["content"].extend([ - "```{eval-rst}\n", - ".. jsoninclude:: ../../docs/examples/example.json\n", - f" :jsonpointer: /projects/0/{'/'.join(ref)}\n", - f" :title: {'/'.join(ref)}\n", + """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}"): + 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", + "```{jsoninclude-quote} ../../schema/project-level/project-schema.json\n", + f":jsonpointer: /definitions/{defn}/description\n", "```\n\n" - ]) + ]) + + # Add a list of properties that reference this definition + definition["references"] = get_definition_references(schema, defn) + definition["content"].append("This sub-schema is referenced by the following properties:\n") - definition["content"].extend([ - "````\n\n", - "`````\n\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'] - schema_reference.extend(definition["content"]) + # noqa: Ideally, these would be relative links - see https://github.com/OpenDataServices/sphinxcontrib-opendataservices/issues/43 + url = 'https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#project-schema.json,' # noqa - with (referencedir/ 'schema.md').open('w') as f: - f.writelines(schema_reference) + # Omit nested references + if ref[0] in schema['definitions'] and len(ref) == 2: + url += '/definitions/' + elif len(ref) == 1: + url += ',' + else: + continue + + url += ','.join(ref) + definition["content"].append(f"* [`{'/'.join(ref)}`]({url})\n") + + # Add schema table + 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(definition['properties'].keys())}\n" + "```\n\n", + "````\n\n", + "````{tab-item} Examples\n\n" + ]) + + # Add examples + for ref in definition["references"]: + if ref[0] not in schema['definitions']: + if ref[-1] == '0': + ref.pop(-1) + + definition["content"].extend([ + "```{eval-rst}\n", + ".. 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"]) + + with (referencedir / 'schema.md').open('w') as f: + f.writelines(schema_reference) @click.group() From 5268c141fd4ed969b15d1cc3a1e6ee30631b43b9 Mon Sep 17 00:00:00 2001 From: James McKinney <26463+jpmckinney@users.noreply.github.com> Date: Thu, 1 Dec 2022 15:29:59 -0500 Subject: [PATCH 07/24] feat: Fix manage.py and update requirements to run make --- common-requirements.txt | 28 ++- docs/_static/i18n.csv | 2 +- docs/conf.py | 2 - docs/examples/example.json | 6 +- docs/reference/schema.md | 436 ++++++++++++++++++------------------- manage.py | 21 +- requirements.txt | 2 +- 7 files changed, 249 insertions(+), 248 deletions(-) diff --git a/common-requirements.txt b/common-requirements.txt index 4c78daee..3e912940 100644 --- a/common-requirements.txt +++ b/common-requirements.txt @@ -43,7 +43,7 @@ cryptography==36.0.2 # via # pyopenssl # urllib3 -docutils==0.16 +docutils==0.18 # via # myst-parser # sphinx @@ -62,11 +62,13 @@ idna==2.10 # requests # trio # urllib3 -imagesize==1.2.0 +imagesize==1.4.1 + # via sphinx +importlib-metadata==5.1.0 # via sphinx iniconfig==1.1.1 # via pytest -jinja2==2.11.3 +jinja2==3.1.2 # via # myst-parser # sphinx @@ -84,11 +86,11 @@ markdown-it-py==1.0.0 # via # mdit-py-plugins # myst-parser -markupsafe==1.1.1 +markupsafe==2.1.1 # via jinja2 -mdit-py-plugins==0.2.8 +mdit-py-plugins==0.3.1 # via myst-parser -myst-parser==0.15.1 +myst-parser==0.18.1 # via -r common-requirements.in ocds-babel==0.3.1 # via -r common-requirements.in @@ -98,7 +100,7 @@ ocdsindex==0.0.7 # via -r common-requirements.in outcome==1.1.0 # via trio -packaging==20.9 +packaging==21.3 # via # pytest # sphinx @@ -110,7 +112,7 @@ pluggy==0.13.1 # via pytest pycparser==2.21 # via cffi -pygments==2.8.1 +pygments==2.13.0 # via sphinx pyopenssl==22.0.0 # via urllib3 @@ -148,7 +150,7 @@ snowballstemmer==2.1.0 # via sphinx sortedcontainers==2.4.0 # via trio -sphinx==3.5.2 +sphinx==5.3.0 # via # -r common-requirements.in # myst-parser @@ -162,13 +164,13 @@ sphinxcontrib-applehelp==1.0.2 # via sphinx sphinxcontrib-devhelp==1.0.2 # via sphinx -sphinxcontrib-htmlhelp==1.0.3 +sphinxcontrib-htmlhelp==2.0.0 # via sphinx sphinxcontrib-jsmath==1.0.1 # via sphinx sphinxcontrib-qthelp==1.0.3 # via sphinx -sphinxcontrib-serializinghtml==1.1.4 +sphinxcontrib-serializinghtml==1.1.5 # via sphinx text-unidecode==1.3 # via python-slugify @@ -186,6 +188,8 @@ trio==0.20.0 # trio-websocket trio-websocket==0.9.2 # via selenium +typing-extensions==4.4.0 + # via myst-parser uc-micro-py==1.0.1 # via linkify-it-py urllib3[secure,socks]==1.26.5 @@ -198,6 +202,8 @@ wheel==0.37.0 # via pip-tools wsproto==1.1.0 # via trio-websocket +zipp==3.11.0 + # via importlib-metadata # The following packages are considered to be unsafe in a requirements file: # pip 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 f011fac0..5d6d8fcb 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -86,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 ebe540df..2ae5e1db 100644 --- a/docs/examples/example.json +++ b/docs/examples/example.json @@ -408,7 +408,8 @@ "period": { "startDate": "2018-01-07T00:00:00Z", "endDate": "2018-01-07T00:00:00Z" - } + }, + "value": {} }, { "id": "2", @@ -455,7 +456,8 @@ "period": { "startDate": "2018-01-07T00:00:00Z", "endDate": "2018-01-07T00:00:00Z" - } + }, + "value": {} }, { "id": "2", diff --git a/docs/reference/schema.md b/docs/reference/schema.md index d16dfa94..d39a5472 100644 --- a/docs/reference/schema.md +++ b/docs/reference/schema.md @@ -21,6 +21,7 @@ Each project has the following fields: ```{jsonschema} ../../build/current_lang/project-schema.json :include: :collapse: period,additionalClassifications,relatedProjects,assetLifetime,locations,budget/amount,budget/budgetBreakdown,forecasts,parties,publicAuthority,documents,contractingProcesses,metrics,completion/finalValue +:addtargets: ``` ## Sub-schemas @@ -35,7 +36,7 @@ This section lists each sub-schema in the OC4IDS schema. Some sub-schemas are re ``` This sub-schema is referenced by the following properties: -* [`contractingProcesses`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#project-schema.json,,contractingProcesses) +* [`contractingProcesses`](project-schema.json,,contractingProcesses) Each `ContractingProcess` has the following fields: @@ -46,16 +47,16 @@ Each `ContractingProcess` has the following fields: ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/ContractingProcess :collapse: id,summary,releases +:addtargets: ``` ```` ````{tab} Examples -```{eval-rst} -.. jsoninclude:: ../../docs/examples/example.json - :jsonpointer: /projects/0/contractingProcesses - :title: contractingProcesses +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/contractingProcesses +:title: contractingProcesses ``` ```` @@ -70,7 +71,7 @@ Each `ContractingProcess` has the following fields: ``` This sub-schema is referenced by the following properties: -* [`ContractingProcess/summary`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#project-schema.json,/definitions/ContractingProcess,summary) +* [`ContractingProcess/summary`](project-schema.json,/definitions/ContractingProcess,summary) Each `ContractingProcessSummary` has the following fields: @@ -81,16 +82,16 @@ Each `ContractingProcessSummary` has the following fields: ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/ContractingProcessSummary :collapse: ocid,externalReference,nature,title,description,status,tender,suppliers,contractValue,contractPeriod,finalValue,documents,modifications,transactions +:addtargets: ``` ```` ````{tab} Examples -```{eval-rst} -.. jsoninclude:: ../../docs/examples/example.json - :jsonpointer: /projects/0/contractingProcesses/0/summary - :title: contractingProcesses/0/summary +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/contractingProcesses/0/summary +:title: contractingProcesses/0/summary ``` ```` @@ -105,7 +106,7 @@ Each `ContractingProcessSummary` has the following fields: ``` This sub-schema is referenced by the following properties: -* [`ContractingProcess/releases`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#project-schema.json,/definitions/ContractingProcess,releases) +* [`ContractingProcess/releases`](project-schema.json,/definitions/ContractingProcess,releases) Each `LinkedRelease` has the following fields: @@ -116,16 +117,16 @@ Each `LinkedRelease` has the following fields: ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/LinkedRelease :collapse: id,tag,date,url +:addtargets: ``` ```` ````{tab} Examples -```{eval-rst} -.. jsoninclude:: ../../docs/examples/example.json - :jsonpointer: /projects/0/contractingProcesses/0/releases - :title: contractingProcesses/0/releases +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/contractingProcesses/0/releases +:title: contractingProcesses/0/releases ``` ```` @@ -143,7 +144,7 @@ For each modification, the following structured information can be provided. ``` This sub-schema is referenced by the following properties: -* [`ContractingProcessSummary/modifications`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#project-schema.json,/definitions/ContractingProcessSummary,modifications) +* [`ContractingProcessSummary/modifications`](project-schema.json,/definitions/ContractingProcessSummary,modifications) Each `Modification` has the following fields: @@ -154,16 +155,16 @@ Each `Modification` has the following fields: ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/Modification :collapse: id,date,description,rationale,type,releaseID,oldContractValue,newContractValue,oldContractPeriod,newContractPeriod +:addtargets: ``` ```` ````{tab} Examples -```{eval-rst} -.. jsoninclude:: ../../docs/examples/example.json - :jsonpointer: /projects/0/contractingProcesses/0/summary/modifications - :title: contractingProcesses/0/summary/modifications +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/contractingProcesses/0/summary/modifications +:title: contractingProcesses/0/summary/modifications ``` ```` @@ -185,13 +186,13 @@ Where the source system does not contain time information, a judgment ought to b ``` This sub-schema is referenced by the following properties: -* [`period`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#project-schema.json,,period) -* [`assetLifetime`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#project-schema.json,,assetLifetime) -* [`ContractingProcessSummary/contractPeriod`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#project-schema.json,/definitions/ContractingProcessSummary,contractPeriod) -* [`Modification/oldContractPeriod`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#project-schema.json,/definitions/Modification,oldContractPeriod) -* [`Modification/newContractPeriod`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#project-schema.json,/definitions/Modification,newContractPeriod) -* [`BudgetBreakdown/period`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#project-schema.json,/definitions/BudgetBreakdown,period) -* [`Observation/period`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#project-schema.json,/definitions/Observation,period) +* [`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: @@ -202,58 +203,51 @@ Each `Period` has the following fields: ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/Period :collapse: startDate,endDate,maxExtentDate,durationInDays +:addtargets: ``` ```` ````{tab} Examples -```{eval-rst} -.. jsoninclude:: ../../docs/examples/example.json - :jsonpointer: /projects/0/period - :title: period +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/period +:title: period ``` -```{eval-rst} -.. jsoninclude:: ../../docs/examples/example.json - :jsonpointer: /projects/0/assetLifetime - :title: assetLifetime +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/assetLifetime +:title: assetLifetime ``` -```{eval-rst} -.. 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/budget/budgetBreakdown/0/period +:title: budget/budgetBreakdown/0/period ``` -```{eval-rst} -.. 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/forecasts/0/observations/0/period +:title: forecasts/0/observations/0/period ``` -```{eval-rst} -.. 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/contractPeriod +:title: contractingProcesses/0/summary/contractPeriod ``` -```{eval-rst} -.. 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/oldContractPeriod +:title: contractingProcesses/0/summary/modifications/0/oldContractPeriod ``` -```{eval-rst} -.. 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/contractingProcesses/0/summary/modifications/0/newContractPeriod +:title: contractingProcesses/0/summary/modifications/0/newContractPeriod ``` -```{eval-rst} -.. jsoninclude:: ../../docs/examples/example.json - :jsonpointer: /projects/0/metrics/0/observations/0/period - :title: metrics/0/observations/0/period +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/metrics/0/observations/0/period +:title: metrics/0/observations/0/period ``` ```` @@ -271,7 +265,7 @@ A classification consists of an identifier for the codelist (the `scheme`) and a ``` This sub-schema is referenced by the following properties: -* [`additionalClassifications`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#project-schema.json,,additionalClassifications) +* [`additionalClassifications`](project-schema.json,,additionalClassifications) Each `Classification` has the following fields: @@ -282,16 +276,16 @@ Each `Classification` has the following fields: ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/Classification :collapse: scheme,id,description,uri +:addtargets: ``` ```` ````{tab} Examples -```{eval-rst} -.. jsoninclude:: ../../docs/examples/example.json - :jsonpointer: /projects/0/additionalClassifications - :title: additionalClassifications +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/additionalClassifications +:title: additionalClassifications ``` ```` @@ -313,7 +307,7 @@ A project can have one or more locations. Locations can be expressed in a number ``` This sub-schema is referenced by the following properties: -* [`locations`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#project-schema.json,,locations) +* [`locations`](project-schema.json,,locations) Each `Location` has the following fields: @@ -324,16 +318,16 @@ Each `Location` has the following fields: ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/Location :collapse: id,description,geometry,gazetteer,uri,address +:addtargets: ``` ```` ````{tab} Examples -```{eval-rst} -.. jsoninclude:: ../../docs/examples/example.json - :jsonpointer: /projects/0/locations - :title: locations +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/locations +:title: locations ``` ```` @@ -351,13 +345,13 @@ All values should be published along with their currency using the following str ``` This sub-schema is referenced by the following properties: -* [`ContractingProcessSummary/contractValue`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#project-schema.json,/definitions/ContractingProcessSummary,contractValue) -* [`ContractingProcessSummary/finalValue`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#project-schema.json,/definitions/ContractingProcessSummary,finalValue) -* [`Modification/oldContractValue`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#project-schema.json,/definitions/Modification,oldContractValue) -* [`Modification/newContractValue`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#project-schema.json,/definitions/Modification,newContractValue) -* [`BudgetBreakdown/amount`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#project-schema.json,/definitions/BudgetBreakdown,amount) -* [`Observation/value`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#project-schema.json,/definitions/Observation,value) -* [`Transaction/value`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#project-schema.json,/definitions/Transaction,value) +* [`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: @@ -368,52 +362,66 @@ Each `Value` has the following fields: ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/Value :collapse: amount,currency +:addtargets: ``` ```` ````{tab} Examples -```{eval-rst} -.. jsoninclude:: ../../docs/examples/example.json - :jsonpointer: /projects/0/budget/amount - :title: budget/amount +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/budget/amount +:title: budget/amount ``` -```{eval-rst} -.. 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/budget/budgetBreakdown/0/amount +:title: budget/budgetBreakdown/0/amount ``` -```{eval-rst} -.. 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/forecasts/0/observations/0/value +:title: forecasts/0/observations/0/value ``` -```{eval-rst} -.. 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/tender/costEstimate +:title: contractingProcesses/0/summary/tender/costEstimate ``` -```{eval-rst} -.. 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/contractValue +:title: contractingProcesses/0/summary/contractValue ``` -```{eval-rst} -.. 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/contractingProcesses/0/summary/finalValue +:title: contractingProcesses/0/summary/finalValue ``` -```{eval-rst} -.. jsoninclude:: ../../docs/examples/example.json - :jsonpointer: /projects/0/completion/finalValue - :title: completion/finalValue +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/contractingProcesses/0/summary/modifications/2/oldContractValue +:title: contractingProcesses/0/summary/modifications/2/oldContractValue +``` + +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/contractingProcesses/0/summary/modifications/2/newContractValue +:title: contractingProcesses/0/summary/modifications/2/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/metrics/0/observations/0/value +:title: metrics/0/observations/0/value +``` + +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/completion/finalValue +:title: completion/finalValue ``` ```` @@ -431,7 +439,7 @@ For each organization, provide as much structured data as you can. ``` This sub-schema is referenced by the following properties: -* [`parties`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#project-schema.json,,parties) +* [`parties`](project-schema.json,,parties) Each `Organization` has the following fields: @@ -442,16 +450,16 @@ Each `Organization` has the following fields: ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/Organization :collapse: name,id,identifier,additionalIdentifiers,address,contactPoint,roles,people +:addtargets: ``` ```` ````{tab} Examples -```{eval-rst} -.. jsoninclude:: ../../docs/examples/example.json - :jsonpointer: /projects/0/parties - :title: parties +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/parties +:title: parties ``` ```` @@ -467,11 +475,11 @@ Each `Organization` has the following fields: ``` This sub-schema is referenced by the following properties: -* [`publicAuthority`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#project-schema.json,,publicAuthority) -* [`ContractingProcessSummary/suppliers`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#project-schema.json,/definitions/ContractingProcessSummary,suppliers) -* [`BudgetBreakdown/sourceParty`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#project-schema.json,/definitions/BudgetBreakdown,sourceParty) -* [`Transaction/payer`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#project-schema.json,/definitions/Transaction,payer) -* [`Transaction/payee`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#project-schema.json,/definitions/Transaction,payee) +* [`publicAuthority`](project-schema.json,,publicAuthority) +* [`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: @@ -482,58 +490,51 @@ Each `OrganizationReference` has the following fields: ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/OrganizationReference :collapse: name,id +:addtargets: ``` ```` ````{tab} Examples -```{eval-rst} -.. 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/budget/budgetBreakdown/0/sourceParty +:title: budget/budgetBreakdown/0/sourceParty ``` -```{eval-rst} -.. jsoninclude:: ../../docs/examples/example.json - :jsonpointer: /projects/0/publicAuthority - :title: publicAuthority +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/publicAuthority +:title: publicAuthority ``` -```{eval-rst} -.. 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/tenderers +:title: contractingProcesses/0/summary/tender/tenderers ``` -```{eval-rst} -.. 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/procuringEntity +:title: contractingProcesses/0/summary/tender/procuringEntity ``` -```{eval-rst} -.. 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/tender/administrativeEntity +:title: contractingProcesses/0/summary/tender/administrativeEntity ``` -```{eval-rst} -.. 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/suppliers +:title: contractingProcesses/0/summary/suppliers ``` -```{eval-rst} -.. 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/payer +:title: contractingProcesses/0/summary/transactions/0/payer ``` -```{eval-rst} -.. jsoninclude:: ../../docs/examples/example.json - :jsonpointer: /projects/0/contractingProcesses/0/summary/transactions/0/payee - :title: contractingProcesses/0/summary/transactions/0/payee +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/contractingProcesses/0/summary/transactions/0/payee +:title: contractingProcesses/0/summary/transactions/0/payee ``` ```` @@ -553,8 +554,8 @@ When working with data, users ought to be aware that addresses might not always ``` This sub-schema is referenced by the following properties: -* [`Location/address`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#project-schema.json,/definitions/Location,address) -* [`Organization/address`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#project-schema.json,/definitions/Organization,address) +* [`Location/address`](project-schema.json,/definitions/Location,address) +* [`Organization/address`](project-schema.json,/definitions/Organization,address) Each `Address` has the following fields: @@ -565,22 +566,21 @@ Each `Address` has the following fields: ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/Address :collapse: streetAddress,locality,region,postalCode,countryName +:addtargets: ``` ```` ````{tab} Examples -```{eval-rst} -.. jsoninclude:: ../../docs/examples/example.json - :jsonpointer: /projects/0/locations/0/address - :title: locations/0/address +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/locations/0/address +:title: locations/0/address ``` -```{eval-rst} -.. jsoninclude:: ../../docs/examples/example.json - :jsonpointer: /projects/0/parties/0/address - :title: parties/0/address +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/parties/0/address +:title: parties/0/address ``` ```` @@ -596,7 +596,7 @@ Each `Address` has the following fields: ``` This sub-schema is referenced by the following properties: -* [`Organization/contactPoint`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#project-schema.json,/definitions/Organization,contactPoint) +* [`Organization/contactPoint`](project-schema.json,/definitions/Organization,contactPoint) Each `ContactPoint` has the following fields: @@ -607,16 +607,16 @@ Each `ContactPoint` has the following fields: ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/ContactPoint :collapse: name,email,telephone,faxNumber,url +:addtargets: ``` ```` ````{tab} Examples -```{eval-rst} -.. jsoninclude:: ../../docs/examples/example.json - :jsonpointer: /projects/0/parties/0/contactPoint - :title: parties/0/contactPoint +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/parties/0/contactPoint +:title: parties/0/contactPoint ``` ```` @@ -645,17 +645,17 @@ Each `BudgetBreakdown` has the following fields: ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/BudgetBreakdown -:collapse: id,description,amount,uri,period,sourceParty +:collapse: id,description,amount,approvalDate,uri,period,sourceParty +:addtargets: ``` ```` ````{tab} Examples -```{eval-rst} -.. jsoninclude:: ../../docs/examples/example.json - :jsonpointer: /projects/0/budget/budgetBreakdown - :title: budget/budgetBreakdown +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/budget/budgetBreakdown +:title: budget/budgetBreakdown ``` ```` @@ -673,8 +673,8 @@ For each document the following structured information can be provided. ``` This sub-schema is referenced by the following properties: -* [`documents`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#project-schema.json,,documents) -* [`ContractingProcessSummary/documents`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#project-schema.json,/definitions/ContractingProcessSummary,documents) +* [`documents`](project-schema.json,,documents) +* [`ContractingProcessSummary/documents`](project-schema.json,/definitions/ContractingProcessSummary,documents) Each `Document` has the following fields: @@ -685,22 +685,21 @@ Each `Document` has the following fields: ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/Document :collapse: id,documentType,title,description,url,datePublished,dateModified,format,language,pageStart,pageEnd,accessDetails,author +:addtargets: ``` ```` ````{tab} Examples -```{eval-rst} -.. jsoninclude:: ../../docs/examples/example.json - :jsonpointer: /projects/0/documents - :title: documents +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/documents +:title: documents ``` -```{eval-rst} -.. jsoninclude:: ../../docs/examples/example.json - :jsonpointer: /projects/0/contractingProcesses/0/summary/documents - :title: contractingProcesses/0/summary/documents +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/contractingProcesses/0/summary/documents +:title: contractingProcesses/0/summary/documents ``` ```` @@ -722,8 +721,8 @@ For example, if identifying a company in Colombia, look up its identifier in the ``` This sub-schema is referenced by the following properties: -* [`Organization/identifier`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#project-schema.json,/definitions/Organization,identifier) -* [`Organization/additionalIdentifiers`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#project-schema.json,/definitions/Organization,additionalIdentifiers) +* [`Organization/identifier`](project-schema.json,/definitions/Organization,identifier) +* [`Organization/additionalIdentifiers`](project-schema.json,/definitions/Organization,additionalIdentifiers) Each `Identifier` has the following fields: @@ -734,22 +733,21 @@ Each `Identifier` has the following fields: ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/Identifier :collapse: scheme,id,legalName,uri +:addtargets: ``` ```` ````{tab} Examples -```{eval-rst} -.. jsoninclude:: ../../docs/examples/example.json - :jsonpointer: /projects/0/parties/0/identifier - :title: parties/0/identifier +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/parties/0/identifier +:title: parties/0/identifier ``` -```{eval-rst} -.. jsoninclude:: ../../docs/examples/example.json - :jsonpointer: /projects/0/parties/0/additionalIdentifiers - :title: parties/0/additionalIdentifiers +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/parties/0/additionalIdentifiers +:title: parties/0/additionalIdentifiers ``` ```` @@ -767,7 +765,7 @@ A reference to a project related to the same set of infrastructure assets as the ``` This sub-schema is referenced by the following properties: -* [`relatedProjects`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#project-schema.json,,relatedProjects) +* [`relatedProjects`](project-schema.json,,relatedProjects) Each `RelatedProject` has the following fields: @@ -778,16 +776,16 @@ Each `RelatedProject` has the following fields: ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/RelatedProject :collapse: id,scheme,identifier,relationship,title,uri +:addtargets: ``` ```` ````{tab} Examples -```{eval-rst} -.. jsoninclude:: ../../docs/examples/example.json - :jsonpointer: /projects/0/relatedProjects - :title: relatedProjects +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/relatedProjects +:title: relatedProjects ``` ```` @@ -802,8 +800,8 @@ Each `RelatedProject` has the following fields: ``` This sub-schema is referenced by the following properties: -* [`forecasts`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#project-schema.json,,forecasts) -* [`metrics`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#project-schema.json,,metrics) +* [`forecasts`](project-schema.json,,forecasts) +* [`metrics`](project-schema.json,,metrics) Each `Metric` has the following fields: @@ -814,22 +812,21 @@ Each `Metric` has the following fields: ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/Metric :collapse: id,title,description,observations +:addtargets: ``` ```` ````{tab} Examples -```{eval-rst} -.. jsoninclude:: ../../docs/examples/example.json - :jsonpointer: /projects/0/forecasts - :title: forecasts +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/forecasts +:title: forecasts ``` -```{eval-rst} -.. jsoninclude:: ../../docs/examples/example.json - :jsonpointer: /projects/0/metrics - :title: metrics +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/metrics +:title: metrics ``` ```` @@ -844,7 +841,7 @@ Each `Metric` has the following fields: ``` This sub-schema is referenced by the following properties: -* [`Metric/observations`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#project-schema.json,/definitions/Metric,observations) +* [`Metric/observations`](project-schema.json,/definitions/Metric,observations) Each `Observation` has the following fields: @@ -855,22 +852,21 @@ Each `Observation` has the following fields: ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/Observation :collapse: id,period,value,measure,unit,dimensions,notes +:addtargets: ``` ```` ````{tab} Examples -```{eval-rst} -.. jsoninclude:: ../../docs/examples/example.json - :jsonpointer: /projects/0/forecasts/0/observations - :title: forecasts/0/observations +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/forecasts/0/observations +:title: forecasts/0/observations ``` -```{eval-rst} -.. jsoninclude:: ../../docs/examples/example.json - :jsonpointer: /projects/0/metrics/0/observations - :title: metrics/0/observations +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/metrics/0/observations +:title: metrics/0/observations ``` ```` @@ -888,7 +884,7 @@ Use this object when you need to disclose the details of people associated with, ``` This sub-schema is referenced by the following properties: -* [`Organization/people`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#project-schema.json,/definitions/Organization,people) +* [`Organization/people`](project-schema.json,/definitions/Organization,people) Each `Person` has the following fields: @@ -899,16 +895,16 @@ Each `Person` has the following fields: ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/Person :collapse: id,name,jobTitle +:addtargets: ``` ```` ````{tab} Examples -```{eval-rst} -.. jsoninclude:: ../../docs/examples/example.json - :jsonpointer: /projects/0/parties/0/people - :title: parties/0/people +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0/parties/0/people +:title: parties/0/people ``` ```` @@ -926,7 +922,7 @@ A spending transaction related to a contracting process. ``` This sub-schema is referenced by the following properties: -* [`ContractingProcessSummary/transactions`](https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#project-schema.json,/definitions/ContractingProcessSummary,transactions) +* [`ContractingProcessSummary/transactions`](project-schema.json,/definitions/ContractingProcessSummary,transactions) Each `Transaction` has the following fields: @@ -937,16 +933,16 @@ Each `Transaction` has the following fields: ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/Transaction :collapse: id,source,date,value,payer,payee,uri +:addtargets: ``` ```` ````{tab} Examples -```{eval-rst} -.. jsoninclude:: ../../docs/examples/example.json - :jsonpointer: /projects/0/contractingProcesses/0/summary/transactions - :title: contractingProcesses/0/summary/transactions +```{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 317ce9ca..6f15e326 100755 --- a/manage.py +++ b/manage.py @@ -16,7 +16,7 @@ from ocdskit.schema import add_validation_properties basedir = Path(__file__).resolve().parent -referencedir = basedir / 'reference' +referencedir = basedir / 'docs' / 'reference' def get(url): @@ -231,7 +231,7 @@ def update_sub_schema_reference(schema): schema["definitions"][defn]["content"] = [] j = i+1 - while j < len(schema_reference) and not schema_reference[j].startswith(f"{defn}"): + 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 @@ -262,8 +262,7 @@ def update_sub_schema_reference(schema): # 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'] - # noqa: Ideally, these would be relative links - see https://github.com/OpenDataServices/sphinxcontrib-opendataservices/issues/43 - url = 'https://standard.open-contracting.org/infrastructure/latest/en/reference/schema/index.html#project-schema.json,' # noqa + url = 'project-schema.json,' # Omit nested references if ref[0] in schema['definitions'] and len(ref) == 2: @@ -279,14 +278,15 @@ def update_sub_schema_reference(schema): # Add schema table definition["content"].extend([ f"\nEach `{defn}` has the following fields:\n\n", - "`````{tab-set}\n\n", - "````{tab-item} Schema\n\n", + "`````{tabs}\n\n", + "````{tab} Schema\n\n", "```{jsonschema} ../../schema/project-level/project-schema.json\n", f":pointer: /definitions/{defn}\n", f":collapse: {','.join(definition['properties'].keys())}\n" + ":addtargets:\n" "```\n\n", "````\n\n", - "````{tab-item} Examples\n\n" + "````{tab} Examples\n\n" ]) # Add examples @@ -296,10 +296,9 @@ def update_sub_schema_reference(schema): ref.pop(-1) definition["content"].extend([ - "```{eval-rst}\n", - ".. jsoninclude:: ../../docs/examples/example.json\n", - f" :jsonpointer: /projects/0/{'/'.join(ref)}\n", - f" :title: {'/'.join(ref)}\n", + "```{jsoninclude} ../../docs/examples/example.json\n", + f":jsonpointer: /projects/0/{'/'.join(ref)}\n", + f":title: {'/'.join(ref)}\n", "```\n\n" ]) diff --git a/requirements.txt b/requirements.txt index d70da2b9..beb36c1a 100644 --- a/requirements.txt +++ b/requirements.txt @@ -2,7 +2,7 @@ # Add your own requirements below. -sphinxcontrib-opencontracting==0.0.3 +sphinxcontrib-opencontracting==0.0.8 sphinxcontrib-opendataservices-jsonschema==0.5.1 sphinxcontrib-opendataservices==0.5.0 sphinx-tabs==3.4.1 From c558d19bf529d1a274dcc313017f2b73be71ffee Mon Sep 17 00:00:00 2001 From: Duncan Dewhurst Date: Wed, 15 Feb 2023 13:46:41 +1300 Subject: [PATCH 08/24] docs/reference/schema.md: Use sphinx-design tabs --- docs/conf.py | 4 +- docs/reference/schema.md | 243 +++++++++++++++++++-------------------- manage.py | 12 +- requirements.txt | 2 +- 4 files changed, 130 insertions(+), 131 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 5d6d8fcb..5e1a8985 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -42,7 +42,7 @@ 'sphinxcontrib.jsonschema', 'sphinxcontrib.opencontracting', 'sphinxcontrib.opendataservices', - 'sphinx_tabs.tabs' + 'sphinx_design' ] # Add any paths that contain templates here, relative to this directory. @@ -86,7 +86,7 @@ smartquotes = False # MyST configuration. -myst_enable_extensions = ['linkify'] +myst_enable_extensions = ['linkify', 'colon_fence'] myst_heading_anchors = 6 myst_heading_slug_func = make_id diff --git a/docs/reference/schema.md b/docs/reference/schema.md index d39a5472..2052565e 100644 --- a/docs/reference/schema.md +++ b/docs/reference/schema.md @@ -26,7 +26,7 @@ Each project has the following fields: ## Sub-schemas -This section lists each sub-schema in the OC4IDS schema. Some sub-schemas are referenced in multiple places in the schema. +This section lists each sub-schema in the OC4IDS schema. Some sub-schemas are referenced from multiple places in the schema. ### ContractingProcess `ContractingProcess` is defined as: @@ -40,9 +40,9 @@ This sub-schema is referenced by the following properties: Each `ContractingProcess` has the following fields: -`````{tabs} +:::::{tab-set} -````{tab} Schema +::::{tab-item} Schema ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/ContractingProcess @@ -50,18 +50,18 @@ Each `ContractingProcess` has the following fields: :addtargets: ``` -```` +:::: -````{tab} Examples +::::{tab-item} Examples ```{jsoninclude} ../../docs/examples/example.json :jsonpointer: /projects/0/contractingProcesses :title: contractingProcesses ``` -```` +:::: -````` +::::: ### ContractingProcessSummary `ContractingProcessSummary` is defined as: @@ -75,9 +75,9 @@ This sub-schema is referenced by the following properties: Each `ContractingProcessSummary` has the following fields: -`````{tabs} +:::::{tab-set} -````{tab} Schema +::::{tab-item} Schema ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/ContractingProcessSummary @@ -85,18 +85,18 @@ Each `ContractingProcessSummary` has the following fields: :addtargets: ``` -```` +:::: -````{tab} Examples +::::{tab-item} Examples ```{jsoninclude} ../../docs/examples/example.json :jsonpointer: /projects/0/contractingProcesses/0/summary :title: contractingProcesses/0/summary ``` -```` +:::: -````` +::::: ### LinkedRelease `LinkedRelease` is defined as: @@ -110,9 +110,9 @@ This sub-schema is referenced by the following properties: Each `LinkedRelease` has the following fields: -`````{tabs} +:::::{tab-set} -````{tab} Schema +::::{tab-item} Schema ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/LinkedRelease @@ -120,18 +120,18 @@ Each `LinkedRelease` has the following fields: :addtargets: ``` -```` +:::: -````{tab} Examples +::::{tab-item} Examples ```{jsoninclude} ../../docs/examples/example.json :jsonpointer: /projects/0/contractingProcesses/0/releases :title: contractingProcesses/0/releases ``` -```` +:::: -````` +::::: ### Modification @@ -148,9 +148,9 @@ This sub-schema is referenced by the following properties: Each `Modification` has the following fields: -`````{tabs} +:::::{tab-set} -````{tab} Schema +::::{tab-item} Schema ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/Modification @@ -158,18 +158,18 @@ Each `Modification` has the following fields: :addtargets: ``` -```` +:::: -````{tab} Examples +::::{tab-item} Examples ```{jsoninclude} ../../docs/examples/example.json :jsonpointer: /projects/0/contractingProcesses/0/summary/modifications :title: contractingProcesses/0/summary/modifications ``` -```` +:::: -````` +::::: ### Period @@ -196,9 +196,9 @@ This sub-schema is referenced by the following properties: Each `Period` has the following fields: -`````{tabs} +:::::{tab-set} -````{tab} Schema +::::{tab-item} Schema ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/Period @@ -206,9 +206,9 @@ Each `Period` has the following fields: :addtargets: ``` -```` +:::: -````{tab} Examples +::::{tab-item} Examples ```{jsoninclude} ../../docs/examples/example.json :jsonpointer: /projects/0/period @@ -250,9 +250,9 @@ Each `Period` has the following fields: :title: metrics/0/observations/0/period ``` -```` +:::: -````` +::::: ### Classification @@ -269,9 +269,9 @@ This sub-schema is referenced by the following properties: Each `Classification` has the following fields: -`````{tabs} +:::::{tab-set} -````{tab} Schema +::::{tab-item} Schema ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/Classification @@ -279,18 +279,18 @@ Each `Classification` has the following fields: :addtargets: ``` -```` +:::: -````{tab} Examples +::::{tab-item} Examples ```{jsoninclude} ../../docs/examples/example.json :jsonpointer: /projects/0/additionalClassifications :title: additionalClassifications ``` -```` +:::: -````` +::::: ### Location @@ -311,9 +311,9 @@ This sub-schema is referenced by the following properties: Each `Location` has the following fields: -`````{tabs} +:::::{tab-set} -````{tab} Schema +::::{tab-item} Schema ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/Location @@ -321,18 +321,18 @@ Each `Location` has the following fields: :addtargets: ``` -```` +:::: -````{tab} Examples +::::{tab-item} Examples ```{jsoninclude} ../../docs/examples/example.json :jsonpointer: /projects/0/locations :title: locations ``` -```` +:::: -````` +::::: ### Value @@ -355,9 +355,9 @@ This sub-schema is referenced by the following properties: Each `Value` has the following fields: -`````{tabs} +:::::{tab-set} -````{tab} Schema +::::{tab-item} Schema ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/Value @@ -365,9 +365,9 @@ Each `Value` has the following fields: :addtargets: ``` -```` +:::: -````{tab} Examples +::::{tab-item} Examples ```{jsoninclude} ../../docs/examples/example.json :jsonpointer: /projects/0/budget/amount @@ -424,9 +424,9 @@ Each `Value` has the following fields: :title: completion/finalValue ``` -```` +:::: -````` +::::: ### Organization @@ -443,9 +443,9 @@ This sub-schema is referenced by the following properties: Each `Organization` has the following fields: -`````{tabs} +:::::{tab-set} -````{tab} Schema +::::{tab-item} Schema ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/Organization @@ -453,18 +453,18 @@ Each `Organization` has the following fields: :addtargets: ``` -```` +:::: -````{tab} Examples +::::{tab-item} Examples ```{jsoninclude} ../../docs/examples/example.json :jsonpointer: /projects/0/parties :title: parties ``` -```` +:::: -````` +::::: ### OrganizationReference @@ -483,9 +483,9 @@ This sub-schema is referenced by the following properties: Each `OrganizationReference` has the following fields: -`````{tabs} +:::::{tab-set} -````{tab} Schema +::::{tab-item} Schema ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/OrganizationReference @@ -493,9 +493,9 @@ Each `OrganizationReference` has the following fields: :addtargets: ``` -```` +:::: -````{tab} Examples +::::{tab-item} Examples ```{jsoninclude} ../../docs/examples/example.json :jsonpointer: /projects/0/budget/budgetBreakdown/0/sourceParty @@ -537,9 +537,9 @@ Each `OrganizationReference` has the following fields: :title: contractingProcesses/0/summary/transactions/0/payee ``` -```` +:::: -````` +::::: ### Address @@ -559,9 +559,9 @@ This sub-schema is referenced by the following properties: Each `Address` has the following fields: -`````{tabs} +:::::{tab-set} -````{tab} Schema +::::{tab-item} Schema ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/Address @@ -569,9 +569,9 @@ Each `Address` has the following fields: :addtargets: ``` -```` +:::: -````{tab} Examples +::::{tab-item} Examples ```{jsoninclude} ../../docs/examples/example.json :jsonpointer: /projects/0/locations/0/address @@ -583,9 +583,9 @@ Each `Address` has the following fields: :title: parties/0/address ``` -```` +:::: -````` +::::: ### ContactPoint @@ -600,9 +600,9 @@ This sub-schema is referenced by the following properties: Each `ContactPoint` has the following fields: -`````{tabs} +:::::{tab-set} -````{tab} Schema +::::{tab-item} Schema ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/ContactPoint @@ -610,18 +610,18 @@ Each `ContactPoint` has the following fields: :addtargets: ``` -```` +:::: -````{tab} Examples +::::{tab-item} Examples ```{jsoninclude} ../../docs/examples/example.json :jsonpointer: /projects/0/parties/0/contactPoint :title: parties/0/contactPoint ``` -```` +:::: -````` +::::: ### BudgetBreakdown @@ -639,9 +639,9 @@ This sub-schema is referenced by the following properties: Each `BudgetBreakdown` has the following fields: -`````{tabs} +:::::{tab-set} -````{tab} Schema +::::{tab-item} Schema ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/BudgetBreakdown @@ -649,18 +649,18 @@ Each `BudgetBreakdown` has the following fields: :addtargets: ``` -```` +:::: -````{tab} Examples +::::{tab-item} Examples ```{jsoninclude} ../../docs/examples/example.json :jsonpointer: /projects/0/budget/budgetBreakdown :title: budget/budgetBreakdown ``` -```` +:::: -````` +::::: ### Document @@ -678,9 +678,9 @@ This sub-schema is referenced by the following properties: Each `Document` has the following fields: -`````{tabs} +:::::{tab-set} -````{tab} Schema +::::{tab-item} Schema ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/Document @@ -688,9 +688,9 @@ Each `Document` has the following fields: :addtargets: ``` -```` +:::: -````{tab} Examples +::::{tab-item} Examples ```{jsoninclude} ../../docs/examples/example.json :jsonpointer: /projects/0/documents @@ -702,9 +702,9 @@ Each `Document` has the following fields: :title: contractingProcesses/0/summary/documents ``` -```` +:::: -````` +::::: ### Identifier @@ -726,9 +726,9 @@ This sub-schema is referenced by the following properties: Each `Identifier` has the following fields: -`````{tabs} +:::::{tab-set} -````{tab} Schema +::::{tab-item} Schema ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/Identifier @@ -736,9 +736,9 @@ Each `Identifier` has the following fields: :addtargets: ``` -```` +:::: -````{tab} Examples +::::{tab-item} Examples ```{jsoninclude} ../../docs/examples/example.json :jsonpointer: /projects/0/parties/0/identifier @@ -750,9 +750,9 @@ Each `Identifier` has the following fields: :title: parties/0/additionalIdentifiers ``` -```` +:::: -````` +::::: ### RelatedProject @@ -769,9 +769,9 @@ This sub-schema is referenced by the following properties: Each `RelatedProject` has the following fields: -`````{tabs} +:::::{tab-set} -````{tab} Schema +::::{tab-item} Schema ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/RelatedProject @@ -779,18 +779,18 @@ Each `RelatedProject` has the following fields: :addtargets: ``` -```` +:::: -````{tab} Examples +::::{tab-item} Examples ```{jsoninclude} ../../docs/examples/example.json :jsonpointer: /projects/0/relatedProjects :title: relatedProjects ``` -```` +:::: -````` +::::: ### Metric `Metric` is defined as: @@ -805,9 +805,9 @@ This sub-schema is referenced by the following properties: Each `Metric` has the following fields: -`````{tabs} +:::::{tab-set} -````{tab} Schema +::::{tab-item} Schema ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/Metric @@ -815,9 +815,9 @@ Each `Metric` has the following fields: :addtargets: ``` -```` +:::: -````{tab} Examples +::::{tab-item} Examples ```{jsoninclude} ../../docs/examples/example.json :jsonpointer: /projects/0/forecasts @@ -829,9 +829,9 @@ Each `Metric` has the following fields: :title: metrics ``` -```` +:::: -````` +::::: ### Observation `Observation` is defined as: @@ -845,9 +845,9 @@ This sub-schema is referenced by the following properties: Each `Observation` has the following fields: -`````{tabs} +:::::{tab-set} -````{tab} Schema +::::{tab-item} Schema ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/Observation @@ -855,9 +855,9 @@ Each `Observation` has the following fields: :addtargets: ``` -```` +:::: -````{tab} Examples +::::{tab-item} Examples ```{jsoninclude} ../../docs/examples/example.json :jsonpointer: /projects/0/forecasts/0/observations @@ -869,9 +869,9 @@ Each `Observation` has the following fields: :title: metrics/0/observations ``` -```` +:::: -````` +::::: ### Person @@ -888,9 +888,9 @@ This sub-schema is referenced by the following properties: Each `Person` has the following fields: -`````{tabs} +:::::{tab-set} -````{tab} Schema +::::{tab-item} Schema ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/Person @@ -898,18 +898,18 @@ Each `Person` has the following fields: :addtargets: ``` -```` +:::: -````{tab} Examples +::::{tab-item} Examples ```{jsoninclude} ../../docs/examples/example.json :jsonpointer: /projects/0/parties/0/people :title: parties/0/people ``` -```` +:::: -````` +::::: ### Transaction @@ -926,9 +926,9 @@ This sub-schema is referenced by the following properties: Each `Transaction` has the following fields: -`````{tabs} +:::::{tab-set} -````{tab} Schema +::::{tab-item} Schema ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/Transaction @@ -936,16 +936,15 @@ Each `Transaction` has the following fields: :addtargets: ``` -```` +:::: -````{tab} Examples +::::{tab-item} Examples ```{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 6f15e326..1431e48d 100755 --- a/manage.py +++ b/manage.py @@ -278,15 +278,15 @@ def update_sub_schema_reference(schema): # Add schema table definition["content"].extend([ f"\nEach `{defn}` has the following fields:\n\n", - "`````{tabs}\n\n", - "````{tab} Schema\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(definition['properties'].keys())}\n" ":addtargets:\n" "```\n\n", - "````\n\n", - "````{tab} Examples\n\n" + "::::\n\n", + "::::{tab-item} Examples\n\n" ]) # Add examples @@ -303,8 +303,8 @@ def update_sub_schema_reference(schema): ]) definition["content"].extend([ - "````\n\n", - "`````\n\n" + "::::\n\n", + ":::::\n\n" ]) schema_reference.extend(definition["content"]) diff --git a/requirements.txt b/requirements.txt index beb36c1a..38cf5586 100644 --- a/requirements.txt +++ b/requirements.txt @@ -5,7 +5,7 @@ sphinxcontrib-opencontracting==0.0.8 sphinxcontrib-opendataservices-jsonschema==0.5.1 sphinxcontrib-opendataservices==0.5.0 -sphinx-tabs==3.4.1 +sphinx-design # Build jsonref From bf176e06e9728b52f5fb885de50907a2e1e56270 Mon Sep 17 00:00:00 2001 From: Duncan Dewhurst Date: Wed, 15 Feb 2023 14:55:38 +1300 Subject: [PATCH 09/24] docs/reference: Update introductory text --- docs/reference/index.md | 4 ++-- docs/reference/schema.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) 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 2052565e..9ad1cb89 100644 --- a/docs/reference/schema.md +++ b/docs/reference/schema.md @@ -6,7 +6,7 @@ } -This section presents each field in the 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). +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). ## Project @@ -26,7 +26,7 @@ Each project has the following fields: ## Sub-schemas -This section lists each sub-schema in the OC4IDS schema. Some sub-schemas are referenced from multiple places in the schema. +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: From d2229512117a90b50f15b4c21ca6484fd6aa6d6f Mon Sep 17 00:00:00 2001 From: Duncan Dewhurst Date: Wed, 15 Feb 2023 15:35:24 +1300 Subject: [PATCH 10/24] manage.py: Handle paths that don't appear in the example data --- docs/reference/schema.md | 15 +++------------ manage.py | 18 ++++++++++++++++-- 2 files changed, 19 insertions(+), 14 deletions(-) diff --git a/docs/reference/schema.md b/docs/reference/schema.md index 9ad1cb89..7e029341 100644 --- a/docs/reference/schema.md +++ b/docs/reference/schema.md @@ -379,11 +379,6 @@ Each `Value` has the following fields: :title: budget/budgetBreakdown/0/amount ``` -```{jsoninclude} ../../docs/examples/example.json -:jsonpointer: /projects/0/forecasts/0/observations/0/value -:title: forecasts/0/observations/0/value -``` - ```{jsoninclude} ../../docs/examples/example.json :jsonpointer: /projects/0/contractingProcesses/0/summary/tender/costEstimate :title: contractingProcesses/0/summary/tender/costEstimate @@ -401,12 +396,12 @@ Each `Value` has the following fields: ```{jsoninclude} ../../docs/examples/example.json :jsonpointer: /projects/0/contractingProcesses/0/summary/modifications/2/oldContractValue -:title: 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/2/newContractValue +:title: contractingProcesses/0/summary/modifications/0/newContractValue ``` ```{jsoninclude} ../../docs/examples/example.json @@ -414,11 +409,6 @@ Each `Value` has the following fields: :title: contractingProcesses/0/summary/transactions/0/value ``` -```{jsoninclude} ../../docs/examples/example.json -:jsonpointer: /projects/0/metrics/0/observations/0/value -:title: metrics/0/observations/0/value -``` - ```{jsoninclude} ../../docs/examples/example.json :jsonpointer: /projects/0/completion/finalValue :title: completion/finalValue @@ -948,3 +938,4 @@ Each `Transaction` has the following fields: :::: ::::: + diff --git a/manage.py b/manage.py index 1431e48d..71e4fe10 100755 --- a/manage.py +++ b/manage.py @@ -257,7 +257,7 @@ def update_sub_schema_reference(schema): # Add a list of properties that reference this definition definition["references"] = get_definition_references(schema, defn) 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'] @@ -288,10 +288,13 @@ def update_sub_schema_reference(schema): "::::\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 for ref in definition["references"]: - if ref[0] not in schema['definitions']: + if ref[0] not in schema['definitions'] and '/'.join(ref) not in paths_to_skip: if ref[-1] == '0': ref.pop(-1) @@ -309,6 +312,17 @@ def update_sub_schema_reference(schema): 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) From ba3c3c9b4e77fbc7a4eb9461272da40916541eb4 Mon Sep 17 00:00:00 2001 From: Duncan Dewhurst Date: Wed, 15 Feb 2023 15:48:44 +1300 Subject: [PATCH 11/24] manage.py: Fix lint errors --- manage.py | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/manage.py b/manage.py index 71e4fe10..1ed266e4 100755 --- a/manage.py +++ b/manage.py @@ -257,7 +257,7 @@ def update_sub_schema_reference(schema): # Add a list of properties that reference this definition definition["references"] = get_definition_references(schema, defn) 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'] @@ -288,7 +288,7 @@ def update_sub_schema_reference(schema): "::::\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'] @@ -314,14 +314,16 @@ def update_sub_schema_reference(schema): # 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' + '/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") + 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) From fd8dcf79ef89ee1ce93de0d8f35c352c3af07d88 Mon Sep 17 00:00:00 2001 From: Duncan Dewhurst Date: Tue, 21 Mar 2023 13:25:12 +1300 Subject: [PATCH 12/24] manage.py: Handle nested properties in reference lists and directives --- docs/reference/schema.md | 13 ++++++++++--- manage.py | 34 +++++++++++++++++++--------------- 2 files changed, 29 insertions(+), 18 deletions(-) diff --git a/docs/reference/schema.md b/docs/reference/schema.md index 7e029341..e4f26be8 100644 --- a/docs/reference/schema.md +++ b/docs/reference/schema.md @@ -81,7 +81,7 @@ Each `ContractingProcessSummary` has the following fields: ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/ContractingProcessSummary -:collapse: ocid,externalReference,nature,title,description,status,tender,suppliers,contractValue,contractPeriod,finalValue,documents,modifications,transactions +:collapse: ocid,externalReference,nature,title,description,status,suppliers,contractValue,contractPeriod,finalValue,documents,modifications,transactions :addtargets: ``` @@ -317,7 +317,7 @@ Each `Location` has the following fields: ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/Location -:collapse: id,description,geometry,gazetteer,uri,address +:collapse: id,description,uri,address :addtargets: ``` @@ -345,6 +345,9 @@ All values should be published along with their currency using the following str ``` 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) @@ -466,6 +469,9 @@ Each `Organization` has the following fields: 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) @@ -626,6 +632,7 @@ See the [documentation of the OCDS Budget Breakdown extension](https://extension ``` This sub-schema is referenced by the following properties: +* [`budget/budgetBreakdown`](project-schema.json,,budget/budgetBreakdown) Each `BudgetBreakdown` has the following fields: @@ -841,7 +848,7 @@ Each `Observation` has the following fields: ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/Observation -:collapse: id,period,value,measure,unit,dimensions,notes +:collapse: id,period,value,measure,notes :addtargets: ``` diff --git a/manage.py b/manage.py index 1ed266e4..49d08f61 100755 --- a/manage.py +++ b/manage.py @@ -164,7 +164,7 @@ 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): +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. @@ -172,6 +172,7 @@ def get_definition_references(schema, defn, parents=None, project_schema=None): :defn: The name of the definition :parents: A list of the parents of schema :project_schema: The full project schema + "include_nested: Whether to include nested references """ references = [] @@ -187,27 +188,27 @@ def get_definition_references(schema, defn, parents=None, project_schema=None): if value.get('type') == 'array' and '$ref' in value['items']: if value['items']['$ref'] == f"#/definitions/{defn}": references.append(parents + [key, '0']) - else: + elif include_nested: references.extend(get_definition_references( project_schema['definitions'][value['items']['$ref'].split('/')[-1]], defn, parents + [key, '0'], - project_schema)) + project_schema, include_nested)) elif '$ref' in value: if value['$ref'] == f"#/definitions/{defn}": references.append(parents + [key]) - else: + elif include_nested: references.extend(get_definition_references( project_schema['definitions'][value['$ref'].split('/')[-1]], defn, parents + [key], - project_schema)) + project_schema, include_nested)) elif 'properties' in value: - references.extend(get_definition_references(value, defn, parents + [key], project_schema)) + 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)) + references.extend(get_definition_references(value, defn, [key], project_schema, include_nested)) return references @@ -255,7 +256,7 @@ def update_sub_schema_reference(schema): ]) # Add a list of properties that reference this definition - definition["references"] = get_definition_references(schema, defn) + 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"]: @@ -265,24 +266,26 @@ def update_sub_schema_reference(schema): url = 'project-schema.json,' # Omit nested references - if ref[0] in schema['definitions'] and len(ref) == 2: - url += '/definitions/' - elif len(ref) == 1: - url += ',' + if ref[0] in schema['definitions']: + url += f"/definitions/{ref[0]},{'/'.join(ref[1:])}" else: - continue + url += f",{'/'.join(ref)}" - url += ','.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(definition['properties'].keys())}\n" + f":collapse: {','.join(properties_to_collapse)}\n" ":addtargets:\n" "```\n\n", "::::\n\n", @@ -293,6 +296,7 @@ def update_sub_schema_reference(schema): 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': From 5b38dccb0b7625f84e3dc0e38aa22f3051d7fe7d Mon Sep 17 00:00:00 2001 From: Duncan Dewhurst Date: Tue, 21 Mar 2023 14:08:30 +1300 Subject: [PATCH 13/24] manage.py: Fix lint errors --- manage.py | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/manage.py b/manage.py index 49d08f61..8680ad78 100755 --- a/manage.py +++ b/manage.py @@ -204,7 +204,11 @@ def get_definition_references(schema, defn, parents=None, project_schema=None, i parents + [key], project_schema, include_nested)) elif 'properties' in value: - references.extend(get_definition_references(value, defn, parents + [key], project_schema, include_nested)) + references.extend(get_definition_references(value, + defn, + parents + [key], + project_schema, + include_nested)) if 'definitions' in schema: for key, value in schema['definitions'].items(): @@ -278,7 +282,7 @@ def update_sub_schema_reference(schema): 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", From 6d73eebf7063068e115810990749a8c2cbfd3cb2 Mon Sep 17 00:00:00 2001 From: Duncan Dewhurst Date: Tue, 21 Mar 2023 14:24:45 +1300 Subject: [PATCH 14/24] docs/reference/schema.md: Reduce repetition of content in the schema --- docs/reference/schema.md | 27 +++------------------------ 1 file changed, 3 insertions(+), 24 deletions(-) diff --git a/docs/reference/schema.md b/docs/reference/schema.md index e4f26be8..fce2f4d7 100644 --- a/docs/reference/schema.md +++ b/docs/reference/schema.md @@ -135,8 +135,6 @@ Each `LinkedRelease` has the following fields: ### Modification -For each modification, the following structured information can be provided. - `Modification` is defined as: ```{jsoninclude-quote} ../../schema/project-level/project-schema.json @@ -256,8 +254,6 @@ Each `Period` has the following fields: ### 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: ```{jsoninclude-quote} ../../schema/project-level/project-schema.json @@ -294,12 +290,6 @@ Each `Classification` has the following fields: ### Location -A project can have one or more locations. Locations can be expressed in a number of different ways, using one or more of: - -* 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. - `Location` is defined as: ```{jsoninclude-quote} ../../schema/project-level/project-schema.json @@ -336,8 +326,6 @@ Each `Location` has the following fields: ### Value -All values should be published along with their currency using the following structure. - `Value` is defined as: ```{jsoninclude-quote} ../../schema/project-level/project-schema.json @@ -423,8 +411,6 @@ Each `Value` has the following fields: ### Organization -For each organization, provide as much structured data as you can. - `Organization` is defined as: ```{jsoninclude-quote} ../../schema/project-level/project-schema.json @@ -539,9 +525,9 @@ Each `OrganizationReference` has the following fields: ### Address -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. +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 properties the specification provides. +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: @@ -621,9 +607,7 @@ Each `ContactPoint` has the following fields: ### BudgetBreakdown -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. - -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/). +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: @@ -661,8 +645,6 @@ Each `BudgetBreakdown` has the following fields: ### Document -For each document the following structured information can be provided. - `Document` is defined as: ```{jsoninclude-quote} ../../schema/project-level/project-schema.json @@ -753,8 +735,6 @@ Each `Identifier` has the following fields: ### RelatedProject -A reference to a project related to the same set of infrastructure assets as the current project. - `RelatedProject` is defined as: ```{jsoninclude-quote} ../../schema/project-level/project-schema.json @@ -945,4 +925,3 @@ Each `Transaction` has the following fields: :::: ::::: - From 189659a103607daa56aa3cdc71ff12a4cb9a3d15 Mon Sep 17 00:00:00 2001 From: Duncan Dewhurst Date: Thu, 23 Mar 2023 15:32:40 +1300 Subject: [PATCH 15/24] docs: Integrate worked example and schema reference --- docs/guidance/example.md | 194 +++------------------------ docs/reference/schema.md | 276 ++++++++++++++++++++++----------------- 2 files changed, 170 insertions(+), 300 deletions(-) diff --git a/docs/guidance/example.md b/docs/guidance/example.md index e061ff23..1260dc46 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`](../../reference/schema/) and [`metrics`](../../reference/schema) that describe planned and actual physical progress +* [`modifications`](../../reference/schema/) that describe changes to the duration, scope and value of contracting processes +* [`completion`](../../reference/schema/) 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/1 -: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/0/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/schema.md b/docs/reference/schema.md index fce2f4d7..f701699f 100644 --- a/docs/reference/schema.md +++ b/docs/reference/schema.md @@ -6,7 +6,11 @@ } -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). +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 @@ -16,13 +20,38 @@ 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. -Each project has the following fields: +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} -```{jsonschema} ../../build/current_lang/project-schema.json +````{tab-item} Schema + +```{jsonschema} ../../schema/project-level/project-schema.json :include: :collapse: period,additionalClassifications,relatedProjects,assetLifetime,locations,budget/amount,budget/budgetBreakdown,forecasts,parties,publicAuthority,documents,contractingProcesses,metrics,completion/finalValue :addtargets: ``` +```` + +````{tab-item} Examples + +```{jsoninclude} ../../docs/examples/example.json +:jsonpointer: /projects/0 +:title: Project +``` + +```` + +````` ## Sub-schemas @@ -40,9 +69,9 @@ This sub-schema is referenced by the following properties: Each `ContractingProcess` has the following fields: -:::::{tab-set} +`````{tab-set} -::::{tab-item} Schema +````{tab-item} Schema ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/ContractingProcess @@ -50,18 +79,18 @@ Each `ContractingProcess` has the following fields: :addtargets: ``` -:::: +```` -::::{tab-item} Examples +````{tab-item} Examples ```{jsoninclude} ../../docs/examples/example.json :jsonpointer: /projects/0/contractingProcesses :title: contractingProcesses ``` -:::: +```` -::::: +````` ### ContractingProcessSummary `ContractingProcessSummary` is defined as: @@ -75,9 +104,9 @@ This sub-schema is referenced by the following properties: Each `ContractingProcessSummary` has the following fields: -:::::{tab-set} +`````{tab-set} -::::{tab-item} Schema +````{tab-item} Schema ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/ContractingProcessSummary @@ -85,18 +114,18 @@ Each `ContractingProcessSummary` has the following fields: :addtargets: ``` -:::: +```` -::::{tab-item} Examples +````{tab-item} Examples ```{jsoninclude} ../../docs/examples/example.json :jsonpointer: /projects/0/contractingProcesses/0/summary :title: contractingProcesses/0/summary ``` -:::: +```` -::::: +````` ### LinkedRelease `LinkedRelease` is defined as: @@ -110,9 +139,9 @@ This sub-schema is referenced by the following properties: Each `LinkedRelease` has the following fields: -:::::{tab-set} +`````{tab-set} -::::{tab-item} Schema +````{tab-item} Schema ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/LinkedRelease @@ -120,18 +149,18 @@ Each `LinkedRelease` has the following fields: :addtargets: ``` -:::: +```` -::::{tab-item} Examples +````{tab-item} Examples ```{jsoninclude} ../../docs/examples/example.json :jsonpointer: /projects/0/contractingProcesses/0/releases :title: contractingProcesses/0/releases ``` -:::: +```` -::::: +````` ### Modification @@ -146,9 +175,9 @@ This sub-schema is referenced by the following properties: Each `Modification` has the following fields: -:::::{tab-set} +`````{tab-set} -::::{tab-item} Schema +````{tab-item} Schema ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/Modification @@ -156,18 +185,18 @@ Each `Modification` has the following fields: :addtargets: ``` -:::: +```` -::::{tab-item} Examples +````{tab-item} Examples ```{jsoninclude} ../../docs/examples/example.json :jsonpointer: /projects/0/contractingProcesses/0/summary/modifications :title: contractingProcesses/0/summary/modifications ``` -:::: +```` -::::: +````` ### Period @@ -194,9 +223,9 @@ This sub-schema is referenced by the following properties: Each `Period` has the following fields: -:::::{tab-set} +`````{tab-set} -::::{tab-item} Schema +````{tab-item} Schema ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/Period @@ -204,9 +233,9 @@ Each `Period` has the following fields: :addtargets: ``` -:::: +```` -::::{tab-item} Examples +````{tab-item} Examples ```{jsoninclude} ../../docs/examples/example.json :jsonpointer: /projects/0/period @@ -248,9 +277,9 @@ Each `Period` has the following fields: :title: metrics/0/observations/0/period ``` -:::: +```` -::::: +````` ### Classification @@ -265,9 +294,9 @@ This sub-schema is referenced by the following properties: Each `Classification` has the following fields: -:::::{tab-set} +`````{tab-set} -::::{tab-item} Schema +````{tab-item} Schema ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/Classification @@ -275,18 +304,18 @@ Each `Classification` has the following fields: :addtargets: ``` -:::: +```` -::::{tab-item} Examples +````{tab-item} Examples ```{jsoninclude} ../../docs/examples/example.json :jsonpointer: /projects/0/additionalClassifications :title: additionalClassifications ``` -:::: +```` -::::: +````` ### Location @@ -301,9 +330,9 @@ This sub-schema is referenced by the following properties: Each `Location` has the following fields: -:::::{tab-set} +`````{tab-set} -::::{tab-item} Schema +````{tab-item} Schema ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/Location @@ -311,18 +340,18 @@ Each `Location` has the following fields: :addtargets: ``` -:::: +```` -::::{tab-item} Examples +````{tab-item} Examples ```{jsoninclude} ../../docs/examples/example.json :jsonpointer: /projects/0/locations :title: locations ``` -:::: +```` -::::: +````` ### Value @@ -346,9 +375,9 @@ This sub-schema is referenced by the following properties: Each `Value` has the following fields: -:::::{tab-set} +`````{tab-set} -::::{tab-item} Schema +````{tab-item} Schema ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/Value @@ -356,9 +385,9 @@ Each `Value` has the following fields: :addtargets: ``` -:::: +```` -::::{tab-item} Examples +````{tab-item} Examples ```{jsoninclude} ../../docs/examples/example.json :jsonpointer: /projects/0/budget/amount @@ -405,9 +434,9 @@ Each `Value` has the following fields: :title: completion/finalValue ``` -:::: +```` -::::: +````` ### Organization @@ -422,9 +451,9 @@ This sub-schema is referenced by the following properties: Each `Organization` has the following fields: -:::::{tab-set} +`````{tab-set} -::::{tab-item} Schema +````{tab-item} Schema ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/Organization @@ -432,18 +461,18 @@ Each `Organization` has the following fields: :addtargets: ``` -:::: +```` -::::{tab-item} Examples +````{tab-item} Examples ```{jsoninclude} ../../docs/examples/example.json :jsonpointer: /projects/0/parties :title: parties ``` -:::: +```` -::::: +````` ### OrganizationReference @@ -465,9 +494,9 @@ This sub-schema is referenced by the following properties: Each `OrganizationReference` has the following fields: -:::::{tab-set} +`````{tab-set} -::::{tab-item} Schema +````{tab-item} Schema ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/OrganizationReference @@ -475,9 +504,9 @@ Each `OrganizationReference` has the following fields: :addtargets: ``` -:::: +```` -::::{tab-item} Examples +````{tab-item} Examples ```{jsoninclude} ../../docs/examples/example.json :jsonpointer: /projects/0/budget/budgetBreakdown/0/sourceParty @@ -519,9 +548,9 @@ Each `OrganizationReference` has the following fields: :title: contractingProcesses/0/summary/transactions/0/payee ``` -:::: +```` -::::: +````` ### Address @@ -541,9 +570,9 @@ This sub-schema is referenced by the following properties: Each `Address` has the following fields: -:::::{tab-set} +`````{tab-set} -::::{tab-item} Schema +````{tab-item} Schema ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/Address @@ -551,9 +580,9 @@ Each `Address` has the following fields: :addtargets: ``` -:::: +```` -::::{tab-item} Examples +````{tab-item} Examples ```{jsoninclude} ../../docs/examples/example.json :jsonpointer: /projects/0/locations/0/address @@ -565,9 +594,9 @@ Each `Address` has the following fields: :title: parties/0/address ``` -:::: +```` -::::: +````` ### ContactPoint @@ -582,9 +611,9 @@ This sub-schema is referenced by the following properties: Each `ContactPoint` has the following fields: -:::::{tab-set} +`````{tab-set} -::::{tab-item} Schema +````{tab-item} Schema ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/ContactPoint @@ -592,18 +621,18 @@ Each `ContactPoint` has the following fields: :addtargets: ``` -:::: +```` -::::{tab-item} Examples +````{tab-item} Examples ```{jsoninclude} ../../docs/examples/example.json :jsonpointer: /projects/0/parties/0/contactPoint :title: parties/0/contactPoint ``` -:::: +```` -::::: +````` ### BudgetBreakdown @@ -620,9 +649,9 @@ This sub-schema is referenced by the following properties: Each `BudgetBreakdown` has the following fields: -:::::{tab-set} +`````{tab-set} -::::{tab-item} Schema +````{tab-item} Schema ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/BudgetBreakdown @@ -630,18 +659,18 @@ Each `BudgetBreakdown` has the following fields: :addtargets: ``` -:::: +```` -::::{tab-item} Examples +````{tab-item} Examples ```{jsoninclude} ../../docs/examples/example.json :jsonpointer: /projects/0/budget/budgetBreakdown :title: budget/budgetBreakdown ``` -:::: +```` -::::: +````` ### Document @@ -657,9 +686,9 @@ This sub-schema is referenced by the following properties: Each `Document` has the following fields: -:::::{tab-set} +`````{tab-set} -::::{tab-item} Schema +````{tab-item} Schema ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/Document @@ -667,9 +696,9 @@ Each `Document` has the following fields: :addtargets: ``` -:::: +```` -::::{tab-item} Examples +````{tab-item} Examples ```{jsoninclude} ../../docs/examples/example.json :jsonpointer: /projects/0/documents @@ -681,9 +710,9 @@ Each `Document` has the following fields: :title: contractingProcesses/0/summary/documents ``` -:::: +```` -::::: +````` ### Identifier @@ -705,9 +734,9 @@ This sub-schema is referenced by the following properties: Each `Identifier` has the following fields: -:::::{tab-set} +`````{tab-set} -::::{tab-item} Schema +````{tab-item} Schema ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/Identifier @@ -715,9 +744,9 @@ Each `Identifier` has the following fields: :addtargets: ``` -:::: +```` -::::{tab-item} Examples +````{tab-item} Examples ```{jsoninclude} ../../docs/examples/example.json :jsonpointer: /projects/0/parties/0/identifier @@ -729,9 +758,9 @@ Each `Identifier` has the following fields: :title: parties/0/additionalIdentifiers ``` -:::: +```` -::::: +````` ### RelatedProject @@ -746,9 +775,9 @@ This sub-schema is referenced by the following properties: Each `RelatedProject` has the following fields: -:::::{tab-set} +`````{tab-set} -::::{tab-item} Schema +````{tab-item} Schema ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/RelatedProject @@ -756,18 +785,18 @@ Each `RelatedProject` has the following fields: :addtargets: ``` -:::: +```` -::::{tab-item} Examples +````{tab-item} Examples ```{jsoninclude} ../../docs/examples/example.json :jsonpointer: /projects/0/relatedProjects :title: relatedProjects ``` -:::: +```` -::::: +````` ### Metric `Metric` is defined as: @@ -782,9 +811,9 @@ This sub-schema is referenced by the following properties: Each `Metric` has the following fields: -:::::{tab-set} +`````{tab-set} -::::{tab-item} Schema +````{tab-item} Schema ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/Metric @@ -792,9 +821,9 @@ Each `Metric` has the following fields: :addtargets: ``` -:::: +```` -::::{tab-item} Examples +````{tab-item} Examples ```{jsoninclude} ../../docs/examples/example.json :jsonpointer: /projects/0/forecasts @@ -806,9 +835,9 @@ Each `Metric` has the following fields: :title: metrics ``` -:::: +```` -::::: +````` ### Observation `Observation` is defined as: @@ -822,9 +851,9 @@ This sub-schema is referenced by the following properties: Each `Observation` has the following fields: -:::::{tab-set} +`````{tab-set} -::::{tab-item} Schema +````{tab-item} Schema ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/Observation @@ -832,9 +861,9 @@ Each `Observation` has the following fields: :addtargets: ``` -:::: +```` -::::{tab-item} Examples +````{tab-item} Examples ```{jsoninclude} ../../docs/examples/example.json :jsonpointer: /projects/0/forecasts/0/observations @@ -846,9 +875,9 @@ Each `Observation` has the following fields: :title: metrics/0/observations ``` -:::: +```` -::::: +````` ### Person @@ -865,9 +894,9 @@ This sub-schema is referenced by the following properties: Each `Person` has the following fields: -:::::{tab-set} +`````{tab-set} -::::{tab-item} Schema +````{tab-item} Schema ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/Person @@ -875,18 +904,18 @@ Each `Person` has the following fields: :addtargets: ``` -:::: +```` -::::{tab-item} Examples +````{tab-item} Examples ```{jsoninclude} ../../docs/examples/example.json :jsonpointer: /projects/0/parties/0/people :title: parties/0/people ``` -:::: +```` -::::: +````` ### Transaction @@ -903,9 +932,9 @@ This sub-schema is referenced by the following properties: Each `Transaction` has the following fields: -:::::{tab-set} +`````{tab-set} -::::{tab-item} Schema +````{tab-item} Schema ```{jsonschema} ../../schema/project-level/project-schema.json :pointer: /definitions/Transaction @@ -913,15 +942,16 @@ Each `Transaction` has the following fields: :addtargets: ``` -:::: +```` -::::{tab-item} Examples +````{tab-item} Examples ```{jsoninclude} ../../docs/examples/example.json :jsonpointer: /projects/0/contractingProcesses/0/summary/transactions :title: contractingProcesses/0/summary/transactions ``` -:::: +```` + +````` -::::: From e29c23cacbd7a5e378340500ce1ba99776ef332e Mon Sep 17 00:00:00 2001 From: Duncan Dewhurst Date: Thu, 23 Mar 2023 15:33:25 +1300 Subject: [PATCH 16/24] Don't use colon fence extension --- docs/conf.py | 2 +- manage.py | 12 ++++++------ 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 5e1a8985..4da09ab8 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -86,7 +86,7 @@ smartquotes = False # MyST configuration. -myst_enable_extensions = ['linkify', 'colon_fence'] +myst_enable_extensions = ['linkify'] myst_heading_anchors = 6 myst_heading_slug_func = make_id diff --git a/manage.py b/manage.py index 8680ad78..737f4d20 100755 --- a/manage.py +++ b/manage.py @@ -285,15 +285,15 @@ def update_sub_schema_reference(schema): definition["content"].extend([ f"\nEach `{defn}` has the following fields:\n\n", - ":::::{tab-set}\n\n", - "::::{tab-item} Schema\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" + "````\n\n", + "````{tab-item} Examples\n\n" ]) # Paths that don't appear in the example data at all @@ -314,8 +314,8 @@ def update_sub_schema_reference(schema): ]) definition["content"].extend([ - "::::\n\n", - ":::::\n\n" + "````\n\n", + "`````\n\n" ]) schema_reference.extend(definition["content"]) From 1f023dcf6ecf15337effb22d2fd7adb7aac06c60 Mon Sep 17 00:00:00 2001 From: Duncan Dewhurst Date: Thu, 23 Mar 2023 15:35:37 +1300 Subject: [PATCH 17/24] pull_request_template.md: Update merge checklist --- pull_request_template.md | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) 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` From 8ed9a1063ae35a56ec3d0e55342f317384799cad Mon Sep 17 00:00:00 2001 From: Duncan Dewhurst Date: Thu, 23 Mar 2023 15:37:31 +1300 Subject: [PATCH 18/24] Update changelog --- docs/reference/changelog.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/reference/changelog.md b/docs/reference/changelog.md index f404b381..a97732cb 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. +* [#299](https://github.com/open-contracting/infrastructure/pull/370) - improve schema reference documentation and integrate worked example. ### Schema From 42299b1c44faefc50122cce6cfb815d620edaf92 Mon Sep 17 00:00:00 2001 From: Duncan Dewhurst Date: Thu, 23 Mar 2023 15:38:41 +1300 Subject: [PATCH 19/24] docs/reference/changelog.md: Fix incorrect PR number --- docs/reference/changelog.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/changelog.md b/docs/reference/changelog.md index a97732cb..650b16ab 100644 --- a/docs/reference/changelog.md +++ b/docs/reference/changelog.md @@ -10,7 +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. -* [#299](https://github.com/open-contracting/infrastructure/pull/370) - improve schema reference documentation and integrate worked example. +* [#370](https://github.com/open-contracting/infrastructure/pull/370) - improve schema reference documentation and integrate worked example. ### Schema From 22529f14db9219b97fa85a48dfa63148a88da1b9 Mon Sep 17 00:00:00 2001 From: Duncan Dewhurst Date: Thu, 23 Mar 2023 15:59:49 +1300 Subject: [PATCH 20/24] docs/guidance/example.md: Add links to field anchors --- docs/guidance/example.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/guidance/example.md b/docs/guidance/example.md index 1260dc46..ad7e1ab5 100644 --- a/docs/guidance/example.md +++ b/docs/guidance/example.md @@ -4,13 +4,13 @@ This page provides examples to help you understand and implement OC4IDS. There a ## Worked example -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). +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). 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: -* [`forecasts`](../../reference/schema/) and [`metrics`](../../reference/schema) that describe planned and actual physical progress -* [`modifications`](../../reference/schema/) that describe changes to the duration, scope and value of contracting processes -* [`completion`](../../reference/schema/) data, describing the final end date, value and scope of the project. +* [`forecasts`](../reference/schema.md#project-schema.json,,forecasts) and [`metrics`](../reference/schema.md#project-schema.json,,metrics) that describe planned and actual physical progress +* [`modifications`](../reference/schema.md#project-schema.json,,metrics) that describe changes to the duration, scope and value of contracting processes +* [`completion`](../reference/schema.md#project-schema.json,,completion) data, describing the final end date, value and scope of the project. ```{jsoninclude} ../../docs/examples/example.json :jsonpointer: @@ -19,7 +19,7 @@ The worked example describes a fictional infrastructure project to upgrade a mot ## Blank example -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: +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: * Empty strings (`""`) or empty arrays (`[]`) * The type of the field, e.g. "string" or "array" From ec0041e554d5b8f5c389e5943b2945353c66e408 Mon Sep 17 00:00:00 2001 From: James McKinney <26463+jpmckinney@users.noreply.github.com> Date: Fri, 24 Mar 2023 21:52:20 -0400 Subject: [PATCH 21/24] chore: Fix broken refs --- docs/guidance/example.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/guidance/example.md b/docs/guidance/example.md index ad7e1ab5..68fe17a5 100644 --- a/docs/guidance/example.md +++ b/docs/guidance/example.md @@ -8,9 +8,9 @@ The worked example is a JSON file that conforms to the [project package schema]( 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: -* [`forecasts`](../reference/schema.md#project-schema.json,,forecasts) and [`metrics`](../reference/schema.md#project-schema.json,,metrics) that describe planned and actual physical progress -* [`modifications`](../reference/schema.md#project-schema.json,,metrics) that describe changes to the duration, scope and value of contracting processes -* [`completion`](../reference/schema.md#project-schema.json,,completion) data, describing the final end date, value and scope of the project. +* [`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. ```{jsoninclude} ../../docs/examples/example.json :jsonpointer: From 1ed94765ac5dd52258369fcb0556ed0d01a25e26 Mon Sep 17 00:00:00 2001 From: Duncan Dewhurst Date: Wed, 29 Mar 2023 14:29:53 +1300 Subject: [PATCH 22/24] Update docs/conf.py Co-authored-by: James McKinney <26463+jpmckinney@users.noreply.github.com> --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 82466511..4df3c67b 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -42,7 +42,7 @@ 'sphinxcontrib.jsonschema', 'sphinxcontrib.opencontracting', 'sphinxcontrib.opendataservices', - 'sphinx_design' + 'sphinx_design', ] # Add any paths that contain templates here, relative to this directory. From e65bbf5f2863bc0cd533f87c22adb259a8f013cb Mon Sep 17 00:00:00 2001 From: Duncan Dewhurst Date: Wed, 29 Mar 2023 14:34:38 +1300 Subject: [PATCH 23/24] docs/reference/schema.md: Use field-description directive --- docs/reference/schema.md | 60 ++++++++++++++-------------------------- manage.py | 3 +- 2 files changed, 21 insertions(+), 42 deletions(-) diff --git a/docs/reference/schema.md b/docs/reference/schema.md index f701699f..4f30ad1d 100644 --- a/docs/reference/schema.md +++ b/docs/reference/schema.md @@ -60,8 +60,7 @@ This section lists each sub-schema in the OC4IDS schema. Sub-schemas are parts o ### ContractingProcess `ContractingProcess` is defined as: -```{jsoninclude-quote} ../../schema/project-level/project-schema.json -:jsonpointer: /definitions/ContractingProcess/description +```{field-description} ../../schema/project-level/project-schema.json /definitions/ContractingProcess ``` This sub-schema is referenced by the following properties: @@ -95,8 +94,7 @@ Each `ContractingProcess` has the following fields: ### ContractingProcessSummary `ContractingProcessSummary` is defined as: -```{jsoninclude-quote} ../../schema/project-level/project-schema.json -:jsonpointer: /definitions/ContractingProcessSummary/description +```{field-description} ../../schema/project-level/project-schema.json /definitions/ContractingProcessSummary ``` This sub-schema is referenced by the following properties: @@ -130,8 +128,7 @@ Each `ContractingProcessSummary` has the following fields: ### LinkedRelease `LinkedRelease` is defined as: -```{jsoninclude-quote} ../../schema/project-level/project-schema.json -:jsonpointer: /definitions/LinkedRelease/description +```{field-description} ../../schema/project-level/project-schema.json /definitions/LinkedRelease ``` This sub-schema is referenced by the following properties: @@ -166,8 +163,7 @@ Each `LinkedRelease` has the following fields: `Modification` is defined as: -```{jsoninclude-quote} ../../schema/project-level/project-schema.json -:jsonpointer: /definitions/Modification/description +```{field-description} ../../schema/project-level/project-schema.json /definitions/Modification ``` This sub-schema is referenced by the following properties: @@ -208,8 +204,7 @@ Where the source system does not contain time information, a judgment ought to b `Period` is defined as: -```{jsoninclude-quote} ../../schema/project-level/project-schema.json -:jsonpointer: /definitions/Period/description +```{field-description} ../../schema/project-level/project-schema.json /definitions/Period ``` This sub-schema is referenced by the following properties: @@ -285,8 +280,7 @@ Each `Period` has the following fields: `Classification` is defined as: -```{jsoninclude-quote} ../../schema/project-level/project-schema.json -:jsonpointer: /definitions/Classification/description +```{field-description} ../../schema/project-level/project-schema.json /definitions/Classification ``` This sub-schema is referenced by the following properties: @@ -321,8 +315,7 @@ Each `Classification` has the following fields: `Location` is defined as: -```{jsoninclude-quote} ../../schema/project-level/project-schema.json -:jsonpointer: /definitions/Location/description +```{field-description} ../../schema/project-level/project-schema.json /definitions/Location ``` This sub-schema is referenced by the following properties: @@ -357,8 +350,7 @@ Each `Location` has the following fields: `Value` is defined as: -```{jsoninclude-quote} ../../schema/project-level/project-schema.json -:jsonpointer: /definitions/Value/description +```{field-description} ../../schema/project-level/project-schema.json /definitions/Value ``` This sub-schema is referenced by the following properties: @@ -442,8 +434,7 @@ Each `Value` has the following fields: `Organization` is defined as: -```{jsoninclude-quote} ../../schema/project-level/project-schema.json -:jsonpointer: /definitions/Organization/description +```{field-description} ../../schema/project-level/project-schema.json /definitions/Organization ``` This sub-schema is referenced by the following properties: @@ -478,8 +469,7 @@ Each `Organization` has the following fields: `OrganizationReference` is defined as: -```{jsoninclude-quote} ../../schema/project-level/project-schema.json -:jsonpointer: /definitions/OrganizationReference/description +```{field-description} ../../schema/project-level/project-schema.json /definitions/OrganizationReference ``` This sub-schema is referenced by the following properties: @@ -560,8 +550,7 @@ When working with data, users ought to be aware that addresses might not always `Address` is defined as: -```{jsoninclude-quote} ../../schema/project-level/project-schema.json -:jsonpointer: /definitions/Address/description +```{field-description} ../../schema/project-level/project-schema.json /definitions/Address ``` This sub-schema is referenced by the following properties: @@ -602,8 +591,7 @@ Each `Address` has the following fields: `ContactPoint` is defined as: -```{jsoninclude-quote} ../../schema/project-level/project-schema.json -:jsonpointer: /definitions/ContactPoint/description +```{field-description} ../../schema/project-level/project-schema.json /definitions/ContactPoint ``` This sub-schema is referenced by the following properties: @@ -640,8 +628,7 @@ For more information about this sub-schema, see the [OCDS Budget Breakdown exten `BudgetBreakdown` is defined as: -```{jsoninclude-quote} ../../schema/project-level/project-schema.json -:jsonpointer: /definitions/BudgetBreakdown/description +```{field-description} ../../schema/project-level/project-schema.json /definitions/BudgetBreakdown ``` This sub-schema is referenced by the following properties: @@ -676,8 +663,7 @@ Each `BudgetBreakdown` has the following fields: `Document` is defined as: -```{jsoninclude-quote} ../../schema/project-level/project-schema.json -:jsonpointer: /definitions/Document/description +```{field-description} ../../schema/project-level/project-schema.json /definitions/Document ``` This sub-schema is referenced by the following properties: @@ -724,8 +710,7 @@ For example, if identifying a company in Colombia, look up its identifier in the `Identifier` is defined as: -```{jsoninclude-quote} ../../schema/project-level/project-schema.json -:jsonpointer: /definitions/Identifier/description +```{field-description} ../../schema/project-level/project-schema.json /definitions/Identifier ``` This sub-schema is referenced by the following properties: @@ -766,8 +751,7 @@ Each `Identifier` has the following fields: `RelatedProject` is defined as: -```{jsoninclude-quote} ../../schema/project-level/project-schema.json -:jsonpointer: /definitions/RelatedProject/description +```{field-description} ../../schema/project-level/project-schema.json /definitions/RelatedProject ``` This sub-schema is referenced by the following properties: @@ -801,8 +785,7 @@ Each `RelatedProject` has the following fields: ### Metric `Metric` is defined as: -```{jsoninclude-quote} ../../schema/project-level/project-schema.json -:jsonpointer: /definitions/Metric/description +```{field-description} ../../schema/project-level/project-schema.json /definitions/Metric ``` This sub-schema is referenced by the following properties: @@ -842,8 +825,7 @@ Each `Metric` has the following fields: ### Observation `Observation` is defined as: -```{jsoninclude-quote} ../../schema/project-level/project-schema.json -:jsonpointer: /definitions/Observation/description +```{field-description} ../../schema/project-level/project-schema.json /definitions/Observation ``` This sub-schema is referenced by the following properties: @@ -885,8 +867,7 @@ Use this object when you need to disclose the details of people associated with, `Person` is defined as: -```{jsoninclude-quote} ../../schema/project-level/project-schema.json -:jsonpointer: /definitions/Person/description +```{field-description} ../../schema/project-level/project-schema.json /definitions/Person ``` This sub-schema is referenced by the following properties: @@ -923,8 +904,7 @@ A spending transaction related to a contracting process. `Transaction` is defined as: -```{jsoninclude-quote} ../../schema/project-level/project-schema.json -:jsonpointer: /definitions/Transaction/description +```{field-description} ../../schema/project-level/project-schema.json /definitions/Transaction ``` This sub-schema is referenced by the following properties: diff --git a/manage.py b/manage.py index 3dd34d57..dd6730f6 100755 --- a/manage.py +++ b/manage.py @@ -254,8 +254,7 @@ def update_sub_schema_reference(schema): # Add description definition["content"].extend([ f"`{defn}` is defined as:\n\n", - "```{jsoninclude-quote} ../../schema/project-level/project-schema.json\n", - f":jsonpointer: /definitions/{defn}/description\n", + f"```{{field-description}} ../../schema/project-level/project-schema.json /definitions/{defn}\n", "```\n\n" ]) From dbd0f9722cb8f29f8c548e7db80b9bb73682f20b Mon Sep 17 00:00:00 2001 From: James McKinney <26463+jpmckinney@users.noreply.github.com> Date: Tue, 25 Apr 2023 21:25:32 -0400 Subject: [PATCH 24/24] docs: Fix manage.py docstring --- manage.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/manage.py b/manage.py index dd6730f6..aa110415 100755 --- a/manage.py +++ b/manage.py @@ -169,10 +169,10 @@ def get_definition_references(schema, defn, parents=None, project_schema=None, i Recursively generate a list of JSON pointers that reference a definition in JSON schema. :param schema: The JSON schema - :defn: The name of the definition - :parents: A list of the parents of schema - :project_schema: The full project schema - "include_nested: Whether to include nested references + :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 = []