A contract you can actually read.

A small envelope with explicit meaning.

The examples share the same top-level structure. That makes a consumer reusable without suggesting that a keyword cluster is the same kind of evidence as an inspected HTML element.

Field	Type	Meaning
`schema_version`	string	The report contract version. The bundled examples use 1.0.
`report_id`	string	An identifier for this report. Sample identifiers begin with sample-.
`sample`	boolean	True identifies an illustrative fixture rather than a live observation.
`analysis_type`	string	One of the eight documented workflow slugs.
`status`	string	complete, partial, or failed. Partial describes incomplete coverage.
`target`	object	A readable label and a description of the supplied input kind.
`summary`	string	A concise interpretation of the report’s scope and findings.
`findings`	array	Evidence-linked items with id, outcome, title, evidence, and action.
`not_measured`	array	Readable descriptions of unavailable or out-of-scope measurements.

A complete example

seo-analysis.json

{
  "schema_version": "1.0",
  "report_id": "sample-seo-analysis",
  "sample": true,
  "analysis_type": "seo-analysis",
  "status": "complete",
  "target": {
    "label": "Documentation page",
    "input_kind": "Supplied HTML"
  },
  "summary": "A small page review, with the evidence attached.",
  "findings": [
    {
      "id": "f01",
      "outcome": "pass",
      "title": "A descriptive title is present",
      "evidence": "<title>Getting started with the sample project</title>",
      "action": "Keep the title specific to this guide."
    },
    {
      "id": "f02",
      "outcome": "review",
      "title": "The description needs attention",
      "evidence": "The supplied document has no description meta element.",
      "action": "Write an accurate summary of the page."
    },
    {
      "id": "f03",
      "outcome": "pass",
      "title": "The main heading is clear",
      "evidence": "One H1 is present: Getting started.",
      "action": "Keep a logical heading hierarchy."
    }
  ],
  "not_measured": [
    "Live indexing status",
    "Search rankings",
    "Real-user performance"
  ]
}

Observations and actions are different fields.

A finding’s evidence describes the supplied input. Its action suggests what a reviewer could do next. The report never needs to hide both ideas inside a score. Preserve the distinction in your interface and in any downstream task created from a finding.

Validate the shape before using it.

The downloadable schema uses JSON Schema Draft 2020-12. It requires the documented envelope, defines the finding shape, and rejects unexpected properties. The sample fixtures are designed to validate against it. A production schema may need additional source identifiers, timestamps, and authorized provider metadata.

Download the JSON Schema

Missing does not mean zero.

Do not fill unavailable measurements with plausible defaults. A partial report should identify the uncollected scope. A failed report can contain an empty findings array and a clear summary of why no useful analysis was completed. The completion status describes processing, not whether a target is high quality.

Our structured JSON guide explains the design tradeoffs in more detail.