diff --git a/.github/rulesets/gitflow-main.overlay.json b/.github/rulesets/gitflow-main.overlay.json index 7d55c8cd..e34527f9 100644 --- a/.github/rulesets/gitflow-main.overlay.json +++ b/.github/rulesets/gitflow-main.overlay.json @@ -16,10 +16,6 @@ "context": "Formatting / Run Prettier Check", "integration_id": 15368 }, - { - "context": "JSON Schema / Check Schema Docs", - "integration_id": 15368 - }, { "context": "JSON Schema / Run JSON validator", "integration_id": 15368 diff --git a/.github/rulesets/gitflow-production.overlay.json b/.github/rulesets/gitflow-production.overlay.json index 8b10478e..bc7d9167 100644 --- a/.github/rulesets/gitflow-production.overlay.json +++ b/.github/rulesets/gitflow-production.overlay.json @@ -21,10 +21,6 @@ "context": "Formatting / Run Prettier Check", "integration_id": 15368 }, - { - "context": "JSON Schema / Check Schema Docs", - "integration_id": 15368 - }, { "context": "JSON Schema / Run JSON validator", "integration_id": 15368 diff --git a/.github/workflows/node-json-schema.yml b/.github/workflows/node-json-schema.yml index 47a57e64..79cc7ad8 100644 --- a/.github/workflows/node-json-schema.yml +++ b/.github/workflows/node-json-schema.yml @@ -42,42 +42,6 @@ jobs: VITE_INCLUDE_INVALID: ${{ steps.set-include.outputs.vite-include-invalid }} run: npm run schema:check - schema-docs: - name: "Check Schema Docs" - runs-on: ubuntu-latest - - steps: - - name: Checkout code - uses: actions/checkout@v7 - - - name: Setup Node.js - uses: actions/setup-node@v7 - with: - node-version-file: .nvmrc - cache: "npm" - cache-dependency-path: package-lock.json - - - name: Install dependencies - run: npm ci - - - name: Run JSON schema render - run: npm run schema:generate:docs - - - name: Compare Results - run: | - git add --all - changes=$(git diff-index HEAD --name-only -- $OUTPUTS) - if [ -n "$changes" ]; then - echo "Changes found after documenting." - echo "$changes" - echo "Please update documentation." - git --no-pager diff HEAD - exit 1 - else - echo "No changes found after documenting." - exit 0 - fi - types-check: name: "Check generated types" runs-on: ubuntu-latest diff --git a/.gitignore b/.gitignore index d8125a30..a09ba3fd 100644 --- a/.gitignore +++ b/.gitignore @@ -24,8 +24,5 @@ yarn-debug.log* yarn-error.log* pnpm-debug.log* -# Python venv -.venv/ - # Generated/copied files public/data/**/* diff --git a/.prettierignore b/.prettierignore index b7826205..1521c8b7 100644 --- a/.prettierignore +++ b/.prettierignore @@ -1,3 +1 @@ -.venv dist -public/schema.html diff --git a/README.md b/README.md index 390baafb..6dfb7b77 100644 --- a/README.md +++ b/README.md @@ -111,14 +111,6 @@ npm run lint:fix npm run format ``` -## Documentation - -### JSON Schema - -To render JSON Schema documentation (available in-app at `/schema.html` route), run `npm run docs:json:schema`, which invokes the `scripts/generate-schema-docs.sh`. This script creates and activates a python virtual environment, and renders the `public/schema.html` file, which will be picked up by the build process. - -There is a GitHub workflow (`schema-docs` in `.github/workflows/node-json-schema.yml`) to check that the documentation and the schema do not diverge. - ## Releases This project uses [`semantic-release`](https://semantic-release.gitbook.io/semantic-release) to manage release versions. diff --git a/package.json b/package.json index 974e9152..8aaaf71e 100644 --- a/package.json +++ b/package.json @@ -22,8 +22,7 @@ "schema:check": "npx ts-node --esm scripts/schema-check-files.ts src/data testdata/valid", "schema:check:srcdata": "npx ts-node --esm scripts/schema-check-files.ts src/data", "schema:check:testdata": "npx ts-node --esm scripts/schema-check-files.ts testdata/valid", - "schema:generate": "npm run schema:generate:types && npm run schema:generate:docs", - "schema:generate:docs": "scripts/generate-schema-docs.sh", + "schema:generate": "npm run schema:generate:types", "schema:generate:types": "npx ts-node --esm scripts/generate-types.ts && prettier --write \"src/types/**/*.d.ts\"", "test": "vitest run", "test:watch": "vitest" diff --git a/public/schema/countryCode.v1.html b/public/schema/countryCode.v1.html deleted file mode 100644 index d17906a3..00000000 --- a/public/schema/countryCode.v1.html +++ /dev/null @@ -1,430 +0,0 @@ - - -
- - - - - - - - - -- A single ISO-3166-1 alpha-2 country code (e.g., US, DE). Only 2-letter - codes are accepted; do not use full country names or 3-letter codes. - 2-letter strings that do not map to a country (e.g., EU) will throw - downstream errors. -
- -^[A-Za-z]{3}$
- ^(?!\s*$).+
-
- "US"
-
- "DE"
-
- "PH"
-
- "JP"
-
- "BR"
-
- - Defines which greenhouse gases are covered in the pathway's modeled - emissions. -
- -- Geographical coverage of a pathway. 'global' marks whole-world coverage - (a literal flag, not a list of every country); 'regions' maps an - author-defined region label, kept as named in the source publication, to - the ISO-3166-1 alpha-2 country codes it contains (member arrays may be - empty when the publication provides no mapping); 'country' lists - standalone ISO-3166-1 alpha-2 country codes. -
- - No Additional Properties - -True if the pathway covers the entire world.
- -- Map from an author-defined region label (as named in the - publication) to the ISO-3166-1 alpha-2 country codes in that - region. Member arrays may be empty when the publication does not - provide a mapping. -
- - -- Each additional property must conform to the following - schema -
- - - Type: array- All items must be unique -
- No Additional Items -- A single ISO-3166-1 alpha-2 country code (e.g., US, - DE). Only 2-letter codes are accepted; do not use - full country names or 3-letter codes. 2-letter - strings that do not map to a country (e.g., EU) will - throw downstream errors. -
- - -^[A-Za-z]{3}$
- ^(?!\s*$).+
-
- "US"
-
- "DE"
-
- "PH"
-
- "JP"
-
- "BR"
-
- - Standalone ISO-3166-1 alpha-2 country codes covered by the - pathway. -
- - -- All items must be unique -
- No Additional Items -- A single ISO-3166-1 alpha-2 country code (e.g., US, DE). - Only 2-letter codes are accepted; do not use full country - names or 3-letter codes. 2-letter strings that do not map to - a country (e.g., EU) will throw downstream errors. -
- - -^[A-Za-z]{3}$
- ^(?!\s*$).+
-
- "US"
-
- "DE"
-
- "PH"
-
- "JP"
-
- "BR"
-
- - A single geography identifier used across schemas. Accepts 'Global', - ISO-3166-1 alpha-2 country codes (e.g., 'US', 'DE'), or a set of region - names (e.g., 'East Asia and Pacific', 'North America'). Any 2-letter - items in the array will be treated as an ISO code. Any 2-letter entries - that do not map to a country will throw errors (EU). Do not use full - country names, only ISO alpha-2 codes. To avoid typographical errors, - items may not be 3 letters long (USA) -
- -^(?!\s*$).+
- ^[A-Za-z]{3}$
- "Global"
-
- "South East Asia"
-
- "Europe and Central Asia"
-
- "North America"
-
- "US"
-
- "DE"
-
- "PH"
-
- Label object with optional abbreviation.
- - No Additional Properties - -Full name or label
- -
- Must be at most 200 characters long
-
Short name, acronym, or abbreviation
- - -
- Must be at most 20 characters long
-
Common definition of a metric used across pathway schemas.
- - No Additional Properties - -Display name of the metric
- -- Specifies which parts of the sector value chain the metric - applies to. -
- - -
- Must be at most 1000 characters long
-
A schema for the pathway metadata dataset in TPR.
- - No Additional Properties - -- URI of the schema that validates this document (see - https://json-schema.org/). -
- - -
- Must be at most 1000 characters long
-
The unique identifier for a pathway.
- - -
- Must be at most 100 characters long
-
Name of the pathway.
- - No Additional Properties - -Full name or label
- -
- Must be at most 200 characters long
-
Short name, acronym, or abbreviation
- - -
- Must be at most 20 characters long
-
Brief description of the pathway.
Must match regular expression:\.$
-
-
- Must be at most 100 characters long
-
Bibliographic information about the report or dataset.
- - - No Additional Properties - -Title of the report or publication.
- -Optional subtitle of the publication.
- - -
- Must be at most 300 characters long
-
- Publisher or organization responsible for the - publication. -
- - -- 😅 ERROR in schema generation, a referenced schema - could not be loaded, no documentation here - unfortunately 🏜️ -
- -"ASEAN Centre for Energy"
- "ACE"
- "Indonesia Just Energy Transition
- Partnership Secretariat"
- "JETP ID"
- "Center for Global Sustainability
- and Institute for Essential Services
- Reform"
- "CGS, IESR"
- "Electricity and Renewable Energy
- Authority in Viet Nam, Danish Energy
- Agency"
- "VN EREA, DEA"
- "European Commission, Joint
- Research Centre"
- "JRC"
- "Institute for Sustainable Futures,
- University of Technology
- Sydney"
- "UTS ISF"
- "International Energy Agency"
- "IEA"
- "Network of Central Banks and
- Supervisors for Greening the
- Financial System"
- "NGFS"
- "Philippines Department of
- Energy"
- "Sustainable Development Solutions
- Network and ClimateWorks
- Centre"
- "UN SDSN, CW"
- "TransitionZero"
- Allowed full publisher names.
- - -- Allowed short publisher names or acronyms. -
- - -Year of publication.
- - -
- Value must be greater or equal to 1900 and
- lesser or equal to 2100
-
Month of publication (1–12).
- - -
- Value must be greater or equal to 1 and
- lesser or equal to 12
-
Day of publication (1–31).
- - -
- Value must be greater or equal to 1 and
- lesser or equal to 31
-
City where the publication was published.
- - -
- Must be at most 100 characters long
-
- Digital Object Identifier for the publication. -
Must match regular expression: -^10\.[^\s/]+/.+$
- International Standard Book Number, if applicable.
- - -
- Must be at most 32 characters long
-
- International Standard Serial Number, if applicable. -
Must match regular expression: -^[0-9]{4}-[0-9]{3}[0-9X]$
- License under which the document is published
- - -
- Must be at most 100 characters long
-
- Links to related materials such as data, supplementary - files, or the full report. -
- - - No Additional Items -Short label for the linked resource.
- - -
- Must be at most 100 characters
- long
-
URL to the linked resource.
Must match regular expression: -^(https?|ftp):\/\/[^\s/$.?#].[^\s]*$
- Type of the pathway pathway.
- -- Year by which net zero is reached in the pathway. If Pathway - does not reach net zero, this field should be omitted. -
- - -
- Value must be greater or equal to 2030 and lesser
- or equal to 2100
-
Year from which the model starts.
- - -
- Value must be greater or equal to 1900 and lesser
- or equal to 2030
-
Year in which the model ends.
- - -
- Value must be greater or equal to 2030 and lesser
- or equal to 2100
-
- Modeled temperature increase expected by the pathway (in degrees - Celsius). -
- - -
- Value must be greater or equal to 0.5 and lesser
- or equal to 3 and a multiple of
- 0.1
-
Geographical areas that the pathway covers.
- - - No Additional Properties - -True if the pathway covers the entire world.
- -- Map from an author-defined region label (as named in the - publication) to the ISO-3166-1 alpha-2 country codes in - that region. Member arrays may be empty when the - publication does not provide a mapping. -
- - -- Each additional property must conform to the - following schema -
- - - Type: array- All items must be unique -
- No Additional Items -- 😅 ERROR in schema generation, a referenced - schema could not be loaded, no documentation - here unfortunately 🏜️ -
- -- Standalone ISO-3166-1 alpha-2 country codes covered by - the pathway. -
- - -- All items must be unique -
- No Additional Items -- 😅 ERROR in schema generation, a referenced schema - could not be loaded, no documentation here - unfortunately 🏜️ -
- -Sectors that the pathway covers.
- - - No Additional Items -Display name of a sector.
- - -Technologies applicable to this sector.
- - - No Additional Items -- Display name of the technology as presented in - charts or tables. -
- - -Overview of the pathway.
Must match regular expression:\.$
-
-
- Must be at most 1000 characters long
-
Expert recommendation for the pathway.
Must match regular expression:\.$
-
-
- Must be at most 10000 characters long
-
- All items must be unique -
- No Additional Items -Display name of the metric
- - -Key features of the pathway.
- - No Additional Properties - -- Describes the overall trend of greenhouse gas emissions - over time, from continued growth to rapid decline. -
- -- Indicates how efficiently energy is used to produce - economic output across the sectors covered in the - pathway. -
- -- Captures the change in total energy consumption, driven - by factors such as socio-economic development, - technology shifts and consumer behavior. -
- -- Represents the extent to which energy end-uses - transition from fossil fuels to electricity. -
- -- Identifies the types of policies modeled as drivers of - the pathway, such as carbon pricing, subsidies, or - mandated phaseouts of specific technologies. -
- - -
- Must contain a minimum of 1 items
-
- All items must be unique -
- No Additional Items -- Describes how technology costs evolve over time, from - static cost assumptions to rapidly declining costs - (e.g., via learning curves). -
- -- Defines which greenhouse gases are covered in the - pathway's modeled emissions. -
- - -- Represents the overall stringency and intent of modeled - policies relative to climate targets, often reflecting - if and how far the included policies go beyond currently - legislated ones -
- -- Specifies the level of granularity in cost data, such as - total system costs or detailed CAPEX/OPEX breakdowns. -
- -- Lists emerging or breakthrough technologies that are - explicitly modeled within the pathway. These are - considered in technology deployment too. -
- - -
- Must contain a minimum of 1 items
-
- All items must be unique -
- No Additional Items -- Summarizes how investment requirements are quantified, - from total system to sector-level or supply-chain - detail. -
- -A schema for the pathway timeseries dataset in TPR.
- - No Additional Properties - -- URI of the schema that validates this document (see - https://json-schema.org/). -
- - -
- Must be at most 1000 characters long
-
The unique identifier for a pathway.
- - -
- Must be at most 100 characters long
-
Identifiers of the associated pathways.
- - - No Additional Items -
- Must be at least 1 characters long
-
- Must be at most 100 characters long
-
Name of the timeseries.
- -
- Must be at most 100 characters long
-
Brief description of the timeseries.
Must match regular expression:\.$
-
-
- Must be at most 100 characters long
-
Bibliographic information about the report or dataset.
- - - No Additional Properties - -Title of the report or publication.
- -Optional subtitle of the publication.
- - -
- Must be at most 300 characters long
-
- Publisher or organization responsible for the - publication. -
- - -- 😅 ERROR in schema generation, a referenced schema - could not be loaded, no documentation here - unfortunately 🏜️ -
- -"ASEAN Centre for Energy"
- "ACE"
- "Indonesia Just Energy Transition
- Partnership Secretariat"
- "JETP ID"
- "Center for Global Sustainability
- and Institute for Essential Services
- Reform"
- "CGS, IESR"
- "Electricity and Renewable Energy
- Authority in Viet Nam, Danish Energy
- Agency"
- "VN EREA, DEA"
- "European Commission, Joint
- Research Centre"
- "JRC"
- "Institute for Sustainable Futures,
- University of Technology
- Sydney"
- "UTS ISF"
- "International Energy Agency"
- "IEA"
- "Network of Central Banks and
- Supervisors for Greening the
- Financial System"
- "NGFS"
- "Philippines Department of
- Energy"
- "Sustainable Development Solutions
- Network and ClimateWorks
- Centre"
- "UN SDSN, CW"
- "TransitionZero"
- Allowed full publisher names.
- - -- Allowed short publisher names or acronyms. -
- - -Year of publication.
- - -
- Value must be greater or equal to 1900 and
- lesser or equal to 2100
-
Month of publication (1–12).
- - -
- Value must be greater or equal to 1 and
- lesser or equal to 12
-
Day of publication (1–31).
- - -
- Value must be greater or equal to 1 and
- lesser or equal to 31
-
City where the publication was published.
- - -
- Must be at most 100 characters long
-
- Digital Object Identifier for the publication. -
Must match regular expression: -^10\.[^\s/]+/.+$
- International Standard Book Number, if applicable.
- - -
- Must be at most 32 characters long
-
- International Standard Serial Number, if applicable. -
Must match regular expression: -^[0-9]{4}-[0-9]{3}[0-9X]$
- License under which the document is published
- - -
- Must be at most 100 characters long
-
- Links to related materials such as data, supplementary - files, or the full report. -
- - - No Additional Items -Short label for the linked resource.
- - -
- Must be at most 100 characters
- long
-
URL to the linked resource.
Must match regular expression: -^(https?|ftp):\/\/[^\s/$.?#].[^\s]*$
- Name of the associated pathway.
- - -
- Must be at most 100 characters long
-
- Defines which greenhouse gases are covered in the pathway's - modeled emissions. -
- - -- Array of yearly data points for each sector, technology, and - metric defined in this timeseries. -
- - - No Additional Items -- If the conditions in the "If" tab are respected, then - the conditions in the "Then" tab should be respected. - Otherwise, the conditions in the "Else" tab should be - respected. -
- - -"emissionsIntensity"
-
- Value must be greater or equal to
- -2 and lesser or equal to
- 2
-
- If the conditions in the "If" tab are respected, then - the conditions in the "Then" tab should be respected. - Otherwise, the conditions in the "Else" tab should be - respected. -
- - -"capacity"
-
- Value must be greater or equal to
- 0
-
- If the conditions in the "If" tab are respected, then - the conditions in the "Then" tab should be respected. - Otherwise, the conditions in the "Else" tab should be - respected. -
- - -"generation"
-
- Value must be greater or equal to
- 0
-
- If the conditions in the "If" tab are respected, then - the conditions in the "Then" tab should be respected. - Otherwise, the conditions in the "Else" tab should be - respected. -
- - -"technologyMix"
- "%"
-
- Value must be greater or equal to
- 0 and lesser or equal to
- 100
-
- If the conditions in the "If" tab are respected, then - the conditions in the "Then" tab should be respected. - Otherwise, the conditions in the "Else" tab should be - respected. -
- - -"absoluteEmissions"
- "MtCO2e"
- "Global"
- "power"
-
- Value must be lesser or equal to
- 2023
-
- Value must be lesser or equal to
- 20000
-
- If the conditions in the "If" tab are respected, then - the conditions in the "Then" tab should be respected. - Otherwise, the conditions in the "Else" tab should be - respected. -
- - -"absoluteEmissions"
- "MtCO2e"
- "Global"
- "power"
-
- Value must be greater or equal to
- 2024
-
- Value must be lesser or equal to
- 30000
-
- If the conditions in the "If" tab are respected, then the - conditions in the "Then" tab should be respected. Otherwise, - the conditions in the "Else" tab should be respected. -
- - -"power"
- - If the conditions in the "If" tab are respected, - then the conditions in the "Then" tab should be - respected. Otherwise, the conditions in the "Else" - tab should be respected. -
- - -"emissionsIntensity"
- "tCO2e/MWh"
- - If the conditions in the "If" tab are respected, - then the conditions in the "Then" tab should be - respected. Otherwise, the conditions in the "Else" - tab should be respected. -
- - -"absoluteEmissions"
- "MtCO2e"
- - If the conditions in the "If" tab are respected, - then the conditions in the "Then" tab should be - respected. Otherwise, the conditions in the "Else" - tab should be respected. -
- - -"capacity"
- "GW"
- - If the conditions in the "If" tab are respected, - then the conditions in the "Then" tab should be - respected. Otherwise, the conditions in the "Else" - tab should be respected. -
- - -"generation"
- "TWh"
- - If the conditions in the "If" tab are respected, - then the conditions in the "Then" tab should be - respected. Otherwise, the conditions in the "Else" - tab should be respected. -
- - -"technologyMix"
- "%"
- Calendar year of the data point.
- - -
- Value must be greater or equal to
- 1900 and lesser or equal to
- 2100
-
- Geographical area that the data covers. This should - be a single string value: either 'Global', a country - ISO-3166-1 alpha-2 code (e.g., 'US', 'DE'), or a - free-text region name (e.g., 'North America', 'South - East Asia'). Only 2-letter codes are accepted for - countries; do not use full country names or 3-letter - codes (e.g., 'USA' is not allowed). If a 2-letter - code does not map to a country (e.g., 'EU'), it will - result in an error. -
- - -^(?!\s*$).+
- ^[A-Za-z]{3}$
- "Global"
-
- "South East Asia"
-
- "Europe and Central Asia"
-
- "North America"
-
- "US"
-
- "DE"
-
- "PH"
-
- - Sector to which this data point belongs (must match - one of the defined sectors). -
- -- Technology represented in this record (e.g., Solar, - Wind, or null if sector-level only). -
- -- Metric reported for this record (e.g., Capacity, - Generation, Emissions Intensity). -
- -- Numeric value of the metric for the given year, - sector, and technology. -
- -- Measurement unit associated with the metric value - (e.g., GW, TWh, tCO2e). -
- -Bibliographic information about the report or dataset.
- - No Additional Properties - -Title of the report or publication.
- - - No Additional Properties - -Full name or label
- -
- Must be at most 200 characters long
-
Short name, acronym, or abbreviation
- - -
- Must be at most 20 characters long
-
Optional subtitle of the publication.
- - -
- Must be at most 300 characters long
-
Publisher or organization responsible for the publication.
- - -"ASEAN Centre for Energy"
- "ACE"
- "Indonesia Just Energy Transition
- Partnership Secretariat"
- "JETP ID"
- "Center for Global Sustainability and
- Institute for Essential Services
- Reform"
- "CGS, IESR"
- "Electricity and Renewable Energy Authority
- in Viet Nam, Danish Energy Agency"
- "VN EREA, DEA"
- "European Commission, Joint Research
- Centre"
- "JRC"
- "Institute for Sustainable Futures,
- University of Technology Sydney"
- "UTS ISF"
- "International Energy Agency"
- "IEA"
- "Network of Central Banks and Supervisors
- for Greening the Financial System"
- "NGFS"
- "Philippines Department of Energy"
- "Sustainable Development Solutions Network
- and ClimateWorks Centre"
- "UN SDSN, CW"
- "TransitionZero"
- Allowed full publisher names.
- - -Allowed short publisher names or acronyms.
- - -Year of publication.
- -
- Value must be greater or equal to 1900 and lesser
- or equal to 2100
-
Month of publication (1–12).
- - -
- Value must be greater or equal to 1 and lesser or
- equal to 12
-
Day of publication (1–31).
- -
- Value must be greater or equal to 1 and lesser or
- equal to 31
-
City where the publication was published.
- - -
- Must be at most 100 characters long
-
Digital Object Identifier for the publication.
Must match regular expression: -^10\.[^\s/]+/.+$
- International Standard Book Number, if applicable.
- - -
- Must be at most 32 characters long
-
- International Standard Serial Number, if applicable. -
Must match regular expression: -^[0-9]{4}-[0-9]{3}[0-9X]$
- License under which the document is published
- - -
- Must be at most 100 characters long
-
- Links to related materials such as data, supplementary files, or - the full report. -
- - - No Additional Items -Short label for the linked resource.
- - -
- Must be at most 100 characters
- long
-
URL to the linked resource.
Must match regular expression: -^(https?|ftp):\/\/[^\s/$.?#].[^\s]*$
- Common definition of a sector used across pathway schemata.
- - No Additional Properties - -Display name of a sector.
- -Technologies for sectors
- No Additional Properties - -- Display name of the technology as presented in charts or tables. -
- - -