Internet-Draft Sustainability-Data Well-Known URI September 2026
Besleaga Expires 13 March 2027 [Page]
Workgroup:
Independent Submission
Internet-Draft:
draft-besleaga-sustainability-wellknown-06
Published:
Intended Status:
Informational
Expires:
Author:
A. N. Besleaga
Independent

The 'sustainability-data' Well-Known URI

Abstract

This document defines the "sustainability-data" well-known URI. This URI provides a uniform, out-of-band convention for web servers and digital services to publish aggregated environmental impact, energy consumption, and carbon footprint metrics for a declared reporting subject -- typically the publishing origin itself.

The convention publishes a single, cacheable JSON document per origin, described by formal schemas and discoverable at a fixed location without prior arrangement, so that environmental disclosures can be located, validated, and ingested automatically. Publication is voluntary, and the metrics are self-asserted claims of the publisher, linked to the publisher's methodology and supporting evidence.

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."

This Internet-Draft will expire on 13 March 2027.

▲

Table of Contents

1. Introduction

The digital economy consumes a significant and growing percentage of global electricity. Emerging regulatory frameworks, such as the EU Corporate Sustainability Reporting Directive (CSRD) [EU-CSRD], as well as industry standards like the Green Software Foundation's Software Carbon Intensity [GSF-SCI] and the W3C Web Sustainability Guidelines [W3C-WSG], increasingly call for organizations to disclose the environmental impact of their digital services.

These transparency efforts align with the United Nations 2030 Agenda for Sustainable Development [UN-SDG], specifically supporting energy efficiency and sustainable infrastructure targets, encouraging companies to integrate sustainability information into their reporting cycles. The need for better data on the environmental impact of Internet systems, and the current gaps in that data, are documented in the report of the IAB Workshop on Environmental Impact of Internet Applications and Systems [RFC9547].

This specification defines a voluntary, purely technical publication mechanism: it standardizes where such a disclosure can be found and what its members mean, not whether anyone publishes one. Nothing in this document creates, discharges, or verifies any regulatory obligation; the regimes cited above motivate the need for a standardized machine-readable form and fix the vocabulary that this document's members map onto, and any obligation to publish, or consequence of publishing, arises outside this specification.

This document leverages [RFC8615] to define a /.well-known/sustainability-data URI for out-of-band reporting. A well-known URI is the established pattern for this shape of problem -- site-wide metadata about an origin, published by the origin, that a client must be able to locate knowing nothing but the origin itself, as security.txt ([RFC9116]) does for security contact information. It gives every consumer the same aggregated, cacheable document at a fixed location, decoupled from individual requests; the aggregation is itself part of the document's privacy design (see Privacy Considerations). This mechanism allows servers to publish periodic, aggregated metrics, enabling workflows where environmental impact is a primary constraint alongside cost and performance. The origin publishes the document; the document's mandatory target member declares the reporting subject -- what the metrics are about. Most commonly that is the publishing origin taken as a whole, but the same convention carries, unchanged, a report about a part of that origin (a subdomain, an individual service, or a resource path prefix such as an API), about a device, a cloud tenant, a software product, or a data source, or about the publishing organization itself -- the entity-level energy and greenhouse-gas figures that appear in corporate ESG and climate disclosures, which is the form most regulatory-style reporting already takes. The OPTIONAL target-type member says which of these a given document is about. The origin is only where the document is published; it does not limit what the document may report on (see the URI Definition section).

[Note to the RFC Editor: the remainder of this paragraph records Internet-Draft lineage and may be removed or reworded at publication.] This document continues and replaces draft-besleaga-green-sustainability-wellknown. The rename reflects that this is an individual Independent Submission and is not scoped to any IETF Working Group. Revision -03 reworked the data model: it adopted member omission as the only "not reported" mechanism, reduced the mandatory member set, introduced a mandatory target member identifying the reporting subject, and renamed two carbon members to the CO2e convention; documents built to that data model carry the informational label "2.0", and the changes are breaking with respect to the historical "1.0"/"1.1" field set (see the Changelog). As of revision -04, the requested well-known URI suffix is sustainability-data (earlier revisions requested the suffix sustainability); the change follows Independent-Stream review feedback on the precision expectations of [RFC8615].

The convention is designed to be usable, unchanged, in four consumption contexts: by web clients, as a plain HTTPS GET on a fixed well-known URI with standard HTTP caching and conditional requests; by machine-to-machine and API integrations, as a stable JSON wire format with formal Concise Data Definition Language (CDDL) and JSON Type Definition (JTD) schemas and well-defined query and response semantics; by human readers, through self-describing member names and a mandatory link to the measurement methodology; and by automated agents and AI systems, as a document that is machine-discoverable at a fixed location, schema-validatable, and safe to ingest without content negotiation or prior arrangement.

As a first orientation, the smallest conformant Sustainability Metadata Document carries only the eight mandatory members; the Example Usage section gives fuller examples, including trends and scoped reporting subjects:

{
  "version": "2.0",
  "updated": "2026-01-05T00:00:00Z",
  "capabilities": "basic",
  "provider": "Example Minimal Systems (esg@minimal.example)",
  "measurement-method": "third-party-modeled",
  "methodology-uri": "https://minimal.example/method",
  "reporting-period": "2025",
  "target": "minimal.example"
}

1.1. Requirements Language

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

1.2. Goals and Non-Goals

1.2.1. Goals

  • Provide a single, discoverable location, per origin, for environmental metrics about a declared reporting subject (typically the origin itself).

  • Define a minimal, machine-readable JSON structure, suitable for broad adoption.

  • Ensure interoperability between clients and servers.

  • Define member semantics that map onto quantities already defined by the Greenhouse Gas (GHG) Protocol [GHG-PROTOCOL], the EU CSRD [EU-CSRD] and the European Sustainability Reporting Standards (ESRS) E1 climate standard [ESRS-E1], and product-level disclosure regimes such as the Digital Product Passport established by the EU Ecodesign for Sustainable Products Regulation [EU-ESPR], so that a publisher can republish figures it already produces rather than compute new ones.

  • Mitigate security and privacy risks associated with publishing the data (like hardware fingerprinting).

1.2.2. Non-Goals

  • This document does not mandate a specific calculation or measurement methodology.

  • It does not define how the published figures are verified, validated, certified, or attested; it carries a link to an external attestation, and the OPTIONAL signature of Document Integrity and Signing establishes the integrity and provenance of the document itself, never the accuracy of what it reports.

  • It does not replace domain-specific reporting standards; it defines discovery and semantics and provides a discovery surface for linking to authoritative reports.

1.3. Roles and Processing Model

Two roles interact through this convention. The publisher (the provider defined in the URI Definition section) operates an origin and publishes one document -- and, optionally, its detached signature -- at the well-known location. The consumer is anything that retrieves it: sustainability and ESG aggregators, procurement and reporting pipelines, research crawlers, an operator's own tooling, a browser extension, and equally a person who opens the URL in a browser or fetches it from a command line. The processing rules below are written for automated consumers, because interoperability depends on them; a human reader is served by the same document, through self-describing member names and the mandatory link to the methodology.

A consumer's processing sequence, in the order the normative sections define it, is: retrieve the document over HTTPS, per Mandatory Minimum Supported Service; validate it against the formal schemas and the prose rules of the Payload Format section, applying the defective-value tolerances of Value Constraints and Omitted Metrics; ignore members it does not recognize, per Versioning and Extensibility; attribute the document, and every value in it, to the origin that served it, as a self-asserted claim of that publisher and nothing more (see Trust and Spoofing); judge freshness from the updated and reporting-period members together with ordinary HTTP caching metadata, rather than assuming currency; and follow the methodology-uri, disclosure-uri, and verifiable-attestation-uri members when it needs the measurement method, the wider disclosure record, or third-party corroboration. The hardening expected of a consumer ingesting what is, by design, untrusted input is specified in Consumer Considerations.

The document is therefore two things at once: a compact data record of the metrics themselves, and a discovery surface for the publisher's authoritative reporting -- the linked methodology, disclosure index, and attestations -- through which anything the document cannot itself establish (above all, the accuracy of its figures) must be pursued.

1.4. Relationship to Other Work

This document specifies an application-layer discovery mechanism for aggregated environmental metrics published at the origin level. It defines discovery and data semantics only, over HTTP [RFC9110], and does not profile or constrain the underlying measurement methodology.

In particular, it does not define, profile, or update network-equipment energy metrics, YANG data models, or network-domain energy monitoring and capability discovery. Such work is the subject of the IETF GREEN Working Group and, earlier, of the EMAN framework [RFC7326]; the GREEN charter explicitly excludes carbon accounting and reporting. This document therefore does not overlap with, update, or obsolete any IETF-stream document, and is complementary to that network-layer work. Terminology for energy-efficient network management is being developed in that group [I-D.ietf-green-terminology]; this document's vocabulary is at the reporting and disclosure layer and does not redefine those network-management terms. Sustainability at the level of the Internet as a whole is also a topic of research in the IRTF (for example, the Sustainability and the Internet Research Group, SUSTAIN), which defers protocol standardization to the IETF; this document is an individual Independent Submission and is not a product of, nor endorsed by, any IETF Working Group or IRTF Research Group.

This document complements existing disclosure conventions rather than replacing them. In particular, the Green Web Foundation carbon.txt convention [CARBON-TXT] is a TOML index that links an origin to its published sustainability disclosures (reports, certificates, and hosting or energy-source evidence); it records where an origin's disclosures live, and contains no quantitative metrics. The "sustainability-data" well-known URI instead publishes the numeric metrics themselves in JSON. The two compose without either depending on the other: a Sustainability Metadata Document (defined in the URI Definition section) can link to a disclosure index -- a carbon.txt file being one such form among others -- through the optional disclosure-uri member, and a carbon.txt file can list the /.well-known/sustainability-data endpoint among an origin's disclosures.

2. The "sustainability-data" Well-Known URI

2.1. URI Definition

This document defines the "sustainability-data" well-known URI and requests its registration in the "Well-Known URIs" registry (see the IANA Considerations section). A client requests metrics by issuing an HTTP GET (or HEAD) request. A provider publishing the metadata MUST make it available at the path /.well-known/sustainability-data on the origin, over HTTPS and with the application/sustainability-data+json media type registered by this document, as required in Mandatory Minimum Supported Service.

The same registration reserves one companion resource, /.well-known/sustainability-data.jws, which carries an OPTIONAL detached signature over the document served at the primary path and nothing else; it is specified in Document Integrity and Signing.

  • Origin: The combination of scheme, host, and optional port (e.g., https://example.com); see also the web origin concept [RFC6454].

  • Sustainability Metadata Document: The JSON document returned from /.well-known/sustainability-data.

  • Provider: The entity operating the origin and publishing the sustainability metadata (also referred to as the publisher).

  • Reporting subject: The entity or scope that a Sustainability Metadata Document's metrics describe, identified by the mandatory target member of each object. The origin is where the document is published; the reporting subject is what the data is about -- most commonly the origin itself (see the target member in Mandatory Response Fields for the range of possible subjects).

2.2. Mandatory Minimum Supported Service

The resource MUST be published and retrieved over HTTPS, and clients MUST NOT accept a Sustainability Metadata Document retrieved over unauthenticated HTTP. This is the document's baseline integrity and origin-authentication mechanism, and the reason the rest of this specification can treat a retrieved document as speaking for the origin that served it; the consequences of it, and the protection it does not provide, are given in the Security Considerations section. The HTTP methods, status codes, and header fields used in this document are defined in HTTP Semantics [RFC9110]. Absent redirection, cache revalidation, or rate limiting, a GET request MUST receive a 200 OK with a JSON body when metadata is available; a HEAD request MUST receive the same status and header fields with no message body. If no metadata is published, servers SHOULD respond with 404 Not Found. A request using any method other than GET or HEAD SHOULD receive 405 Method Not Allowed with an Allow: GET, HEAD header ([RFC9110], Section 15.5.6).

Successful (200 OK) responses MUST use the application/sustainability-data+json media type registered in the IANA Considerations section, MUST NOT use any other media type, SHOULD follow I-JSON [RFC7493] for maximum compatibility, and SHOULD include appropriate caching directives (see Operational Considerations). Clients MUST accept application/sustainability-data+json and SHOULD also accept application/json, under which documents published before the registration of the dedicated media type are found in the field; a client MAY, for the same reason, parse a response whose media type is neither, but MUST NOT rely on media typing alone to conclude that a response is a Sustainability Metadata Document, and determines that from the document's own content.

Because the correctness of the media type is what allows a retriever to know precisely what it is getting, servers SHOULD send X-Content-Type-Options: nosniff on responses to the well-known URI, so that a client cannot be induced to interpret the document as some other, more dangerous type. Because the document is public and intended for browser-based clients as well, successful responses SHOULD also include an Access-Control-Allow-Origin: * header (Cross-Origin Resource Sharing), following the practice of WebFinger [RFC7033]. A server MAY redirect the well-known URI; clients that follow a redirect MUST attribute the returned document to the origin of the final response, MUST require HTTPS for every hop, and providers SHOULD NOT redirect to a different origin.

A compliant server MUST support the following "Basic" service level:

  • No Parameters: Requests to the root URI with no query strings.

  • Scope: The response to a parameterless request MUST cover the provider's full declared reporting subject, identified by the target member (see Mandatory Response Fields). When the reporting subject is the origin itself -- the common case -- the metrics MUST represent the aggregate impact of the entire origin, not a subset of its resources. A publisher that cannot yet report at that scope declares a narrower reporting subject instead; see Partial Knowledge and Incremental Adoption.

  • Default Period: The server MUST return the most recently completed reporting period it publishes. A period matching the publisher's own reporting cycle is RECOMMENDED: a full calendar year for the periodic, regulatory-style disclosure that is the common case, or a full calendar month for publishers that report more frequently.

  • Format: The server MUST return a single JSON object.

2.3. Partial Knowledge and Incremental Adoption

The Scope rule above prevents one specific misrepresentation: metrics computed over a subset of a declared reporting subject being presented as the subject's whole. It does not require an organization to understand its entire footprint before publishing anything. Three provisions of this document form the intended on-ramp for a publisher whose visibility is partial:

  • Declare the subject you can stand behind. The reporting subject is whatever the publisher declares in the mandatory target member -- a single service, product, device, tenant, or data source, classified by target-type -- and the parameterless response then covers that declared subject in full. An operator that today understands only its public website, or one region's deployment, publishes for that subject, and widens the declared subject as measurement coverage grows.

  • Report the metrics you have. Every metric member is OPTIONAL, and omission is the only "not reported" mechanism, so a document carrying a single measured quantity is conformant.

  • Estimate the remainder, and say so. A subject-wide figure MAY rest on estimation for the parts not directly measured -- declaring this is what measurement-method is for -- provided the methodology-uri document describes what is measured, what is estimated, and how.

What the Scope rule forbids is only the case these provisions make unnecessary: publishing, for a declared subject, figures that in fact cover part of it while presenting them as the whole.

2.4. Optional Extended Query Parameters

Servers MAY support "Extended" capabilities via the following parameters:

  • target: Scopes the metrics to a resource path prefix (e.g., ?target=/api/v1/search), matched against the origin's resource paths; the value follows URI path syntax [RFC3986] with characters not permitted in a query component percent-encoded. Matching is byte-wise and case-sensitive, on complete path segments, and is performed after percent-decoding. A server that scopes a response to a requested target parameter MUST set the target member of each returned object to the matched prefix. The target query parameter and the target response member are distinct: the parameter requests path-prefix scoping, while the member identifies the reporting subject of whatever is returned (see Mandatory Response Fields). Servers SHOULD honor the target parameter only for a deliberately published set of path prefixes, responding identically (per the no-data rule below) for all other values; this avoids disclosing the existence of unpublished paths (see Privacy Considerations, Path Disclosure). The prefix set is published in the methodology-uri document, alongside the reporting-boundary description that gives the prefixes their meaning; this document deliberately defines no in-band, machine-readable list of honored prefixes, since such a list would itself disclose the path information that rule protects.

  • period: Specifies the timeframe using one of the following calendar-date precision forms (only YYYY-MM-DD is an RFC 3339 [RFC3339] full-date):

    • Year: YYYY (e.g., 2025)

    • Month: YYYY-MM (e.g., 2025-01)

    • Day: YYYY-MM-DD (e.g., 2026-01-01)

    Calendar periods are interpreted in UTC unless the methodology document states otherwise.

    These forms name a whole calendar period rather than a pair of start and end instants, which is a deliberate choice. Calendar periods -- most commonly the reporting year -- are the granularities at which the disclosure regimes this document serves already aggregate their figures, so two publishers reporting 2026 report the same nominal period, subject to the UTC default above, and their documents are directly comparable, whereas arbitrary intervals would have to be re-apportioned before any comparison. Calendar periods also keep the set of distinct parameter values small, enumerable, and canonical, which is what keeps bounded the cache-key space that Denial of Service in the Security Considerations addresses. The forms are the reduced-precision calendar dates of ISO 8601, whose use to denote a whole year or a whole month has wire precedent in vCard [RFC6350], Section 4.3.1; [RFC3339] itself defines no interval type in its normative text. A publisher whose reporting year does not align with the calendar year can publish the constituent months, or the enclosing calendar years, and describe the alignment in the methodology-uri document; an explicit interval form could be introduced later as an extension under Versioning and Extensibility without invalidating any document published under this specification.

  • granularity: Defines the time "slices" within a period. This document defines the values monthly and daily; a server SHOULD ignore an unrecognized value or a granularity that is not finer than the requested period. When the granularity is finer than the period, the server SHOULD return an array of objects.

A period request without a (finer) granularity requests a single object covering exactly that period; a granularity without a period applies to the default period of the Basic service. If the server holds only finer-grained data for the requested period, it SHOULD either aggregate it into a single object or respond per the no-data rule below. Aggregation sums energy and carbon after conversion to a single declared unit; other metrics SHOULD be recomputed for the aggregated period or omitted. The server MUST NOT return an array unless a granularity finer than the period was requested. For a requested period that has not yet completed, the server SHOULD report the completed portion to date.

Servers that do not support the Extended parameters MUST ignore any such parameters and return the Basic response, rather than failing the request. If a supported parameter carries a malformed value (for example, a period that is not a valid date), the server MAY respond with 400 Bad Request, or ignore the offending parameter and process the remainder of the request. (This applies to syntactically invalid values; an unrecognized value of an enumerated parameter such as granularity is instead ignored, as specified above.) When a server supports the requested parameters but has no data for a valid requested period or target parameter value, it SHOULD respond with 404 Not Found (the "no-data rule").

2.5. Payload Format (JSON Data Model)

A successful response body MUST be either a single JSON object [RFC8259] or an array of such objects (an array is used to convey a trend, that is, several reporting periods); the media type is application/sustainability-data+json, as required in Mandatory Minimum Supported Service. A single object is equivalent to a one-element array; clients MUST accept both forms and determine which was returned from the JSON top-level type. An array response MUST contain at least one object (a server with nothing to report follows the no-data rule instead); a client that nevertheless receives an empty array SHOULD treat it as conveying no report.

In an array response, the entries MUST be sorted in ascending order of reporting-period, MUST NOT cover overlapping periods, and MUST share the same period precision and the same target value; target-type MUST be either present in every entry with the same value or absent from every entry. The same units SHOULD be used across all entries; other members (for example, capabilities or provider) are not constrained across entries.

2.5.1. Mandatory Response Fields

  • version (string): An informational label naming the data model the document was built to. This document defines a single value, "2.0", and a publisher of a document conforming to this specification MUST use it. (The value is inherited from the pre-publication drafts of this document, where it distinguished the present data model from an earlier field set; it carries no ordering or comparison semantics, and no consumer computes with it.) The label is a provenance and debugging hint with no negotiation or conformance semantics: clients MUST NOT reject a document, or alter their processing of it, because of this member's value -- including a value this document does not define, which a client treats exactly as it treats "2.0" -- and determine what a document reports from the members actually present. Adding members never calls for a new label; extension members are covered by the ignore-unknown rule (see Versioning and Extensibility).

  • updated (string, date-time): The timestamp ([RFC3339]) when the document was last updated.

  • capabilities (string): A self-declared hint about the query-parameter support a consumer can expect for this reporting subject. It MUST be either "basic" or "extended": "basic" states that the publisher offers only the Mandatory Minimum Supported Service, and "extended" that at least one of the Optional Extended Query Parameters is supported. The member describes query-parameter support only, never which members a document carries: a document declaring "basic" MAY carry any optional member.

    The hint exists to spare a consumer a request that the publisher has already said it will not honor, which is the common case, and nothing in this specification depends on it. It is not authoritative: "extended" promises no particular parameter, since support can differ between parameters and between reporting subjects, and a publisher whose declaration is optimistic causes no failure, because a server that does not support a parameter ignores it and returns the Basic response, as Optional Extended Query Parameters requires. A consumer that ignores this member therefore loses nothing and behaves no differently. Clients determine actual support from the server's behavior, and MUST NOT treat this member as a precondition for issuing a request, or as a guarantee about the response to one.

  • provider (string): Information about the provider publishing the metadata.

  • measurement-method (string): The methodology used, given as a short token or reference. The values hardware-metered, hardware-estimated, cloud-billing, and third-party-modeled are RECOMMENDED and are machine-matchable tokens compared as described in the Internationalization Considerations section; a publisher whose method is not one of these gives a brief description instead, which is human-readable text.

  • methodology-uri (string): Link to the full methodology specification (calculation methodology). In general, the methodology document SHOULD describe the measurement or estimation method in enough detail to interpret the published figures, and is the designated place for details that other provisions of this document direct there -- among them: any non-UTC interpretation of calendar periods, the precise meaning of a functional-unit, the extrapolation behind estimated-annual-emissions-kgCO2e, the net-accounting basis of any negative scope values, and any anti-fingerprinting noise applied (see Privacy Considerations). See also the minimum-reporting rule in Value Constraints and Omitted Metrics.

  • reporting-period (string): The timeframe covered by the object, expressed using the same calendar-date forms as the period parameter (YYYY, YYYY-MM, or the [RFC3339] full-date YYYY-MM-DD); those forms, and the reasons this document names whole calendar periods rather than arbitrary intervals, are given in Optional Extended Query Parameters.

  • target (string): The reporting subject of this object: an identifier of the entity or scope to which the metrics are attributed. It is an opaque protocol element, not display text: clients compare it octet-for-octet and MUST NOT translate or transliterate it (see Internationalization Considerations, which gives the comparison rules for a target that names a host or a path prefix). Typical values are an origin or domain (for an origin-wide report the origin's host, e.g., "example.com", is RECOMMENDED), a resource path prefix (e.g., "/api/v1"), an organizational entity, a cloud tenant or provider scope, a software product or data source (e.g., "example-metrics-feed"), or a device. When the response is scoped by the target query parameter, the member carries the matched prefix, as required in Optional Extended Query Parameters -- which also distinguishes the parameter from this member. The reporting subject SHOULD be within the provider's own operational responsibility; clients SHOULD treat a target naming a subject other than the origin as a claim made by the origin's operator about that subject, and nothing more (see Trust and Spoofing). The OPTIONAL target-type member (see Optional Response Fields) can classify the kind of subject named here.

2.5.2. Optional Response Fields

The JSON object MAY contain the following OPTIONAL keys to align with the GHG Protocol [GHG-PROTOCOL], the ESRS E1 climate standard [ESRS-E1], and other sustainability recommendations:

  • energy-consumption (numeric): Total energy consumed by the reporting subject during the reporting period. The value MUST NOT be negative. It is expressed in the unit given by energy-unit (default kWh; see that member).

  • energy-unit (string): The unit of energy for energy-consumption (MUST be one of: Wh, kWh, MWh, or GWh). When this member is absent, the default kWh applies. Publishers SHOULD state the unit explicitly; an energy-unit member without an accompanying energy-consumption member has no effect and SHOULD be omitted.

  • carbon-footprint (numeric): Total gross emissions impact attributable to the reporting subject during the reporting period, expressed in the unit given by carbon-unit (default gCO2e; see that member). The value MUST NOT be negative; see Value Constraints and Omitted Metrics for the treatment of removals and net accounting.

  • carbon-unit (string): The unit of carbon measurement (MUST be one of: gCO2e, kgCO2e, or mtCO2e). When this member is absent, the default gCO2e applies, both to carbon-footprint and to every other member expressed "in the unit given by carbon-unit". A carbon-unit member without any member it parameterizes has no effect and SHOULD be omitted.

  • carbon-accounting (string): "location-based" or "market-based" (following [GHG-PROTOCOL]).

  • scope-1 (numeric): Estimated Scope 1 (direct) carbon emissions.

  • scope-2 (numeric): Estimated Scope 2 (indirect/purchased energy) carbon emissions.

  • scope-3 (numeric): Estimated Scope 3 (value chain) carbon emissions.

  • sci-score (numeric): Software Carbon Intensity (SCI) score [GSF-SCI]. The value MUST NOT be negative. If sci-score is present, functional-unit MUST also be present.

  • functional-unit (string): The functional unit to which per-unit metrics are expressed (e.g., "per-request", "per-user"); its precise meaning SHOULD be defined in the methodology-uri document.

  • carbon-intensity-gCO2e-per-kWh (numeric): Weighted carbon intensity in grams of CO2e per kWh. The value MUST NOT be negative.

  • estimated-annual-emissions-kgCO2e (numeric): Estimated annual gross emissions attributable to the reporting subject, in kilograms of CO2e regardless of carbon-unit. The value MUST NOT be negative. This is an annualized figure: when reporting-period is shorter than a year, it is an extrapolation, and the extrapolation method SHOULD be described in the methodology-uri document.

  • renewable-energy (numeric): Percentage of energy from renewable sources; the value MUST be between 0 and 100 inclusive.

  • verifiable-attestation-uri (string): Link to a third-party attestation of the published metrics: a statement about them made, and cryptographically signed, by an entity other than the publisher, so that a consumer can check the claim against a party it already trusts. A verifiable credential following the W3C Verifiable Credentials Data Model [VC-DATA-MODEL-2] is one such form; this document does not constrain the format, and a consumer that does not recognize the format learns nothing from the member. Because the attestation is issued by a third party, it is the only mechanism defined here that can establish the authenticity of the published figures, as opposed to their integrity; the signature mechanism of Document Integrity and Signing does not, by itself, do so. Clients MUST NOT treat the mere presence of this member as evidence of anything: it is a claim by the publisher that an attestation exists at that URI, and acquires weight only when the client retrieves the attestation and validates it against an issuer it trusts.

  • disclosure-uri (string): URI of a machine-readable sustainability disclosure index for the origin or reporting subject, that is, a single document listing links to its public sustainability disclosures (reports, certificates, hosting and energy-source evidence). This document does not constrain the format of that index, and does not define or recommend any path at which it is published: the member carries whatever URI the publisher's disclosure index actually has. A disclosure-uri links to supporting evidence, not proof: retrieving and weighing that evidence is the consumer's affair, and the rule that no linked resource verifies the metrics in this document is given in Trust and Spoofing.

  • target-type (string): A hint classifying the reporting subject named by target, to aid machine interpretation of that member. This document defines the following values:

    • origin (the publishing origin itself; target SHOULD then be the origin's host)

    • path (a resource path prefix on the origin)

    • organization

    • service

    • product

    • device

    • tenant

    • data-source

    The member classifies target; it does not change target's syntax or the attribution rules in its definition. A client that does not recognize the value interprets target as if this member were absent (see Value Constraints and Omitted Metrics).

The scope-1, scope-2, and scope-3 values are expressed in the unit given by carbon-unit, including its default; sci-score is expressed in grams of CO2e per the declared functional-unit.

The three URI-valued members (methodology-uri, verifiable-attestation-uri, and disclosure-uri) MUST be absolute URIs [RFC3986] using the "https" scheme, for the same reason the document itself is served over HTTPS: a supporting resource fetched over an unauthenticated channel would carry none of the assurance for which it is being fetched. Clients MUST NOT automatically dereference a URI member carrying any other scheme, and clients that fetch these URIs SHOULD apply the usual protections against server-side request forgery (SSRF), such as refusing redirects or addresses into private networks.

Members not defined in this specification MAY be present; clients handle members they do not recognize per the ignore-unknown rule in Versioning and Extensibility.

2.5.3. Value Constraints and Omitted Metrics

A metric that is not reported for the scope or period covered by an object is omitted from that object. This document defines no in-band "not reported" marker: a member that is present always carries an actual value. Consumers that require a value not present in a Sustainability Metadata Document SHOULD look to the linked disclosure or reporting resources.

Several numeric members carry range constraints in their definitions: the gross-quantity members (energy-consumption, carbon-footprint, sci-score, carbon-intensity-gCO2e-per-kWh, and estimated-annual-emissions-kgCO2e) are non-negative, and renewable-energy is bounded to 0-100. carbon-footprint reports gross emissions. Where the declared carbon-accounting methodology supports them, carbon removals, offsets, and net accounting are conveyed through scope-1, scope-2, and scope-3, which MAY be negative for that purpose, or through the linked attestation or disclosure resources; a publisher reporting a negative scope value SHOULD explain the net-accounting basis in the methodology-uri document.

A client encountering a defective member value SHOULD NOT reject the document; instead:

  • A value outside a member's stated range (for example, a negative value in a member defined here as non-negative) is treated as not reported.

  • A value of the wrong JSON type (including null) is treated as not reported.

  • An unrecognized value in an enumerated string member defined here (capabilities, energy-unit, carbon-unit, carbon-accounting, or target-type) causes that member to be disregarded. For a unit member, the numeric member(s) it parameterizes are then treated as not reported; for capabilities, the client relies on observed server behavior, as that member's definition directs; for target-type, the client interprets target as if the member were absent.

  • A sci-score unaccompanied by functional-unit is treated as not reported.

Note that the CDDL and JTD schemas below close the enumerated value sets. A validating client whose schema check fails only on such a defective value SHOULD apply this tolerance rather than reject the document; a validating client is to assume that the schemas, like the member set they describe, will be extended over time (see Versioning and Extensibility). A document that omits a mandatory member does not conform to this specification; a consumer MAY read the members such a document does carry, but MUST NOT treat it as a conformant Sustainability Metadata Document.

A Sustainability Metadata Document (in an array response, at least one of its objects) SHOULD contain at least one reported numeric metric (for example, energy-consumption or carbon-footprint) or at least one of disclosure-uri or verifiable-attestation-uri. A document containing none of these can be conformant only by virtue of the mandatory methodology-uri, and this document defines that case narrowly: such a document is conformant only if the resource identified by methodology-uri (in an array response, by each object's methodology-uri) is publicly retrievable without authentication or payment, describes the measurement or estimation method, and either states the metric values themselves or points directly to where they are published. These are conformance conditions on the document, not obligations on the publisher's business: a publisher whose methodology or figures sit behind access control publishes a conformant document by reporting at least one metric member or evidence link in the document itself. A consumer MAY treat a metric-less document whose methodology-uri resource is not so retrievable as carrying no disclosure.

2.5.4. Versioning and Extensibility

This document is designed so that new members can be introduced over time without breaking deployed clients and without revising this specification.

  • Forward compatibility rests on a single rule: clients MUST ignore members they do not recognize. Because no member defined here is security-critical, silently ignoring an unknown member is safe. The formal schemas (CDDL and JTD) are correspondingly open and permit additional members.

  • Interoperability does not depend on the version member, which is a provenance label rather than a negotiation mechanism. What a consumer does on meeting a label it does not know is fully specified and testable: nothing -- processing is driven by the members present, never by the label. [RFC6709], Section 4.1, asks that a protocol carrying a version field state exactly that expectation, and gives the MIME-Version field as the counter-example of one whose handling was left unstated; here the expectation is stated, which is what allows the label to be the constant its definition makes it.

  • Extension members. A member not defined here may be introduced by any implementer at any time; the ignore-unknown rule above is what makes doing so always safe. Four rules govern them:

    • Naming. Member names that do not contain a "." (FULL STOP, U+002E) are reserved for this document and any document that revises or replaces it, which makes collisions structurally impossible rather than merely unlikely. An extension member SHOULD therefore be named with reverse-domain-name notation rooted in a domain the definer controls -- com.example.pue for a power-usage-effectiveness figure defined by example.com -- consistent with [RFC6648]. Semantics-free markers such as an "X-" or "vendor-" prefix SHOULD NOT be used. Extension names are case-sensitive, SHOULD be lowercase, and their values are subject to the same I-JSON expectations as the rest of the document.

    • No registry. No IANA registry of member names is defined: the ignore-unknown rule makes central coordination unnecessary for interoperability, and the reserved undotted name space protects this document's own members.

    • A name is an identifier, not a locator. Nothing is ever fetched from the domain an extension name is rooted in, so that domain later expiring or changing hands changes nothing about documents already published under the name. A definer SHOULD nonetheless keep the definition available, and a consumer that implements an extension keeps its own copy of the definition it implemented.

    • A private convention, and reusable. This document defines no mechanism by which a consumer discovers or negotiates the meaning of a member it does not know, because the ignore-unknown rule makes such resolution unnecessary: a consumer without the definition ignores the member and loses nothing this specification defines, including where different publishers' extensions diverge. A publisher MAY use an extension member defined by another party, provided it implements that party's published definition; an implementer with a member of general interest is encouraged to publish its definition, which a future specification could adopt under an undotted name.

  • Taken together, these rules make this specification complete as published. A publisher needing to convey something this document does not define adds an extension member; a consumer that does not recognize it ignores it. Neither step requires a new label, an IANA registry of members, or a revision of this document. A different data model, were one ever specified, would be a different specification declaring its own label, and nothing here anticipates or depends on one.

2.5.5. Formal Definition (CDDL)

The following CDDL [RFC8610] definition describes the response:

; Root: a single object, or an array of objects for trends
sustainability-response =
  sustainability-metrics / [+ sustainability-metrics]

sustainability-metrics = {
  ; Versioning and provenance
  version: tstr,
  updated: tstr,
  capabilities: "basic" / "extended",
  provider: tstr,

  ; Mandatory methodology disclosure
  measurement-method: tstr,
  methodology-uri: tstr,

  ; Timeframe of the report (YYYY, YYYY-MM, or RFC3339 full-date)
  reporting-period: tstr,

  ; Reporting subject (origin host, path prefix, entity, ...)
  target: tstr,

  ; Energy metrics; when energy-unit is absent, kWh applies
  ? energy-consumption: number,   ; non-negative
  ? energy-unit: "Wh" / "kWh" / "MWh" / "GWh",

  ; Carbon metrics; when carbon-unit is absent, gCO2e applies
  ? carbon-footprint: number,     ; gross, non-negative
  ? carbon-unit: "gCO2e" / "kgCO2e" / "mtCO2e",

  ; Other optional metric and linkage members
  ? carbon-accounting: "location-based" / "market-based",
  ? scope-1: number,              ; may be negative (removals)
  ? scope-2: number,              ; may be negative (removals)
  ? scope-3: number,              ; may be negative (removals)
  ? sci-score: number,            ; non-negative
  ? functional-unit: tstr,
  ? carbon-intensity-gCO2e-per-kWh: number,   ; non-negative
  ? estimated-annual-emissions-kgCO2e: number, ; non-negative
  ? renewable-energy: number,     ; percentage, 0-100
  ? verifiable-attestation-uri: tstr,
  ? disclosure-uri: tstr,

  ; Classification hint for the reporting subject in target
  ? target-type: "origin" / "path" / "organization" / "service"
               / "product" / "device" / "tenant" / "data-source",

  ; Extension members (reverse-domain names); clients
  ; ignore unknown members
  * tstr => any
}

2.5.6. Formal Definition (JTD)

The following JSON Type Definition [RFC8927] defines the reporting object:

{
  "properties": {
    "version": { "type": "string" },
    "updated": { "type": "string" },
    "capabilities": { "enum": ["basic", "extended"] },
    "provider": { "type": "string" },
    "measurement-method": { "type": "string" },
    "methodology-uri": { "type": "string" },
    "reporting-period": { "type": "string" },
    "target": { "type": "string" }
  },
  "optionalProperties": {
    "energy-consumption": { "type": "float64" },
    "energy-unit": { "enum": ["Wh", "kWh", "MWh", "GWh"] },
    "carbon-footprint": { "type": "float64" },
    "carbon-unit": { "enum": ["gCO2e", "kgCO2e", "mtCO2e"] },
    "carbon-accounting": {
      "enum": ["location-based", "market-based"]
    },
    "scope-1": { "type": "float64" },
    "scope-2": { "type": "float64" },
    "scope-3": { "type": "float64" },
    "sci-score": { "type": "float64" },
    "functional-unit": { "type": "string" },
    "carbon-intensity-gCO2e-per-kWh": { "type": "float64" },
    "estimated-annual-emissions-kgCO2e": { "type": "float64" },
    "renewable-energy": { "type": "float64" },
    "verifiable-attestation-uri": { "type": "string" },
    "disclosure-uri": { "type": "string" },
    "target-type": {
      "enum": ["origin", "path", "organization", "service",
               "product", "device", "tenant", "data-source"]
    }
  },
  "additionalProperties": true
}

Range constraints (the non-negativity rules and the 0-100 bound on renewable-energy), the sci-score/functional-unit co-occurrence rule, the date formats of updated and reporting-period, the unit defaults, the URI-member constraints (absolute https URIs), and the array-level ordering and uniformity rules are prose rules of this document; they are not captured by the schemas above, and validating implementations enforce them at the application layer.

3. Example Usage

3.1. Basic Response (Root Request)

Request: GET /.well-known/sustainability-data

This is the common case: a publisher reporting on its own annual cycle, serving a single document with no query parameters, as the Mandatory Minimum Supported Service requires.

{
  "version": "2.0",
  "updated": "2026-03-01T12:00:00Z",
  "capabilities": "basic",
  "provider": "Example Corp (sustain@example.org)",
  "measurement-method": "cloud-billing",
  "methodology-uri": "https://example.com/methodology",
  "reporting-period": "2025",
  "target": "example.com",
  "energy-consumption": 15000,
  "energy-unit": "kWh",
  "carbon-footprint": 4140,
  "carbon-unit": "kgCO2e",
  "target-type": "origin"
}

3.2. Yearly Trend (Monthly Granularity)

Request: GET /.well-known/sustainability-data?period=2025&granularity=monthly

The response is an array with one object per month; only the first two months are shown here for brevity.

[
  {
    "version": "2.0",
    "updated": "2026-01-05T09:00:00Z",
    "capabilities": "extended",
    "provider": "CloudProvider Ops (ops@example.com)",
    "measurement-method": "hardware-metered",
    "methodology-uri": "https://example.com/methodology",
    "reporting-period": "2025-01",
    "target": "example.com",
    "energy-consumption": 1100,
    "energy-unit": "kWh",
    "carbon-footprint": 302,
    "carbon-unit": "kgCO2e",
    "carbon-accounting": "location-based",
    "renewable-energy": 45
  },
  {
    "version": "2.0",
    "updated": "2026-01-05T09:00:00Z",
    "capabilities": "extended",
    "provider": "CloudProvider Ops (ops@example.com)",
    "measurement-method": "hardware-metered",
    "methodology-uri": "https://example.com/methodology",
    "reporting-period": "2025-02",
    "target": "example.com",
    "energy-consumption": 1050,
    "energy-unit": "kWh",
    "carbon-footprint": 288,
    "carbon-unit": "kgCO2e",
    "carbon-accounting": "location-based",
    "renewable-energy": 48
  }
]

3.3. Target-Specific Request (Day Period)

Request: GET /.well-known/sustainability-data?target=/api/v1&period=2026-03-15

{
  "version": "2.0",
  "updated": "2026-03-16T12:00:00Z",
  "capabilities": "extended",
  "provider": "Example Corp (sustain@example.org)",
  "measurement-method": "cloud-billing",
  "methodology-uri": "https://example.com/methodology",
  "reporting-period": "2026-03-15",
  "target": "/api/v1",
  "energy-consumption": 1.5,
  "energy-unit": "kWh",
  "carbon-footprint": 414,
  "carbon-unit": "gCO2e"
}

3.4. Target-Specific Yearly Trend (Monthly Granularity)

Request: GET /.well-known/sustainability-data?target=/api/v1&period=2026&granularity=monthly

As above, the array holds one object per completed month.

[
  {
    "version": "2.0",
    "updated": "2026-03-21T07:00:00Z",
    "capabilities": "extended",
    "provider": "Example Corp (sustain@example.org)",
    "measurement-method": "third-party-modeled",
    "methodology-uri": "https://example.com/api-modeling",
    "reporting-period": "2026-01",
    "target": "/api/v1",
    "energy-consumption": 45,
    "energy-unit": "kWh",
    "carbon-footprint": 12450,
    "carbon-unit": "gCO2e",
    "sci-score": 12,
    "functional-unit": "per-thousand-requests"
  },
  {
    "version": "2.0",
    "updated": "2026-03-21T07:00:00Z",
    "capabilities": "extended",
    "provider": "Example Corp (sustain@example.org)",
    "measurement-method": "third-party-modeled",
    "methodology-uri": "https://example.com/api-modeling",
    "reporting-period": "2026-02",
    "target": "/api/v1",
    "energy-consumption": 42,
    "energy-unit": "kWh",
    "carbon-footprint": 11800,
    "carbon-unit": "gCO2e",
    "sci-score": 10,
    "functional-unit": "per-thousand-requests"
  }
]

3.5. Highly Detailed Combined Extended Request

Request: GET /.well-known/sustainability-data?target=/app/storage&period=2026-03-20

This example utilizes all optional members, including GHG Protocol Scopes, a verifiable attestation link to combat greenwashing, the target-type classification hint, and a reverse-domain-named extension member (com.example.pue, a power-usage-effectiveness figure defined by example.com) that clients not recognizing it simply ignore (see Versioning and Extensibility).

{
  "version": "2.0",
  "updated": "2026-03-21T00:05:00Z",
  "capabilities": "extended",
  "provider": "Global Storage Inc. (compliance@storage.example)",
  "measurement-method": "hardware-estimated",
  "methodology-uri": "https://storage.example/transparency/methods",
  "reporting-period": "2026-03-20",
  "target": "/app/storage",
  "energy-consumption": 12,
  "energy-unit": "kWh",
  "carbon-footprint": 3.2,
  "carbon-unit": "kgCO2e",
  "carbon-accounting": "market-based",
  "scope-1": 0.0,
  "scope-2": 2.1,
  "scope-3": 1.1,
  "sci-score": 0.85,
  "functional-unit": "per-terabyte-day",
  "carbon-intensity-gCO2e-per-kWh": 267,
  "estimated-annual-emissions-kgCO2e": 1168,
  "renewable-energy": 45,
  "verifiable-attestation-uri": "https://verify.example/vc/storage",
  "disclosure-uri": "https://storage.example/disclosures",
  "target-type": "path",
  "com.example.pue": 1.21
}

3.6. Partial Reporting (Omitted Metrics and Default Units)

Request: GET /.well-known/sustainability-data

In this example the provider reports a carbon figure (for example, from a supplier or a CSRD report) but does not report energy for the period: energy-consumption and energy-unit are simply omitted (see Value Constraints and Omitted Metrics). carbon-unit is also omitted, so the default gCO2e applies to both carbon-footprint and scope-2. The document declares basic capabilities -- no Extended query parameters are supported -- while still carrying optional members, and the disclosure-uri points to where fuller data can be found.

{
  "version": "2.0",
  "updated": "2026-04-01T00:00:00Z",
  "capabilities": "basic",
  "provider": "Partial Metrics Co. (sustainability@partial.example)",
  "measurement-method": "third-party-modeled",
  "methodology-uri": "https://partial.example/methodology",
  "reporting-period": "2026-03",
  "target": "partial.example",
  "carbon-footprint": 4200,
  "carbon-accounting": "location-based",
  "scope-2": 4200,
  "disclosure-uri": "https://partial.example/disclosures"
}

4. Operational Considerations

Because this endpoint can be dynamic, servers SHOULD implement heavy caching for the well-known responses (see also the rate-limiting guidance in the Security Considerations). HTTP caching and conditional requests are as defined in [RFC9111] and [RFC9110].

5. Interoperability

Interoperability between independently built publishers and consumers rests on three things already specified above: the fixed location, media type, and response rules of Mandatory Minimum Supported Service; the data model and its formal schemas in the Payload Format section; and the ignore-unknown rule of Versioning and Extensibility, which is what lets a consumer read a document carrying members it has never seen.

Two practices outside anything this document can require have proved useful in building implementations of it: publishing example payloads and test vectors alongside an implementation, so that publishers and consumers can be tested against the same material; and, for an aggregator that republishes these figures in a model of its own, documenting how it maps them.

6. Deployment

7. Document Integrity and Signing

HTTPS, which Mandatory Minimum Supported Service requires, authenticates the origin and protects the document while it is in flight. It says nothing about the document once it has been stored, forwarded, aggregated into a third-party dataset, or presented months later as evidence of what an origin published. For those uses this section defines an OPTIONAL detached signature that can be verified offline, after the fact, and by a party that did not perform the original fetch.

The mechanism is optional to deploy and adds no member to the data model: a signature is a separate resource, so a signed document is byte-for-byte the same document as an unsigned one, and a client that ignores signatures is unaffected.

7.1. The Signature Resource

A publisher that signs its document MUST publish the signature at the path /.well-known/sustainability-data.jws on the same origin as the document, retrievable under the same conditions as the document itself (HTTPS, GET and HEAD, no authentication). Where the document is reached through a redirect, that origin is the origin of the final response -- the one Mandatory Minimum Supported Service already attributes the document to -- and a client MUST NOT follow a redirect of the signature resource to any other origin. The resource is registered as a companion of the primary suffix in the IANA Considerations section, and carries a signature over the primary resource and nothing else.

The signature MUST be a JSON Web Signature (JWS) [RFC7515] using the JWS Compact Serialization with the detached-payload form of [RFC7515], Appendix F: the payload part between the two period characters is empty, and the payload for verification is supplied by the verifier from the retrieved document. Responses SHOULD use the application/jose media type ([RFC7515], Section 9.2.1). A 404 Not Found at this path means only that the publisher does not sign; it carries no other meaning.

7.2. What the Signature Covers

The JWS signing input is the exact octet sequence of the representation served at /.well-known/sustainability-data for a request with no query parameters, taken after any content coding ([RFC9110], Section 8.4) has been removed. There is no canonicalization step: the signature is over the bytes as served, not over a normalized form of the JSON value. This is a deliberate choice, and it has three consequences for publishers:

  • Any change to the served bytes -- including reserialization with different whitespace, member ordering, or number formatting that leaves the JSON value unchanged -- invalidates the signature. A publisher MUST regenerate and republish the signature whenever the document is regenerated, in the same deployment step, and MUST NOT let a generator reformat the document between signing and serving.

  • A publisher whose server negotiates representations of the document (for example, on Accept-Language, as Internationalization Considerations permits) cannot sign them all with one signature; such a publisher SHOULD either serve a single representation or not publish a signature.

  • The signature covers only the parameterless Basic response. Responses to the Optional Extended Query Parameters are computed per request and are outside the scope of this mechanism.

In exchange, the mechanism requires no JSON canonicalization scheme, no dynamic server behavior, and no change to the data model: signing and verification work on any static host, and the two resources can be generated by an offline tool and uploaded together.

7.3. Header Parameters and Algorithms

The JOSE header of the signature:

  • MUST contain an alg parameter identifying an asymmetric digital-signature algorithm. EdDSA using the Ed25519 curve [RFC8037] and ES256 ([RFC7518], Section 3.4) are RECOMMENDED, and a verifying client SHOULD implement both.

  • MUST NOT use the value none ([RFC7518], Section 3.6), and MUST NOT use a MAC-based algorithm such as HS256: verification here is performed by parties that hold no secret shared with the publisher, so a symmetric algorithm would prove nothing to them. A client MUST reject a signature whose alg is none or a MAC algorithm.

  • SHOULD carry the signing key, either as a jwk parameter ([RFC7515], Section 4.1.3) or as an x5c certificate chain ([RFC7515], Section 4.1.6), so that verification requires only the two retrieved resources. A publisher that distributes its key out of band MAY omit both and identify the key with kid.

A verifying client MUST determine the acceptable algorithm from the key and from its own policy, and MUST NOT let the alg parameter of the received header select the verification algorithm on its own; it MUST reject a signature carrying a crit header parameter it does not understand ([RFC7515], Section 4.1.11). The JSON Web Token best current practices [RFC8725] give this guidance in "Perform Algorithm Verification" and "Use Appropriate Algorithms" (Sections 3.1 and 3.2); although framed around JWTs, that document addresses the cryptographic mechanisms of [RFC7515] and [RFC7518] underlying them, and applies to the bare JWS used here.

7.4. What a Signature Proves, and What It Does Not

A signature whose verification key arrives in the signature's own header is self-asserted, exactly as the metrics are: whoever can publish the document can publish a key alongside it. Such a signature therefore establishes:

  • Integrity -- the document has not been altered since it was signed, whatever path it travelled after leaving the origin; and

  • Key continuity -- successive documents carrying the same key were signed by the same holder of that key, so a consumer that pinned the key on an earlier retrieval can detect a change of signer.

It does not establish identity or authenticity. Binding a signature to a real-world party requires a key the client has obtained out of band, or an x5c chain that validates to a trust anchor the client already trusts -- and even then the binding is to the certified name, not to the correctness of the figures. Independent assurance about the figures themselves comes only from a third party, through the verifiable-attestation-uri member; see also Greenwashing and Misrepresentation. A valid signature over false data yields correctly signed false data, and clients MUST NOT treat signature validity as evidence that any published metric is accurate.

7.5. Client Behavior

  • A client for which document integrity matters SHOULD attempt to retrieve the signature resource, and SHOULD retrieve it and the document close enough in time, or with consistent cache validators, that it does not verify one version's signature against another version's bytes.

  • An absent signature MUST NOT be treated as evidence that the document is false, altered, or of lower quality: signing is OPTIONAL, and most conformant deployments are expected not to sign.

  • A signature that fails to verify -- for any reason, including an algorithm or key the client rejects -- MUST cause the client to treat the document as unverified. It MUST NOT be treated as proof that the document is false; the far more common causes are a republished document whose signature was not regenerated and a verifier that received a transformed body. A client that distinguishes verified from unverified data SHOULD record such a document as unverified rather than discard it, and MUST NOT present it to a user or a downstream consumer as verified.

7.6. Alternatives Considered

An embedded signature member was considered and rejected: verifying it requires a canonicalization of the JSON value such as JCS [RFC8785], which adds a dependency and a class of implementation divergence that a byte-level signature does not have, and it would change the data model. An OpenPGP cleartext signature, as used by security.txt ([RFC9116], Section 2.3), is the closest precedent for signing a self-published claims document from the beginning, but its tooling is a poor fit for the JSON and web-PKI ecosystem in which this document is consumed. Either could be added later as an extension without invalidating anything specified here.

8. Security Considerations

The document this specification defines is public data, self-asserted by its publisher, retrieved by unauthenticated clients, and intended for automated ingestion. The table below summarizes the threats that follow from those properties and the mitigation each has in this document; the subsections that follow give the detail.

Table 1: Threats and their mitigations
Threat Mitigations specified in this document
Spoofing -- a third party serves a forged document as if it came from the origin, or an aggregator misattributes a document to an origin that never published it HTTPS is mandatory for publication and retrieval, and clients MUST NOT accept the document over unauthenticated HTTP (Mandatory Minimum Supported Service); a followed redirect attributes the document to the final origin; an OPTIONAL detached signature (Document Integrity and Signing) lets attribution survive storage and relaying
Tampering -- the bytes are altered in transit, in an intermediary, or in storage; or the document is coerced into being interpreted as a different, more dangerous content type Mandatory HTTPS; a dedicated, registered media type that responses MUST use, plus X-Content-Type-Options: nosniff (Mandatory Minimum Supported Service); the detached signature for integrity outside the TLS session
Repudiation and greenwashing -- the publisher reports figures that are wrong, flattering, or selectively scoped, and no party can hold the claim to account The conformance rule that a document reporting no metrics counts as conformant only when its methodology-uri resource is openly retrievable and states the method and figures (Value Constraints and Omitted Metrics); the third-party attestation channel of verifiable-attestation-uri; the rule that clients MUST NOT treat a document, or a valid signature over it, as proof of any claim (Trust and Spoofing; Greenwashing and Misrepresentation)
Information disclosure -- published metrics leak infrastructure, traffic patterns, deployment topology, the existence of internal paths, or personal data in contact strings The 24-hour granularity floor, optional generation-time noise, and aggregation guidance (Privacy Considerations); honoring the target parameter only for a published set of prefixes, which closes the path-existence oracle (Path Disclosure); role rather than personal contact addresses
Denial of service -- against the server, by forcing on-demand aggregation or unbounded distinct cache keys; against the client, by serving an unbounded or hostile document Rate limiting, precomputation, and a bounded cache-key space (Denial of Service); a mandatory documented cap on array size (Array Size Limits); client-side size, time, redirect, and parser hardening (Consumer Considerations)

Two limits apply throughout and are stated once here. First, nothing in this document makes a published figure true: every mechanism below concerns the integrity and provenance of a claim, never its accuracy. Second, the mechanisms are only as good as the deployment; a publisher that serves the document correctly but computes it carelessly is not addressed by any of them.

8.1. Transport Security and Media Typing

Mandatory Minimum Supported Service requires that the document be published and retrieved over HTTPS and that clients refuse it over unauthenticated HTTP. That requirement, and not any property of the data model, is what lets a consumer attribute a retrieved document to the origin that served it.

  • Clients MUST validate TLS certificates as required for HTTPS [RFC9110], and apply that requirement to every hop of a followed redirect and to the signature resource.

  • The requirement is unconditional. The data is public, so confidentiality is not the reason for it: HTTPS is required here for integrity and origin authentication, which a public document needs exactly as much as a confidential one. No exception is made for constrained or legacy origins, since this specification has no deployed base whose interoperability such an exception would preserve. The same reasoning, and the same conclusion, are found in security.txt ([RFC9116], Section 5.7), which likewise requires HTTPS for a public, self-published, well-known document.

  • Serving the document under its own registered media type, and with X-Content-Type-Options: nosniff, keeps a retriever from being induced to process it as some other, more dangerous type; that is why the media type is required rather than recommended.

8.2. Trust and Spoofing

Publishing sustainability metadata at a well-known location is convenient but does not provide any cryptographic assurance of correctness. An attacker who controls DNS, TLS certificates, or the origin can publish false metadata, and a party that obtained the document by some means other than fetching it over HTTPS from the origin has no assurance of where it came from.

  • What a successful retrieval establishes is attribution -- the origin published these claims -- and nothing more. A consumer MUST NOT treat the presence of a sustainability document, or of any member within it, as verification of a claim it carries, and a consumer that presents, stores, or forwards the data MUST NOT represent it as verified or proven. These are processing requirements on conforming consumers -- they constrain how an implementation labels and propagates what it ingested -- not statements about what any party may conclude from the data by other means.

  • For high-assurance use cases, clients SHOULD rely on additional attestations, signed statements, or third-party verification. This document provides two such channels: the detached signature of Document Integrity and Signing, which carries integrity beyond the TLS session, and the verifiable-attestation-uri member, which is the only one of the two that can speak to authenticity. The limits of each are stated where it is defined, and neither speaks to the accuracy of a metric.

8.3. Greenwashing and Misrepresentation

There is a risk that providers publish misleading or incomplete metrics to appear more sustainable. This is the threat least amenable to protocol mechanism: a document that is correctly served, correctly typed, and validly signed can still be untrue, and the mechanisms here bound only how a claim can be attributed and how a change to it can be detected.

  • Beyond the mandatory methodology-uri, providers SHOULD link authoritative reports, signed statements, or third-party verification through the verifiable-attestation-uri member -- a cryptographically signed verifiable credential [VC-DATA-MODEL-2] being one such form.

  • Consumers SHOULD treat the document as a discovery mechanism and validate claims against external sources when necessary.

8.4. Privacy and Information Leakage

Publishing detailed operational metrics may reveal sensitive information about infrastructure, traffic patterns, or deployment topology. The privacy-related risks of this mechanism -- and the corresponding publisher guidance on aggregation, granularity, fingerprinting noise, and path disclosure -- are consolidated in the Privacy Considerations section.

8.5. Denial of Service (DoS)

Because this endpoint may require internal database queries to aggregate data -- especially when dynamic period or other query parameters are utilized -- it could become a vector for Denial of Service (DoS) attacks.

  • Servers SHOULD rate-limit requests to the well-known URI and cache all generated reports.

  • Because each distinct query-string combination is a distinct cache entry, an attacker iterating unique parameter values can bypass a response cache; honoring the target query parameter only for a published set of path prefixes (see Optional Extended Query Parameters) bounds the key space, and servers SHOULD precompute reports rather than aggregate on demand.

8.6. Array Size Limits

To prevent DoS via memory exhaustion, servers supporting granularity MUST enforce a documented maximum on the number of objects returned.

  • A cap of 366 objects is RECOMMENDED.

  • When a response would exceed the limit, the server SHOULD return the most recent periods and MAY signal the truncation with an extension member it defines (for example, a boolean com.example.truncated; this document defines no in-band truncation marker, and a client can in any case detect possible truncation by comparing the number of entries received against the server's documented cap), or MAY respond with 400 Bad Request (treating the over-broad query as a client error).

8.7. Consumer Considerations

A Sustainability Metadata Document is untrusted input fetched from an arbitrary origin, and this document deliberately positions it as safe for automated ingestion; consumers are responsible for making that true on their side:

  • Clients SHOULD enforce a response-size limit and bound the number of array entries they accept (the 366-object cap is a server obligation that a client cannot rely on a hostile server to honor).

  • Clients SHOULD bound the time and redirects spent on a single fetch, and apply the same bounds to the signature resource.

  • Clients SHOULD parse the body with a JSON parser hardened against untrusted input, validate against the formal schemas before use, and treat member values as data, never as code or markup. The format carries no active content: it has no scripting, macro, or external-entity mechanism, and a consumer that evaluates a member value has introduced a hazard the format does not contain.

  • Duplicate member names make JSON interoperability unpredictable ([RFC8259]); clients SHOULD reject a document with duplicate names or apply their parser's documented last-value behavior consistently.

  • The URI-valued members carry the dereferencing restrictions and SSRF guidance given in Optional Response Fields.

9. Privacy Considerations

Publishing sustainability metadata can have privacy implications when metrics are correlated with traffic or user behavior. Providers SHOULD evaluate the privacy impact of any metric that could be linked to individual users or small groups, SHOULD avoid publishing data that could be used to infer internal architecture or expose personally identifiable information, and, when in doubt, SHOULD aggregate or redact fine-grained data. Aggregators SHOULD use privacy-preserving aggregation techniques when publishing derived datasets. Human-readable contact strings (such as the provider member) can carry personal data; role addresses (for example, sustainability@example.com) are RECOMMENDED over personal ones. (See also Privacy and Information Leakage in the Security Considerations.)

9.1. Traffic Analysis

Servers SHOULD NOT report metrics at a granularity finer than 24 hours, and real-time telemetry is NOT RECOMMENDED: either would allow an observer to correlate energy spikes with specific real-time user actions.

9.2. Hardware Fingerprinting

Precise metrics can reveal hardware architectures. Servers MAY apply "noise" (fuzzing), as a multiplicative factor bounded within 1% of the true values, to mitigate identification with limited impact on aggregate accuracy. Noise MUST be applied once, at document-generation time, deterministically per reporting period, and consistently across arithmetically related fields, so that ratios between them (such as a published carbon intensity) are preserved; the noised values are the published values for caching and conditional-request purposes. Members bounded to a range (such as renewable-energy) MUST remain within their stated range after noise. Because ratios are preserved, publishers for whom ratio-based fingerprinting is a concern SHOULD omit the derived members rather than rely on noise. Providers applying noise SHOULD disclose this in the methodology-uri document so that auditors can reconcile published figures with filed reports.

9.3. Path Disclosure

When the target query parameter is honored for arbitrary values, the difference between a scoped response and a no-data response can reveal which resource paths exist and carry traffic on the origin. For this reason, Optional Extended Query Parameters directs servers to honor the parameter only for a deliberately published set of path prefixes -- published in the methodology-uri document, as that section specifies -- and to respond identically (per the no-data rule) for all other values.

10. IANA Considerations

This document makes three registration requests: two entries in the "Well-Known URIs" registry and one media type.

10.1. Well-Known URI Registrations

IANA is requested to register two entries in the "Well-Known URIs" registry, following the procedure outlined in [RFC8615]. The second is a companion of the first and has no meaning without it.

Following the registration template of [RFC8615], Section 3.1:

  • URI Suffix: sustainability-data

  • Change Controller: Andrei Nicolae Besleaga (andrei.besleaga@ieee.org)

  • Specification Document(s): This document.

  • Status: provisional

  • Related Information: This suffix is used with the "https" URI scheme. The response uses the application/sustainability-data+json media type registered by this document and follows I-JSON [RFC7493]. Formal definitions of the response are provided in this document using CDDL [RFC8610] and JSON Type Definition (JTD) [RFC8927]. An OPTIONAL detached signature over the resource is published under the companion suffix "sustainability-data.jws".

and, for the companion signature resource:

  • URI Suffix: sustainability-data.jws

  • Change Controller: Andrei Nicolae Besleaga (andrei.besleaga@ieee.org)

  • Specification Document(s): This document, Document Integrity and Signing.

  • Status: provisional

  • Related Information: This suffix is used with the "https" URI scheme. The resource is a detached JSON Web Signature [RFC7515], in JWS Compact Serialization and using the application/jose media type, over the representation served at "/.well-known/sustainability-data" on the same origin. It carries no other content and has no meaning independently of that resource.

A status of "provisional" is requested for both entries, in keeping with [RFC8615], Section 3.1: this is an Independent Submission rather than a Standards-Track or other open-standards-process document. Per that procedure, the designated expert(s) may promote the entries to "permanent" once they are found to be in broad use. A permanent registration from this stream, held by an individual change controller, would not be unprecedented -- [RFC8522] registered the "looking-glass" suffix on exactly that footing -- but this document does not ask for one until the convention has demonstrated use.

[RFC8615], Section 3, provides that "Registrations MAY also contain additional information, such as the syntax of additional path components, query strings, and/or fragment identifiers to be appended to the well-known URI"; this document uses that allowance for the target, period, and granularity query parameters. The signature resource is not such an appended component: ".jws" forms a distinct suffix rather than a path component beneath the registered name, so this document registers it explicitly rather than treating it as covered by the primary entry. The two entries are one registration package, under one change controller and one specification. Registering a dot-suffixed companion of a registered name in this way has precedent in the registry, where "host-meta" and "host-meta.json" were registered together by [RFC6415]. A sub-path such as "/.well-known/sustainability-data/signature.jws" was considered and rejected: on ordinary static hosting a file and a directory of the same name cannot coexist, which would deny the mechanism to exactly the deployments a byte-level detached signature is designed to serve.

The suffix "sustainability-data" names the specific application registered here -- a machine-readable data document of sustainability metrics for a declared reporting subject -- rather than claiming the generic term "sustainability" for one convention, in keeping with the precision expectations of [RFC8615], Section 3 (earlier revisions of this document requested the bare suffix "sustainability"). The metadata the URI names is published per origin, which is the pattern for which well-known URIs are appropriate [RFC8615]; resource-specific scoping is provided through the target query parameter rather than through additional path segments. The use of query parameters on a well-known URI follows existing practice such as WebFinger [RFC7033] and is permitted by [RFC8615], Section 3. Registration is sought to enable interoperable discovery, not to signal endorsement of the publisher's claims.

10.2. Media Type Registration

IANA is requested to register the application/sustainability-data+json media type in the "Media Types" registry, in the standards tree, following the procedure of [RFC6838].

The subtype uses the "+json" structured syntax suffix, as [RFC6838], Section 4.2.8, directs for a media type whose representation employs a registered structured syntax; "+json" is registered in [RFC6839], Section 3.1. The dedicated media type replaces the generic application/json that earlier revisions of this document required, so that a retriever knows from the response alone what kind of document it has received, rather than inferring it from the path it happened to request. Clients continue to accept application/json as specified in Mandatory Minimum Supported Service, since documents published before this registration exist in the field.

[RFC6838], Section 3.1, requires registrations in the standards tree to be approved by the IESG in the case of registrations associated with IETF specifications, or to be registered by a recognized standards-related organization. This document is an Independent Submission and is not the product of an IETF Working Group; the standards-tree registration is therefore requested subject to IESG approval under that provision. Independent Submissions have obtained standards-tree media types on this basis before: [RFC7351] (application/xml-patch+xml, Informational), [RFC7903] (image/emf and image/wmf, Informational), [RFC8351] (application/pkcs8-encrypted, Informational), and [RFC9230] (application/oblivious-dns-message, Experimental). Consistent with that path, change control over the registration is assigned to the IETF rather than to the author.

[RFC6838], Section 4.6, requires that an analysis of security issues be carried out for all types registered in the standards tree; the "Security considerations" field below carries that analysis, and the Security Considerations and Privacy Considerations sections of this document carry it in full.

Following the registration template of [RFC6838], Section 5.6:

  • Type name: application

  • Subtype name: sustainability-data+json

  • Required parameters: N/A

  • Optional parameters: N/A

  • Encoding considerations: binary. Documents are JSON text and are encoded in UTF-8 ([RFC8259], Section 8.1); publishers follow I-JSON [RFC7493].

  • Security considerations: Documents of this media type are JSON text and inherit the security considerations of JSON ([RFC8259], Section 12), notably the hazards of parsing untrusted input and the implementation-dependent handling of duplicate member names and of numbers outside the range exactly representable in IEEE 754 double precision. The format carries no active content: it defines no scripting, macro, or external-entity mechanism, and a consumer that evaluates a member value rather than treating it as data introduces a hazard the format does not contain. The format defines three URI-valued members that a consumer may choose to dereference; automatic dereferencing exposes the consumer to server-side request forgery and to redirect-based attacks, and the specification restricts those members to absolute "https" URIs and directs consumers to apply the usual protections. The content is self-asserted by its publisher and carries no inherent assurance of accuracy: an instance states what an origin claims about environmental impact, not what is true, so misrepresentation ("greenwashing") is the principal content-level risk, mitigated in the specification only by a mandatory link to a public methodology and by a channel to third-party attestations; consumers, including automated ones, must not treat an instance as verified. Instances may carry operational information -- energy consumption, carbon intensity, and their variation over time -- from which infrastructure characteristics, deployment topology, or traffic patterns can be inferred, and their human-readable contact strings can carry personal data; the specification directs publishers to aggregate, to bound reporting granularity, and to prefer role over personal contact addresses. Instances describe a stated reporting period and carry a last-updated timestamp; a stale instance can misrepresent a current state, and consumers evaluate those members rather than assume currency. Instances are normally retrieved over HTTPS, which authenticates the origin and protects the document in transit, and an OPTIONAL detached JWS [RFC7515] is defined for integrity outside the TLS session; neither establishes the accuracy of the data. The full analysis is in the Security Considerations and Privacy Considerations sections of this document.

  • Interoperability considerations: The structure of an instance is specified by this document, including formal CDDL [RFC8610] and JTD [RFC8927] schemas. Consumers ignore members they do not recognize, so extension members do not affect interoperability. Publishers follow I-JSON [RFC7493]; consumers should be aware that generic JSON parsers differ in their treatment of duplicate member names and of large or high-precision numbers.

  • Published specification: This document.

  • Applications that use this media type: Publishers of environmental-impact, energy, and carbon-footprint disclosures; web clients, sustainability aggregators, procurement and regulatory reporting tools, and automated agents that retrieve such disclosures, in particular from the "/.well-known/sustainability-data" URI defined by this document.

  • Fragment identifier considerations: The syntax and semantics of fragment identifiers are as specified for "application/json" ([RFC6839], Section 3.1). At the time of writing, no fragment identification syntax is defined for "application/json".

  • Additional information:

    • Deprecated alias names for this type: N/A

    • Magic number(s): N/A

    • File extension(s): .json

    • Macintosh file type code(s): TEXT

  • Person & email address to contact for further information: Andrei Nicolae Besleaga (andrei.besleaga@ieee.org)

  • Intended usage: COMMON

  • Restrictions on usage: None. Responses to the well-known URI defined by this document are required to use this media type.

  • Author: Andrei Nicolae Besleaga (andrei.besleaga@ieee.org)

  • Change controller: IETF

  • Provisional registration?: No

11. Internationalization Considerations

This section classifies every member of a Sustainability Metadata Document according to the distinction BCP 18 [RFC2277], Section 2, draws between protocol elements, which are not localized, and text intended for human consumption, which is.

A Sustainability Metadata Document is JSON [RFC8259] and is therefore encoded in UTF-8 for interchange ([RFC8259], Section 8.1), so any member value can carry the full range of Unicode characters. Publishers SHOULD emit human-readable strings in Unicode Normalization Form C ([RFC5198], Section 3).

Nearly every member of this data model is a protocol element rather than text. Member names, the version label (whose value space is under change control, as Versioning and Extensibility specifies), and the values of the enumerated members (capabilities, energy-unit, carbon-unit, carbon-accounting, and target-type) are ASCII tokens defined by this document; they are compared octet-for-octet, and no case folding, Unicode normalization, or other transformation is applied to them by clients. The updated and reporting-period members carry the date forms specified for them, and the three URI-valued members carry URIs [RFC3986]. The RECOMMENDED values of measurement-method are likewise machine-matchable tokens, compared octet-for-octet. The functional-unit member is also a token rather than display text: it is the denominator in which sci-score is expressed, its precise meaning is defined in the methodology-uri document rather than in the string itself, and localizing it would make the accompanying sci-score incomparable. The numeric members carry JSON numbers, which have no language or script dimension; their units are carried by the enumerated unit members above. None of these are translated, and a publisher MUST NOT localize them.

The target member is an opaque identifier, as its definition states: it is compared octet-for-octet and MUST NOT be translated or transliterated, since doing so would change which subject it names. Two qualifications follow from what target can name. Where it is a host, the ordinary case-insensitive comparison rules for host names apply, and an internationalized host is given in its A-label form ([RFC5890], Section 2.3.2.1) so that an octet comparison is well defined. Where it is a path prefix, it carries the percent-decoded form, as Optional Extended Query Parameters specifies for a response scoped by the target query parameter.

That leaves a small set of members whose values are text for human consumption: provider, a measurement-method value outside the RECOMMENDED set, and any human-readable extension member. Language is conveyed for these at the HTTP layer rather than in the data model, following the approach that problem details ([RFC9457], Sections 1.7 and 3.1.3) takes for its human-readable strings: a server publishing such text in a known language SHOULD send a Content-Language header field ([RFC9110], Section 8.5) identifying it. A server that can produce a document in more than one language MAY select a representation using proactive content negotiation on Accept-Language ([RFC9110], Section 12.5.4), in which case it MUST send a Vary: Accept-Language header field so that caches do not serve one language in place of another. Because these members carry no machine-processable meaning, a client that does not understand the language of a provider string loses no interoperability: the metrics, the units, and the reporting subject are all unaffected. Such a string may also be written in a right-to-left script or mix scripts and directions; a client that displays one SHOULD render it under the Unicode Bidirectional Algorithm [UAX9] and SHOULD isolate it from surrounding text, since directional formatting characters within the string could otherwise reorder the text displayed around it.

No in-document language-tagging mechanism (such as a map from language tag to string) is defined, since the small set of human-readable values identified above does not warrant one; the pattern used for WebFinger titles ([RFC7033], Section 4.4.4.4) is available to a future revision should localized text within one document ever be needed.

12. Acknowledgments

Thanks to the early reviewers and to members of the Internet sustainability community who provided feedback on sustainability metadata and discovery patterns.

13. References

13.1. Normative References

[RFC2119]
Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, , <https://www.rfc-editor.org/info/rfc2119>.
[RFC3339]
Klyne, G. and C. Newman, "Date and Time on the Internet: Timestamps", RFC 3339, DOI 10.17487/RFC3339, , <https://www.rfc-editor.org/info/rfc3339>.
[RFC8174]
Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, , <https://www.rfc-editor.org/info/rfc8174>.
[RFC7493]
Bray, T., Ed., "The I-JSON Message Format", RFC 7493, DOI 10.17487/RFC7493, , <https://www.rfc-editor.org/info/rfc7493>.
[RFC8259]
Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", STD 90, RFC 8259, DOI 10.17487/RFC8259, , <https://www.rfc-editor.org/info/rfc8259>.
[RFC8610]
Birkholz, H., Vigano, C., and C. Bormann, "Concise Data Definition Language (CDDL): A Notational Convention to Express Concise Binary Object Representation (CBOR) and JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, , <https://www.rfc-editor.org/info/rfc8610>.
[RFC8615]
Nottingham, M., "Well-Known Uniform Resource Identifiers (URIs)", RFC 8615, DOI 10.17487/RFC8615, , <https://www.rfc-editor.org/info/rfc8615>.
[RFC8927]
Carion, U., "JSON Type Definition", RFC 8927, DOI 10.17487/RFC8927, , <https://www.rfc-editor.org/info/rfc8927>.
[RFC3986]
Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, , <https://www.rfc-editor.org/info/rfc3986>.
[RFC9110]
Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, Ed., "HTTP Semantics", STD 97, RFC 9110, DOI 10.17487/RFC9110, , <https://www.rfc-editor.org/info/rfc9110>.
[RFC9111]
Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, Ed., "HTTP Caching", STD 98, RFC 9111, DOI 10.17487/RFC9111, , <https://www.rfc-editor.org/info/rfc9111>.
[RFC6838]
Freed, N., Klensin, J., and T. Hansen, "Media Type Specifications and Registration Procedures", BCP 13, RFC 6838, DOI 10.17487/RFC6838, , <https://www.rfc-editor.org/info/rfc6838>.
[RFC6839]
Hansen, T. and A. Melnikov, "Additional Media Type Structured Syntax Suffixes", RFC 6839, DOI 10.17487/RFC6839, , <https://www.rfc-editor.org/info/rfc6839>.
[RFC7515]
Jones, M., Bradley, J., and N. Sakimura, "JSON Web Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, , <https://www.rfc-editor.org/info/rfc7515>.
[RFC7518]
Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, DOI 10.17487/RFC7518, , <https://www.rfc-editor.org/info/rfc7518>.
[RFC8037]
Liusvaara, I., "CFRG Elliptic Curve Diffie-Hellman (ECDH) and Signatures in JSON Object Signing and Encryption (JOSE)", RFC 8037, DOI 10.17487/RFC8037, , <https://www.rfc-editor.org/info/rfc8037>.

13.2. Informative References

[RFC8725]
Sheffer, Y., Hardt, D., and M. Jones, "JSON Web Token Best Current Practices", BCP 225, RFC 8725, DOI 10.17487/RFC8725, , <https://www.rfc-editor.org/info/rfc8725>.
[VC-DATA-MODEL-2]
W3C Verifiable Credentials Working Group, "Verifiable Credentials Data Model v2.0", , <https://www.w3.org/TR/vc-data-model-2.0/>.
[UAX9]
The Unicode Consortium, "Unicode Standard Annex #9: Unicode Bidirectional Algorithm", n.d., <https://www.unicode.org/reports/tr9/>.
[GHG-PROTOCOL]
World Resources Institute and World Business Council for Sustainable Development, "The Greenhouse Gas Protocol: A Corporate Accounting and Reporting Standard (Revised Edition)", , <https://ghgprotocol.org/corporate-standard>.
[GSF-SCI]
Green Software Foundation, "Software Carbon Intensity (SCI) Specification (standardized as ISO/IEC 21031:2024)", , <https://sci.greensoftware.foundation/>.
[RFC9547]
Arkko, J., Perkins, C. S., and S. Krishnan, "Report from the IAB Workshop on Environmental Impact of Internet Applications and Systems, 2022", RFC 9547, DOI 10.17487/RFC9547, , <https://www.rfc-editor.org/info/rfc9547>.
[EU-CSRD]
European Parliament and Council, "Directive (EU) 2022/2464 as regards corporate sustainability reporting (CSRD)", , <https://eur-lex.europa.eu/eli/dir/2022/2464/oj>.
[UN-SDG]
United Nations, "Transforming our world: the 2030 Agenda for Sustainable Development", , <https://sdgs.un.org/2030agenda>.
[W3C-WSG]
W3C Sustainable Web Interest Group, "Web Sustainability Guidelines (WSG) (W3C Group Draft Note)", , <https://www.w3.org/TR/web-sustainability-guidelines/>.
[CARBON-TXT]
Green Web Foundation, "carbon.txt: A TOML convention for discovering an origin's sustainability disclosures", , <https://carbontxt.org/>.
[ESRS-E1]
European Commission, "Commission Delegated Regulation (EU) 2023/2772 supplementing Directive 2013/34/EU as regards sustainability reporting standards (ESRS; Annex I, ESRS E1 Climate change)", , <https://eur-lex.europa.eu/eli/reg_del/2023/2772/oj>.
[EU-ESPR]
European Parliament and Council, "Regulation (EU) 2024/1781 establishing a framework for the setting of ecodesign requirements for sustainable products (ESPR; Digital Product Passport)", , <https://eur-lex.europa.eu/eli/reg/2024/1781/oj>.
[RFC9116]
Foudil, E. and Y. Shafranovich, "A File Format to Aid in Security Vulnerability Disclosure", RFC 9116, DOI 10.17487/RFC9116, , <https://www.rfc-editor.org/info/rfc9116>.
[RFC7326]
Parello, J., Claise, B., Schoening, B., and J. Quittek, "Energy Management Framework", RFC 7326, DOI 10.17487/RFC7326, , <https://www.rfc-editor.org/info/rfc7326>.
[I-D.ietf-green-terminology]
Chen, G., Boucadair, M., Wu, Q., Contreras, L. M., and M. P. Palmero, "Terminology for Energy Efficiency Network Management", Work in Progress, Internet-Draft, draft-ietf-green-terminology-02, , <https://datatracker.ietf.org/doc/html/draft-ietf-green-terminology-02>.
[RFC6454]
Barth, A., "The Web Origin Concept", RFC 6454, DOI 10.17487/RFC6454, , <https://www.rfc-editor.org/info/rfc6454>.
[RFC7033]
Jones, P., Salgueiro, G., Jones, M., and J. Smarr, "WebFinger", RFC 7033, DOI 10.17487/RFC7033, , <https://www.rfc-editor.org/info/rfc7033>.
[RFC6350]
Perreault, S., "vCard Format Specification", RFC 6350, DOI 10.17487/RFC6350, , <https://www.rfc-editor.org/info/rfc6350>.
[RFC6709]
Carpenter, B., Aboba, B., Ed., and S. Cheshire, "Design Considerations for Protocol Extensions", RFC 6709, DOI 10.17487/RFC6709, , <https://www.rfc-editor.org/info/rfc6709>.
[RFC6648]
Saint-Andre, P., Crocker, D., and M. Nottingham, "Deprecating the "X-" Prefix and Similar Constructs in Application Protocols", BCP 178, RFC 6648, DOI 10.17487/RFC6648, , <https://www.rfc-editor.org/info/rfc6648>.
[RFC8785]
Rundgren, A., Jordan, B., and S. Erdtman, "JSON Canonicalization Scheme (JCS)", RFC 8785, DOI 10.17487/RFC8785, , <https://www.rfc-editor.org/info/rfc8785>.
[RFC8522]
Stubbig, M., "Looking Glass Command Set", RFC 8522, DOI 10.17487/RFC8522, , <https://www.rfc-editor.org/info/rfc8522>.
[RFC6415]
Hammer-Lahav, E., Ed. and B. Cook, "Web Host Metadata", RFC 6415, DOI 10.17487/RFC6415, , <https://www.rfc-editor.org/info/rfc6415>.
[RFC7351]
Wilde, E., "A Media Type for XML Patch Operations", RFC 7351, DOI 10.17487/RFC7351, , <https://www.rfc-editor.org/info/rfc7351>.
[RFC7903]
Leonard, S., "Windows Image Media Types", RFC 7903, DOI 10.17487/RFC7903, , <https://www.rfc-editor.org/info/rfc7903>.
[RFC8351]
Leonard, S., "The PKCS #8 EncryptedPrivateKeyInfo Media Type", RFC 8351, DOI 10.17487/RFC8351, , <https://www.rfc-editor.org/info/rfc8351>.
[RFC9230]
Kinnear, E., McManus, P., Pauly, T., Verma, T., and C.A. Wood, "Oblivious DNS over HTTPS", RFC 9230, DOI 10.17487/RFC9230, , <https://www.rfc-editor.org/info/rfc9230>.
[RFC2277]
Alvestrand, H., "IETF Policy on Character Sets and Languages", BCP 18, RFC 2277, DOI 10.17487/RFC2277, , <https://www.rfc-editor.org/info/rfc2277>.
[RFC5198]
Klensin, J. and M. Padlipsky, "Unicode Format for Network Interchange", RFC 5198, DOI 10.17487/RFC5198, , <https://www.rfc-editor.org/info/rfc5198>.
[RFC5890]
Klensin, J., "Internationalized Domain Names for Applications (IDNA): Definitions and Document Framework", RFC 5890, DOI 10.17487/RFC5890, , <https://www.rfc-editor.org/info/rfc5890>.
[RFC9457]
Nottingham, M., Wilde, E., and S. Dalal, "Problem Details for HTTP APIs", RFC 9457, DOI 10.17487/RFC9457, , <https://www.rfc-editor.org/info/rfc9457>.

Appendix A. Changelog

This appendix summarizes changes in recent revisions of this document, for the convenience of reviewers. The complete revision history, including the revisions published under the document's former name (draft-besleaga-green-sustainability-wellknown), is maintained in the project repository.

A.1. Since -05

This revision responds to two rounds of Independent-Stream feedback: the Independent Submissions Editor's direction that security belongs in the document from the beginning, given that the convention has no installed base and therefore no compatibility debt to protect, and the first commissioned review, which asked that the protocol be separated cleanly from policy, that the consumer be defined, and that the incremental-adoption path be made explicit. It changes no member of the data model: none is added, removed, renamed, or retyped, the CDDL and JTD schemas are byte-for-byte unchanged, and every document conformant to -04 or -05 validates unchanged against this revision's schemas. The new integrity mechanism is a separate resource rather than a member, which is why the wire format is untouched.

  • Registered a dedicated media type and made it required. IANA Considerations now requests application/sustainability-data+json in the standards tree, with the complete RFC 6838, Section 5.6, template and the security analysis that Section 4.6 requires of standards-tree registrations; the "+json" suffix follows RFC 6838, Section 4.2.8, and RFC 6839, Section 3.1. Successful responses MUST now use that media type and MUST NOT use another; clients MUST accept it and SHOULD also accept application/json, under which documents published before the registration exist. The prose notes that RFC 6838, Section 3.1, admits standards-tree registrations from outside the IETF stream subject to IESG approval, with the Independent-Submission precedents RFC 7351, RFC 7903, RFC 8351, and (Experimental) RFC 9230, and assigns change control to the IETF accordingly. The Payload Format section, the URI Definition, and the well-known registration's Related Information track the change.

  • HTTPS is now a MUST, for publication and for retrieval. Clients MUST NOT accept a Sustainability Metadata Document over unauthenticated HTTP, MUST require HTTPS on every hop of a followed redirect, and the three URI-valued members are now restricted to absolute "https" URIs. The former justification for HTTPS being only a SHOULD is withdrawn: it rested on constrained plain-HTTP origins, and there is no deployed base to protect. RFC 9116, Section 5.7, reaches the same conclusion for the same kind of document.

  • Added the section "Document Integrity and Signing", specifying an OPTIONAL detached JWS (the detached-payload form of RFC 7515) over the exact octets of the parameterless representation as served, published at the companion well-known path /.well-known/sustainability-data.jws with the application/jose media type. Signing over served octets needs no canonicalization and works on static hosting, at the cost of an invalidated signature on any reserialization; that trade-off, and the three deployment consequences that follow from it, are stated explicitly. EdDSA/Ed25519 (RFC 8037) and ES256 (RFC 7518) are RECOMMENDED; none and MAC-based algorithms MUST NOT be used and MUST be rejected; the header SHOULD carry jwk or x5c; RFC 8725's algorithm-confusion guidance is applied to the bare JWS. The section states plainly that a self-carried key proves integrity and key continuity but not identity, that authenticity requires an out-of-band or certified key or a third-party attestation, and that a valid signature over false data is still false data. Clients MUST NOT read an absent or invalid signature as proof of falsity, and an invalid signature MUST cause the document to be treated as unverified. Embedded-signature and OpenPGP alternatives are recorded with the reasons for rejecting them.

  • Registered the companion suffix "sustainability-data.jws" as a second Well-Known URIs entry in the same registration package, rather than assuming it is covered by the first: RFC 8615, Section 3, allows a registration to describe appended path components, but ".jws" forms a distinct suffix, not a path component. RFC 6415 registered "host-meta" and "host-meta.json" the same way. A sub-path form was rejected because a file and a directory of the same name cannot coexist on ordinary static hosting.

  • Servers SHOULD send X-Content-Type-Options: nosniff, stated once alongside the media-type requirement in Mandatory Minimum Supported Service.

  • Restructured the Security Considerations around a threat-model table mapping spoofing, tampering, repudiation and greenwashing, information disclosure, and denial of service to the mitigations this document specifies, followed by subsections in the same order. The former "Integrity and Transport Security" subsection became "Transport Security and Media Typing" and carries the new unconditional HTTPS rationale; existing prose was reorganized and cross-referenced rather than duplicated, and the statement that the format carries no active content was added to the consumer guidance.

  • Sharpened verifiable-attestation-uri to say what a third-party attestation is for -- it is the only mechanism defined here that can speak to authenticity rather than integrity -- with an informative reference to the W3C Verifiable Credentials Data Model v2.0, and with the rule that the member's presence alone is evidence of nothing.

  • Moved Internationalization Considerations after IANA Considerations, the relative order in which RFC 7322, Section 4.8, lists the two sections, and added a note on the display of provider strings written in or mixing right-to-left scripts (Unicode Bidirectional Algorithm; isolation from surrounding text).

  • Requested "provisional" status for both well-known entries, noting RFC 8522 as precedent that a permanent entry with an individual change controller is available from this stream once use is demonstrated; named the IRTF research group by its acronym; and required CDNs and reverse proxies not to rewrite or re-encode the body, which would break a published signature.

  • Review-driven reframing (first commissioned review). The abstract now describes the mechanism by what it provides -- a cacheable, schema-described, automatically discoverable disclosure document -- rather than by comparison with per-request headers, and the Introduction states explicitly that the mechanism is voluntary and purely technical: the cited regulatory regimes motivate the need and fix the member vocabulary, and no obligation to publish, or consequence of publishing, arises from this document. The Introduction also carries the justification for using a well-known URI and a minimal first example.

  • Added "Roles and Processing Model", defining the publisher and consumer roles and the consumer's processing sequence (retrieve, validate, ignore unknown members, attribute as self-asserted claims, judge freshness from updated and reporting-period, follow the evidence links), and stating that the document is both a data record and a discovery surface for the publisher's authoritative reporting.

  • Added "Partial Knowledge and Incremental Adoption", making the existing on-ramp explicit: declare a narrower reporting subject via target/target-type, report only the metrics you have (the omission model), and estimate the unmeasured remainder with the basis disclosed in the methodology document. The Scope rule itself is unchanged: figures covering part of a declared subject may not be presented as the whole.

  • Recast publication-policy statements as conformance conditions. The metric-less-document rule now defines when such a document counts as conformant (an openly retrievable methodology-uri resource that states method and figures) instead of reading as an obligation on the publisher's business, notes that an access-controlled publisher conforms by reporting a metric member instead, and adds the consumer-side consequence; the word "substantive" was removed in favor of those testable properties. The in-definition "not proof" statement on disclosure-uri now points to Trust and Spoofing, where the requirement is phrased as processing behavior of conforming consumers (how an implementation labels and propagates what it ingested), with attribution stated as what retrieval does establish.

  • Closed smaller review gaps: specified where the honored target prefix set is published (the methodology-uri document) and why no in-band machine-readable list is defined; made the truncation-signaling guidance concrete; moved the version value-space change-control text into the member's definition, with a note on how a publisher would learn of a new value; replaced the "future specification" schema wording with the client-side assumption that the schemas will be extended over time; answered the durability and discovery questions about reverse-domain extension names (identifiers rather than locators; private conventions; ignoring is the interoperability mechanism; another party's published extension may be implemented); and set the target-type value list off from its prose.

  • Fixed the version member as a single, final label. This document now defines exactly one value, "2.0", which a conforming publisher MUST use, and states what a consumer does with any other value: nothing, since processing is driven by the members present. The former change-control text, which reserved new labels to a future RFC revising this document, is gone, as are the definitions of the pre-publication "1.0"/"1.1" field set and the associated target-path compatibility rule -- there is no deployed base of those documents to protect, and their presence implied a revision series this specification does not need. Versioning and Extensibility now states positively that the document is complete as published: an extension member plus the ignore-unknown rule covers new information without a new label, a member registry, or a revision, and a different data model would be a different specification with its own label. [RFC6709], Section 4.1, is cited for the requirement that a version field's handling be stated and testable. In place of the removed legacy rule, the Payload Format section now says plainly that a document omitting a mandatory member does not conform and MUST NOT be treated as conformant.

  • Widened, at the start of the document, what a reporting subject can be: the publishing origin as a whole, a part of it (a subdomain, a service, or a path prefix), a device, tenant, product, or data source, or the publishing organization itself -- the entity-level figures that corporate ESG and climate disclosures already carry. The Introduction also states that the origin is only where the document is published and does not limit what it may report on.

  • Corrected the consumer role to include people: a consumer is anything that retrieves the document, a person opening the URL in a browser included, with the processing rules written for automated consumers because interoperability depends on them.

  • Reconciled the Non-Goals with the new signing section, which defines integrity and provenance for the document but no verification of the figures; removed the stale comparison with per-request HTTP header reporting, an approach abandoned in the predecessor drafts; and reworded the alignment goal as defining member semantics that map onto quantities publishers already produce.

  • Removed normative language this specification cannot own. The Interoperability section no longer requires implementers to publish test vectors, aggregators to document their mappings, or servers to "keep documents current"; it now states what interoperability actually rests on and records those practices as useful rather than required. The multi-tenant Deployment bullet no longer "SHOULD"s operators into making a decision, and the automation bullet is descriptive.

  • Stated what capabilities is for, and what it is not. The member is now described as a hint that spares a consumer a request the publisher has said it will not honor; it is explicitly not authoritative, promises no particular parameter, and causes no failure when optimistic, because an unsupported parameter is ignored and the Basic response returned. Clients MUST NOT treat it as a precondition for a request or a guarantee about the response. This replaces the former sentence leaving the value's scope to the provider's discretion among the server, a response, or a reporting subject.

  • Readability: the extension-member rules are now four labelled sub-rules rather than one long bullet; the media-type paragraph and the signature-origin sentence were split; the cache guidance names the case it means (a response for a completed past period) instead of "historical reports".

A.2. Since -04

This revision responds to the initial Independent Submission Editor review. It changes no member of the data model: none is added, removed, renamed, or retyped, the CDDL and JTD schemas are unchanged, and every document conformant to -04 validates unchanged against this revision's schemas.

  • Removed the sentence in the disclosure-uri definition that named one particular disclosure-index convention as the canonical example and cited two unregistered paths at which it is commonly published, so as not to encourage the use of unregistered well-known names. The member is now stated to be format-agnostic and location-agnostic: this document neither defines nor recommends any path for a disclosure index. The two example documents that used such a value now use a neutral URI on the publisher's own site, and the target definition no longer refers to a site listed in such an index. The carbon.txt convention remains cited, without any path reference, in Relationship to Other Work as adjacent and complementary work.

  • Added an Internationalization Considerations section classifying every member per BCP 18 (RFC 2277), Section 2: member names, the version label, enumerated values, dates, URIs, target, functional-unit, the numeric members, and the RECOMMENDED measurement-method tokens are protocol elements compared octet-for-octet and never localized, while provider, a non-RECOMMENDED measurement-method description, and human-readable extension members are text, for which language is conveyed with Content-Language and MAY be negotiated with Accept-Language (with Vary), following the approach of RFC 9457. The section also gives the comparison rules for a target that names a host (case-insensitive, A-label form for an internationalized host) or a path prefix (percent-decoded).

  • Removed the "free-form" characterization from the running text, which mischaracterized the members it was applied to: measurement-method is described as a token with RECOMMENDED values or otherwise a human-readable description, target as an opaque identifier compared octet-for-octet, target-type as classifying that member rather than a free-form one, and the provider string in Privacy Considerations as human-readable.

  • Stated in the document the rationale for naming whole calendar periods rather than start/end instants (comparability across publishers, a bounded and canonical cache-key space, the reduced-precision calendar dates of ISO 8601 with vCard precedent, and the absence of a normative interval type in RFC 3339), together with the migration path for offset reporting years and the note that an interval form could be added later as a compatible extension.

  • Made the relationship between reporting-period and the period parameter explicit at the point of definition, so the parameter's specification and the rationale above are reachable from the member.

  • Changed the Basic Response example to an annual report ("2025", in kWh and kgCO2e), so that the document's first example shows the case its own recommendation now calls common, and noted at that example that a parameterless annual document is the ordinary deployment.

  • Editorial: folded the single "Caching" subsection directly into Operational Considerations, which contained nothing else, so that section no longer has exactly one child. No normative text changed.

  • Recognized the calendar year as the common reporting cycle: the RECOMMENDED default period of the Basic service is now the period matching the publisher's own reporting cycle, a full calendar year for periodic regulatory-style disclosure or a full calendar month for publishers reporting more frequently. This relaxes a recommendation and invalidates no existing deployment.

A.3. Since -03

  • Renamed the requested well-known URI suffix from sustainability to sustainability-data, following Independent-Stream review feedback on the precision ("squatting") expectations of RFC 8615, Section 3; the document title changed accordingly, and the registration rationale in IANA Considerations was rewritten for the precise name. The Datatracker document name is unchanged. No IANA action had occurred on the previously requested suffix, so no migration or alias mechanism is defined.

  • Added the OPTIONAL target-type member: an enumerated hint (origin, path, organization, service, product, device, tenant, data-source) classifying the reporting subject named by target. Unrecognized values fall under the existing enumerated-member tolerance rule; array responses share one value; added to the CDDL/JTD schemas and to two examples.

  • Placed the version value space under change control: the defined labels are "1.0", "1.1", and "2.0", and new values may be defined only by a future RFC that revises or replaces this document; publishers MUST NOT mint other values. The member itself remains informational-only.

  • Replaced the loose vendor-extension naming advice with a normative "Extension members" rule: member names without a "." are reserved for this specification and its successors; implementer extensions SHOULD use reverse-domain-name notation, avoiding "X-"-style markers per RFC 6648; no IANA member-name registry is created. The worked example member was renamed from vendor-example-pue to com.example.pue.

  • Corrected the CDDL root so an array response requires at least one object ([+ ...]), matching the prose, and fixed a "schemas above"/"below" direction error in Value Constraints.

  • Clarifications from a full review: stated in the Introduction proper that the origin publishes the document while the target member declares what the data is about; required the methodology resource behind the minimum-reporting rule to be publicly retrievable without authentication or payment (and identified it per object in array responses); extended the schema-tolerance note to the historical absent-target case; scoped percent-encoding of the target parameter to characters not permitted in a query component; labeled the "no-data rule" at its definition; broadened disclosure-uri to the origin or reporting subject; neutralized two example methodology URLs; updated the greenwashing guidance to build on the now-mandatory methodology-uri; merged duplicated traffic-analysis wording; listed the date formats among the prose-only rules; noted the carbon.txt convention carries no quantitative metrics; and noted terminology alignment with the IETF GREEN Working Group's terminology document.

  • Final pre-submission audit round (correctness): corrected the legacy-compatibility rule so a historical document carrying target-path is attributed to that subject rather than to the whole origin; qualified the 200-OK requirement for redirects, cache revalidation, and rate limiting; added a Cross-Origin Resource Sharing recommendation (Access-Control-Allow-Origin: *) for browser-based clients, following WebFinger practice; made the array target-type rule all-or-none; extended client tolerance to wrong-JSON-type (including null) values and to sci-score without functional-unit, restructuring the tolerance rules as a list; defined granularity without period (applies to the default period) and separated malformed from unrecognized parameter values; specified that target matching is performed after percent-decoding; stated the client behavior for an empty array; required range-bounded members to stay in range after anti-fingerprinting noise, and corrected the noise-consistency example to ratio preservation; required a documented array-size maximum.

  • Final pre-submission audit round (editorial): consolidated duplicated normative statements to single owning locations (the ignore-unknown rule, version tolerance, the target parameter/member distinction and echo rule, the range constraints, the published-prefix rule, the unit defaults, and the greenwashing attestation guidance); rescaled the day-period path-scoped example for plausibility against its monthly counterpart; expanded GHG, ESRS, SSRF, and CDN at first use and set the header workgroup label to "Independent Submission"; merged the duplicated DoS motivation sentence; noted that non-uniform members (for example, capabilities) are unconstrained across array entries; and other minor wording polish.

A.4. Since -02

This revision is a breaking change to the data model and wire format; documents and clients built to -02 ("1.0"/"1.1") interoperate with -03 ("2.0") consumers only through the compatibility rules in Versioning and Extensibility. Examples now declare version "2.0".

  • Removed the negative "not reported" sentinel entirely: an unreported metric is now conveyed by omitting the member. Negative values are no longer special: gross-quantity members (energy-consumption, carbon-footprint, sci-score, carbon-intensity-gCO2e-per-kWh, estimated-annual-emissions-kgCO2e) MUST be non-negative, renewable-energy is bounded 0-100, and scope-1/2/3 MAY be negative to express removals or net accounting (resolving the previous gap for net-negative scope reporters). Clients encountering a negative value in a non-negative member treat it as not reported, preserving compatibility with historical sentinel-bearing documents.

  • Made energy-consumption, energy-unit, carbon-footprint, and carbon-unit OPTIONAL. When a value member is present and its unit member is absent, wire-level defaults apply: kWh for energy and gCO2e for carbon (the carbon default also parameterizes scope-1/2/3).

  • Added a minimum-reporting rule: a document SHOULD carry at least one reported numeric metric or a disclosure-uri/verifiable-attestation-uri; a document carrying none is conformant only because the publisher MUST ensure the mandatory methodology-uri leads to the substantive disclosure. (Replaces the -02 rule about documents with both required metrics unreported.)

  • Renamed the optional target-path member to target, made it MANDATORY, and generalized it to identify the reporting subject (origin host, RECOMMENDED for origin-wide reports; path prefix, organizational entity, cloud tenant or provider scope, software source, or carbon.txt-listed site). A response scoped by the target query parameter echoes the matched prefix in the target member; the previous "absence means origin-wide" rule is removed (the member is always present). Array responses now uniformly share one target value.

  • Renamed carbon-intensity-gCO2-per-kWh to carbon-intensity-gCO2e-per-kWh and estimated-annual-emissions-kgCO2 to estimated-annual-emissions-kgCO2e, aligning all carbon quantities on the CO2e (CO2-equivalent) convention; stated that the annual figure is an extrapolation whose method belongs in the methodology document.

  • Redefined capabilities to describe query-parameter support only ("basic" = minimum service; "extended" = Extended parameters supported); a "basic" document MAY carry optional members. The mandatory member set is now: version, updated, capabilities, provider, measurement-method, methodology-uri, reporting-period, target (8 of the 23 defined members).

  • Versioning: "1.0"/"1.1" now denote the historical pre-2.0 field set; "2.0" denotes this revision. version remains informational-only (clients MUST NOT reject or branch on it); compatibility with historical documents is achieved through field-driven tolerance rules.

  • Replaced the "Not-Reported Sentinel" example with a "Partial Reporting" example (carbon reported, energy omitted, default units, basic with optional members); added target to all examples; added a worked vendor-extension member (vendor-example-pue) to the detailed example.

  • Added an applicability paragraph to the Introduction describing the convention's web, machine-to-machine/API, human-reader, and automated-agent/AI readiness.

  • Consolidated the privacy material: the Security Considerations "Privacy and Information Leakage" subsection now defers to the Privacy Considerations section; the HTTPS requirement is stated once (Mandatory Minimum Supported Service) and cross-referenced from Integrity and Transport Security; corrected the target bullet's cross-reference to point at Privacy Considerations, Path Disclosure.

  • Editorial: HEAD responses now use MUST (parallel to GET); the updated member cites RFC 3339 formally; expanded the CDDL and JTD abbreviations on first use; cited ESRS E1 formally and tied Digital Product Passports to the EU ESPR; updated the W3C-WSG reference to its current Group Draft Note form; forward-referenced the "Sustainability Metadata Document" definition at first use; aligned the prose/CDDL/JTD member ordering; noted that the formal schemas cannot express the range constraints and unit defaults; removed trailing whitespace.

  • For the historical record: the weekly granularity value, introduced in the predecessor draft draft-besleaga-green-sustainability-wellknown-01, was removed before the present document series began; the defined granularity values are monthly and daily (this note keeps the in-document changelog in lockstep with the repository CHANGELOG, corrected in the same pass).

A.5. Since -01

This revision applies editorial and normative clarifications to improve interoperability and readiness for Independent-stream publication; no fields are added or removed, and all previously published example payloads remain valid.

  • Aligned the formal schemas with the "clients MUST ignore unknown fields" rule: the CDDL map now permits vendor extensions (* tstr => any) and the JTD gains "additionalProperties": true, so a conformant validator no longer rejects the extensions the text permits.

  • Corrected the date-format references: the YYYY and YYYY-MM forms are calendar-date precision forms, not RFC 3339 productions (RFC 3339 defines the YYYY-MM-DD full-date).

  • Clarified HTTP method handling (GET/HEAD; other methods -> 405 with Allow), the no-data response (404), the granularity value set, and malformed-parameter handling.

  • Specified that scope-1/2/3 are expressed in carbon-unit and sci-score in gCO2e per functional-unit; extended the not-reported sentinel to optional numeric fields; relaxed the Basic default period so annual-only reporters can comply; and normativized that a basic response omits optional fields.

  • Defined target prefix-matching semantics and percent-encoding (RFC 3986, added as a normative reference).

  • Added HTTP Semantics (RFC 9110) and HTTP Caching (RFC 9111) as normative references, since the document relies on HTTP methods, status codes (including 405/Allow), conditional requests (ETag/Last-Modified/If-None-Match), and caching; cited them at the relevant points.

  • Redefined the version member as an informational, non-negotiated label (clients MUST NOT reject or branch on it) and rewrote "Versioning and Extensibility" around the must-ignore rule, so that the specification accommodates future fields without a revision and without an in-band version-negotiation mechanism.

  • Changed the requested IANA registry status from "permanent" to "provisional" (appropriate for an Independent Submission per RFC 8615, promotable once in broad use), and added a rationale for the single-token suffix and the query-parameter design (WebFinger precedent).

  • Sharpened the "Relationship to Other Work" section to distinguish this application-layer, origin-level HTTP disclosure surface from network-layer energy work (IETF GREEN, EMAN/RFC 7326) and from IRTF research, and to state clearly that it complements, and does not duplicate, the Green Web Foundation carbon.txt convention; cited the IAB e-impact workshop report (RFC 9547) as motivating context.

  • Clarified that a single object is equivalent to a one-element array and that clients MUST accept both response forms; array entries are sorted, non-overlapping, and of uniform precision and target.

  • Interoperability hardening from pre-submission review: a period request without finer granularity yields a single (possibly aggregated) object; a server scoping a response to target echoes target-path (absence means origin-wide); target matching is byte-wise, case-sensitive, on complete path segments, against a published set of prefixes (also closing a path-disclosure oracle and bounding the cache key space); calendar periods are interpreted in UTC; incomplete periods report the completed portion; array truncation keeps the most recent periods; anti-fingerprinting noise is applied once at generation time, deterministically and consistently across related fields; sci-score requires functional-unit; a document with both required metrics unreported carries a disclosure link; redirect responses are attributed to the final origin.

  • Reference precision: identified carbon.txt as a TOML index, W3C WSG as a Community Group Report, and SCI by its ISO/IEC 21031:2024 form.

  • Corrected the arithmetic of the highly-detailed example (scopes now sum to the reported carbon-footprint).

  • Revised the Acknowledgments to thank the Internet sustainability community generally, without implying review or endorsement by any IETF Working Group or IRTF Research Group.

  • Numerous editorial fixes (typos, comma splices, heading hyphenation, host/origin terminology, Acknowledgments spelling, bare IANA URL). The pre-rename revision history was moved out of this appendix to the project repository.

A.6. Since -00

Editorial/positioning update only; no change to the data model, field semantics, service levels, or wire format, and all published example payloads remain valid.

  • Replaced "standardized, out-of-band mechanism" with "uniform, out-of-band convention" in the Abstract, to reflect that this is an Informational document describing a common, interoperable convention (suited to the Independent Submission Stream and Research Group discussion) rather than a standards-track specification.

A.7. draft-besleaga-sustainability-wellknown-00 (replaces draft-besleaga-green-sustainability-wellknown)

This document is an administrative continuation of draft-besleaga-green-sustainability-wellknown, which it replaces. It makes no change to the field set or wire format; the previously published example payloads remain valid.

  • Renamed the document from draft-besleaga-green-sustainability-wellknown to draft-besleaga-sustainability-wellknown and recorded a "Replaces" relationship. The prior name's "green" token could imply a scope tied to the IETF GREEN Working Group; this is an individual Independent Submission with no working-group affiliation.

  • Adopted schema version 1.1 as the default across all examples (version 1.1 introduced the optional disclosure-uri field; documents declaring 1.0 remain valid).

  • Clarified the meaning of a negative value in a required numeric field: it denotes an unreported metric (not a real negative measurement); see "Unreported Numeric Metrics" (a section since removed). Also noted that carbon-footprint is gross (non-negative) and that the anti-fingerprinting noise is not applied to the "not reported" sentinel.

  • Editorial and clarity corrections for publication: the URI Definition now states that this document requests the registration (rather than asserting it is already registered); added a "Relationship to Other Work" note (application-layer scope; does not update or obsolete any IETF-stream document; complementary to carbon.txt); and specified that servers not supporting the Extended parameters MUST ignore them and return the Basic response.

  • Data-model and example corrections: clarified the capabilities semantics (a simple basic/extended indicator that is determined per response and MAY reflect the server, the specific response, or a resource path) and corrected the Target-Specific example, which had declared basic while carrying an optional field (target-path) and had reused the whole-host totals for a sub-path; pinned reporting-period to the same date formats as the period parameter; noted that measurement-method is a free-form string with RECOMMENDED values; bounded renewable-energy to 0-100; documented malformed-parameter handling (400 or ignore); and added a "Not-Reported Sentinel" example.

The revision history of the replaced document, the former draft-besleaga-green-sustainability-wellknown (its versions -00 through -05), is not reproduced here; it is retained in the project repository's CHANGELOG.

Author's Address

Andrei Nicolae Besleaga
Independent