Skip to main content

Declarative Config Reference

Use this reference to write, review, and validate policy-config.yaml. It shows the supported declarative config.

Declarative resources control their runtime tags​

Verdictan uses the config document as the authoritative source for declarative resource metadata. In the console, you can directly edit tags only for manual resources. For declarative resources, change tags through the config draft and apply workflow.

Use these rules:

  • For a manual resource, edit the tags directly.
  • For a declarative resource, update the draft. Review and apply the draft.

Workflow map​

Validate and start the gateway​

Lint the config​

verdictan policy lint --file policy-config.yaml

Start the gateway with a policy config​

export VERDICTAN_API_TOKEN="vdt_your_gateway_runtime_token"
export VERDICTAN_OPENAI_API_KEY="sk-..."

verdictan gateway run \
  --agent docs-reference \
  --listen 127.0.0.1:41002 \
  --policy-config policy-config.yaml \
  --fail-mode block

For one experiment, you can pass --upstream flags on the CLI. For long-term configs, keep provider targets in YAML. Then, the document works for local runs, connected gateways, and console configuration workflows.

Verify the running config​

curl http://127.0.0.1:41002/verdictan/config | jq .

What the config is for​

The declarative config is the authoritative document for local gateway behavior. Use it to do these tasks:

  • Define the policy chain.
  • Declare provider targets and provider data-handling metadata.
  • Declare agents for agent-scoped context fabric and MCP configuration.
  • Tune behavior for each policy type.
  • Validate changes before starting the gateway.
  • Apply a known local config to a connected gateway from Configurations.
  • Verify the running state in Gateways.
  • Verify representative request results with verdictan events tail or GET /v1/events and the necessary since value.
  • Use History only for captured session context when history capture is enabled.

Deep-dive index​

This reference shows the top-level shape. Use these guides for sections that have many fields:

Strict validation rules​

Verdictan uses the config as a strict contract.

  • Unknown top-level keys are rejected.
  • Unknown policy types are rejected.
  • Unknown keys in a supported policy block are rejected.
  • Validation occurs after YAML is parsed into an object model.

Do not add metadata unless the schema supports it.

Supported document shapes​

There are two supported shapes.

1. Config document​

This is the usual production and template shape.

pack:
  name: demo-pack
  version: 1.0.0
  enabled: true
  description: Demo config

policies:
  chain:
    - audit-logger
    - pii-detector

policy:
  audit-logger: {}
  pii-detector:
    action: redact

Necessary top-level objects:

  • pack
  • policies

Frequent optional top-level sections:

  • policy
  • providers
  • agents
  • routes and consumer_groups
  • global_rate_limit, ip_rate_limit, user_rate_limit, and token_rate_limit
  • distributed_rate_limit, size_limits, ip_allowlist, and cors
  • history, moderation, auto, models, and cache
  • testing, callbacks, tool_servers, and mcp_server

The configuration also supports the documented context, AI usage, region, and silent-engine sections. Use the linked guides and request-type reference for their active runtime limits.

2. Single-policy document​

This shape is only supported for four policy types:

  • prompt-injection
  • agent-firewall
  • citation-verifier
  • quality-scorer

Example:

policy:
  name: prompt-injection
  version: 1.0.0
  enabled: true

detection:
  embedding_threshold: 0.8

encoding:
  decode_base64: true
  normalize_unicode: true

boundaries:
  enforce_delimiters: true

response:
  action: block

Config document structure​

pack​

Necessary fields:

  • name: non-empty string.
  • version: SemVer string.
  • enabled: boolean.

Optional field:

  • description: string.
  • tags: string map.

When enabled is false, the gateway excludes the pack. It does not load the pack's chains, routes, providers, callbacks, tests, or side effects.

policies​

Necessary field:

  • chain: non-empty array of supported policy types or conditional chain entries.

Execution rules:

  • Policies execute in the chain sequence.
  • Conditional chain entries can attach when, stage, parallel, and targeting metadata to a policy type.
  • If chain contains a policy type without policy.<kind>, the gateway uses the runtime defaults.
  • If policy.<kind> is available but chain does not contain the type, validation succeeds. The policy does not run.

policy​

This optional object holds the per-policy configuration blocks.

providers​

This optional object defines provider targets and their routing behavior.

Shared sub-objects:

  • targets: one or more provider targets.
  • routing: ordered or latency-based selection strategy.
  • model_groups: virtual model aliases that map to ordered target lists.
  • pipelines: virtual model aliases that control multiple provider targets in sequence or fan_out mode.

Use providers.routing.allow_fallbacks: false to stop after the first eligible target.

Each target can declare data_policy metadata. This metadata records retention, training, and routing terms from your provider contract:

pack:
  name: declarative-config-reference-providers-3
  version: 1.0.0
  enabled: true
providers:
  targets:
    - id: openai-zdr
      provider: openai
      model: your-openai-model
      base_url: https://api.openai.com
      secret_key_ref:
        env: VERDICTAN_OPENAI_API_KEY
      data_policy:
        zero_data_retention: true
        training_opt_out: true
        retention_days: 0
policies:
  chain:
    - audit-logger
policy:
  audit-logger: {}

The operator declares this metadata. data-routing-policy uses it to allow or exclude targets before the fallback loop starts.

agents​

This optional array declares agents for context fabric and MCP configuration. Each entry must have id and team. The only optional fields are context_fabric and mcp.

pack:
  name: agent-declaration-example
  version: 1.0.0
  enabled: true
agents:
  - id: support-agent
    team: customer-success
policies:
  chain:
    - audit-logger
policy:
  audit-logger: {}

Do not add usage_constraints to this array. It is not part of GatewayAgentDeclaration. The verdictan policy lint command rejects it. The API stores and controls agent usage constraints.

Agent usage constraints are not declarative gateway configuration fields. Manage them with the control-plane API:

  • To list or create a constraint, use GET or POST /v1/agents/{id}/usage-constraints.
  • To update or delete a constraint, use PUT or DELETE /v1/agents/{id}/usage-constraints/{constraint_id}.

auto​

The auto virtual provider accepts enabled, name, description, and a routing block. The active routing fields are:

  • cost_weight
  • latency_weight
  • max_price_per_1m_tokens

Set enabled explicitly because the runtime default is true and the active schema material shows a different default. If the price limit excludes all targets, the request fails with no_eligible_provider. Automatic selection pins the request to one target and does not try a different provider after a failure.

Supported declarative policy types​

The schema accepts these policy types in policy.<kind> blocks. Most types can also occur in policies.chain for runtime enforcement. The eu-ai-act type is reporting-only. Configure it in policy.eu-ai-act for POST /verdictan/compliance/report. Do not put it in policies.chain. The runtime rejection cause is policy.reporting_only.

Types accepted in schema policy.<kind> blocks:

  • agent-firewall
  • audit-logger
  • bias-monitor
  • bot-detector
  • case-privacy
  • citation-verifier
  • cjis-mode
  • code-sanitizer
  • content-extractor
  • data-routing-policy
  • dlp-filter
  • document-analyzer
  • dual-use-filter
  • embedding-detector
  • entity-list-filter
  • eu-ai-act
  • external-moderation
  • financial-compliance
  • flagged-review
  • gdpr-compliance
  • healthcare-compliance
  • hipaa-phi-detector
  • human-oversight
  • itar-ear-filter
  • language-validator
  • legal-privilege
  • mnpi-filter
  • pii-detector
  • prompt-injection
  • quality-scorer
  • rbac
  • regulated-execution
  • request-rewriter
  • response-rewriter
  • safety-filter
  • student-privacy
  • tool-budget
  • tool-security
  • tool-validation
  • upl-filter

Policy field reference​

Access, tool, and runtime governance​

agent-firewall​

Supported shapes:

  • Simple form with allowed_tools, blocked_tools, and max_actions_per_session.
  • Expanded form with role-based tool rules, rate limits, transaction limits, and supported kill-switch checks.

Supported fields:

  • allowed_tools: string array.
  • blocked_tools: string array.
  • max_actions_per_session: integer.
  • tools.roles.<role>.allowed: non-empty string array.
  • tools.roles.<role>.denied: string array.
  • rate_limits.<tool_or_default>: integer.
  • transaction_limits.max_single_transaction: number.
  • transaction_limits.max_daily_total: number.
  • transaction_limits.require_approval_above: number.
  • kill_switches.halt_on_pii_in_action: boolean.
  • kill_switches.halt_on_suspicious_pattern: boolean.

The role comes from the authenticated policy identity. Do not use a raw role header as the authority for role-based rules.

rbac​

Supported fields:

  • deny_if_missing: string array.
  • require_auth: boolean.
  • roles.<role>.allowed_tools: string array.
  • roles.<role>.denied_tools: string array.
  • data_access.<scope>.max_sensitivity: public | internal | confidential | restricted.
  • minimum_necessary.enabled: boolean.
  • minimum_necessary.allowed_phi_roles: string array.

Set require_auth: true explicitly. Roles come from resolved identity claims. deny_if_missing checks only the presence of the specified request headers.

cjis-mode​

Supported fields:

  • require_auth: boolean.
  • access_logging: boolean.
  • session_timeout_minutes: integer from 1 through 1440.
  • required_assurance: multi_factor | phishing_resistant.

Runtime note: CJIS mode must have a verified subject, organization, correct proof, active session, and MFA assurance. The session age must not exceed session_timeout_minutes. Caller-supplied identity headers do not give access.

audit-logger​

Public-safe shape:

  • audit-logger: {}

Active behavior:

  • The policy uses audit-logger as an allow-only marker in the chain.
  • Configure retention, immutability, and storage through their owning platform workflows.

data-routing-policy​

Use this control to limit upstream providers. The declared data properties set which providers can receive traffic.

Supported fields:

  • require_zero_data_retention: boolean.
  • require_no_training: boolean.
  • max_retention_days: integer.
  • on_no_compliant_provider: block | warn.
  • log_provider_selection: boolean.
  • require_in_memory_only: boolean.
  • sanitize_before_provider: boolean.
  • tokenize_sensitive_fields: boolean.
  • allow_internet_egress: boolean.
  • local_only_processing: boolean.

Runtime behavior:

  • Runs before provider fallback selection.
  • Excludes targets that do not satisfy the declared requirements.
  • Returns HTTP 403 if no providers are available and on_no_compliant_provider is block.
  • Uses the full target list if no providers are available and on_no_compliant_provider is warn.
  • Uses customer-declared provider metadata. It does not verify provider terms.
  • Records sanitize_before_provider as a routing requirement. It does not sanitize request data.

Validation and lint checks identify these frequent errors:

  • data-routing-policy without providers.targets
  • contradictory target metadata when zero_data_retention: true
  • configurations where each provider can be excluded at runtime

regulated-execution​

Supported policy-block fields:

  • tokenize_sensitive_fields: boolean.
  • require_in_memory_only: boolean.

This request-stage policy records classification details and returns allow with regulated-execution.classification_gate. These two fields are recorded in the result. The policy block does not tokenize the request or enforce an in-memory provider by itself.

Privacy, safety, and content filters​

prompt-injection​

Supported fields:

  • embedding_threshold: number.
  • backend: local | external.
  • endpoint: non-empty string.
  • model: non-empty string.
  • api_key: non-empty string.
  • timeout_ms: integer from 1 through 60000.
  • attack_patterns: string array.
  • encoding.decode_base64: boolean.
  • encoding.normalize_unicode: boolean.
  • encoding.detect_homoglyphs: boolean.
  • boundaries.enforce_delimiters: boolean.
  • boundaries.reject_fake_boundaries: boolean.
  • response.action: block.
  • data_poisoning.enabled: boolean.
  • data_poisoning.backdoor_trigger_patterns: string array.
  • data_poisoning.perplexity_threshold: non-negative number.
  • data_poisoning.anomaly_action: block | warn | audit.

Runtime note: the detector uses encoding, boundary, attack pattern, embedding, and data poisoning fields. For data poisoning, only anomaly_action: block changes the verdict. The warn and audit values allow the request. They put the signal in the policy details.

pii-detector​

Supported fields:

  • action: redact | block.
  • healthcare_mode: boolean.
  • pci_mode: boolean.
  • detect_patterns: string array.
  • redaction.marker_format: label | asterisk | partial.
  • redaction.include_metadata: boolean.
  • redaction.preserve_length: boolean.
  • redaction.custom_markers.<entity>: string map.

hipaa-phi-detector​

Supported fields:

  • action: redact | block.

dlp-filter​

Supported fields:

  • detect_patterns: string array.
  • blocked_terms: string array.
  • action: redact | block.
  • fuzzy_matching: boolean.
  • max_distance: integer.
  • sensitivity_level: standard | high | restricted.

document-analyzer​

Supported fields:

  • enabled: boolean.
  • sanitize_code: boolean.
  • max_document_bytes: integer.
  • allowed_mime_types: string array.

dual-use-filter​

Supported fields:

  • blocked_terms: string array.
  • action: block | redact.
  • fuzzy_matching: boolean.
  • max_distance: integer.

embedding-detector​

Supported fields:

  • backend: local | external.
  • endpoint: string.
  • model: string.
  • api_key: string.
  • similarity_threshold: number.
  • timeout_ms: integer.
  • action: redact | block.
  • categories[].label: string.
  • categories[].reference_text: string.

entity-list-filter​

Supported fields:

  • blocked_entities: string array.
  • fuzzy_matching: boolean.
  • max_distance: integer.

The policy always blocks on a match. There is no configurable action variant.

external-moderation​

Supported fields:

  • provider: openai-moderation | azure-content-safety | bedrock-apply-guardrail | embedding-endpoint | presidio | guardrails-ai | dynamo-ai | lakera.
  • secret_key_ref.env: string.
  • endpoint: string.
  • categories: string array.
  • threshold: number.
  • timeout_ms: integer.
  • fail_closed: boolean.
  • aws_region: string.
  • aws_access_key_env: string.
  • aws_secret_key_env: string.
  • aws_session_token_env: string.
  • guardrail_id: string.
  • guardrail_version: string.
  • embedding_model: string.
  • reference_texts: string array.
  • presidio_language: string.
  • presidio_entities: string array.
  • guard_name: string.
  • policy_id: string.
  • lakera_categories: string array.

Set provider and fail_closed: true explicitly. The runtime default provider is openai-moderation, and all provider or configuration failures block. The active runtime does not support a webhook provider.

itar-ear-filter​

Supported fields:

  • blocked_terms: string array.
  • action: block.
  • fuzzy_matching: boolean.
  • max_distance: integer from 0 through 8.

safety-filter​

Supported fields:

  • mode: critical_infrastructure | automotive | education | law_enforcement | government | military | hr | justice | healthcare | finance | legal | defense.
  • block_if: string array.
  • action: block | escalate.
  • fuzzy_matching: boolean.
  • max_distance: integer from 0 through 8.
  • max_age: non-negative integer.

The gateway has different built-in term sets for critical_infrastructure, automotive, education, and law_enforcement. Other accepted modes use the general critical-term set. The block_if field can add domain terms.

student-privacy​

Supported fields:

  • action: redact | block.
  • age_gate: boolean.

case-privacy​

Supported fields:

  • action: redact.

language-validator​

Supported fields:

  • allowed_languages: string array.
  • action: block | warn.
  • apply_to: input | output | both.

Set apply_to: input explicitly. The runtime default is input. The output value skips input checks, and both checks input only. Streaming requests with output or both are rejected with streaming.policy_cannot_enforce.

Domain-specific output and compliance controls​

citation-verifier​

Supported fields:

  • require_sources: boolean.

  • require_source_match: boolean.

  • min_confidence: number.

  • min_groundedness: number.

  • extract_patterns: array of case_law | academic | url | quote | statistic.

  • rag_context.verify_against_context: boolean.

  • rag_context.min_context_overlap: number.

  • output_action.unverified_action: flag | redact | block.

  • response.include_verification_report: boolean.

  • block is the only unverified action that changes the verdict. The flag and redact actions keep the allow verdict. They show verification details. The redact action does not change the response.

quality-scorer​

Core tuning fields:

  • min_output_chars: integer.
  • min_sentences: integer.

Benchmark fields:

  • benchmarks.ragas_faithfulness: boolean.
  • benchmarks.ragas_relevancy: boolean.
  • benchmarks.bleu_score: boolean.
  • benchmarks.nli_entailment: boolean.
  • benchmarks.coherence: boolean.
  • benchmarks.completeness: boolean.

Assertion support:

  • assertions[] supports output, context, conversational, and trajectory-based assertion types.
  • Each assertion must have type.
  • Assertions can also include name, enabled, threshold, weight, and config.

Supported assertion categories:

  • Output-based types:

    • assert-set, search-rubric, model-graded-closedqa, model-graded-fact, factuality, g-eval, llm-rubric, and answer-relevance
    • contains, contains-all, contains-any, contains-json, contains-html, contains-sql, contains-xml, and cost
    • equals, f-score, finish-reason, icontains, icontains-all, icontains-any, is-html, and is-json
    • is-refusal, is-sql, is-valid-function-call, is-valid-openai-function-call, is-valid-openai-tools-call, and is-xml
    • javascript, latency, levenshtein, perplexity-score, perplexity, pi, python, and regex
    • rouge-n, similar, classifier, moderation, select-best, starts-with, and tool-call-f1
    • trace-span-count, trace-span-duration, trace-error-spans, word-count, and max-score

  • Context-based: context-recall, context-relevance, context-faithfulness.

  • Conversational: conversation-relevance.

  • Trajectory-based: trajectory:goal-success, trajectory:tool-used, trajectory:tool-sequence, trajectory:step-count.

Threshold and weighting fields:

  • thresholds.min_aggregate
  • thresholds.min_faithfulness
  • thresholds.min_relevancy
  • thresholds.min_bleu
  • thresholds.min_coherence
  • thresholds.min_completeness
  • thresholds.min_accuracy
  • weights.faithfulness
  • weights.relevancy
  • weights.bleu
  • weights.coherence
  • weights.completeness
  • weights.accuracy

Industry profile and failure behavior fields:

  • industry_profiles.<profile>.min_aggregate
  • industry_profiles.<profile>.min_accuracy
  • industry_profiles.<profile>.min_faithfulness
  • industry_profiles.<profile>.min_relevancy
  • industry_profiles.<profile>.min_coherence
  • industry_profiles.<profile>.min_completeness
  • failure_action.action: block | fallback.
  • failure_action.fallback_message: string.
  • pass_policy: assertion aggregation object.
  • judge: optional secondary judge configuration.

failure_action.action: fallback uses fallback_message and allows the replacement response.

human-oversight​

Supported fields:

  • action: escalate.

Runtime note: action: escalate escalates each response that this policy evaluates.

bias-monitor​

Supported fields:

  • threshold: number.

Runtime note: the evaluator uses threshold with its built-in HR heuristic for protected data types. A match always causes escalate.

mnpi-filter​

Supported fields:

  • detect_patterns: string array.
  • action: block.

financial-compliance​

Supported fields:

  • blocked_patterns: string array.
  • required_disclaimers: string array.

healthcare-compliance​

Supported fields:

  • blocked_patterns: string array.
  • required_disclaimers: string array.
  • fda_class: I | II | III.

Supported fields:

  • privilege_markers: string array.
  • action: block.

upl-filter​

Supported fields:

  • blocked_patterns: string array.
  • require_disclaimer: boolean.
  • rewrite_to_educational: boolean.

Single-policy top-level sections​

If you use the single-policy shape, the policy type sets the allowed top-level sections.

  • prompt-injection: detection, encoding, boundaries, response.
  • agent-firewall: Use the simple fields (allowed_tools, blocked_tools, and optional max_actions_per_session). Alternatively, use the expanded sections (tools, rate_limits, transaction_limits, and kill_switches).
  • citation-verifier: verification, rag_context, output_action, response.
  • quality-scorer: benchmarks, assertions, thresholds, weights, industry_profiles, failure_action.

All other top-level sections are rejected.

Frequent validation failures​

  • Missing pack or policies in a config document.
  • Empty policies.chain.
  • Unsupported policy type in chain.
  • A single-policy structure for a type that supports only the config document shape.
  • Config metadata that the schema does not recognize.
  1. Start from a template or a known-good policy-config.yaml.
  2. Put each policy in the policies.chain execution sequence.
  3. Add only the policy blocks that must override defaults.
  4. Validate before runtime with verdictan policy lint --file policy-config.yaml.
  5. Run the gateway with the same file.
  6. Send representative traffic.
  7. Save the request IDs.
  8. Verify the running state in Gateways.
  9. Verify the Events with verdictan events tail or the Events API.
  10. Examine Inbox for related human review work.
  11. Use History only when capture is enabled and stored session context is necessary for the investigation.

Next steps​