Enrichment Extension Catalog

Source of truth for every x-* extension that appears in docs/specifications/api/*.json. Parity with scripts/utils/extension_constants.py is enforced by tests/test_extension_catalog.py.

Three classes of extensions are documented here:

• Injected here — extensions our enrichers add (x-f5xc-* and x-ves-cli-* / x-ves-field-* / x-ves-operation-* / discovery variants). These are the ones downstream tools should consume.
• Upstream pass-through — extensions F5 emits in the source specs and we preserve unchanged (x-ves-proto-*, x-displayname, etc.). Documented for transparency but not controlled by this repo.
• Future-injected — not yet emitted; documented here the moment an enricher begins to produce them (not applicable at the initial population).

Entry schema

Every entry below has exactly this shape. The parity test in tests/test_extension_catalog.py tolerates the section body being stubby as long as the ### x-name header exists and the Pass-through from upstream: flag is present with value yes or no.

### x-<name>
- **Applied at:** <schema | parameter | operation | path-item | info | response>
- **Purpose:** <one sentence>
- **Consumers:** <CLI | VSCode | Terraform | Web UI | multiple | N/A>
- **Value type:** <string | number | boolean | object | array>
- **Value schema:** <JSON Schema snippet, or N/A>
- **Injected by:** <scripts/utils/<enricher>.py, or "upstream">
- **Driven by config:** <config/<file>.yaml, or "hardcoded", or "upstream">
- **Example:** <short snippet>
- **Pass-through from upstream:** <yes/no>

Injected — spec-level (info section)

x-f5xc-network-allowlist

• Applied at: info (canonical openapi.json only)
• Purpose: Complete F5 network address and domain inventory for firewall and proxy allowlisting. The reference page supplies port, direction, and site-specific rules; this inventory alone is not a firewall rule set.
• Consumers: multiple
• Value type: object
• Value schema: {"source_url": "HTTPS URL", "sha256": "lowercase SHA-256 of sorted-key compact UTF-8 manifest JSON", "manifest": "validated F5 JSON object"}
• Injected by: scripts/network_allowlist.py
• Driven by config: hardcoded F5 feed URL
• Example: "x-f5xc-network-allowlist": {"source_url": "https://docs.cloud.f5.com/docs-v2/downloads/platform/reference/network-cloud-ref/ips-domains.json", "sha256": "...", "manifest": {"manifest_type": "firewall_proxy_allowlist", "services": {}, "customer_edge": {}}}
• Pass-through from upstream: no

x-f5xc-cli-domain

• Applied at: info
• Purpose: Identifies the CLI domain slug (e.g. http_loadbalancer) for an enriched spec.
• Consumers: CLI
• Value type: string
• Value schema: {"type": "string"}
• Injected by: scripts/merge_specs.py
• Driven by config: hardcoded
• Example: "x-f5xc-cli-domain": "http_loadbalancer"
• Pass-through from upstream: no

x-f5xc-cli-metadata

• Applied at: info
• Purpose: CLI-wide metadata block (tool name, version hints, domain grouping).
• Consumers: CLI
• Value type: object
• Value schema: {"type": "object"}
• Injected by: scripts/merge_specs.py
• Driven by config: config/cli_metadata.yaml
• Example: "x-f5xc-cli-metadata": {"tool": "xcsh", "domain": "http_loadbalancer"}
• Pass-through from upstream: no

x-f5xc-upstream-timestamp

• Applied at: info
• Purpose: Timestamp of the upstream source spec the enriched file was built from.
• Consumers: multiple
• Value type: string
• Value schema: {"type": "string", "format": "date-time"}
• Injected by: scripts/merge_specs.py
• Driven by config: hardcoded
• Example: "x-f5xc-upstream-timestamp": "2026-04-21T12:00:00Z"
• Pass-through from upstream: no

x-f5xc-upstream-etag

• Applied at: info
• Purpose: ETag of the upstream source spec release asset.
• Consumers: multiple
• Value type: string
• Value schema: {"type": "string"}
• Injected by: scripts/merge_specs.py
• Driven by config: hardcoded
• Example: "x-f5xc-upstream-etag": "\"abc123\""
• Pass-through from upstream: no

x-f5xc-enriched-version

• Applied at: info
• Purpose: Semantic version stamped on the enriched spec by the pipeline.
• Consumers: multiple
• Value type: string
• Value schema: {"type": "string"}
• Injected by: scripts/merge_specs.py
• Driven by config: hardcoded
• Example: "x-f5xc-enriched-version": "3.2.1"
• Pass-through from upstream: no

x-f5xc-glossary

• Applied at: info
• Purpose: Branding/terminology glossary block applied to each domain spec.
• Consumers: multiple
• Value type: object
• Value schema: {"type": "object"}
• Injected by: scripts/utils/branding.py
• Driven by config: config/branding.yaml
• Example: "x-f5xc-glossary": {"XC": "F5 Distributed Cloud"}
• Pass-through from upstream: no

x-f5xc-discovered-at

• Applied at: info
• Purpose: Timestamp when the live-API discovery pass was executed.
• Consumers: multiple
• Value type: string
• Value schema: {"type": "string", "format": "date-time"}
• Injected by: scripts/utils/discovery_enricher.py
• Driven by config: config/discovery.yaml
• Example: "x-f5xc-discovered-at": "2026-04-21T09:15:00Z"
• Pass-through from upstream: no

x-f5xc-api-url

• Applied at: info
• Purpose: Base URL of the live API that was probed during discovery.
• Consumers: multiple
• Value type: string
• Value schema: {"type": "string", "format": "uri"}
• Injected by: scripts/utils/discovery_enricher.py
• Driven by config: config/discovery.yaml
• Example: "x-f5xc-api-url": "https://f5-amer-ent.console.ves.volterra.io"
• Pass-through from upstream: no

x-f5xc-api-reference-url

• Applied at: info
• Purpose: URL to the hosted API reference documentation page for this domain.
• Consumers: multiple
• Value type: string
• Value schema: {"type": "string", "format": "uri"}
• Injected by: scripts/utils/external_docs_enricher.py
• Driven by config: none (derived from domain name)
• Example: "x-f5xc-api-reference-url": "https://f5-sales-demo.github.io/api-specs-enriched/api-reference/sites/"
• Pass-through from upstream: no

x-f5xc-response-time-ms

• Applied at: info
• Purpose: Observed response time (ms) for the probed API during discovery.
• Consumers: multiple
• Value type: number
• Value schema: {"type": "number"}
• Injected by: scripts/utils/discovery_enricher.py
• Driven by config: config/discovery.yaml
• Example: "x-f5xc-response-time-ms": 42
• Pass-through from upstream: no

x-f5xc-summary

• Applied at: info
• Purpose: Concise domain summary for CLI banners and tooltips.
• Consumers: CLI, IDE, documentation
• Value type: string
• Value schema: {"type": "string", "maxLength": 150}
• Injected by: scripts/utils/description_enricher.py
• Driven by config: config/domain_descriptions.yaml
• Example: "x-f5xc-summary": "Application delivery and security APIs."
• Pass-through from upstream: no

x-f5xc-best-practices

• Applied at: info
• Purpose: Curated best-practice guidance for a domain.
• Consumers: multiple
• Value type: array
• Value schema: {"type": "array", "items": {"type": "object"}}
• Injected by: scripts/utils/best_practices_enricher.py
• Driven by config: config/best_practices.yaml
• Example: "x-f5xc-best-practices": [{"id": "bp-1", "text": "Prefer HTTPS"}]
• Pass-through from upstream: no

x-f5xc-guided-workflows

• Applied at: info
• Purpose: Named step-by-step workflows to accomplish common tasks in a domain.
• Consumers: multiple
• Value type: array
• Value schema: {"type": "array", "items": {"type": "object"}}
• Injected by: scripts/utils/guided_workflow_enricher.py
• Driven by config: config/guided_workflows.yaml
• Example: "x-f5xc-guided-workflows": [{"name": "create-lb", "steps": [...]}]
• Pass-through from upstream: no

x-f5xc-acronyms

• Applied at: info
• Purpose: Per-domain acronym expansion table.
• Consumers: multiple
• Value type: object
• Value schema: {"type": "object", "additionalProperties": {"type": "string"}}
• Injected by: scripts/utils/acronym_enricher.py
• Driven by config: config/acronyms.yaml
• Example: "x-f5xc-acronyms": {"LB": "Load Balancer"}
• Pass-through from upstream: no

x-f5xc-console-navigation

• Applied at: spec info
• Purpose: Global console navigation tree — workspace and menu hierarchy.
• Consumers: console-catalog, xcsh, browser-automation
• Value type: object
• Value schema: {"type": "object", "properties": {"workspaces": "object"}}
• Injected by: scripts/utils/console_ui_enricher.py
• Driven by config: config/console_ui.yaml
• Example: "x-f5xc-console-navigation": {"workspaces": {"web-app-and-api-protection": {"label": "Web App & API Protection", "route_prefix": "/web/workspaces/web-app-and-api-protection"}}}
• Pass-through from upstream: no

Injected — schema-level (component schemas)

x-f5xc-minimum-configuration

• Applied at: schema
• Purpose: Minimum viable field set required to successfully POST/PUT this resource.
• Consumers: multiple
• Value type: object
• Value schema: {"type": "object"}
• Injected by: scripts/utils/minimum_configuration_enricher.py
• Driven by config: config/minimum_configs.yaml
• Example: "x-f5xc-minimum-configuration": {"required_fields": ["name"]}
• Pass-through from upstream: no

x-f5xc-namespace-profile

• Applied at: info
• Purpose: Provides namespace constraint, recommendation, and classification metadata for a resource.
• Consumers: multiple
• Value type: object
• Value schema: {"type": "object", "properties": {"constraint": {"type": "object"}, "recommendation": {"type": "object"}, "classification": {"type": "object"}}}
• Injected by: scripts/utils/namespace_profile_enricher.py
• Driven by config: config/namespace_profile.yaml
• Example: "x-f5xc-namespace-profile": {"constraint": {"allowed": ["system", "shared", "user"]}, "recommendation": {"default": "shared"}, "classification": {"multi_tenant_pattern": "shared-ref"}}
• Pass-through from upstream: no

x-f5xc-displayorder

• Applied at: schema
• Purpose: Suggested ordering of properties for UI/CLI presentation.
• Consumers: multiple
• Value type: array
• Value schema: {"type": "array", "items": {"type": "string"}}
• Injected by: scripts/utils/field_metadata_enricher.py
• Driven by config: config/field_metadata.yaml
• Example: "x-f5xc-displayorder": ["name", "description", "spec"]
• Pass-through from upstream: no

x-f5xc-terraform-resource

• Applied at: schema
• Purpose: Terraform resource type name that maps to this schema.
• Consumers: Terraform
• Value type: string
• Value schema: {"type": "string"}
• Injected by: scripts/utils/field_metadata_enricher.py
• Driven by config: config/field_metadata.yaml
• Example: "x-f5xc-terraform-resource": "volterra_http_loadbalancer"
• Pass-through from upstream: no

x-f5xc-display-name

• Applied at: schema
• Purpose: Human-readable display name for a resource schema (overrides auto-generation).
• Consumers: multiple
• Value type: string
• Value schema: {"type": "string"}
• Injected by: scripts/utils/field_metadata_enricher.py
• Driven by config: config/field_metadata.yaml
• Example: "x-f5xc-display-name": "HTTP Load Balancer"
• Pass-through from upstream: no

x-f5xc-console

• Applied at: schema
• Purpose: Console UI navigation, routing, and form structure for this resource.
• Consumers: console-catalog, xcsh, vscode-xcsh, browser-automation
• Value type: object
• Value schema: {"type": "object", "properties": {"workspace": "string", "menu_path": "array", "route_pattern": "string", "breadcrumbs": "array", "add_action": "object", "form_sections": "array", "metadata": "object"}}
• Injected by: scripts/utils/console_ui_enricher.py
• Driven by config: config/console_ui.yaml
• Example: "x-f5xc-console": {"workspace": "web-app-and-api-protection", "menu_path": ["Manage", "Load Balancers", "HTTP Load Balancers"]}
• Pass-through from upstream: no

x-f5xc-action

• Applied at: schema
• Purpose: Marks a schema whose operation is an action-style resource, e.g. approve, so codegen emits an action resource rather than CRUD.
• Consumers: Terraform
• Value type: string
• Value schema: {"type": "string"}
• Injected by: scripts/utils/schema_override_enricher.py
• Driven by config: config/schema_overrides.yaml
• Example: "x-f5xc-action": "approve"
• Pass-through from upstream: no

x-f5xc-upstream-defect

• Applied at: schema
• Purpose: Documents an upstream contract defect that required a local compatibility stub.
• Consumers: pipeline, documentation, SDK generators
• Value type: string
• Value schema: {"type": "string"}
• Injected by: reviewed generated-source repair
• Driven by config: upstream defect evidence linked in the value
• Example: "x-f5xc-upstream-defect": "Stub for a referenced schema missing upstream."
• Pass-through from upstream: yes

x-f5xc-ce-automation-contract

• Applied at: schema
• Purpose: Checksum-bound Secure Mesh Site v2 automation contract. It identifies the real collection and item paths, the required system namespace, and provider support evidence.
• Consumers: Terraform, CLI, MCP, IDE, documentation
• Value type: object
• Value schema: {"type":"object","required":["version","contract_id","resource","api","providers"]}
• Injected by: scripts/utils/interface_contract_enricher.py
• Driven by config: config/interface_contracts.yaml
• Example: "x-f5xc-ce-automation-contract":{"contract_id":"f5xc-ce-automation/v1","providers":{"aws":{"availability":"schema_only"}}}
• Pass-through from upstream: no

Injected — property-level

x-f5xc-concurrency-token

• Applied at: schema property
• Purpose: Marks server-assigned optimistic-concurrency state that clients retain from a read and echo only on declared write operations.
• Consumers: Terraform, CLI, MCP, IDE
• Value type: object
• Value schema: {"type":"object","required":["server_assigned","echo_on_operations"]}
• Injected by: scripts/utils/schema_override_enricher.py
• Driven by config: config/schema_overrides.yaml
• Example: "x-f5xc-concurrency-token":{"server_assigned":true,"echo_on_operations":["replace"]}
• Pass-through from upstream: no

x-f5xc-sensitive

• Applied at: schema property
• Purpose: Marks credentials, secrets, and signed URLs that consumers must redact.
• Consumers: Terraform, CLI, MCP, IDE
• Value type: boolean
• Value schema: {"type": "boolean"}
• Injected by: scripts/utils/schema_override_enricher.py
• Driven by config: config/schema_overrides.yaml
• Example: "x-f5xc-sensitive": true
• Pass-through from upstream: no

x-f5xc-description

• Applied at: schema property
• Purpose: Enriched property description that supplements the upstream description.
• Consumers: multiple
• Value type: string
• Value schema: {"type": "string"}
• Injected by: scripts/utils/field_metadata_enricher.py
• Driven by config: config/field_descriptions.yaml
• Example: "x-f5xc-description": "Fully-qualified domain name used for TLS SNI."
• Pass-through from upstream: no

x-f5xc-validation

• Applied at: schema property
• Purpose: Declarative validation rules derived from upstream protobuf ves.io.schema.rules.
• Consumers: multiple
• Value type: object
• Value schema: {"type": "object"}
• Injected by: scripts/utils/validation_enricher.py
• Driven by config: config/validation_rules.yaml
• Example: "x-f5xc-validation": {"min_len": 1, "max_len": 64}
• Pass-through from upstream: no

x-f5xc-examples

• Applied at: schema property
• Purpose: Multiple illustrative example values for a property.
• Consumers: multiple
• Value type: array
• Value schema: {"type": "array"}
• Injected by: scripts/utils/resource_examples_enricher.py
• Driven by config: config/resource_examples.yaml
• Example: "x-f5xc-examples": ["example.com", "api.example.com"]
• Pass-through from upstream: no

x-f5xc-example

• Applied at: schema property
• Purpose: A single canonical example value.
• Consumers: multiple
• Value type: string
• Value schema: {}
• Injected by: scripts/utils/field_description_enricher.py
• Driven by config: config/field_descriptions.yaml
• Example: "x-f5xc-example": "example.com"
• Pass-through from upstream: no

x-f5xc-completion

• Applied at: schema property
• Purpose: Shell completion hints (static enum or dynamic command).
• Consumers: CLI
• Value type: object
• Value schema: {"type": "object"}
• Injected by: scripts/utils/field_metadata_enricher.py
• Driven by config: config/field_metadata.yaml
• Example: "x-f5xc-completion": {"source": "command", "cmd": "xcsh namespace list"}
• Pass-through from upstream: no

x-f5xc-defaults

• Applied at: schema property
• Purpose: Default value(s) to surface in generated docs and UIs.
• Consumers: multiple
• Value type: object
• Value schema: {"type": "object"}
• Injected by: scripts/utils/field_metadata_enricher.py
• Driven by config: config/field_metadata.yaml
• Example: "x-f5xc-defaults": {"value": "default"}
• Pass-through from upstream: no

x-f5xc-required-for-operations

• Applied at: schema property
• Purpose: Lists HTTP operations (POST/PUT/…) that require this property.
• Consumers: multiple
• Value type: array
• Value schema: {"type": "array", "items": {"type": "string"}}
• Injected by: scripts/utils/field_metadata_enricher.py
• Driven by config: config/field_metadata.yaml
• Example: "x-f5xc-required-for-operations": ["POST", "PUT"]
• Pass-through from upstream: no

x-f5xc-required-for

• Applied at: schema property
• Purpose: Lists named feature combinations that require this property.
• Consumers: multiple
• Value type: array
• Value schema: {"type": "array", "items": {"type": "string"}}
• Injected by: scripts/utils/minimum_configuration_enricher.py
• Driven by config: config/minimum_configs.yaml
• Example: "x-f5xc-required-for": ["tls-origin", "mtls"]
• Pass-through from upstream: no

x-f5xc-conditions

• Applied at: schema property
• Purpose: Conditional requirements (e.g. required when sibling field equals X).
• Consumers: multiple
• Value type: array
• Value schema: {"type": "array", "items": {"type": "object"}}
• Injected by: scripts/utils/field_metadata_enricher.py
• Driven by config: config/field_metadata.yaml
• Example: "x-f5xc-conditions": [{"when": "tls.enabled == true", "require": "cert"}]
• Pass-through from upstream: no

x-f5xc-deprecated

• Applied at: schema property
• Purpose: Deprecation notice with replacement guidance.
• Consumers: multiple
• Value type: object
• Value schema: {"type": "object"}
• Injected by: scripts/utils/field_metadata_enricher.py
• Driven by config: config/field_metadata.yaml
• Example: "x-f5xc-deprecated": {"since": "3.0.0", "use": "new_field"}
• Pass-through from upstream: no

x-f5xc-server-default

• Applied at: schema property
• Purpose: Default value the server assigns when the client omits the property.
• Consumers: multiple
• Value type: string
• Value schema: {}
• Injected by: scripts/utils/default_value_enricher.py
• Driven by config: config/discovered_defaults.yaml
• Example: "x-f5xc-server-default": "ROUND_ROBIN"
• Pass-through from upstream: no

x-f5xc-recommended-value

• Applied at: schema property
• Purpose: Recommended production value for a field where the server default is suboptimal.
• Consumers: multiple
• Value type: string
• Value schema: {}
• Injected by: scripts/utils/default_value_enricher.py
• Driven by config: config/discovered_defaults.yaml
• Example: "x-f5xc-recommended-value": "LEAST_REQUEST"
• Pass-through from upstream: no

x-f5xc-recommended-oneof-variant

• Applied at: schema property
• Purpose: For oneOf blocks, indicates which variant is recommended.
• Consumers: multiple
• Value type: string
• Value schema: {"type": "string"}
• Injected by: scripts/utils/default_value_enricher.py
• Driven by config: config/discovered_defaults.yaml
• Example: "x-f5xc-recommended-oneof-variant": "tls_parameters"
• Pass-through from upstream: no

x-f5xc-conflicts-with

• Applied at: schema property
• Purpose: Lists sibling properties that cannot be set alongside this one.
• Consumers: multiple
• Value type: array
• Value schema: {"type": "array", "items": {"type": "string"}}
• Injected by: scripts/utils/conflicts_with_enricher.py
• Driven by config: hardcoded
• Example: "x-f5xc-conflicts-with": ["plaintext", "auto_cert"]
• Pass-through from upstream: no

x-f5xc-required-oneof-groups

• Applied at: component schema
• Purpose: Names OneOf groups for which exactly one member must be configured.
• Consumers: terraform, cli, mcp, IDE
• Value type: object
• Value schema: {"type": "object", "additionalProperties": {"type": "array", "items": {"type": "string"}}}
• Injected by: scripts/utils/schema_override_enricher.py
• Driven by config: config/schema_overrides.yaml
• Example: "x-f5xc-required-oneof-groups": {"next_hop_choice": ["default_gateway", "ip_address", "node_interface"]}
• Pass-through from upstream: no

x-f5xc-references

• Applied at: schema property
• Purpose: Declares an ObjectRefType field’s referred resource-kind (the resource it points to, which must exist first), with oneOf choice-gating, required-for-create, and cardinality — the resource-reference dimension of the dependency model.
• Consumers: terraform, cli, mcp, IDE, ai-assistants
• Value type: array
• Value schema: {"type": "array", "items": {"type": "object", "properties": {"resource_kind": {"type": ["string", "null"]}, "field_path": {"type": "string"}, "gated_by": {"type": ["object", "null"]}, "required": {"type": "boolean"}, "cardinality": {"type": "string"}}}}
• Injected by: scripts/utils/references_enricher.py
• Driven by config: config/resource_references.yaml
• Example: "x-f5xc-references": [{"resource_kind": "app_firewall", "field_path": "app_firewall", "gated_by": {"choice": "waf_choice"}, "required": false, "cardinality": "single"}]
• Pass-through from upstream: no

x-f5xc-field-examples

• Applied at: schema (CreateSpecType)
• Purpose: Per-field create example values (flat field_path to value map) derived from x-f5xc-minimum-configuration.example_yaml — the single source of deterministic create values for downstream form/workflow generation.
• Consumers: cli, workflow-generator, sweep, ai-assistants
• Value type: object
• Value schema: {"type": "object", "additionalProperties": true}
• Injected by: scripts/utils/example_field_enricher.py
• Driven by config: derived from x-f5xc-minimum-configuration.example_yaml
• Example: "x-f5xc-field-examples": {"spec.port": 8080}
• Pass-through from upstream: no

x-f5xc-requires

• Applied at: schema property
• Purpose: Documents cross-field dependencies where one field requires another to be set.
• Consumers: compile_catalog.py, xcsh CLI
• Value type: array
• Value schema: {"type": "array", "items": {"type": "object", "properties": {"field": {"type": "string"}, "required": {"type": "boolean"}, "reason": {"type": "string"}}}}
• Injected by: scripts/utils/dependency_enricher.py
• Driven by config: config/minimum_configs.yaml (dependencies section)
• Example: "x-f5xc-requires": [{"field": "tls_config", "required": true, "reason": "use_tls requires tls_config sub-field"}]
• Pass-through from upstream: no

x-f5xc-constraints

• Applied at: schema property
• Purpose: Numeric / string constraints derived from live-API probing or static patterns.
• Consumers: multiple
• Value type: object
• Value schema: {"type": "object"}
• Injected by: scripts/utils/constraint_enricher.py
• Driven by config: config/constraint_patterns.yaml
• Example: "x-f5xc-constraints": {"min": 1, "max": 65535, "source": "live-api"}
• Pass-through from upstream: no

x-f5xc-uniqueness

• Applied at: schema property
• Purpose: Declares whether a field must be unique within its scope.
• Consumers: multiple
• Value type: object
• Value schema: {"type": "object"}
• Injected by: scripts/utils/uniqueness_enricher.py
• Driven by config: hardcoded
• Example: "x-f5xc-uniqueness": {"scope": "namespace"}
• Pass-through from upstream: no

x-f5xc-console-field

• Applied at: schema property
• Purpose: Console form widget metadata for this API property.
• Consumers: console-catalog, xcsh, browser-automation
• Value type: object
• Value schema: {"type": "object", "properties": {"widget_type": "string", "label": "string", "default": "any", "selector": "string", "form_section": "string", "show_when": "object", "advanced": "boolean"}}
• Injected by: scripts/utils/console_ui_enricher.py
• Driven by config: config/console_field_metadata.yaml
• Example: "x-f5xc-console-field": {"widget_type": "listbox", "default": "HTTPS with Automatic Certificate", "form_section": "domains-and-lb-type"}
• Pass-through from upstream: no

Injected — operation-level

x-f5xc-operation-aliases

• Applied at: operation
• Purpose: Preserves equivalent upstream operation identities that share the canonical route and method.
• Consumers: Terraform, CLI, MCP
• Value type: array
• Value schema: {"type": "array", "items": {"type": "string"}}
• Injected by: scripts/utils/canonical_merge.py
• Driven by config: explicit reviewed alias registry in the canonical merger
• Example: "x-f5xc-operation-aliases": ["ves.io.schema.discovered_service.CustomAPI.SuggestValues"]
• Pass-through from upstream: no

x-f5xc-operation-metadata

• Applied at: operation
• Purpose: Groups purpose, field, safety, error, and performance metadata for an operation.
• Consumers: CLI, MCP, IDE
• Value type: object
• Value schema: {"type": "object"}
• Injected by: scripts/utils/operation_metadata_enricher.py
• Driven by config: config/operation_metadata.yaml and config/operation_descriptions.yaml
• Example: "x-f5xc-operation-metadata": {"purpose": "HTTP load balancer configuration"}
• Pass-through from upstream: no

x-f5xc-operation-role

• Applied at: operation
• Purpose: Classifies response operations whose HTTP method does not communicate their API semantics.
• Consumers: Terraform, CLI, MCP
• Value type: string
• Value schema: {"type": "string", "enum": ["query", "issuance", "collection", "action"]}
• Injected by: scripts/utils/operation_metadata_enricher.py
• Driven by config: config/operation_metadata.yaml
• Example: "x-f5xc-operation-role": "query"
• Pass-through from upstream: no

x-f5xc-terraform-name

• Applied at: operation
• Purpose: Provides the stable source-owned Terraform name for a response operation, without the provider prefix.
• Consumers: Terraform
• Value type: string
• Value schema: {"type": "string", "pattern": "^[a-z][a-z0-9_]*$"}
• Injected by: scripts/utils/operation_metadata_enricher.py
• Driven by config: config/operation_metadata.yaml
• Example: "x-f5xc-terraform-name": "site_registrations_by_site"
• Pass-through from upstream: no

x-f5xc-required-fields

• Applied at: operation
• Purpose: Names the operation-body fields that must be provided for success.
• Consumers: multiple
• Value type: array
• Value schema: {"type": "array", "items": {"type": "string"}}
• Injected by: scripts/utils/operation_metadata_enricher.py
• Driven by config: config/operation_metadata.yaml
• Example: "x-f5xc-required-fields": ["metadata.name", "spec.domains"]
• Pass-through from upstream: no

x-f5xc-prerequisites

• Applied at: operation
• Purpose: Documents typed external or server-enforced prerequisites without claiming a writable API for the prerequisite.
• Consumers: Terraform, CLI, MCP
• Value type: array
• Value schema: {"type": "array", "items": {"type": "object"}}
• Injected by: scripts/utils/operation_metadata_enricher.py
• Driven by config: config/operation_metadata.yaml
• Example: "x-f5xc-prerequisites": [{"id": "maurice_config_cardinality_exactly_one", "cardinality": {"exactly": 1}}]
• Pass-through from upstream: no

x-f5xc-danger-level

• Applied at: operation
• Purpose: Classifies the blast radius of an operation (low/medium/high/critical).
• Consumers: multiple
• Value type: string
• Value schema: {"type": "string", "enum": ["low", "medium", "high", "critical"]}
• Injected by: scripts/utils/operation_metadata_enricher.py
• Driven by config: config/operation_metadata.yaml
• Example: "x-f5xc-danger-level": "high"
• Pass-through from upstream: no

x-f5xc-confirmation-required

• Applied at: operation
• Purpose: Whether CLI/UI should prompt the user to confirm before executing.
• Consumers: multiple
• Value type: boolean
• Value schema: {"type": "boolean"}
• Injected by: scripts/utils/operation_metadata_enricher.py
• Driven by config: config/operation_metadata.yaml
• Example: "x-f5xc-confirmation-required": true
• Pass-through from upstream: no

x-f5xc-side-effects

• Applied at: operation
• Purpose: Lists observable side effects of the operation (restart, reconfigure, etc.).
• Consumers: multiple
• Value type: array
• Value schema: {"type": "array", "items": {"type": "string"}}
• Injected by: scripts/utils/operation_metadata_enricher.py
• Driven by config: config/operation_metadata.yaml
• Example: "x-f5xc-side-effects": ["invalidates-cache"]
• Pass-through from upstream: no

x-f5xc-discovered-response-time

• Applied at: operation
• Purpose: Empirically measured response time for this operation during discovery.
• Consumers: multiple
• Value type: object
• Value schema: {"type": "object"}
• Injected by: scripts/utils/discovery_enricher.py
• Driven by config: config/discovery_enrichment.yaml
• Example: "x-f5xc-discovered-response-time": {"p50_ms": 40, "p95_ms": 120}
• Pass-through from upstream: no

x-f5xc-discovered-rate-limits

• Applied at: operation
• Purpose: Observed rate-limit headers / behavior surfaced from the live API.
• Consumers: multiple
• Value type: object
• Value schema: {"type": "object"}
• Injected by: scripts/utils/discovery_enricher.py
• Driven by config: config/discovery_enrichment.yaml
• Example: "x-f5xc-discovered-rate-limits": {"limit": 100, "window_s": 60}
• Pass-through from upstream: no

x-f5xc-discovered-error-catalog

• Applied at: operation
• Purpose: Catalog of error responses observed during live discovery, with sample payloads.
• Consumers: multiple
• Value type: array
• Value schema: {"type": "array", "items": {"type": "object"}}
• Injected by: scripts/utils/discovery_enricher.py
• Driven by config: config/discovery_enrichment.yaml
• Example: "x-f5xc-discovered-error-catalog": [{"status": 400, "reason": "bad_request"}]
• Pass-through from upstream: no

Injected — index-level (domain metadata)

x-f5xc-category

• Applied at: info
• Purpose: Top-level CLI / UI / docs / Terraform grouping category for a domain.
• Consumers: multiple
• Value type: string
• Value schema: {"type": "string"}
• Injected by: scripts/merge_specs.py
• Driven by config: config/domain_patterns.yaml
• Example: "x-f5xc-category": "networking"
• Pass-through from upstream: no

x-f5xc-primary-resources

• Applied at: info
• Purpose: List of primary resource types that define the domain.
• Consumers: multiple
• Value type: array
• Value schema: {"type": "array", "items": {"type": "string"}}
• Injected by: scripts/merge_specs.py
• Driven by config: config/domain_patterns.yaml
• Example: "x-f5xc-primary-resources": ["http_loadbalancer"]
• Pass-through from upstream: no

x-f5xc-critical-resources

• Applied at: info
• Purpose: Resources that require elevated care (production-critical).
• Consumers: multiple
• Value type: array
• Value schema: {"type": "array", "items": {"type": "string"}}
• Injected by: scripts/merge_specs.py
• Driven by config: config/critical_resources.yaml
• Example: "x-f5xc-critical-resources": ["tls_certificate"]
• Pass-through from upstream: no

x-f5xc-description-short

• Applied at: info
• Purpose: Short (~60 char) domain description. Also applies at property level for long descriptions.
• Consumers: multiple
• Value type: string
• Value schema: {"type": "string"}
• Injected by: scripts/utils/property_description_short_enricher.py
• Driven by config: config/property_description_short.yaml
• Example: "x-f5xc-description-short": "Layer-7 HTTPS load balancing."
• Pass-through from upstream: no

x-f5xc-description-medium

• Applied at: info
• Purpose: Medium (~150 char) domain description. Also applies at property level.
• Consumers: multiple
• Value type: string
• Value schema: {"type": "string"}
• Injected by: scripts/utils/property_description_short_enricher.py
• Driven by config: config/property_description_short.yaml
• Example: "x-f5xc-description-medium": "HTTP/HTTPS load balancer with advanced routing, WAF, and TLS."
• Pass-through from upstream: no

x-f5xc-description-long

• Applied at: info
• Purpose: Long (~500 char) domain description.
• Consumers: multiple
• Value type: string
• Value schema: {"type": "string"}
• Injected by: scripts/utils/description_enricher.py
• Driven by config: config/domain_descriptions.yaml
• Example: "x-f5xc-description-long": "Full paragraph describing the domain..."
• Pass-through from upstream: no

x-f5xc-complexity

• Applied at: info
• Purpose: Relative complexity tier for authoring configurations in this domain.
• Consumers: multiple
• Value type: string
• Value schema: {"type": "string", "enum": ["low", "medium", "high"]}
• Injected by: scripts/merge_specs.py
• Driven by config: config/domain_patterns.yaml
• Example: "x-f5xc-complexity": "medium"
• Pass-through from upstream: no

x-f5xc-requires-tier

• Applied at: info
• Purpose: Minimum F5 XC subscription tier required.
• Consumers: multiple
• Value type: string
• Value schema: {"type": "string"}
• Injected by: scripts/merge_specs.py
• Driven by config: config/domain_patterns.yaml
• Example: "x-f5xc-requires-tier": "enterprise"
• Pass-through from upstream: no

x-f5xc-is-preview

• Applied at: info
• Purpose: Flags a domain as a preview / beta feature.
• Consumers: multiple
• Value type: boolean
• Value schema: {"type": "boolean"}
• Injected by: scripts/merge_specs.py
• Driven by config: config/domain_patterns.yaml
• Example: "x-f5xc-is-preview": false
• Pass-through from upstream: no

x-f5xc-use-cases

• Applied at: info
• Purpose: Named use cases this domain supports.
• Consumers: multiple
• Value type: array
• Value schema: {"type": "array", "items": {"type": "string"}}
• Injected by: scripts/merge_specs.py
• Driven by config: config/domain_patterns.yaml
• Example: "x-f5xc-use-cases": ["tls-termination", "waf"]
• Pass-through from upstream: no

x-f5xc-icon

• Applied at: info
• Purpose: Icon identifier to use when rendering this domain in a UI.
• Consumers: Web UI
• Value type: string
• Value schema: {"type": "string"}
• Injected by: scripts/merge_specs.py
• Driven by config: config/domain_patterns.yaml
• Example: "x-f5xc-icon": "f5xc:load-balancer"
• Pass-through from upstream: no

x-f5xc-logo-svg

• Applied at: info
• Purpose: Inline SVG (or path) for a brand logo representing the domain.
• Consumers: Web UI
• Value type: string
• Value schema: {"type": "string"}
• Injected by: scripts/merge_specs.py
• Driven by config: config/domain_patterns.yaml
• Example: "x-f5xc-logo-svg": "<svg>...</svg>"
• Pass-through from upstream: no

x-f5xc-related-domains

• Applied at: info
• Purpose: Cross-links to other domains commonly used together with this one.
• Consumers: multiple
• Value type: array
• Value schema: {"type": "array", "items": {"type": "string"}}
• Injected by: scripts/merge_specs.py
• Driven by config: config/domain_patterns.yaml
• Example: "x-f5xc-related-domains": ["origin_pool", "tls_certificate"]
• Pass-through from upstream: no

x-f5xc-doc-section

• Applied at: info
• Purpose: Documentation section / nav grouping slug for rendered docs.
• Consumers: multiple
• Value type: string
• Value schema: {"type": "string"}
• Injected by: scripts/merge_specs.py
• Driven by config: config/domain_patterns.yaml
• Example: "x-f5xc-doc-section": "load-balancing"
• Pass-through from upstream: no

Upstream pass-through

x-ves-proto-package

• Applied at: upstream
• Purpose: Preserved unchanged from F5 upstream spec.
• Consumers: N/A
• Value type: varies
• Value schema: N/A
• Injected by: upstream
• Driven by config: upstream
• Example: "x-ves-proto-package": "ves.io.schema.virtual_host"
• Pass-through from upstream: yes

x-ves-proto-file

• Applied at: upstream
• Purpose: Preserved unchanged from F5 upstream spec.
• Consumers: N/A
• Value type: varies
• Value schema: N/A
• Injected by: upstream
• Driven by config: upstream
• Example: "x-ves-proto-file": "ves.io/schema/virtual_host/types.proto"
• Pass-through from upstream: yes

x-ves-proto-message

• Applied at: upstream
• Purpose: Preserved unchanged from F5 upstream spec.
• Consumers: N/A
• Value type: varies
• Value schema: N/A
• Injected by: upstream
• Driven by config: upstream
• Example: "x-ves-proto-message": "ves.io.schema.virtual_host.CreateSpecType"
• Pass-through from upstream: yes

x-ves-proto-service

• Applied at: upstream
• Purpose: Preserved unchanged from F5 upstream spec.
• Consumers: N/A
• Value type: varies
• Value schema: N/A
• Injected by: upstream
• Driven by config: upstream
• Example: "x-ves-proto-service": "ves.io.schema.virtual_host.API"
• Pass-through from upstream: yes

x-ves-proto-rpc

• Applied at: upstream
• Purpose: Preserved unchanged from F5 upstream spec.
• Consumers: N/A
• Value type: varies
• Value schema: N/A
• Injected by: upstream
• Driven by config: upstream
• Example: "x-ves-proto-rpc": "ves.io.schema.api_sec.api_crawler.API.Create"
• Pass-through from upstream: yes

x-displayname

• Applied at: upstream
• Purpose: Preserved unchanged from F5 upstream spec.
• Consumers: N/A
• Value type: varies
• Value schema: N/A
• Injected by: upstream
• Driven by config: upstream
• Example: "x-displayname": "Namespace"
• Pass-through from upstream: yes

x-ves-oneof

• Applied at: upstream
• Purpose: Preserved unchanged from F5 upstream spec.
• Consumers: N/A
• Value type: varies
• Value schema: N/A
• Injected by: upstream
• Driven by config: upstream
• Example: See F5 upstream docs.
• Pass-through from upstream: yes

x-ves-default

• Applied at: upstream
• Purpose: Preserved unchanged from F5 upstream spec.
• Consumers: N/A
• Value type: varies
• Value schema: N/A
• Injected by: upstream
• Driven by config: upstream
• Example: See F5 upstream docs.
• Pass-through from upstream: yes

x-ves-required

• Applied at: upstream
• Purpose: Preserved unchanged from F5 upstream spec.
• Consumers: N/A
• Value type: varies
• Value schema: N/A
• Injected by: upstream
• Driven by config: upstream
• Example: See F5 upstream docs.
• Pass-through from upstream: yes

x-f5xc-wire-name

• Applied at: schema property
• Purpose: Original upstream property key that must appear on the wire. The buffer zone renames F5’s misspelled property names and records the original key here, because the F5 server accepts only the original spelling.
• Consumers: Terraform
• Value type: string
• Value schema: {"type": "string"}
• Injected by: upstream (f5-sales-demo/api-specs)
• Driven by config: upstream
• Example: "blocked_service": {"x-f5xc-wire-name": "blocked_sevice"}
• Pass-through from upstream: yes