Carbon.txt syntax

This page specifies the current v0.4 syntax for carbon.txt files.

Viewing syntax for

Carbon.txt v0.4

Latest version	Language	Valid from	Valid to
true	TOML	2025-12-02	-

Syntax

Property	Parent	Type	Required	Description
version		string	true	carbon.txt syntax version, e.g. "0.4", required from version 0.3 onwards.
`version = "0.4"`

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-12-13".
`last_updated = "2025-12-13"`

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-12-13".
↳ 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.).
↳ title	disclosures	string	false	A meaningful title describing the disclosure.
`[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", title = "Emissions Report 2025" } ]`

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.
`[upstream] services = [ { domain = "cloud.google.com", service_type = "shared-hosting" }, { domain = "aws.amazon.com", service_type = "cdn" } ]`

Code sample

version="0.4"
last_updated="2025-12-13"

[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", title = "Emissions Report 2025" }
]

[upstream]
services = [
	{ domain = "cloud.google.com", service_type = "shared-hosting" },
	{ domain = "aws.amazon.com" }
]