Validation Specification

This document describes the structure and contents of the validation specification published by the api-specs-enriched project.

Overview

The validation specification consolidates API validation constraints, default values, and configuration metadata into a single JSON file. This specification is generated from the enriched OpenAPI specs and published alongside them.

Publication location: docs/specifications/api/validation.json

Specification Structure

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "version": "2.1.0",
  "generated_at": "2026-01-17T12:00:00Z",
  "source": "api-specs-enriched",

  "required_fields": { ... },
  "enum_values": { ... },
  "constraints": { ... },
  "patterns": [ ... ],
  "conditional_requirements": { ... },
  "minimum_configurations": { ... },
  "defaults": { ... },
  "extensions": { ... }
}

Sections

required_fields

Specifies fields required for each operation type per resource.

{
  "required_fields": {
    "common": {
      "all_operations": ["metadata.name", "metadata.namespace"]
    },
    "resources": {
      "origin_pool": {
        "create": ["metadata.name", "metadata.namespace", "spec.origin_servers", "spec.port"],
        "update": ["metadata.name", "metadata.namespace"],
        "minimum_config": ["metadata.name", "metadata.namespace", "spec.origin_servers", "spec.port"]
      }
    }
  }
}

enum_values

Defines allowed values for constrained fields.

{
  "enum_values": {
    "loadbalancer_algorithm": {
      "description": "Load balancing algorithm for distributing traffic across origin servers",
      "values": [
        {"value": "ROUND_ROBIN", "description": "Each healthy endpoint selected in round robin order"},
        {"value": "LEAST_REQUEST", "description": "Endpoint with fewest active requests selected"},
        {"value": "RING_HASH", "description": "Consistent hashing using ring hash of endpoint names"},
        {"value": "RANDOM", "description": "Random healthy endpoint selection"},
        {"value": "LB_OVERRIDE", "description": "Hash policy inherited from parent load balancer"}
      ],
      "default": "ROUND_ROBIN"
    }
  }
}

constraints

Type-level validation defaults and pattern-based rules.

{
  "constraints": {
    "type_defaults": {
      "string": {"minLength": 0, "maxLength": 1024},
      "integer": {"minimum": 0, "maximum": 2147483647}
    }
  }
}

patterns

Field name pattern-based validation rules with confidence scores.

{
  "patterns": [
    {
      "pattern": "\\bport$",
      "constraints": {"minimum": 1, "maximum": 65535},
      "confidence": 0.99,
      "description": "Valid TCP/UDP port range"
    },
    {
      "pattern": "\\bname$",
      "constraints": {
        "minLength": 1,
        "maxLength": 63,
        "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$"
      },
      "confidence": 0.90,
      "description": "Kubernetes-style naming convention"
    }
  ]
}

defaults

All default values organized by resource type in a unified structure.

{
  "defaults": {
    "description": "All default values organized by resource type",
    "resources": {
      "healthcheck": {
        "server_applied": {
          "jitter": 0,
          "jitter_percent": 0
        },
        "recommended": {
          "timeout": 3,
          "interval": 15,
          "unhealthy_threshold": 1,
          "healthy_threshold": 3,
          "jitter_percent": 30
        },
        "oneof_recommended": {
          "health_check": "http_health_check"
        },
        "nested_recommended": {
          "http_health_check": {
            "path": "/",
            "use_http2": false,
            "expected_status_codes": ["200"],
            "use_origin_server_name": {}
          }
        }
      },
      "origin_pool": {
        "server_applied": {
          "no_tls": {},
          "healthcheck": [],
          "loadbalancer_algorithm": "ROUND_ROBIN",
          "endpoint_selection": "DISTRIBUTED"
        },
        "recommended": {
          "port": 443,
          "connection_timeout": 2000,
          "http_idle_timeout": 300000
        },
        "advanced_options": {
          "connection_timeout": 2000,
          "http_idle_timeout": 300000,
          "same_as_endpoint_port": {},
          "default_circuit_breaker": {},
          "disable_outlier_detection": {}
        },
        "oneof_choices": {
          "port_choice": "port",
          "tls_choice": "no_tls",
          "circuit_breaker_choice": "default_circuit_breaker"
        },
        "ui_vs_server": {
          "loadbalancer_algorithm": {
            "ui_default": "LB_OVERRIDE",
            "server_default": "ROUND_ROBIN",
            "note": "UI preselects LB_OVERRIDE but server applies ROUND_ROBIN if omitted"
          }
        }
      },
      "app_firewall": {
        "server_applied": {
          "allow_all_response_codes": {},
          "default_anonymization": {},
          "monitoring": {}
        }
      }
    }
  }
}

Default Categories

Category	Description	Source
`server_applied`	Values the API applies when fields are omitted	Live API testing
`recommended`	F5 XC web console pre-populated values	UI analysis
`advanced_options`	Nested defaults within advanced_options objects	API discovery
`oneof_choices`	Default OneOf variant selections	API behavior
`oneof_recommended`	Recommended OneOf variants	Console defaults
`nested_recommended`	Recommended values for nested schemas	UI analysis
`ui_vs_server`	Cases where UI defaults differ from API defaults	Comparative analysis

conditional_requirements

Mutually exclusive fields and conditional dependencies.

{
  "conditional_requirements": {
    "resources": {
      "healthcheck": {
        "mutually_exclusive": [
          {
            "fields": ["spec.http_health_check", "spec.tcp_health_check", "spec.udp_icmp_health_check"],
            "reason": "Choose exactly one health check type"
          }
        ],
        "conditional": []
      }
    }
  }
}

minimum_configurations

Minimum viable configurations with working examples.

{
  "minimum_configurations": {
    "resources": {
      "origin_pool": {
        "description": "Backend origin servers for load balancing",
        "example": {
          "metadata": {"name": "backend-pool", "namespace": "default"},
          "spec": {
            "origin_servers": [{"public_name": {"dns_name": "backend1.example.com"}}],
            "port": 8080
          }
        }
      }
    }
  }
}

OpenAPI Extension Mapping

The enriched OpenAPI specs embed validation metadata using these extensions:

Extension	Purpose	Location
`x-f5xc-required-for`	Context-specific required fields	Schema properties
`x-f5xc-server-default`	Marks server-applied defaults	Schema properties
`x-f5xc-recommended-value`	Recommended default value	Schema properties
`x-f5xc-recommended-oneof-variant`	Recommended OneOf variant	Schema definitions
`x-f5xc-conditions`	Conditional requirements	Schema properties
`x-f5xc-minimum-configuration`	Minimum config examples	Schema definitions
`x-f5xc-validation`	Discovery-derived constraints	Schema properties

Data Access

Publication URLs

Source	URL
GitHub Pages	`https://f5xc-salesdemos.github.io/api-specs-enriched/specifications/api/validation.json`
Raw GitHub	`https://raw.githubusercontent.com/f5xc-salesdemos/api-specs-enriched/main/docs/specifications/api/validation.json`

Local Path

After running the pipeline: docs/specifications/api/validation.json

Versioning

The validation spec follows semantic versioning in the version field:

Change Type	Version Bump	Example
Breaking structure changes	Major	Field renames, removed sections
New validation rules or resources	Minor	New resource defaults
Bug fixes or description updates	Patch	Typo corrections

Reconciliation Priority

When multiple sources provide constraints, the reconciliation priority is:

Existing - Constraints in original OpenAPI spec (highest priority)
Discovery - Constraints from live API discovery
Inferred - Constraints from pattern matching (lowest priority)

Healthcheck Enhancements - Healthcheck schema enrichments
Origin Pool Enhancements - Origin pool schema enrichments
CLAUDE.md - AI assistant instructions
DEVELOPMENT.md - Developer guide

Changelog

Version	Date	Changes
2.1.2	2026-01-18	Rewritten as pure API reference; added oneof_recommended and nested_recommended categories
2.1.0	2026-01-18	Unified defaults structure replacing fragmented sections
2.0.0	2026-01-15	Initial validation specification