Metadata Validation Guardrail

​

What is Metadata Validation?

​

Key Features

1. Required Keys: Ensure specific metadata keys are always present in the request.
2. Value Constraints: Validate a key’s value against a regex pattern or restrict it to a fixed set of allowed values.
3. Unknown Key Control: Optionally reject any metadata key that is not explicitly declared in your rules.

​

Adding Metadata Validation Guardrail

1

Navigate to Guardrails

Go to the AI Gateway dashboard and navigate to the Guardrails section.

2

Create or Select a Guardrails Group

Create a new guardrails group or select an existing one where you want to add the Metadata Validation guardrail.

3

Add Metadata Validation Integration

Click on Add Guardrail and select Metadata Validation from the TrueFoundry Guardrails section.

4

Configure the Guardrail

Fill in the configuration form with your desired settings (see Configuration Options below). Toggle Allow unknown keys and add a rule for each metadata key you want to enforce.

5

Save the Configuration

Click Save to add the guardrail to your group.

​

Configuration Options

​

Key Rules

​

Key must exist

​

Value must match

​

How It Works

1. If Allow unknown keys is off, every metadata key that is not declared in your rules raises an unknown_key violation. Keys injected by the gateway itself (for example subject, subjectType, tfy_agent_name, and any default gateway metadata) are exempt from this check.
2. For each declared key rule:
   • Key must exist: a missing key raises a missing_required violation.
   • Value must match (required): a missing key raises a missing_required violation.
   • Value must match (regex): if the key is present, its value must match the pattern, otherwise a pattern_mismatch violation is raised. An invalid regex pattern raises an invalid_regex_pattern violation.
   • Value must match (allowed values): if the key is present, its value must be in the allowed set, otherwise a value_not_allowed violation is raised.
3. If any violations are found, the verdict fails. The response handling then depends on the configured Enforcing Strategy.

​

Violation Reasons

​

Examples

• environment — Value must match, allowed values: prod, staging, dev
• customer_id — Value must match, regex: ^cust_[0-9]+$
• team — Key must exist

{"environment": "prod", "customer_id": "cust_12345", "team": "billing"}

{"environment": "prod", "customer_id": "cust_12345"}

{"environment": "production", "customer_id": "cust_12345", "team": "billing"}

{"environment": "dev", "customer_id": "12345", "team": "billing"}

{"environment": "dev", "customer_id": "cust_1", "team": "billing", "debug": "true"}

​

Sending Metadata

curl -X POST "{GATEWAY_BASE_URL}/chat/completions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H 'X-TFY-METADATA: {"environment":"prod","customer_id":"cust_12345","team":"billing"}' \
  -H 'X-TFY-GUARDRAILS: {"llm_input_guardrails":["my-guardrail-group/metadata-validation"],"llm_output_guardrails":[]}' \
  -d '{
    "model": "openai-main/gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "Hello"}
    ]
  }'

​

Use Cases

​

Example use cases

Restrict the prod gateway to production applications

When you run more than one gateway against the same control plane — for example a dev gateway and a prod gateway — you may want to lock down the prod gateway so only production applications can call it, and a dev application that points at it is rejected.You can enforce this with Metadata Validation, without changing any application code, by combining two pieces of metadata the gateway already provides:

• The caller’s environment comes from virtual account tags. Tagging a virtual account with env: prod means every request made with that account’s token carries env: prod.
• The gateway’s environment comes from default gateway metadata. Each gateway stamps every request that passes through it with its own value, for example tfy_gateway_region: PROD.

A guardrail rule then matches on the gateway’s stamp (tfy_gateway_region) and applies a Metadata Validation guardrail that requires the caller’s env to be the matching value. Because the rule only fires on the gateway whose stamp it matches, the prod-environment guardrail runs only on the prod gateway:

Caller (virtual account tag)	Gateway (stamped value)	Result
Prod app — env: prod	Prod gateway — tfy_gateway_region: PROD	Allowed
Dev app — env: dev	Prod gateway — tfy_gateway_region: PROD	Blocked

1

Tag each virtual account with its environment

Add a tag to every virtual account: set env: prod on the accounts used by production applications and env: dev on the ones used by dev applications. These tags are injected as metadata on every request made with that account’s token.

2

Stamp each gateway with its environment

Set DEFAULT_GATEWAY_METADATA on each gateway plane so it tags every request that passes through it. On the prod gateway plane’s values file:

tfy-llm-gateway:
  env:
    DEFAULT_GATEWAY_METADATA: '{"tfy_gateway_region":"PROD"}'

On the dev gateway plane’s values file:

tfy-llm-gateway:
  env:
    DEFAULT_GATEWAY_METADATA: '{"tfy_gateway_region":"DEV"}'

3

Create a Metadata Validation guardrail for the production environment

Add a Metadata Validation guardrail (for example gateway-checker) with a single key rule:

• Key Name: env
• Is key required?: on
• Value should be among the ones defined here: on, with Allowed Values: prod

Set the Enforcing Strategy to Enforce so non-matching requests are blocked. This guardrail blocks any request whose env is not prod.

4

Apply it with a rule that matches the production gateway

Create a guardrail rule under AI Gateway → Guardrails → Policies that runs gateway-checker on the LLM Input hook only when the request carries the prod gateway’s stamp. In the rule builder, add a WITH METADATA condition of tfy_gateway_region = PROD, set APPLY ON HOOKS → LLM Input to the gateway-checker guardrail, and optionally set a Custom Error Message such as This gateway can only be accessed from prod env.

The equivalent GitOps configuration is:

name: gateway-env-pinning
type: gateway-guardrails-config
rules:
  - id: prod-gateway-check
    when:
      target:
        operator: or
        conditions:
          metadata:
            tfy_gateway_region: PROD
    llm_input_guardrails:
      - <guardrail-group>/gateway-checker
    llm_output_guardrails: []
    mcp_tool_pre_invoke_guardrails: []
    mcp_tool_post_invoke_guardrails: []
    custom_error_message: "This gateway can only be accessed from prod env"

The rule fires only on requests stamped tfy_gateway_region: PROD — that is, requests reaching the prod gateway — so a dev application (env: dev) calling the prod gateway is rejected, while it is unaffected on the dev gateway.

5

Verify the behavior

Send a request with env: prod in its metadata through the prod gateway — it passes. Send one with any other env value (or none) and it is blocked with your custom error message.

Only the prod gateway is pinned. Production traffic comes from applications using virtual accounts, whose env: prod tag is injected automatically — so requiring it on the prod gateway is safe. The dev gateway is intentionally left open: developers typically access it interactively with Personal Access Tokens (PATs), which do not carry the virtual account’s env tag. Enforcing the same guardrail on the dev gateway would block those legitimate users.

This assumes every production virtual account is tagged with env: prod. With Is key required? on, a request that reaches the prod gateway without that tag is blocked. Tag all production virtual accounts first, and consider starting the guardrail in Audit mode to confirm legitimate traffic passes before switching to Enforce.

Mandate cost-attribution metadata on every request

To guarantee every request can be attributed in analytics and cost reports, require the metadata keys your finance and platform teams group by — for example team and cost_center — so no request reaches a model without them.

1

Create a Metadata Validation guardrail with the required keys

Add a Metadata Validation guardrail (for example cost-attribution) with one rule per key:

• Key Name: team — Is key required?: on (Key must exist)
• Key Name: cost_center — Is key required?: on, Value should be among the ones defined here: on, Regex: ^cc-[0-9]{4}$

Set the Enforcing Strategy to Enforce. Requests missing team, or with a cost_center that does not match the format, are rejected before reaching the model.

2

Apply it to all requests on the LLM Input hook

Add a guardrail rule with an empty when block so it applies to every request:

name: cost-attribution-enforcement
type: gateway-guardrails-config
rules:
  - id: require-cost-attribution
    when: {}
    llm_input_guardrails:
      - <guardrail-group>/cost-attribution
    llm_output_guardrails: []
    mcp_tool_pre_invoke_guardrails: []
    mcp_tool_post_invoke_guardrails: []

Combine this with automatic metadata injection — tag virtual accounts and teams so team and cost_center are added without any client-side changes — and the guardrail simply confirms they are always present.

​

Recommended Hooks

​

Best Practices