Skip to main content

Documentation Index

Fetch the complete documentation index at: https://www.truefoundry.com/llms.txt

Use this file to discover all available pages before exploring further.

This guide explains how to use TrueFoundry’s built-in Metadata Validation guardrail to enforce that requests carry the metadata your organization requires, with the values you expect.

​
What is Metadata Validation?

Metadata Validation is a built-in TrueFoundry guardrail that checks the custom metadata sent with a request against a set of rules you define. It runs directly within the AI Gateway without requiring external API calls, providing fast and cost-effective validation. Metadata is passed to the gateway using the X-TFY-METADATA header (see Log Custom Metadata). This guardrail lets you require that certain keys are always present, constrain their values to a regex pattern or a fixed list, and optionally reject any keys you have not explicitly allowed.
Metadata Validation only runs on the LLM Input hook (beforeRequestHook). When attached to any other hook (LLM Output, MCP Pre Tool, MCP Post Tool), it passes through without performing any checks.

​
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

To add Metadata Validation to your TrueFoundry setup, follow these steps:
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.
Metadata Validation configuration form showing the Allow unknown keys toggle and per-key rules for required keys, regex, and allowed values
5

Save the Configuration

Click Save to add the guardrail to your group.

​
Configuration Options

ParameterDefaultDescription
NameRequiredUnique identifier for this guardrail
OperationvalidateMetadata Validation can only be used for validation
Enforcing Strategyenforce_but_ignore_on_errorenforce, enforce_but_ignore_on_error, or audit
Allow unknown keystrueWhen on, metadata keys not listed in the rules pass through. When off, only listed keys are accepted
KeysNoneThe per-key rules applied to specific metadata fields (see Key Rules below)
See Guardrails Overview for details on Operation Modes and Enforcing Strategy.

​
Key Rules

Each entry under Keys maps a metadata key name to a rule. There are two kinds of rules:

​
Key must exist

Only the presence of the key is checked — any value passes. Once configured, the key must be present in the request metadata.

​
Value must match

Validates the key’s value, with an optional requirement that the key be present:
FieldDefaultDescription
RequiredtrueWhen on, the key must be present. When off, the key is optional, but if present its value must still satisfy the constraint
Value constraintRequiredHow the value is validated — either a regex pattern or a fixed list of allowed values
The value constraint is one of:
ConstraintDescription
RegexThe value must match the provided regular expression
Allowed valuesThe value must exactly match one of the listed values. Comparison is case-sensitive

​
How It Works

When a request reaches the LLM Input hook, the guardrail evaluates the request metadata as follows:
  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

ReasonMeaning
missing_requiredA required key was not present in the request metadata
pattern_mismatchThe key’s value did not match the configured regex pattern
value_not_allowedThe key’s value was not in the configured allowed values list
unknown_keyA metadata key was present that is not declared in the rules (only when Allow unknown keys is off)
invalid_regex_patternThe configured regex pattern itself was invalid

​
Examples

Consider a guardrail with Allow unknown keys turned off and the following key rules:
  • environment — Value must match, allowed values: prod, staging, dev
  • customer_id — Value must match, regex: ^cust_[0-9]+$
  • team — Key must exist
Metadata:
{"environment": "prod", "customer_id": "cust_12345", "team": "billing"}
Result: Allowed — all keys are present and valid, and no unknown keys are sent.
Metadata:
{"environment": "prod", "customer_id": "cust_12345"}
Result: Blocked — team:missing_required (the team key is missing).
Metadata:
{"environment": "production", "customer_id": "cust_12345", "team": "billing"}
Result: Blocked — environment:value_not_allowed (production is not in [prod, staging, dev]).
Metadata:
{"environment": "dev", "customer_id": "12345", "team": "billing"}
Result: Blocked — customer_id:pattern_mismatch (12345 does not match ^cust_[0-9]+$).
Metadata:
{"environment": "dev", "customer_id": "cust_1", "team": "billing", "debug": "true"}
Result: Blocked — debug:unknown_key (the debug key is not declared and unknown keys are not allowed).

​
Sending Metadata

Metadata is sent using the X-TFY-METADATA header as a JSON object of string key-value pairs: 
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"}
    ]
  }'
See Log Custom Metadata for how to attach metadata using the OpenAI, LangChain, and Node.js SDKs.

​
Use Cases

ScenarioConfiguration
Mandatory cost-attribution tagsRequire keys like team or customer_id so every request can be attributed in analytics
Restrict environment valuesConstrain environment to an allowed list (prod, staging, dev) to prevent typos and unexpected values
Enforce ID formatsUse a regex to ensure identifiers such as customer_id follow your organization’s format
Lock down metadataTurn off Allow unknown keys to reject any metadata field that is not explicitly approved
HookUse Case
LLM InputValidate request metadata before the request is processed
Metadata Validation runs only on the LLM Input hook. Attaching it to other hooks has no effect.

​
Best Practices

Start with the Audit enforcing strategy to observe metadata violations in Request Traces before switching to Enforce. This helps you confirm that callers are already sending the metadata your rules expect.
All metadata values are compared as strings, and allowed-value matching is case-sensitive. Make sure your allowed values and regex patterns account for the exact casing and format your applications send.