# Schemas

Three JSON Schemas (draft-07) ship in the `schemas/` folder of the `shadcn-maestro` package. The CLI validates with Ajv on every write. The copies below match `shadcn-maestro` 0.3.0.

## map

The map stored in `.shadcn-maestro/map/`: files with their regions and hashes, screens, components, unresolved references, annotations and reviews. `annotation` and `review` reuse its definitions (`sourceRef`, `relativePath`, `hash`).

A `sourceRef` points at code: `relativePath` (application-relative POSIX path), `fileHash` (SHA-256), `start` and `end` (`line` and `column`, from 1) and `symbolId`.

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "map",
  "title": "Structural UI map",
  "definitions": {
    "relativePath": {
      "description": "Application-relative POSIX path: never absolute, never through a .. segment.",
      "type": "string",
      "minLength": 1,
      "pattern": "^(?!/)(?![A-Za-z]:)(?!(.*/)?\\.\\.(/|$))[^\\\\]+$"
    },
    "hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
    "position": {
      "type": "object",
      "required": ["line", "column"],
      "properties": { "line": { "type": "integer", "minimum": 1 }, "column": { "type": "integer", "minimum": 1 } }
    },
    "sourceRef": {
      "type": "object",
      "required": ["relativePath", "fileHash", "start", "end", "symbolId"],
      "properties": {
        "relativePath": { "$ref": "#/definitions/relativePath" },
        "fileHash": { "$ref": "#/definitions/hash" },
        "start": { "$ref": "#/definitions/position" },
        "end": { "$ref": "#/definitions/position" },
        "symbolId": { "type": "string" }
      }
    },
    "unresolved": {
      "type": "object",
      "required": ["kind", "reason", "evidence", "ref"],
      "properties": {
        "kind": { "type": "string" },
        "reason": { "type": "string" },
        "evidence": { "type": "string" },
        "ref": { "anyOf": [{ "$ref": "#/definitions/sourceRef" }, { "type": "null" }] }
      }
    },
    "region": {
      "type": "object",
      "required": ["id", "parentId", "tag", "hash", "ref"],
      "additionalProperties": false,
      "properties": {
        "id": { "type": "string" },
        "parentId": { "type": ["string", "null"] },
        "tag": { "type": "string" },
        "hash": { "$ref": "#/definitions/hash" },
        "ref": { "$ref": "#/definitions/sourceRef" }
      }
    },
    "file": {
      "type": "object",
      "required": ["kind", "id", "fileHash", "status", "imports", "regions", "unresolved"],
      "properties": {
        "kind": { "const": "file" },
        "id": { "$ref": "#/definitions/relativePath" },
        "fileHash": { "$ref": "#/definitions/hash" },
        "status": { "enum": ["parsed", "parse-error"] },
        "imports": { "type": "array", "items": { "$ref": "#/definitions/relativePath" } },
        "regions": { "type": "array", "items": { "$ref": "#/definitions/region" } },
        "unresolved": { "type": "array", "items": { "$ref": "#/definitions/unresolved" } }
      }
    },
    "screen": {
      "type": "object",
      "required": ["kind", "id", "patterns", "router", "entryFile", "layoutIds", "regionIds", "componentIds"],
      "properties": {
        "kind": { "const": "screen" },
        "id": { "type": "string" },
        "patterns": { "type": "array", "items": { "type": "string" } },
        "router": { "type": "string" },
        "entryFile": { "$ref": "#/definitions/relativePath" },
        "layoutIds": { "type": "array", "items": { "$ref": "#/definitions/relativePath" } },
        "regionIds": { "type": "array", "items": { "type": "string" } },
        "componentIds": { "type": "array", "items": { "type": "string" } }
      }
    },
    "component": {
      "type": "object",
      "required": ["kind", "id", "definition", "uses", "children", "screenIds"],
      "properties": {
        "kind": { "const": "component" },
        "id": { "type": "string" },
        "definition": { "$ref": "#/definitions/sourceRef" },
        "uses": { "type": "array", "items": { "$ref": "#/definitions/sourceRef" } },
        "children": { "type": "array", "items": { "type": "string" } },
        "screenIds": { "type": "array", "items": { "type": "string" } }
      }
    },
    "identity": {
      "type": "object",
      "required": ["host", "session"],
      "properties": { "host": { "type": "string", "minLength": 1 }, "session": { "type": "string", "minLength": 1 } }
    },
    "annotation": {
      "type": "object",
      "required": ["kind", "id", "subjectId", "revision", "purpose", "rationale", "evidence", "evidenceKind", "author", "authorObserved", "sourceHashes", "status"],
      "properties": {
        "kind": { "const": "annotation" },
        "id": { "type": "string" },
        "subjectId": { "type": "string" },
        "revision": { "type": "integer", "minimum": 1 },
        "purpose": { "type": "string" },
        "rationale": { "type": "string" },
        "evidence": { "type": "array", "items": { "$ref": "#/definitions/sourceRef" } },
        "evidenceKind": { "enum": ["source", "browser"] },
        "author": { "$ref": "#/definitions/identity" },
        "authorObserved": { "anyOf": [{ "$ref": "#/definitions/identity" }, { "type": "null" }], "description": "Session the host exposed to the CLI; null when only the declared author exists." },
        "sourceHashes": {
          "type": "object",
          "propertyNames": { "$ref": "#/definitions/relativePath" },
          "additionalProperties": { "$ref": "#/definitions/hash" }
        },
        "status": { "enum": ["pending", "reviewed", "disputed", "stale"] }
      }
    },
    "review": {
      "type": "object",
      "required": ["kind", "id", "annotationId", "annotationRevision", "reviewer", "reviewerObserved", "verdict", "rationale", "checkedRefs", "sourceHashes"],
      "properties": {
        "kind": { "const": "review" },
        "id": { "type": "string" },
        "annotationId": { "type": "string" },
        "annotationRevision": { "type": "integer", "minimum": 1 },
        "reviewer": { "$ref": "#/definitions/identity" },
        "reviewerObserved": { "anyOf": [{ "$ref": "#/definitions/identity" }, { "type": "null" }], "description": "Session the host exposed to the CLI; null when only the declared reviewer exists." },
        "verdict": { "enum": ["confirmed", "disputed", "insufficient_evidence"] },
        "rationale": { "type": "string" },
        "checkedRefs": { "type": "array", "items": { "$ref": "#/definitions/sourceRef" } },
        "sourceHashes": {
          "type": "object",
          "propertyNames": { "$ref": "#/definitions/relativePath" },
          "additionalProperties": { "$ref": "#/definitions/hash" }
        }
      }
    },
    "record": {
      "oneOf": [
        { "$ref": "#/definitions/file" },
        { "$ref": "#/definitions/screen" },
        { "$ref": "#/definitions/component" },
        { "$ref": "#/definitions/annotation" },
        { "$ref": "#/definitions/review" }
      ]
    },
    "index": {
      "type": "object",
      "required": ["schemaVersion", "revision", "extractorVersion", "baselineId", "profile", "routes", "screens", "records", "configHashes", "unresolved", "unresolvedCounts"],
      "properties": {
        "schemaVersion": { "const": 2 },
        "revision": { "type": "string" },
        "extractorVersion": { "type": "string" },
        "baselineId": { "type": "string" },
        "profile": {
          "type": "object",
          "required": ["framework", "routers"],
          "properties": { "framework": { "type": ["string", "null"] }, "routers": { "type": "array", "items": { "type": "string" } } }
        },
        "routes": {
          "type": "array",
          "items": {
            "type": "object",
            "required": ["id", "pattern", "router", "screenId"],
            "properties": { "id": { "type": "string" }, "pattern": { "type": "string" }, "router": { "type": "string" }, "screenId": { "type": "string" } }
          }
        },
        "screens": { "type": "array", "items": { "type": "string" } },
        "records": {
          "type": "object",
          "additionalProperties": { "type": "string", "pattern": "^(files|screens|components|annotations|reviews)/[A-Za-z0-9._-]+\\.json$" }
        },
        "configHashes": {
          "type": "object",
          "propertyNames": { "$ref": "#/definitions/relativePath" },
          "additionalProperties": { "$ref": "#/definitions/hash" }
        },
        "unresolved": { "type": "array", "items": { "$ref": "#/definitions/unresolved" } },
        "unresolvedCounts": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } }
      }
    }
  }
}
```

## annotation

Input of [`reviewer annotate`](/cli/annotate). Status is not an input: every accepted submission starts `pending`.

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "annotation",
  "title": "Annotation submission (shadcn-maestro reviewer annotate --input)",
  "description": "A semantic interpretation submitted for review. Status is not an input: every accepted submission starts pending.",
  "type": "object",
  "additionalProperties": false,
  "required": ["subjectId", "expectedMapRevision", "expectedAnnotationRevision", "purpose", "rationale", "evidence", "author", "sourceHashes"],
  "properties": {
    "subjectId": { "type": "string", "minLength": 1 },
    "expectedMapRevision": { "type": "string", "minLength": 1 },
    "expectedAnnotationRevision": { "type": ["integer", "null"], "minimum": 1 },
    "purpose": { "type": "string", "minLength": 1, "description": "Contextual function of the subject, e.g. list filters or primary navigation." },
    "rationale": { "type": "string", "minLength": 1 },
    "evidence": {
      "type": "object",
      "additionalProperties": false,
      "required": ["kind", "refs"],
      "properties": {
        "kind": { "enum": ["source", "browser"] },
        "refs": { "type": "array", "minItems": 1, "items": { "$ref": "map#/definitions/sourceRef" } }
      }
    },
    "author": {
      "type": "object",
      "additionalProperties": false,
      "required": ["host", "session"],
      "properties": { "host": { "type": "string", "minLength": 1 }, "session": { "type": "string", "minLength": 1 } }
    },
    "sourceHashes": {
      "type": "object",
      "propertyNames": { "$ref": "map#/definitions/relativePath" },
      "additionalProperties": { "$ref": "map#/definitions/hash" }
    }
  }
}
```

## review

Input of [`reviewer review`](/cli/review). Without a reviewer identity no review is recorded.

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "review",
  "title": "Review submission (shadcn-maestro reviewer review --input)",
  "description": "An independent verdict on one exact annotation revision. Reviewer identity is required: without it no review is recorded.",
  "type": "object",
  "additionalProperties": false,
  "required": ["annotationId", "annotationRevision", "reviewer", "verdict", "rationale", "checkedRefs", "sourceHashes"],
  "properties": {
    "annotationId": { "type": "string", "minLength": 1 },
    "annotationRevision": { "type": "integer", "minimum": 1 },
    "reviewer": {
      "type": "object",
      "additionalProperties": false,
      "required": ["host", "session"],
      "properties": { "host": { "type": "string", "minLength": 1 }, "session": { "type": "string", "minLength": 1 } }
    },
    "verdict": { "enum": ["confirmed", "disputed", "insufficient_evidence"] },
    "rationale": { "type": "string", "minLength": 1 },
    "checkedRefs": { "type": "array", "minItems": 1, "items": { "$ref": "map#/definitions/sourceRef" } },
    "sourceHashes": {
      "type": "object",
      "propertyNames": { "$ref": "map#/definitions/relativePath" },
      "additionalProperties": { "$ref": "map#/definitions/hash" }
    }
  }
}
```