上流スペックに適用される修正

リコンサイラー（scripts/reconcile.py）は、上流スペックに対して4つのカテゴリの修正を適用します。制約の修正はAPIコントラクトを観測された動作に一致するよう変更します。その他のすべての修正はメタデータのみであり、APIコントラクトを変更しません。

制約の修正

これらの修正は、スペックがライブAPIが実際に適用する内容と一致するよう、OpenAPIスキーマの制約を調整します。各修正は、バリデーション中に生成されるDiscrepancyオブジェクトによって駆動されます。

戦略	トリガー	動作内容	コントラクト変更
緩和	`SPEC_STRICTER`	スペックがAPIが受け入れる値を拒否している。`minLength`/`minimum`を下げ、`maxLength`/`maximum`を上げ、不足しているenum値を追加する。	あり — 受け入れ値を拡大
厳格化	`SPEC_LOOSER`	スペックがAPIが拒否する値を受け入れている。`minLength`/`minimum`を上げ、`maxLength`/`maximum`を下げ、enumを観測された値に制限する。	あり — 受け入れ値を縮小
追加	`MISSING_CONSTRAINT`	APIがスペックに文書化されていない制約を適用している。スキーマに制約を追加する。	あり — 新しい制約を追加
削除	`EXTRA_CONSTRAINT`	スペックがAPIが無視する制約を宣言している。スキーマから制約を削除する。	あり — 制約を削除

サポートされる制約タイプ

テストおよび修正される10のOpenAPI制約カテゴリ：

文字列長 — minLength、maxLength
パターン — pattern（正規表現）
数値範囲 — minimum、maximum、exclusiveMinimum、exclusiveMaximum
必須フィールド — required
Enum値 — enum
配列範囲 — minItems、maxItems、uniqueItems
オブジェクト構造 — additionalProperties、properties、propertyNames
合成 — oneOf、anyOf、allOf
依存関係 — dependentRequired、dependentSchemas
データ型 — type、format

Spectralエンリッチメント

これらの修正は、Spectralリンティングで検出されたOAS3品質の問題に対処します。API動作を変更することなく、メタデータを追加または修正します。

サーバーブロックの挿入

ルール: oas3-api-servers | コントラクト変更: なし

serversブロックが欠落しているスペックにF5 XCテナントURLテンプレートを追加します：

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

サーバーURLと変数値はvalidation.yamlのspectral.serversから取得されます。

連絡先情報の挿入

ルール: info-contact | コントラクト変更: なし

連絡先情報が欠落しているスペックのinfo.contactに連絡先情報を追加します：

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

値はvalidation.yamlのspectral.contactから取得されます。

オペレーションタグの導出

ルール: operation-tags | コントラクト変更: なし

タグが付いていないオペレーションに対して、URLパスプレフィックスからタグを導出します。/api/config/namespaces/{namespace}/healthchecksのようなパスの場合、タグはconfig（2番目の非パラメータセグメント）になります。タグはオペレーションのtags配列とスペックレベルのtagsリストの両方に追加されます。

未使用コンポーネントの削除

ルール: oas3-unused-component | コントラクト変更: なし

スペック内のどこからも参照されていないコンポーネントスキーマをcomponents.schemasから削除します。オペレーションに影響を与えることなくスペックサイズを削減します。

OperationIdの重複排除

ルール: operation-operationId-unique | コントラクト変更: なし

複数のオペレーションが同じoperationIdを共有している場合、HTTPメソッドをサフィックスとして付加します（例：ListItems_get）。これにより、コードジェネレーター向けに各operationIdを一意にします。

無効なExample/Defaultの削除

ルール: oas3-valid-schema-example | コントラクト変更: なし

値がスキーマ自体の制約に適合しない場合（型の不一致、範囲外など）、スキーマからexampleまたはdefault値を削除します。コードジェネレーターが無効なサンプルペイロードを生成するのを防ぎます。

Scriptタグの除去

ルール: no-script-tags-in-markdown | コントラクト変更: なし

正規表現置換を使用してdescriptionフィールドから<script>タグを除去します。一部の上流スペックには、ドキュメントレンダラーを壊すインジェクトされたスクリプトタグが含まれています。

セキュリティメタデータ

コントラクト変更: なし（ドキュメントのみ）

すべてのスペックには、まだ存在しない場合にapiKeyAuthセキュリティスキームが追加されます。これはSpectralがフラグを立てたかどうかに関係なく、常に挿入されます。

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

スキーム定義はvalidation.yamlのspectral.security_schemeから取得されます。これはAPIコンシューマーに認証方法を伝えますが、ランタイム動作は変更しません。

JSONフォーマット

コントラクト変更: なし

すべての出力JSONスペックは、Biome互換の配列コンパクター（scripts/utils/spec_loader.pyの_compact_short_arrays）を通過します。120文字以内に収まる短い配列は1行に折りたたまれます：

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

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

行長の閾値を超える配列は複数行のまま維持されます。

修正の優先順位

複数の修正戦略が適用可能な場合、リコンサイラーはreconciliation.priorityで設定された優先順位を使用します：

existing — 既存のスペック制約が有効であればそれを使用
discovery — 発見されたライブAPI動作を使用
inferred — 類似エンドポイント間のパターンから推論

すべての修正が適用された後、修正済みスペックはopenapi-spec-validatorで検証されます。検証が失敗した場合、元のスペックがフォールバックとして使用され、修正はエラーとしてログに記録されます。