Template Directives

Template directives are special YAML keys that enable resource composition, references, and dynamic configuration in Compozy. They allow you to build modular, reusable configurations by referencing and composing other resources.

Overview

Compozy provides two main directive types that enable powerful composition patterns:

$ref Directive

Reference existing resources by path and filter criteria

$use Directive

Use and instantiate resources like tools and agents

Composition Benefits: Directives enable clean, readable configurations while promoting reusability and modularity across your Compozy resources.

`$ref` Directive

The $ref directive creates references to existing resources using path-based queries with optional filtering.

Basic Syntax

Reference Syntax

$ref: scope::path.#(filter_expression)

Components:

scope: local, global, or resource
path: Dot-notation path to the resource collection
filter: JSONPath-style filter expression

Reference Types

Local References point to resources within the same file:

Local References

# Reference a schema by ID
input:
  $ref: local::schemas.#(id=="user_input")

# Reference a tool by ID
tools:
  - $ref: local::tools.#(id=="weather_tool")

# Reference a task by ID
on_success:
  next:
    $ref: local::tasks.#(id=="next_step")

# Reference multiple tools by type
tools:
  - $ref: local::tools.#(category=="data_processing")

Local reference patterns:

Use for resources defined in the same file
Ideal for task chaining and schema reuse
Keeps related resources together

`$use` Directive

The $use directive instantiates and configures tools, agents, and other executable resources.

Using Tools enables tool execution within tasks:

Tool Usage

# Basic tool usage
- id: weather_check
  type: basic
  $use: tool(local::tools.#(id=="weather_tool"))
  with:
    city: "{{ .workflow.input.city }}"

# Tool with specific version
- id: data_processor
  type: basic
  $use: tool(local::tools.#(id=="processor" && version=="2.1"))
  with:
    input_data: "{{ .workflow.input.data }}"

# External tool usage
- id: external_api
  type: basic
  $use: tool(resource::tool::#(id=="external_service"))
  with:
    endpoint: "{{ .env.API_ENDPOINT }}"
    api_key: "{{ .env.API_KEY }}"

Tool usage patterns:

Use tool(reference) syntax for tool instantiation
Pass parameters via with section
Filter tools by version, capabilities, or other criteria

Composition Patterns

Schema Composition builds complex schemas from simpler ones:

Schema Composition

schemas:
  # Base user schema
  - id: base_user
    type: object
    properties:
      id:
        type: string
      name:
        type: string
      email:
        type: string

  # Extended user schema
  - id: full_user
    type: object
    allOf:
      - $ref: local::schemas.#(id=="base_user")
      - type: object
        properties:
          profile:
            $ref: local::schemas.#(id=="user_profile")
          preferences:
            $ref: local::schemas.#(id=="user_preferences")

Schema composition benefits:

Reuse common schema definitions
Build complex structures incrementally
Maintain consistency across schemas

Advanced Patterns

Dynamic References use templates in reference expressions:

Dynamic References

# Dynamic tool selection
$use: tool(local::tools.#(id=="{{ .workflow.input.processor_type }}_tool"))

# Dynamic schema reference
schema:
  $ref: local::schemas.#(version=="{{ .config.schema_version }}")

# Environment-based references
model:
  $ref: global::models.#(environment=="{{ .env.DEPLOYMENT_ENV }}")

Dynamic reference benefits:

Adapt references based on runtime data
Support environment-specific configurations
Enable flexible resource selection

Error Handling

Reference Fallbacks handle missing references gracefully:

Reference Fallbacks

# Provide fallback options
primary_tool:
  $ref: local::tools.#(id=="preferred_tool")
fallback_tool:
  $ref: local::tools.#(id=="backup_tool")

# Use conditional references
tool_ref: |
  {{- if .tools.advanced_tool -}}
  local::tools.#(id=="advanced_tool")
  {{- else -}}
  local::tools.#(id=="basic_tool")
  {{- end -}}

Fallback strategies:

Provide multiple fallback options
Use conditional logic for resource selection
Implement graceful degradation

References

Sprig Functions

Learn about data transformation capabilities with template functions

Context Variables

Understand how to access and use context data in directives

Basic Tasks

See how directives work in basic task configuration

Template directives enable powerful composition and modularity in Compozy configurations, allowing you to build reusable, maintainable workflow configurations.

Template Directives

$ref Directive

$use Directive

On this page