# Designesy — /specs Canonical page: https://www.designesy.org/specs --- ## 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. ## Top-level fields ## 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. ## Severity normalization Each tool uses its own severity vocabulary. The canonical schema normalizes them while preserving the native token in `severityRaw`. ## Usage 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. `curl -X POST https://www.designesy.org/api/score \ -H "Content-Type: application/json" \ -d '{"url":"https://www.designesy.org/","format":"canonical"}'`