Support structured parameters (objects and arrays) in recipe templates

[jordigilh]

Problem

Recipe parameters today are flat scalars (string, number, boolean, date, file, select). This works well for interactive and desktop use cases where a human fills in a form. However, when an orchestrator invokes a recipe programmatically — for example, an enterprise platform passing structured incident context to a recipe — the orchestrator must flatten all structured data into individual string parameters.

For a real-world example: an incident response orchestrator needs to pass signal context, enrichment data, and findings from prior pipeline phases to a recipe. Today, this requires 25+ flat string parameters:

parameters:
  - key: signal_name
    input_type: string
    requirement: required
    description: "Signal type"
  - key: signal_namespace
    input_type: string
    requirement: required
    description: "K8s namespace"
  - key: signal_severity
    input_type: string
    requirement: required
    description: "Signal severity"
  - key: signal_resource_kind
    input_type: string
    requirement: required
    description: "Resource kind"
  # ... 20+ more flat params

And the recipe author cannot use conditionals or loops over structured data:

# NOT POSSIBLE TODAY:
prompt: |
  {% if enrichment.owner_chain %}
  Owner chain: {{ enrichment.owner_chain }}
  {% endif %}

  {% for finding in prior_findings %}
  ## {{ finding.name }}
  {{ finding.output }}
  {% endfor %}

Observation

Goose already uses MiniJinja for recipe template rendering (prompt_template.rs). MiniJinja natively supports:

• Dot-notation attribute access: {{ signal.namespace }}
• Conditionals on nested fields: {% if enrichment.owner_chain %}
• Iteration over arrays: {% for item in findings %}
• Filters: {{ data | tojson }}

These capabilities are already compiled into Goose. The test suite in validate_recipe.rs even validates {% if %} conditionals in recipes today. The gap is not the template engine — it's that recipe parameters are passed as HashMap<String, String>, which discards structure before reaching MiniJinja.

Proposal

Add object and array as parameter input types, and pass structured values into the MiniJinja rendering context.

Recipe author experience:

version: "1.0.0"
title: "Incident Pre-Check"
description: "Verify resource in CMDB before investigation"
parameters:
  - key: signal
    input_type: object
    requirement: required
    description: "Structured signal context from orchestrator"
  - key: enrichment
    input_type: object
    requirement: optional
    default: {}
    description: "Enrichment data (owner chain, labels)"
  - key: prior_findings
    input_type: array
    requirement: optional
    default: []
    description: "Findings from prior pipeline phases"

prompt: |
  A {{ signal.severity }} signal "{{ signal.name }}" fired for
  {{ signal.resource_kind }}/{{ signal.resource_name }}
  in namespace {{ signal.namespace }}.

  {% if enrichment.owner_chain %}
  Owner chain: {{ enrichment.owner_chain }}
  {% endif %}

  {% for finding in prior_findings %}
  ## {{ finding.name }} ({{ finding.phase }})
  {{ finding.output }}
  {% endfor %}

  Check the CMDB for this resource before proceeding.

extensions:
  - type: streamable_http
    name: cmdb-mcp
    uri: "http://cmdb-service:8080/mcp"
    timeout: 30

response:
  json_schema:
    type: object
    properties:
      status:
        type: string
        enum: [available, not_registered, decommissioned]
      recommendation:
        type: string
    required: [status, recommendation]

Orchestrator passes structured values:

{
  "signal": {
    "name": "OOMKilled",
    "namespace": "production",
    "severity": "critical",
    "resource_kind": "Pod",
    "resource_name": "api-server-abc123"
  },
  "enrichment": {
    "owner_chain": "Pod/api-server-abc123 → ReplicaSet/api-server → Deployment/api-server"
  },
  "prior_findings": [
    {
      "name": "change-freeze-check",
      "phase": "pre-investigation",
      "output": "No active change freeze for namespace production"
    }
  ]
}

Scope of Change

Based on code review, the changes are localized to the recipe module:

1. recipe/mod.rs: Add Object and Array variants to RecipeParameterInputType
2. recipe/template_recipe.rs: Change render_recipe_content_with_params signature from params: &HashMap<String, String> to params: &HashMap<String, serde_json::Value> (or minijinja::Value). MiniJinja's Value::from_serialize() already handles the conversion.
3. recipe/validate_recipe.rs: Update validate_parameters_in_template to recognize dot-notation variables (e.g., signal.namespace → verify signal is a declared parameter). undeclared_variables(true) already returns signal as the top-level name.
4. Parameter passing callers (e.g., recipe_utils.rs in goose-server): Accept serde_json::Value for object/array params instead of forcing string conversion.

Use Cases

• Enterprise orchestrators: Pass structured incident/alert context to investigation recipes
• CI/CD pipelines: Pass build metadata as objects to automation recipes
• Multi-phase workflows: Pass structured outputs from earlier recipe phases to later ones (via sub-recipes with values)
• API integrations: Pass API response payloads directly into recipes without manual field extraction

Backward Compatibility

• Existing recipes with string/number/boolean/date/file/select parameters are unaffected
• The rendering function can accept serde_json::Value and auto-convert scalar values to strings for backward compatibility
• Desktop UI would show object/array parameters as JSON text inputs (or skip them for orchestrator-only use cases)
• Validation rules for object/array parameters: optionality rules apply to the top-level value; nested field validation is left to the template's runtime behavior (consistent with how MiniJinja handles missing attributes)

Prior Art

• MiniJinja's own examples pass structured contexts: context!(users => vec![...]) with {% for user in users %}
• Jinja2 (Python) natively supports structured contexts — this is standard Jinja behavior
• Goose's own render_string<T: Serialize>() in prompt_template.rs already accepts arbitrary serializable types — the recipe path is the only one that narrows to HashMap<String, String>

---

Posted as a Discussion per CONTRIBUTING.md guidance for architectural changes. Happy to follow up with a focused issue and PR if this direction aligns with Goose's goals.

[jordigilh]

Opened a PR implementing this proposal: #8934

The PR adds object and array variants to RecipeParameterInputType and wires structured parameter support end-to-end through the build pipeline. Summary of what landed:

• New render_recipe_content_with_structured_params function in template_recipe.rs
• Automatic detection and JSON parsing of structured params in build_recipe/mod.rs (existing HashMap<String, String> API preserved)
• Type validation: object params must receive JSON objects, array params must receive JSON arrays
• Template variable normalization in validate_recipe.rs (dot and bracket notation mapped to root parameter keys)
• Structured default validation for object/array parameters
• 18 new tests (serde round-trip, unit, integration, negative/edge cases)
• Documentation updates in recipe-reference.md

All CI checks passing. Happy to iterate based on maintainer feedback.