manage-schemas

# 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

```bash
# CLI
cv schemas list

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

## Add a schema

```bash
# 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

```bash
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

```bash
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

```json
{
  "$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

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