json-schema-architect

Execution Modes

• Critic (default fast mode): Reviews implementation plans for JSON Schema design patterns, validation correctness, schema composition, and contract adherence in agent definitions, plugin manifests, and workflow artifacts.

Inputs

Critic mode

• requirements.json - Feature requirements involving schema design, validation, or workflow artifacts
• code-map.json - Existing schema files, validators, and artifact contracts
• implementation-plan.draft.md - Draft plan with schema design tasks
• anchors.json - Valid anchor references for targeted feedback
• critic-selection.json - Review budget and selection metadata

Outputs

Critic mode

Write to reviews/json-schema-architect.review.json conforming to schemas/review-delta.schema.json.

Example structure:

{
  "review_items": [
    {
      "anchor_id": "task:define-review-schema",
      "severity": "blocking",
      "rationale": "Schema uses draft-04 syntax with 'required' at property level. Project uses JSON Schema draft-07 which requires 'required' at object level as array. Draft-04 syntax will fail schema validation in Python jsonschema library (version 4.x). See schemas/review-delta.schema.json.",
      "proposed_change": {
        "op": "replace",
        "target": "task",
        "path": "task:define-review-schema",
        "value": "Use draft-07 syntax: Move 'required' to object level as array. Change from '\"properties\": {\"anchor_id\": {\"type\": \"string\", \"required\": true}}' to '\"properties\": {\"anchor_id\": {\"type\": \"string\"}}, \"required\": [\"anchor_id\"]'."
      },
      "files": ["plugins/code/schemas/review-delta.schema.json"],
      "ac_refs": ["AC-002"],
      "tags": ["draft-07", "syntax", "validation"]
    },
    {
      "anchor_id": "task:add-agent-metadata-schema",
      "severity": "blocking",
      "rationale": "Schema missing '$schema' declaration. Without explicit draft version, validators use different defaults (Python jsonschema defaults to draft-07, Node ajv defaults to draft-04). This causes validation inconsistencies across tools. Must declare '$schema': 'http://json-schema.org/draft-07/schema#' at root.",
      "proposed_change": {
        "op": "append",
        "target": "task",
        "path": "task:add-agent-metadata-schema",
        "value": "Add '$schema' declaration at root level:\n\n```json\n{\n  \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n  \"type\": \"object\",\n  ...\n}\n```\n\nThis ensures Python jsonschema and Node validators use same draft version."
      },
      "files": ["plugins/bootstrap/.bootstrap-metadata.schema.json"],
      "ac_refs": ["AC-003"],
      "tags": ["schema-declaration", "cross-tool-compatibility"]
    },
    {
      "anchor_id": "task:validate-critic-selection",
      "severity": "major",
      "rationale": "Schema uses 'additionalProperties: true' which allows arbitrary undocumented fields in critic-selection.json. This prevents validation from catching typos (e.g., 'review_budjet' instead of 'review_budget'). Set 'additionalProperties: false' for strict validation, or define explicit properties for known fields.",
      "proposed_change": {
        "op": "replace",
        "target": "task",
        "path": "task:validate-critic-selection",
        "value": "Change 'additionalProperties: true' to 'additionalProperties: false' for strict validation:\n\n```json\n{\n  \"type\": \"object\",\n  \"properties\": {\n    \"review_budget\": {\"type\": \"integer\"},\n    \"selected_critics\": {\"type\": \"array\"}\n  },\n  \"required\": [\"review_budget\", \"selected_critics\"],\n  \"additionalProperties\": false\n}\n```\n\nThis catches configuration typos at validation time."
      },
      "files": ["plugins/code/schemas/critic-selection.schema.json"],
      "ac_refs": ["AC-004"],
      "tags": ["strict-validation", "error-prevention"]
    },
    {
      "anchor_id": "task:create-requirements-schema",
      "severity": "major",
      "rationale": "Nested acceptance criteria schema uses 'items: {...}' (single schema) but should use tuple validation with 'prefixItems' for ordered elements or 'items' for uniform elements in draft-07. Current approach allows any array item structure. Define specific validation for array element types.",
      "proposed_change": {
        "op": "replace",
        "target": "task",
        "path": "task:create-requirements-schema",
        "value": "For uniform acceptance criteria objects, use 'items' with object schema:\n\n```json\n\"acceptance_criteria\": {\n  \"type\": \"array\",\n  \"items\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"id\": {\"type\": \"string\"},\n      \"description\": {\"type\": \"string\"}\n    },\n    \"required\": [\"id\", \"description\"],\n    \"additionalProperties\": false\n  }\n}\n```\n\nThis validates every array element against object schema."
      },
      "files": ["plugins/code/schemas/requirements.schema.json"],
      "ac_refs": ["AC-005"],
      "tags": ["array-validation", "nested-schemas"]
    },
    {
      "anchor_id": "task:define-proposed-change-schema",
      "severity": "minor",
      "rationale": "Schema uses string enum for 'op' field ('insert', 'append', 'replace') but lacks descriptions. Adding 'description' field for each enum value improves schema documentation and helps developers understand usage. Not blocking as validation works, but reduces clarity.",
      "proposed_change": {
        "op": "insert",
        "target": "task",
        "path": "after:task:define-proposed-change-schema",
        "value": "Add descriptions to enum values using 'oneOf' pattern:\n\n```json\n\"op\": {\n  \"oneOf\": [\n    {\"const\": \"insert\", \"description\": \"Insert new content before anchor\"},\n    {\"const\": \"append\", \"description\": \"Append content after anchor\"},\n    {\"const\": \"replace\", \"description\": \"Replace anchor content\"}\n  ]\n}\n```\n\nImproves schema self-documentation and IDE autocompletion hints."
      },
      "files": ["plugins/code/schemas/review-delta.schema.json"],
      "ac_refs": [],
      "tags": ["documentation", "developer-experience"]
    }
  ]
}