Root

The root object is the top-level structure of a CTRF document. Every valid CTRF report must include the required fields that identify the format and contain the test results.

Properties

Name	Type	Required	Description
reportFormat	String	Required	Identifies the document format. Must always be "CTRF". Consumers should reject documents with any other value.
specVersion	String	Required	The CTRF specification version this document conforms to. Must follow Semantic Versioning format (e.g., 0.1.0).
reportId	String	Optional	Identifies this emitted CTRF document as a serialized artifact. Must be a valid UUID if provided. A materially changed, merged, filtered, or transformed document should receive a new value.
runId	String	Optional	Identifies the logical test run. Related documents, such as shards from one coordinated execution, should share the same non-empty value.
timestamp	String	Optional	When the report was generated. Must be a valid RFC 3339 / ISO 8601 date-time string.
generatedBy	String	Optional	Identifies the tool, framework, or system that produced this CTRF document.
results	Object	Required	Contains the test outcomes represented by this document. See Results Object.
insights	Object	Optional	Aggregated metrics computed across multiple test runs for trend analysis. See Insights Object.
baseline	Object	Optional	Reference to a previous report used for comparison when computing insights. See Baseline Object.
extra	Object	Optional	Extension point for arbitrary metadata. The only place where custom fields are permitted at the top level.

Example

{
  "reportFormat": "CTRF",
  "specVersion": "0.1.0",
  "reportId": "550e8400-e29b-41d4-a716-446655440000",
  "runId": "run-2026-08-15-e2e",
  "timestamp": "2025-01-24T10:30:00Z",
  "generatedBy": "jest-ctrf-reporter",
  "results": {
    ...
  }
}

reportId and runId identify different things. reportId belongs to one emitted document, while runId connects every CTRF document that belongs to the same logical test run. For example, four shard reports should have four distinct reportId values and one shared runId.

An emitted report is an immutable artifact. Merging, filtering, enriching, or otherwise transforming it produces a new document and, when identifiers are used, a new reportId. See Report Immutability for the complete lifecycle guidance.

Version Compatibility

These documentation examples follow CTRF 0.1.0. specVersion identifies the specification a report conforms to; a valid SemVer string alone does not establish that a consumer supports that version.

Before CTRF 1.0.0, MINOR releases may add capabilities or introduce breaking contract changes. PATCH releases must preserve compatibility. Consumers must treat different pre-1.0 MINOR versions as potentially incompatible and should support PATCH releases within a supported MINOR version. Breaking changes must be identified in the changelog, with migration guidance where action is required.

Beginning with 1.0.0, MAJOR releases contain breaking changes, MINOR releases contain backward-compatible additions, and PATCH releases contain compatible corrections and clarifications. Consumers must reject incompatible MAJOR versions.

See Versioning in the normative specification.