Carbon.txt syntax
This page specifies the current v0.3 syntax for carbon.txt files.
Viewing syntax for
Carbon.txt v0.3
| Latest version | Language | Valid from | Valid to |
|---|---|---|---|
| true | TOML | 2025-11-24 | - |
Syntax
| Property | Parent | Type | Required | Description |
|---|---|---|---|---|
| version | string | true | carbon.txt syntax version, e.g. "0.3", required from version 0.3 onwards. | |
| ||||
| Property | Parent | Type | Required | Description |
|---|---|---|---|---|
| last_updated | string | false | The date this file was last updated, as a string in ISO8601 format, e.g "2025-11-26". | |
| ||||
| Property | Parent | Type | Required | Description |
|---|---|---|---|---|
| org | [table] | true | ||
| ↳ disclosures | org | [[array]] | true | Links to documents that show your organisations sustainability data disclosures. |
| ↳ doc_type | disclosures | string | true | A slugified string representing the type of document you are linking to. Accepted values are: "web-page", "annual-report", "sustainability-page", "certificate", "csrd-report", "other" |
| ↳ url | disclosures | url | true | The URL of the document you are linking to beginning with "http://" or "https://. |
| ↳ valid_until | disclosure | date | false | The last date that this disclosure is valid for, if it is time-limited (for example, an annual report or renewable energy certificate), as a string in ISO8601 format, e.g "2025-11-26". |
| ↳ domain | disclosures | string | false | The domain for which the disclosure applies, if this carbon.txt is to be used across multiple domains. This can include any subdomains (e.g. "www."), but should not include the protocol (i.e. "http://" or "https://") or any content paths (e.g "/news/", "/about", "news-update-2025" etc.). |
| ||||
| Property | Parent | Type | Required | Description |
|---|---|---|---|---|
| upstream | [table] | false | ||
| ↳ services | upstream | [[array]] | false | Information linking your organisation to upstream providers you use. |
| ↳ domain | services | string | false | The domain of the organisation providing the upstream service. This can include any subdomains (e.g. "www."), but should not include the protocol (i.e. "http://" or "https://") or any content paths (e.g "/news/", "/about", "news-update-2025" etc.). |
| ↳ service_type | services | string or ["array of strings"] | false | A slug representing the service provided by the upstream provider. |
| ||||
Code sample
version="0.3"
last_updated="2025-11-26"
[org]
disclosures = [
{ doc_type = "web-page", url = "https://mycompany.com/sustainability", domain = "mycompany.com" },
{ doc_type = "annual-report", url = "https://mycompany.com/carbon-emissions-2025.pdf", valid_until = "2025-12-31" }
]
[upstream]
services = [
{ domain = "cloud.google.com", service_type = "shared-hosting" },
{ domain = "aws.amazon.com" }
]