Verification schema
Specs
The canonical format for design verification findings. One JSON schema that any verification tool can populate.
Agents consuming findings from multiple verifiers need a common schema to aggregate, compare, and act. This is that schema.
Why a standard matters
Emission formats
POST to /api/score with a “format” field to select the output shape. The canonical JSON is the source of truth; the others are lossy projections.
designesyapplication/jsonThe native designesy shape — the current response with score, grade, checks, categoryScores.canonicalapplication/jsonThe full review-findings.json schema — the superset with all fields. The source of truth.reviewtext/markdownjakubkrehel better-interface-compatible markdown report — Scope, Findings table, Verdict.googleapplication/jsonGoogle @google/design.md-compatible shape — { findings, summary, designSystem }.Top-level fields
schemaVersionstringSchema version (currently "1.0").generatedAtdate-timeISO 8601 timestamp.toolobjectTool name, version, user agent.subjectobjectThe artifact under review (url, file, token-spec).configobjectTool configuration (ruleset, thresholds, categories).coveragearrayScope and coverage table (jakubkrehel pattern).categoriesarrayCategory scores (designesy categoryScores, Lighthouse categories).findingsarrayIndividual check findings — the core payload.consideredButRejectedarrayFindings considered but rejected (jakubkrehel).verificationarrayVerification steps taken (jakubkrehel).summaryobjectComposite score, grade, counts by status and severity.verdictstringOverall verdict: pass, fail, block, needs-changes, approve, not-scored.runtimeErrorobjectFatal error if the tool could not complete.runWarningsarrayNon-fatal warnings during the run.rawobjectNative tool output preserved verbatim for lossless round-trip.Finding object fields
Each entry in the findings array is a finding object. Each tool populates the subset of fields it has — fields a tool does not produce are omitted.
idstringCheck identifier (v01-v37, audit id, rule name).itemstringHuman-readable check name.categorystringCheck category (cadence, accessibility, motion, etc.).severitystringNormalized severity (pass/fail/warn/skip/error/warning/info/high/medium/low).severityRawstringNative severity token verbatim.messagestringFinding detail / explanation.remediationstringHow to fix this finding.pathstringDotted token path (Google design.md).locationstringSource location (jakubkrehel: "src/Dialog.tsx:42").domainstringReview domain (jakubkrehel: accessibility, layout, etc.).beforestringCurrent implementation (jakubkrehel).afterstringActionable replacement (jakubkrehel).whystringViolated principle + user impact (jakubkrehel).scorenumber|nullNumeric score 0-1 (Lighthouse).numericValuenumberRaw metric value (Lighthouse: ms, bytes).weightnumberCheck weight in the category.Severity normalization
Each tool uses its own severity vocabulary. The canonical schema normalizes them while preserving the native token in severityRaw.
designesyPASSpassdesignesyFAILerrordesignesyWARNwarningdesignesySKIPskipGoogle design.mderrorerrorGoogle design.mdwarningwarningGoogle design.mdinfoinfojakubkrehelHIGHhighjakubkrehelMEDIUMmediumjakubkrehelLOWlowLighthousescore=0 binaryfailLighthousescore=1 binarypassLighthouseinformativeinformativeLighthousenotApplicablenotApplicableUsage
POST /api/score
Send a JSON body with url and optional format. The default format is designesy (the native shape). Use canonical for the full schema, review for markdown, or google for the design.md-compatible shape.
Example request
curl -X POST https://www.designesy.org/api/score \
-H "Content-Type: application/json" \
-d '{"url":"https://www.designesy.org/","format":"canonical"}'