ChatDev/docs/user_guide/en/config_schema_contract.md

Config Schema API Contract

This reference explains how /api/config/schema and /api/config/schema/validate expose DevAll's dynamic config metadata so IDEs, frontend form builders, and CLI tools can scope schemas with breadcrumbs.

1. Endpoints

Method & Path	Purpose
POST /api/config/schema	Returns the schema for a config node described by breadcrumbs.
POST /api/config/schema/validate	Validates a YAML/JSON document and optionally echoes the scoped schema.

1.1 Request body (shared fields)

{
  "breadcrumbs": [
    {"node": "DesignConfig", "field": "graph"},
    {"node": "GraphConfig", "field": "nodes"},
    {"node": "NodeConfig", "value": "model"}
  ]
}

• node (required): class name (DesignConfig, GraphConfig, NodeConfig, etc.) that must match the class reached so far.
• field (optional): child field to traverse. When omitted, the breadcrumb only asserts you remain on node.
• value (optional): use when the child class depends on a discriminator (e.g., node type). Supply the value as it would appear in YAML.
• index (optional int): reserved for list traversal; current configs rely on value/field for navigation.

1.2 /schema response

{
  "schemaVersion": "0.1.0",
  "node": "NodeConfig",
  "fields": [
    {
      "name": "id",
      "typeHint": "str",
      "required": true,
      "description": "Unique node identifier"
    },
    {
      "name": "type",
      "typeHint": "str",
      "required": true,
      "enum": ["model", "python", "agent"],
      "enumOptions": [
        {"value": "model", "label": "LLM Node", "description": "Runs provider-backed models"}
      ]
    }
  ],
  "constraints": [...],
  "breadcrumbs": [...],
  "cacheKey": "f90d..."
}

• fields: serialized ConfigFieldSpec entries; nested targets include childRoutes.
• constraints: emitted from collect_schema() (mutual exclusivity, required combos, etc.).
• cacheKey: SHA-1 hash of {node, breadcrumbs} so clients can memoize responses.

1.3 /schema/validate payloads

Add document alongside breadcrumbs:

{
  "breadcrumbs": [{"node": "DesignConfig"}],
  "document": """
name: demo
version: 0.4.0
workflow:
  nodes: []
  edges: []
"""
}

Responses:

• Valid document: { "valid": true, "schema": { ... } }
• Config error:

  {
    "valid": false,
    "error": "field 'nodes' must not be empty",
    "path": ["workflow", "nodes"],
    "schema": { ... }
  }
  

• Malformed YAML: HTTP 400 with { "message": "invalid_yaml", "error": "..." }.

2. Breadcrumb Tips

• Begin with { "node": "DesignConfig" }.
• Each hop’s node must match the current config class or the API returns HTTP 422.
• Use field to step into nested configs (graph → nodes → config, etc.).
• Use value for discriminator-based children (node type, tooling type, etc.).
• Non-navigable targets raise field '<name>' on <node> is not navigable.

3. CLI Helper

python run.py --inspect-schema --schema-breadcrumbs '[{"node":"DesignConfig","field":"graph"}]'

The CLI prints the same JSON as /schema, which is useful while editing FIELD_SPECS or debugging registries before exporting templates.

4. Frontend Pattern

1. Fetch base schema with [{node: 'DesignConfig', field: 'graph'}] to render the workflow form.
2. When users open nested modals (node config, tooling config, etc.), append breadcrumbs describing the path and refetch.
3. Cache responses using cacheKey + breadcrumbs.
4. Before saving, call /schema/validate to surface error + path inline.

5. Error Reference

HTTP Code	Situation	Detail payload
400	YAML parse failure	{ "message": "invalid_yaml", "error": "..." }
422	Breadcrumb resolution failure	{ "message": "breadcrumb node 'X'..." }
200 + valid=false	Backend ConfigError	{ "error": "...", "path": ["workflow", ...] }
200 + valid=true	Document OK	Schema echoed back for the requested breadcrumbs.

Pair this contract with FIELD_SPECS to build schema-aware experiences without hardcoding config structures.