designesy.org/specsschema v1.015 top-level fields22 finding fieldsthe JSON Schema
Specs
One JSON format for design-verification findings, which any tool can fill in. Designesy, Google design.md, Lighthouse and jakubkrehel/skills all map into it.
Why one format
- One shape to aggregate
- Agents reading findings from several verifiers need one schema to combine, compare and act on them.
- The union of the tools
- Lighthouse, axe, Google design.md and designesy each emit their own JSON; this schema holds all of it.
- Nothing lost
- The raw field keeps each tool’s native output, for a lossless round trip where the canonical shape drops detail.
- Routed by source
- The tool field lets a consumer route: designesy for contract conformance, Lighthouse for performance, axe for accessibility.
- One verdict for CI
- The verdict field gives a gate one answer: pass, fail, block or needs-changes.
- One severity vocabulary
- Severity is normalised across tools, so an agent can triage everything with one scale.
Emission formats
POST /api/score with a format field
The canonical JSON is the source of truth; the other formats are projections of it that drop some detail.
| Format | Content type | What it is |
|---|---|---|
designesy | application/json | The native shape: score, grade, checks and categoryScores. The default. |
canonical | application/json | This schema in full, every field. The source of truth the others project from. |
review | text/markdown | A report in the better-interface style: scope, a findings table, the verdict. |
google | application/json | The DESIGN.md format's lint shape: findings, summary and designSystem. |
Top-level fields
15 fields · 6 required · read from the schema itself
| Field | Type | Required | What it holds |
|---|---|---|---|
schemaVersion | "1.0" | required | Schema version. Increment on breaking changes. |
generatedAt | string | ISO 8601 timestamp when the report was generated. | |
tool | object | required | The verification tool that produced this report. |
subject | object | required | The artifact under review. |
config | object | Tool configuration (ruleset, thresholds, categories enabled). Opaque. | |
coverage | array | Scope and coverage table (jakubkrehel pattern). One row per domain reviewed. | |
categories | array | Category scores (designesy categoryScores, Lighthouse categories). Each category gets a 0-100 score. | |
findings | array | required | Individual check findings. Each finding is one check result from the verification engine. |
consideredButRejected | array | Findings considered during review but rejected (jakubkrehel pattern). Opaque for most tools. | |
verification | array | Verification steps taken (jakubkrehel pattern). Commands run, interactions tested. | |
summary | object | required | Composite score and counts. |
verdict | string | required | Overall verdict. pass = no FAIL/error findings; fail = at least one FAIL/error; block = any HIGH (jakubkrehel); needs-changes = only WARN remaining; approve = no actionable findings; not-scored = all SKIP and/or MANUAL. One of: pass, fail, block, needs-changes, approve, not-scored. |
runtimeError | object | Fatal error if the tool could not complete. If present, findings may be incomplete. | |
runWarnings | array | Non-fatal warnings during the run. | |
raw | object | Native tool output preserved verbatim for lossless round-trip. Consumers that need the original shape can read this. |
The finding object
22 fields · 3 required · each tool fills the ones it has
Each entry in findings is one of these. A field a tool does not produce is left out, never set to null.
| Field | Type | Required | What it holds |
|---|---|---|---|
id | string | required | Check identifier (a designesy check id such as v01 or x01, a Lighthouse audit id, or a Google rule name). |
item | string | Human-readable check name (designesy item field). | |
category | string | Check category (designesy: cadence, accessibility, motion, tokens, etc.). Maps to Lighthouse categoryId and jakubkrehel domain. | |
severity | string | required | Normalized severity. Designesy uses pass/fail/warn/skip. Google uses error/warning/info. jakubkrehel uses high/medium/low. Lighthouse uses informative/notApplicable/manual. One of: pass, fail, warn, skip, error, warning, info, high, medium, low, informative, notApplicable, manual. |
severityRaw | string | The native severity token verbatim (e.g. "PASS", "warning", "HIGH"). Preserved for lossless round-trip. | |
status | string | designesy-native status. MANUAL = requires browser/CDP (excluded from score, run the audit); SKIP = not applicable (excluded from score). One of: PASS, FAIL, WARN, SKIP, MANUAL. | |
message | string | required | Human-readable finding detail. Designesy detail, Google message, Lighthouse explanation. |
detail | string | Extended detail string (designesy detail field). May overlap with message. | |
remediation | string | How to fix this finding (designesy remediation guidance). | |
path | string | Dotted token path (the DESIGN.md format: "components.button-primary"). | |
location | string | Source location (jakubkrehel: "src/Dialog.tsx:42"). | |
locations | array | Multiple locations for a systemic finding (jakubkrehel consolidation). | |
domain | string | Review domain (jakubkrehel: accessibility, layout, writing, typography, colors, ui). | |
before | string | Current implementation (jakubkrehel before column). | |
after | string | Actionable replacement (jakubkrehel after column). | |
why | string | Violated principle + user impact (jakubkrehel why column). | |
score | number | null | Numeric score 0-1 (Lighthouse audit score). null if not scored. | |
numericValue | number | Raw metric value (Lighthouse: ms, bytes, count). | |
displayValue | string | Display string for the metric (Lighthouse). | |
scoreDisplayMode | string | How the score is displayed (Lighthouse). One of: binary, numeric, error, manual, notApplicable, informative. | |
weight | number | Check weight in the category (designesy per-check weight, Lighthouse auditRef weight). | |
group | string | Display group (Lighthouse categoryGroups). |
Severity, normalised
the native token is kept in severityRaw
| Tool | Native | Canonical |
|---|---|---|
| designesy | PASS | pass |
| designesy | FAIL | error |
| designesy | WARN | warning |
| designesy | SKIP | skip |
| Google design.md | error | error |
| Google design.md | warning | warning |
| Google design.md | info | info |
| jakubkrehel | HIGH | high |
| jakubkrehel | MEDIUM | medium |
| jakubkrehel | LOW | low |
| Lighthouse | score = 0, binary | fail |
| Lighthouse | score = 1, binary | pass |
| Lighthouse | informative | informative |
| Lighthouse | notApplicable | notApplicable |
Usage
POST /api/score · url, format
Send url and, optionally, format. The default is designesy; use canonical for the full schema, review for markdown, google for the design.md shape.
curl -X POST https://www.designesy.org/api/score \
-H "Content-Type: application/json" \
-d '{"url":"https://www.designesy.org/","format":"canonical"}'