Correções Aplicadas às Especificações Upstream

O reconciliador (scripts/reconcile.py) aplica quatro categorias de correções às especificações upstream. Correções de restrição alteram contratos de API para corresponder ao comportamento observado. Todas as outras correções são apenas de metadados e não alteram contratos de API.

Correções de Restrição

Essas correções ajustam as restrições do esquema OpenAPI para que a especificação corresponda ao que a API em produção realmente aplica. Cada correção é conduzida por um objeto Discrepancy produzido durante a validação.

Estratégia	Gatilho	O Que Faz	Alteração de Contrato
Relaxar	SPEC_STRICTER	A especificação rejeita valores que a API aceita. Reduz minLength/minimum, aumenta maxLength/maximum, adiciona valores enum faltantes.	Sim — amplia valores aceitos
Restringir	SPEC_LOOSER	A especificação aceita valores que a API rejeita. Aumenta minLength/minimum, reduz maxLength/maximum, restringe enums aos valores observados.	Sim — reduz valores aceitos
Adicionar	MISSING_CONSTRAINT	A API aplica uma restrição não documentada na especificação. Adiciona a restrição ao esquema.	Sim — adiciona nova restrição
Remover	EXTRA_CONSTRAINT	A especificação declara uma restrição que a API ignora. Remove a restrição do esquema.	Sim — remove restrição

Cuidado

Correções de restrição alteram o contrato da API. Elas são aplicadas apenas quando respaldadas por evidências do Schemathesis ou testes de validação de restrições contra a API em produção.

Tipos de Restrição Suportados

As 10 categorias de restrição OpenAPI testadas e corrigidas:

• Comprimento de string — minLength, maxLength
• Padrão — pattern (regex)
• Limites numéricos — minimum, maximum, exclusiveMinimum, exclusiveMaximum
• Campos obrigatórios — required
• Valores enum — enum
• Limites de array — minItems, maxItems, uniqueItems
• Estrutura de objeto — additionalProperties, properties, propertyNames
• Composição — oneOf, anyOf, allOf
• Dependências — dependentRequired, dependentSchemas
• Tipos de dados — type, format

Enriquecimentos Spectral

Essas correções tratam problemas de qualidade OAS3 encontrados pelo linting Spectral. Elas adicionam ou corrigem metadados sem alterar o comportamento da API.

Injeção do Bloco Servers

Regra: oas3-api-servers | Alteração de contrato: Não

Adiciona o template de URL do tenant F5 XC às especificações que não possuem um bloco servers:

"servers": [{
  "url": "https://{tenant}.console.ves.volterra.io",
  "description": "F5 Distributed Cloud API",
  "variables": {
    "tenant": {
      "default": "example-tenant",
      "description": "Your F5 XC tenant name"
    }
  }
}]

A URL do servidor e os valores das variáveis vêm de spectral.servers em validation.yaml.

Injeção de Informações de Contato

Regra: info-contact | Alteração de contrato: Não

Adiciona informações de contato em info.contact para especificações que não as possuem:

"contact": {
  "name": "F5 Distributed Cloud",
  "url": "https://docs.cloud.f5.com",
  "email": "support@f5.com"
}

Os valores vêm de spectral.contact em validation.yaml.

Derivação de Tags de Operação

Regra: operation-tags | Alteração de contrato: Não

Deriva uma tag a partir do prefixo do caminho URL para operações sem tags. Para um caminho como /api/config/namespaces/{namespace}/healthchecks, a tag é config (o segundo segmento que não é parâmetro). A tag é adicionada tanto ao array tags da operação quanto à lista tags no nível da especificação.

Remoção de Componentes Não Utilizados

Regra: oas3-unused-component | Alteração de contrato: Não

Remove esquemas de componentes de components.schemas que não são referenciados em nenhum lugar da especificação. Reduz o tamanho da especificação sem afetar nenhuma operação.

Deduplicação de OperationId

Regra: operation-operationId-unique | Alteração de contrato: Não

Adiciona o método HTTP como sufixo (ex.: ListItems_get) quando múltiplas operações compartilham o mesmo operationId. Isso torna cada operationId único para geradores de código.

Remoção de Exemplos/Valores Padrão Inválidos

Regra: oas3-valid-schema-example | Alteração de contrato: Não

Remove valores example ou default dos esquemas quando o valor não está em conformidade com as próprias restrições do esquema (tipo errado, fora do intervalo, etc.). Evita que geradores de código produzam payloads de exemplo inválidos.

Remoção de Tags Script

Regra: no-script-tags-in-markdown | Alteração de contrato: Não

Remove tags <script> dos campos description usando substituição por regex. Algumas especificações upstream contêm tags script injetadas que quebram renderizadores de documentação.

Metadados de Segurança

Alteração de contrato: Não (apenas documentação)

Toda especificação recebe um esquema de segurança apiKeyAuth se um ainda não estiver presente. Isso é sempre injetado independentemente de o Spectral ter sinalizado ou não.

"components": {
  "securitySchemes": {
    "apiKeyAuth": {
      "type": "apiKey",
      "in": "header",
      "name": "Authorization",
      "description": "F5 XC API Token (format: APIToken <token>)"
    }
  }
},
"security": [{ "apiKeyAuth": [] }]

A definição do esquema vem de spectral.security_scheme em validation.yaml. Isso informa aos consumidores da API como autenticar, mas não altera o comportamento em tempo de execução.

Formatação JSON

Alteração de contrato: Não

Todas as especificações JSON de saída passam por um compactador de arrays compatível com Biome (_compact_short_arrays em scripts/utils/spec_loader.py). Arrays curtos que cabem em 120 caracteres são colapsados em uma única linha:

// Before
"enum": [
  "ACTIVE",
  "INACTIVE"
]

// After
"enum": ["ACTIVE", "INACTIVE"]

Arrays que excedem o limite de comprimento de linha permanecem em múltiplas linhas.

Prioridade de Correção

Quando múltiplas estratégias de correção podem ser aplicadas, o reconciliador usa uma ordem de prioridade configurada em reconciliation.priority:

1. existing — Usar a restrição existente da especificação se for válida
2. discovery — Usar o comportamento descoberto da API em produção
3. inferred — Inferir a partir de padrões em endpoints similares

Toda especificação corrigida é validada com openapi-spec-validator após todas as correções serem aplicadas. Se a validação falhar, a especificação original é usada como fallback e a correção é registrada como erro.