Introducing our new work on carbon.txt – the carbon.txt validator and an updated spec

Over the last few months we’ve been working on some new software to make it easier to discover sustainability data online. These data disclosures are driven by laws like the Corporate Sustainability Reporting Directive (CSRD) in Europe that come into effect this year. In this post, our Tech and Policy Director Chris Adams introduces the new releases, showing what you can do with the software, and shares few new updates to the developing carbon.txt spec.

Setting the context around carbon.txt

Last year, we wrote a post introducing our carbon.txt project – an open source project to make sustainability information easier to discover and use. We also wrote about why we felt that having a single place to look on any domain for public sustainability data relating to that company was a good idea.

We followed this with a bunch of primary research: in-depth interviews with experts on the new disclosure laws, and people in the technology sector who had to prepare the documents that contained this new data coming into the public domain.

We also spent a decent amount of time thinking about how the architecture of our own platform might need to change if we were to ‘eat our own dogfood’, and start using this newly public data in our own verification process. We offer a verification service for hosting providers who want to make claims about running their digital infrastructure on green energy. If this describes you, then check our guidance on how to get verified.

You can see the extensive report called Making carbon.txt work in the Green Web Foundation, elsewhere on the website, where it summarises our thinking and our intended approach.

We spent the last 2-3 months building the software described in that report and now we have:

1. An extendable open source carbon.txt validator – written in Python, that works as a stand-alone project from our platform. This has an API for parsing, validating, and processing carbon.txt files, plus any disclosure documents linked in them like CSRD reports.
2. A refreshed carbon.txt website – this has an updated file builder and syntax checker that integrates with the validation tool.
3. Updated documentation – instructions on creating, and using carbon.txt files, as well as guidance on extending the validator to do useful new things with linked disclosure documents.
4. Example plugins demonstrating how we are using carbon.txt ourselves – shows how we are parsing data in documents like CSRD reports being published later this year.

In the next part of this post we look at each of these in more detail.

1. An extendable open source carbon.txt validator

Our goal is for people to adopt carbon.txt as a mechanism for linking to disclosed sustainability data in various forms. To enable people to share this type of data in a predictable, structured fashion, it makes sense to have tooling available to increase the likelihood of this happening successfully. Our open-source accessible tooling is designed to allow others to do just this: build carbon.txt files in a low-effort and error-free way.

The first part of our suite of tools is the carbon.txt validator. It reads carbon.txt files and validates them against a spec defined on http://carbontxt.org.

Under the hood it is written in Python and is available for download from the Pypi software repository at https://pypi.org/project/carbon-txt. It’s also being developed in the open on Github at https://github.com/thegreenwebfoundation/carbon-txt-validator.

This validator works locally on the command line for easy integration into data pipelines. It also offers an OpenAPI-compatible API that supports building new software on top of it. We used the API to provide the tools on our project website, found at carbontxt.org.

Under the hood this validator uses an XBRL-certified validating processor, Arelle, for parsing CSRD reports. This is the same software people use for parsing financial data. This is neat because sustainability data is increasingly being treated with the same respect as financial data.

2. A refreshed carbon.txt website

The second part of our suite of recent work is our carbon.txt website. Its been around since we ran an initial, closed pilot of the carbon.txt idea a few years ago. Our recent funding from NGI Search has allowed us to build out our ideas and create the new validator package described above. The website is now a key tool in its own right demonstrating the validator package in use and empowering people to get using it.

Make carbon.txt files with our file builder

Our interactive builder makes the process of creating carbon.txt files easy. A carbon.txt file can contain two key sections of information:

1. Links to online documents that show evidence of your green claims, such as CSRD, EED, ESG and/or other sustainability reporting.
2. Disclosures of the supply chain of digital services your organisation uses.

To help you along the way, our updated specification also explains the different elements that make up valid carbon.txt syntax.

Validating carbon.txt files

As mentioned, while we have built tooling that lets you validate and parse carbon.txt files locally, the tools also offer an API. In fact, our online validator demonstrates the use of this API to both check the syntax of the contents of carbon.txt files.

Additionally we have extended that functionaility using the plugin architecture to parse and process linked documents you might use for disclosure. We’ll cover this in more detail shortly.

3. Updated technical documentation

The third part of our recent work is our technical documentation which signposts to instructions on creating and using carbon.txt files, and explains how developers can extend the carbon.txt code.

Our carbon.txt approach is very much about connecting, not collecting sustainability data. Therefore we want to empower the wider developer community to connect to all types of data in the ways that suit them. Our tech docs also have guidance for developers who wish to extend the validator using our plugin system to do other useful new things with linked disclosure documents.

In fact, the functionality in our online implementation of the validator, the ability to parse CSRD reports and output its data in human readable format is implemented as a plugin to demonstrate how this works.

4. Example plugins demonstrating how we are using carbon.txt ourselves

Lastly we come to the fourth element of our recent work – the example plugins. The online version of the carbon.txt validator seen on the carbon.txt website uses a custom plugin we’ve built that extends the validator package. This plugin focuses on a subset of data related to green energy in the E1 part of the European Sustainability Reporting Standards.

Under the hood this data is parsed using Arelle – one of the same libraries used in software to help companies publish this data too.

Because the code is open source, you can see the specific data points we’re targetting – here’s the Python class containing them. If you follow the link you’ll see things listed like “E1-5 AR 34 – Percentage of renewable sources in total energy consumption”, and so on.

For now, you can view a running list of all the example plugins we’ve created on our internal docs site.

Querying for more than green energy

We’re focussing on that specific subset of ESRS E1 because our mission as an organisation has historically been orientated around green energy. But CSRD does cover a range of other environmental justice and governance-related considerations, and these all have their own standardised datapoints you could query by extending our tooling.

So if you cared about say… Pollution (ESRS E2) or Water and Marine Resources (ESRS E3) you’d make your own plugin and list a different set of datapoints instead. This makes it pretty straight forward to extend carbon.txt to query any published report from any company covered by the CSRD in Europe, and there are thousands of them.

The full list of datapoints that we might expect to be published is extensive. For those curious we’ve published a list from EFRAG of ALL the datapoints that can be queried. EFRAG is the organisation acting as a steward for the standards, so it’s about as close to the source as we can find.

Querying more than just CSRD reports

We’ve focussed quite a lot on the CSRD in carbon.txt files in this blog post. We’ve done so because we think it’s an important law, and the reports mandated by the CSRD should be very data-rich documents. But it’s not the only form of structured, disclosed sustainability data.

We know that every datacentre in Europe above certain size has had to compile and publish similar kinds of data as a result of the Energy Efficiency Directive, which we’ve written about. How about a plugin for parsing those documents?

We know that all certified B-Corps above a certain size also need to make parts of their B Impact Assessment public. If this is in the public domain, then we shoud be able to link to it, and make this information easier to discover and use. Maybe a plugin for that too?

Zooming specifically into green energy, we’ve been working with Energy Tag and Green Software Foundation, and poring over the APIs and specs they publish. It looks like it’s technically possible to publicly link to a set of certificates for a specific amount of period of power, from a specific generation plant, at a specific time, to back claims about powering digital infrastructure with clean energy. We’ve outlined how in this issue here in the GSF’s Real time Cloud working group project.

These potential for expanding carbon.txt to query these other kinds of data open up an unprecedented level of transparency, and speaks to how a connect, not collect style approach is powerful, webby and from our point of view really exciting.

How to get involved

Need support?

For technical queries or suggestions, please open an issue on the carbon-txt-site github repository – our chosen place for community support.

For a query you’re not comfortable sharing publicly, or for commercial support using any of the tooling around carbon.txt, please use our contact form.

Onwards!