Specification
Draft · protocol 3.0.0-draft
This page defines how to read the specification, how TRP is versioned, and the structure shared by every resource.
Normative language
Section titled “Normative language”In the approved normative specification, MUST, MUST NOT, SHOULD, SHOULD NOT and MAY follow RFC 2119 and RFC 8174 usage. While TRP is in draft, these terms describe proposed requirements, not established compliance obligations.
Every published page shows a state: Draft, Candidate, Stable or Deprecated, and the applicable protocol version.
Four different claims
Section titled “Four different claims”Avoid a single ambiguous “TRP certified” badge. TRP separates:
- Data-conformant: payloads validate against the published schemas for a conformance profile.
- Methodology-validated: a calculation follows a declared, reviewed method.
- Verified: specific claim data is backed by evidence at a stated grade.
- Certified: an organization has been assessed. No certification program exists today.
Versioning
Section titled “Versioning”Version each of these separately, and record all of them with any calculation:
protocol_version, schema_version, methodology_version, factor_dataset_version, engine_version, mapping_version, report_template_version.
Semantic versioning is used for the public schema. Calculations must be reproducible against the exact versions in force when they were produced.
Design principles
Section titled “Design principles”- Event-oriented and provenance-first. Record observed activities and their evidence; derive summaries from immutable event versions.
- System-neutral. Preserve original identifiers, source payload hashes and mappings. Do not force one vendor’s internal IDs on partners.
- Claim-native. Estimate revisions, line items, jobs, contractors, buildings, contents and material decisions are first-class.
- Uncertainty-aware. Distinguish measurements, documented derived values, estimates and assumptions.
- Decision-aware. Preserve not just what was installed but why alternatives were accepted or rejected.
- Privacy by design. Separate personally identifying claim metadata from public aggregate reports.
- Extendable. Unknown extension fields must not silently break compatible readers.
Common envelope
Section titled “Common envelope”Every TRP resource SHOULD include:
| Field | Purpose |
|---|---|
id |
UUID or collision-resistant URI |
type |
Resource type, for example trp.waste_event |
schema_version |
Version of the schema the resource was written against |
created_at, updated_at, effective_at |
ISO 8601 timestamps with offsets |
source_system, source_record_id |
Where the record came from, and its ID there |
organization_id, claim_id |
Tenant and claim context |
data_classification |
Sensitivity label controlling sharing |
provenance, evidence_ids |
How the value was obtained and what supports it |
revision, supersedes_id, status |
Version history |
extensions |
Namespaced additions that readers may ignore |
A pseudonymous claim_id may replace direct insurance identifiers for sensitive entities. Use ISO 8601 timestamps, ISO 4217 currency codes, ISO 3166 region codes and UUIDs.
Event lifecycle
Section titled “Event lifecycle”observed → submitted → validated → accepted or rejected → superseded
Correct an accepted event with a new revision, never an undetectable in-place edit. Preserve source timestamps separately from ingestion timestamps. Late evidence may update confidence and calculation versions without altering historical raw observations.
Use explicit unit codes and conversions: kg, metric_ton, short_ton, lb, m2, ft2, m3, yd3, kWh, MJ, L, US_gal, km, mi, kgCO2e, tCO2e, USD, CAD, GBP.
Quantities must not carry hidden scale factors: 423.72 MWh is not 423.72 kWh. Factors MUST include numerator_unit and denominator_unit, plus boundary, region, vintage and source.