manage-schemas

name

manage-schemas

description

Create, update, and delete JSON Schema definitions in config-validator. Use when you need to add a new schema for a config file type, update a schema after adding required fields, list available schemas, or remove an obsolete schema. Triggers include "add schema", "create validation schema", "update schema", "list schemas", "delete schema", "manage validation rules", or any task involving the JSON Schema definitions used by config-validator.

manage-schemas

Manage JSON Schema definitions used by config-validator.

When to use

• Adding a new schema for a newly introduced config file format
• Updating a schema after adding required fields to an app config
• Listing schemas to find the correct ID to use in CI
• Deleting an old schema that is no longer in use

List schemas

# CLI
cv schemas list

# API
curl -s http://localhost:3000/api/schemas | jq '[.[] | {id, name}]'

Add a schema

# CLI - read from a local file
cv schemas add ./schemas/worker-config.json \
  --id worker-config \
  --name "Worker Config" \
  --server http://localhost:3000 \
  --key cv_...

# API - POST with JSON body
curl -s -X POST http://localhost:3000/api/schemas \
  -H "Authorization: Bearer cv_..." \
  -H "Content-Type: application/json" \
  -d '{
    "id": "worker-config",
    "name": "Worker Config",
    "description": "Background job worker settings",
    "schema": {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "type": "object",
      "required": ["queue", "concurrency"],
      "properties": {
        "queue": { "type": "string" },
        "concurrency": { "type": "number", "minimum": 1, "maximum": 32 }
      }
    }
  }'

Update a schema

curl -s -X PUT http://localhost:3000/api/schemas/worker-config \
  -H "Authorization: Bearer cv_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Worker Config v2",
    "schema": { "..." }
  }'

Delete a schema

cv schemas delete old-schema --key cv_...

# API
curl -s -X DELETE http://localhost:3000/api/schemas/old-schema \
  -H "Authorization: Bearer cv_..."

Schema format requirements

• Must be valid JSON Schema (draft-07 or draft-2020-12)
• The server validates the schema itself before storing it
• Schema ID: lowercase letters, numbers, hyphens only (e.g. my-app-config)
• Invalid JSON Schema returns 400 with an error message

Minimal valid schema example

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["port", "host"],
  "properties": {
    "port": { "type": "number", "minimum": 1, "maximum": 65535 },
    "host": { "type": "string", "minLength": 1 }
  }
}

Schema API response shape

{
  "id": "my-app-config",
  "name": "App Config",
  "description": "Main application config",
  "createdAt": "2026-03-10T10:00:00Z",
  "updatedAt": "2026-03-18T14:22:00Z",
  "schema": { "..." }
}