Support for YAML Anchors and Metadata Fields in Manifest

[Leoyzen]

Background

When managing complex agent configurations in manifest.yaml, users frequently rely on YAML anchors (&) and aliases (*) to maintain a DRY (Don't Repeat Yourself) configuration. To use anchors effectively at the root level, it is common practice to define a dedicated "definition" or "template" block (e.g., .anchors, .templates, or x-common-configs) where reusable fragments are stored.

Currently, the AgentsManifest Pydantic model is strict about extra fields. This prevents users from adding these top-level metadata blocks without triggering validation errors or warnings, effectively limiting the use of native YAML reusability features.

Purpose

The goal is to allow AgentsManifest to ignore specific "hidden" or "extension" fields that are used for metadata or YAML anchors. This will:

1. Enable Configuration Reusability: Allow users to define shared tool configurations, model settings, or prompts once and reference them across multiple agents.
2. Align with Industry Standards: Follow established conventions from tools like GitLab CI (which uses the . prefix for hidden keys) and Docker Compose (which uses the x- prefix for extensions).
3. Maintain Validation Integrity: Ensure that actual typos in core fields (e.g., writing agent: instead of agents:) are still caught, while being "permissive" only toward intentional metadata fields.

Proposal

I propose a "Controlled Extras" approach by relaxing the extra field restriction in a targeted way:

1. Update Model Configuration

Change the model_config of AgentsManifest to extra='allow'.

2. Implement Metadata Filtering Validator

Add a model_validator(mode="after") to AgentsManifest that inspects model_extra.

• Allowed Prefixes: Fields starting with . (dot), _ (underscore), or x- (common extension prefix) should be silently allowed.
• Unknown Fields: Any other extra field that does not match these prefixes should trigger a logger.warning (or a ValueError), helping users catch configuration typos while allowing metadata.

3. JSON Schema Support

Update the JSON schema generation logic to include patternProperties. This ensures that IDEs using the yaml-language-server (configured via your provided $schema URL) will not flag these fields as errors.

Suggested Schema Addition:

"patternProperties": {
  "^\\.[a-zA-Z0-9_-]+$": { "description": "Hidden metadata or YAML anchors" },
  "^x-": { "description": "Custom extension fields" },
  "^_[a-zA-Z0-9_-]+$": { "description": "Private metadata fields" }
}

Implementation Example

class AgentsManifest(Schema):
    # ... existing fields ...

    model_config = ConfigDict(extra="allow", ...)

    @model_validator(mode="after")
    def handle_extra_metadata(self) -> Self:
        if self.model_extra:
            for key in self.model_extra:
                if not key.startswith((".", "_", "x-")):
                    logger.warning(f"Unrecognized field '{key}' in manifest. "
                                   f"Metadata/anchor fields must start with '.', '_', or 'x-'.")
        return self

[phil65]

Do YAML LSPs still warn about invalid, non-prefixed keys this way?

[Leoyzen]

@phil65 Yeah，fixed and no errors from lsp now.

[Leoyzen]

LSP diagnostics found no errors or warnings. The YAML LSP is working correctly and does NOT report any issues with the YAML anchors.
Result:

• . prefixed keys (.anchors) are ALLOWED by the schema
• No LSP warnings about invalid/non-prefixed keys
• The PR Feat/issue 12 manifest metadata #13 fix works as intended