Reporting Organisation Schema v0.1.0

The Reporting Organisation Schema defines the root structure for Technology Carbon Standard documents, including organisation details and the collection of emissions reports over time.

Purpose

The Reporting Organisation Schema provides:

• Organisational Context: Captures essential information about the reporting entity
• Report Collection: Manages multiple emissions reports with different schema versions
• Flexibility: Allows each emissions report to use different schema versions as standards evolve
• Identification: Links organisations to external registries like Open Corporates

Schema Information

• Schema ID: https://techcarbonstandard.org/schemas/reporting_organisation/v0.1.0.json
• Version: 0.1.0
• Parent Schema: Referenced by Router Schema for version 0.1.0
• Child Schemas: References Emissions Report schemas

Schema Structure

{
  "schema_version": "0.1.0",
  "organisation": {
    "organisation_name": "Example Corp",
    "description": "Description of the organisation",
    "open_corporates_url": "https://opencorporates.com/companies/gb/12345678",
    "registered_country": "England"
  },
  "emissions_reports": [
    {
      "schema_version": "0.0.1",
      // Emissions report content validated against v0.0.1 schema
    }
  ]
}

Root Level Fields

Schema Version (required)

Specifies the version of the Reporting Organisation Schema being used:

"schema_version": "0.1.0"

Organisation (required)

Contains information about the reporting organisation:

"organisation": {
  "organisation_name": "Scott Logic",
  "description": "Software consultancy specialising in complex applications",
  "open_corporates_url": "https://opencorporates.com/companies/gb/05377430",
  "registered_country": "England"
}

Organisation Fields

Emissions Reports (required)

An array containing one or more emissions reports. Each report can use a different schema version:

"emissions_reports": [
  {
    "schema_version": "0.0.1",
    "reporting_period": {
      "from_date": "2023-01-01",
      "to_date": "2023-12-31"
    },
    "verification": "self reported",
    "tech_carbon_standard": {
      "schema_version": "0.0.1"
    }
  }
]

Emissions Report Versioning

Each emissions report specifies its own schema version, allowing organisations to:

• Migrate Gradually: Use newer schema versions for new reports while maintaining historical data
• Mix Versions: Have reports from different time periods using different schema versions
• Future-Proof: Adopt new schema features as they become available

Currently supported emissions report schema versions:

• "0.0.1" - Initial emissions report schema

Validation Rules

Required Fields

• Root level schema_version must be "0.1.0"
• organisation object is required
• organisation.organisation_name is required
• emissions_reports array is required and must contain at least one report
• Each emissions report must have a valid schema_version

Additional Properties

• Root level: No additional properties allowed (additionalProperties: false)
• Organisation level: No additional properties allowed (additionalProperties: false)
• Emissions reports: Additional properties allowed (additionalProperties: true) to accommodate different schema versions

Example Document

{
  "schema_version": "0.1.0",
  "organisation": {
    "organisation_name": "Scott Logic",
    "description": "Software consultancy and product development company",
    "open_corporates_url": "https://opencorporates.com/companies/gb/05377430",
    "registered_country": "England"
  },
  "emissions_reports": [
    {
      "schema_version": "0.0.1",
      "reporting_period": {
        "from_date": "2023-01-01",
        "to_date": "2023-12-31"
      },
      "verification": "self reported",
      "tech_carbon_standard": {
        "schema_version": "0.0.1",
        "upstream_emissions": {
          "employee_hardware": {
            "emissions": 55000,
            "notes": "Embodied carbon of purchased laptops and monitors"
          }
        },
        "direct_emissions": {
          "onsite_employee_hardware": {
            "emissions": 5000,
            "notes": "Office electricity consumption for employee devices",
            "method": "location-based"
          }
        }
      }
    }
  ]
}

Migration from v0.0.1

If migrating from the original schema (v0.0.1), key changes include:

1. Root Structure: The document structure now explicitly separates organisation information from emissions reports
2. Organisation Object: Organisation details are now grouped in a dedicated organisation object
3. Schema Versioning: Both the root schema and emissions reports have explicit version declarations
4. Report Array: Emissions reports are now contained in an array, allowing multiple reports per organisation

Testing

The schema includes a set of unit tests which use the Jest testing framework.

To run the tests:

1. Ensure Node.js is installed (version 17+ is required)
2. Install dependencies:

   npm install
   

3. Run the tests:

   npm test
   

The tests are located in schemas/tests and load example data from the schemas/examples directory.

Any new tests with the extension .spec.ts will be picked up by the npm test command.

Validation

The schema includes a validation utility based on AJV (Another JSON Validator).

Running the Validator

To validate a TCS document:

1. Ensure Node.js is installed
2. Install dependencies:

   npm install ajv ajv-formats
   

3. Run the validator:

   node schemas/validators/validate.js
   

The validator will:

• Check if all required schema files exist
• Load and parse all schemas
• Register them with AJV
• Validate the example document against the schema
• Display detailed error messages if validation fails

Common Validation Errors

1. Missing schema_version: Ensure the root level has "schema_version": "0.1.0"
2. Missing organisation_name: The organisation object must include organisation_name
3. Empty emissions_reports: At least one emissions report is required
4. Invalid URI format: open_corporates_url must be a valid URI if provided

Related Documentation

• Router Schema
• Emissions Report Schema v0.0.1
• Tech Carbon Standard Schema v0.0.1
• Implementation Guide

Resources

• Schema File
• GitHub Repository
• Open Corporates - For organisation registration lookup