UAT: Resource type YAML config format in spec uses different field names than implementation #4597

New issue

Open

opened 2026-04-08 15:57:20 +00:00 by HAL9000 · 0 comments

HAL9000 commented

2026-04-08 15:57:20 +00:00

Owner

Bug Report

Feature Area: Resource type YAML configuration

Summary

The spec's example resource type YAML configuration (§ Custom Resource Types, line 24504–24558) uses different field names than what the implementation actually accepts. Users following the spec documentation will get validation errors.

Expected Behavior (from spec)

The spec shows this YAML format for custom resource types (lines 24504–24558):

# File: resource-types/database.yaml
cleveragents:
  version: "3.0"

resource_type:
  name: local/database
  description: "A SQL database (PostgreSQL, MySQL, SQLite, etc.)"
  physical_or_virtual: physical
  user_addable: true

  # CLI arguments for `agents resource add local/database`
  cli_arguments:
    - name: connection-string
      type: string
      required: true
      description: "Database connection string"
      validation:
        pattern: "^(postgresql|mysql|sqlite)://"

  sandbox_strategy: transaction_rollback
  handler: DatabaseHandler
  checkpointable: true

  allowed_parent_types: []

  child_types:
    - type: local/db-schema
      auto_discover: true
      manual_link: false
      description: "Discovered database schemas"

  capabilities:
    readable: true
    writable: true
    sandboxable: true
    checkpointable: true

Key spec field names:

physical_or_virtual (not resource_kind)
cli_arguments (not cli_args)
allowed_parent_types (not parent_types)
checkpointable as a top-level field (not inside capabilities)
cleveragents: wrapper with resource_type: key
capabilities.readable, capabilities.writable, capabilities.sandboxable, capabilities.checkpointable (not read, write, sandbox, checkpoint)
child_types as a list of objects with type, auto_discover, manual_link, description (not a flat list of strings)

Actual Behavior

The implementation (src/cleveragents/resource/schema.py, src/cleveragents/domain/models/core/resource_type.py) uses:

resource_kind (not physical_or_virtual)
cli_args (not cli_arguments)
parent_types (not allowed_parent_types)
No cleveragents: wrapper — flat YAML structure
capabilities.read, capabilities.write, capabilities.sandbox, capabilities.checkpoint
child_types as a flat list of strings

The formal schema file (docs/schema/resource_type.schema.yaml) also uses the implementation's field names (resource_kind, cli_args, parent_types), confirming the spec documentation example is inconsistent with both the schema and the implementation.

Steps to Reproduce

Create a YAML file following the spec example at line 24504–24558
Run agents resource type add --config ./database.yaml
Observe validation error: resource_kind is required but not provided

Code Locations

Spec example: docs/specification.md lines 24504–24558
Implementation schema: src/cleveragents/resource/schema.py
Domain model: src/cleveragents/domain/models/core/resource_type.py
Formal schema: docs/schema/resource_type.schema.yaml

Impact

High — Users following the spec documentation to create custom resource types will get validation errors. The spec is the primary reference for users.

Resolution Options

Either:

Update the spec documentation example to use the implementation's field names (resource_kind, cli_args, parent_types, flat YAML without wrapper), OR
Update the implementation to accept the spec's field names (with backward compatibility aliases)

Option 1 is simpler. Option 2 would require updating the schema, domain model, and service.

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: uat-tester

## Bug Report **Feature Area:** Resource type YAML configuration ### Summary The spec's example resource type YAML configuration (§ Custom Resource Types, line 24504–24558) uses different field names than what the implementation actually accepts. Users following the spec documentation will get validation errors. ### Expected Behavior (from spec) The spec shows this YAML format for custom resource types (lines 24504–24558): ```yaml # File: resource-types/database.yaml cleveragents: version: "3.0" resource_type: name: local/database description: "A SQL database (PostgreSQL, MySQL, SQLite, etc.)" physical_or_virtual: physical user_addable: true # CLI arguments for `agents resource add local/database` cli_arguments: - name: connection-string type: string required: true description: "Database connection string" validation: pattern: "^(postgresql|mysql|sqlite)://" sandbox_strategy: transaction_rollback handler: DatabaseHandler checkpointable: true allowed_parent_types: [] child_types: - type: local/db-schema auto_discover: true manual_link: false description: "Discovered database schemas" capabilities: readable: true writable: true sandboxable: true checkpointable: true ``` Key spec field names: - `physical_or_virtual` (not `resource_kind`) - `cli_arguments` (not `cli_args`) - `allowed_parent_types` (not `parent_types`) - `checkpointable` as a top-level field (not inside `capabilities`) - `cleveragents:` wrapper with `resource_type:` key - `capabilities.readable`, `capabilities.writable`, `capabilities.sandboxable`, `capabilities.checkpointable` (not `read`, `write`, `sandbox`, `checkpoint`) - `child_types` as a list of objects with `type`, `auto_discover`, `manual_link`, `description` (not a flat list of strings) ### Actual Behavior The implementation (`src/cleveragents/resource/schema.py`, `src/cleveragents/domain/models/core/resource_type.py`) uses: - `resource_kind` (not `physical_or_virtual`) - `cli_args` (not `cli_arguments`) - `parent_types` (not `allowed_parent_types`) - No `cleveragents:` wrapper — flat YAML structure - `capabilities.read`, `capabilities.write`, `capabilities.sandbox`, `capabilities.checkpoint` - `child_types` as a flat list of strings The formal schema file (`docs/schema/resource_type.schema.yaml`) also uses the implementation's field names (`resource_kind`, `cli_args`, `parent_types`), confirming the spec documentation example is inconsistent with both the schema and the implementation. ### Steps to Reproduce 1. Create a YAML file following the spec example at line 24504–24558 2. Run `agents resource type add --config ./database.yaml` 3. Observe validation error: `resource_kind` is required but not provided ### Code Locations - Spec example: `docs/specification.md` lines 24504–24558 - Implementation schema: `src/cleveragents/resource/schema.py` - Domain model: `src/cleveragents/domain/models/core/resource_type.py` - Formal schema: `docs/schema/resource_type.schema.yaml` ### Impact **High** — Users following the spec documentation to create custom resource types will get validation errors. The spec is the primary reference for users. ### Resolution Options Either: 1. Update the spec documentation example to use the implementation's field names (`resource_kind`, `cli_args`, `parent_types`, flat YAML without wrapper), OR 2. Update the implementation to accept the spec's field names (with backward compatibility aliases) Option 1 is simpler. Option 2 would require updating the schema, domain model, and service. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: uat-tester

HAL9000 added this to the v3.5.0 milestone

2026-04-08 17:41:21 +00:00

HAL9000 added the

labels

2026-04-09 01:18:02 +00:00

HAL9000 referenced this issue