Configuration Reference

All pipeline behavior is controlled by two YAML files in config/.

`config/validation.yaml`

API Settings

api:
  timeout: 30
  retries: 3

Field	Description
`timeout`	HTTP request timeout in seconds.
`retries`	Number of retry attempts on failure.

Live validation requires all three environment variables below. They have no source-controlled defaults, and authentication, connection, or namespace probe failure stops validation without generating a successful dry-run report.

export F5XC_API_URL="https://example-tenant.console.ves.volterra.io"
export F5XC_NAMESPACE="example-namespace"
export F5XC_API_TOKEN="your-api-token"

Download Settings

download:
  url: "https://docs.cloud.f5.com/docs-v2/downloads/f5-distributed-cloud-open-api.zip"
  output_dir: "specs/original"
  etag_cache: ".etag_cache"

Field	Description
`url`	URL of the official F5 XC OpenAPI spec bundle (ZIP).
`output_dir`	Where extracted specs are stored.
`etag_cache`	File that stores the HTTP ETag for conditional downloads.

Live Validation Input

validation:
  input_dir: "specs/transformed"

Live tests resolve their semantic domains from the corrected transform output. Raw files in specs/original/ remain the immutable upstream landing bytes and are never presented as the corrected intermediate API contract.

Validation Categories

Ten categories corresponding to the OpenAPI schema constraint types. Each can be independently enabled/disabled.

validation_categories:
  string_length:
    enabled: true
    keywords: ["minLength", "maxLength"]
    description: "Validate string length boundaries"

Category	Keywords
`string_length`	`minLength`, `maxLength`
`pattern`	`pattern`
`numeric_bounds`	`minimum`, `maximum`, `exclusiveMinimum`, `exclusiveMaximum`
`required_fields`	`required`
`enum_values`	`enum`
`array_bounds`	`minItems`, `maxItems`, `uniqueItems`
`object_structure`	`additionalProperties`, `properties`, `propertyNames`
`composition`	`oneOf`, `anyOf`, `allOf`
`dependencies`	`dependentRequired`, `dependentSchemas`
`data_types`	`type`, `format`

Schemathesis Settings

schemathesis:
  examples_per_operation: 1

Field	Description
`examples_per_operation`	Exact number of generated test cases per configured operation.

Generation is derandomized and uses only Hypothesis’s generation phase, so an unchanged spec and configuration produce the same example sequence. Requests are sent to F5XC_API_URL with the APIToken authorization scheme.

Reconciliation Settings

reconciliation:
  priority:
    - existing
    - discovery
    - inferred
  fix_strategies:
    tighter_spec: "relax"
    looser_spec: "tighten"
    missing_constraint: "add"
    extra_constraint: "remove"

Field	Description
`priority`	Order of preference when multiple data sources disagree.
`fix_strategies`	Maps each discrepancy type to its fix action. See Fixes Applied.

Spectral Settings

spectral:
  enabled: true
  ruleset: "spectral-pipeline.yaml"
  auto_fix:
    oas3-api-servers: true
    info-contact: true
    operation-tags: true
    oas3-unused-component: true
    operation-operationId-unique: true
    oas3-valid-schema-example: true
    no-script-tags-in-markdown: true
  gate:
    max_errors: null
    max_warnings: null
  contact:
    name: "F5 Distributed Cloud"
    url: "https://docs.cloud.f5.com"
    email: "support@f5.com"
  servers:
    - url: "https://{tenant}.console.ves.volterra.io"
      description: "F5 Distributed Cloud API"
      variables:
        tenant:
          default: "example-tenant"
          description: "Your F5 XC tenant name"
  security_scheme:
    type: "apiKey"
    in: "header"
    name: "Authorization"
    description: "F5 XC API Token (format: APIToken <token>)"

Field	Description
`enabled`	Toggle Spectral linting entirely.
`ruleset`	Which Spectral config file to use (pipeline uses `spectral-pipeline.yaml`).
`auto_fix`	Map of rule name to boolean. `true` means the reconciler will fix violations.
`gate.max_errors`	Maximum allowed errors in the post-reconcile gate. `null` disables the check.
`gate.max_warnings`	Maximum allowed warnings. `null` disables the check.
`contact`	Contact info injected into `info.contact` by the `info-contact` fixer.
`servers`	Servers array injected by the `oas3-api-servers` fixer.
`security_scheme`	Security scheme definition injected into every spec.

Report Settings

reports:
  output_dir: "reports"
  formats:
    - json
    - html
    - markdown
  include_examples: true
  max_examples_per_issue: 5

Release Settings

release:
  output_dir: "release"
  include_changelog: true
  include_validation_report: true
  version_from: "git"

Field	Description
`output_dir`	Directory for release artifacts.
`include_changelog`	Include `CHANGELOG.md` in the release package.
`include_validation_report`	Include the validation report in the release package.
`version_from`	Version source. `git` derives version from spec metadata date + patch number.

`config/endpoints.yaml`

Defines the baseline endpoints used for live API validation. Each entry maps a logical resource name to its spec file, API group, and CRUD paths.

Endpoint Structure

endpoints:
  healthcheck:
    resource: healthchecks
    domain_file: docs-cloud-f5-com.0124.public.ves.io.schema.healthcheck.ves-swagger.json
    api_group: config
    crud_operations:
      create: POST /api/config/namespaces/{namespace}/healthchecks
      read: GET /api/config/namespaces/{namespace}/healthchecks/{name}
      list: GET /api/config/namespaces/{namespace}/healthchecks
      update: PUT /api/config/namespaces/{namespace}/healthchecks/{name}
      delete: DELETE /api/config/namespaces/{namespace}/healthchecks/{name}
    test_priority: high
    description: "Health check configurations for origin monitoring"

Field	Description
`resource`	API resource name (used in URL paths).
`domain_file`	Filename of the OpenAPI spec in `specs/original/`.
`api_group`	API group prefix (`config`, `web`, etc.).
`crud_operations`	HTTP method and path for each CRUD operation.
`test_priority`	`high`, `medium`, or `low` — controls test execution order.
`description`	Human-readable description of the resource.

Current Baseline Endpoints

10 endpoints across three domains:

Endpoint	Domain	Priority
`healthcheck`	Virtual	high
`origin_pool`	Virtual	high
`app_firewall`	Virtual	high
`service_policy`	Virtual	medium
`api_definition`	API Security	high
`api_discovery`	API Security	medium
`api_groups`	API Security	medium
`code_base_integration`	API Security	low
`data_type`	Data Privacy	medium
`sensitive_data_policy`	Data Privacy	medium

Adding New Endpoints

To add a new endpoint for validation:

Find the spec filename in specs/original/ (format: docs-cloud-f5-com.NNNN.*.ves-swagger.json)
Add an entry under endpoints: following the structure above
Add the domain file mapping under domain_files: with a priority number
Add the endpoint name to test_order: in the desired position