Feat/openapi 3.1 support

[AlinsRan]

Summary

Comprehensive OpenAPI 3.1 / JSON Schema 2020-12 support, building on the base implementation in getkin/kin-openapi#1125.

This PR adds the remaining implementation on top of that base: built-in validator enhancements, components/pathItems support, and anchor resolution.

---

What this PR does

1. components/pathItems — full implementation (OAS 3.1)

OAS 3.1 added components/pathItems for reusable path items referenced via $ref from paths.

• Added PathItems map[string]*PathItem type with JSONLookup for JSON Pointer support
• Added Components.PathItems PathItems field with full marshal/unmarshal/validate
• UnmarshalJSON deletes "pathItems" from Extensions (no longer treated as unknown extension)
• Components.Validate() iterates and validates each pathItem entry
• Loader.ResolveRefsIn() now iterates components.PathItems and resolves $ref within each PathItem
• MarshalYAML emits pathItems when non-empty
• Docs regenerated

Tests added:

• openapi3/loader_test.go: TestLoadComponentsPathItems — verifies loader resolves $ref in components/pathItems
• routers/gorillamux/router_test.go: TestRouterComponentsPathItems — verifies router finds routes through components/pathItems $ref
• openapi3filter/validate_request_test.go: TestValidateRequestComponentsPathItems — verifies request validation through components/pathItems $ref
• openapi3filter/components_path_items_test.go: TestComponentsPathItemsDocValidate, TestComponentsPathItemsRefResolved, TestComponentsPathItemsRouterAndValidation
• openapi3filter/components_path_items_maingo_test.go: TestComponentsPathItemsValidateRequestSimulateMainGo

---

2. Built-in validator enhancements (OAS 3.1 / JSON Schema 2020-12)

Features implemented directly in the built-in validator (schema.go) without requiring EnableJSONSchema2020():

prefixItems — positional tuple validation

• visitJSONArray validates each array element against its corresponding prefixItems schema by position
• items schema now applies only to elements beyond the prefixItems tuple length (correct 3.1 semantics; in 3.0, items applied to all elements)

patternProperties — pattern-based property validation

• visitJSONObject compiles each pattern, matches against property names, and validates matched values
• Tracks matchedPattern set for correct additionalProperties interaction

const: null — null value constraint (ConstIsSet flag)

• Added ConstIsSet bool field (not serialized) that is set by UnmarshalJSON when "const" key is present
• visitConstOperation skips only when !ConstIsSet && Const == nil, allowing const: null to correctly reject non-null values
• Fixes ambiguity between "no const constraint" (Const == nil, ConstIsSet == false) and "must be null" (Const == nil, ConstIsSet == true)

Silent fallback fix

• visitJSONWithJSONSchema previously silently passed validation if JSON Schema compilation failed
• Now falls back to the built-in validator on compilation failure, ensuring validation is always applied

---

3. Loader enhancements

$anchor fragment resolution

• Loader builds an anchorIndex map[string]*Schema during resolveSchemaRef
• resolveComponent resolves bare fragment $refs (e.g., "#AnchorName") by looking up the anchor index
• Enables schemas with $anchor to be referenced directly by anchor name

$dynamicAnchor indexing

• Loader builds dynamicAnchorIndex map[string]*Schema alongside anchorIndex
• Groundwork for full $dynamicRef resolution (not yet dereferenced)

Sibling $ref merge (3.1 only)

• In OAS 3.1, keywords alongside $ref (e.g., description, title, default, nullable, example) are valid and must be applied
• Added mergeSiblingFields() in loader; applied when doc.IsOpenAPI3_1() and sibling fields are present
• Supported siblings: description, title, default, readOnly, writeOnly, deprecated, nullable, example, externalDocs

---

4. Format as annotation-only (3.1)

• Per JSON Schema 2020-12, format is an annotation (not a validator)
• visitJSONNumber and visitJSONString now skip format enforcement when useJSONSchema2020 is active
• Prevents spurious validation errors for formats in 3.1 documents

---

OAS 3.1 Validation Feature Coverage

Feature	Built-in validator	JSON Schema 2020-12	Tests
prefixItems (tuple)	✅ implemented	✅ via santhosh-tekuri	✅
patternProperties	✅ implemented	✅ via santhosh-tekuri	partial (doc-level only)
const: null	✅ fixed (ConstIsSet)	✅ via santhosh-tekuri	partial
$anchor resolution	✅ loader	✅ via santhosh-tekuri	no dedicated test
$dynamicAnchor indexing	✅ indexed	✅ via santhosh-tekuri	no dedicated test
Sibling $ref merge	✅ loader (3.1 only)	n/a	no dedicated test
Format annotation-only	✅ skipped in 3.1	✅ via santhosh-tekuri	no dedicated test
type arrays with null	✅ (base PR)	✅ via santhosh-tekuri	✅
exclusiveMin/Max numeric	✅ (base PR)	✅ via santhosh-tekuri	✅
if/then/else	❌ silently ignored	✅ via santhosh-tekuri	✅ (2020-12 path)
dependentRequired	❌ silently ignored	✅ via santhosh-tekuri	✅ (2020-12 path)
contains/minContains/maxContains	❌ silently ignored	✅ via santhosh-tekuri	partial
unevaluatedItems	❌ silently ignored	✅ via santhosh-tekuri	partial
unevaluatedProperties	❌ silently ignored	✅ via santhosh-tekuri	partial
dependentSchemas	❌ silently ignored	✅ via santhosh-tekuri	partial
propertyNames	❌ silently ignored	✅ via santhosh-tekuri	partial
components/pathItems	✅ full	n/a	✅
$dynamicRef	❌ not dereferenced	✅ via santhosh-tekuri	no test
Webhooks	✅ (base PR)	n/a	✅

Note on built-in vs JSON Schema 2020-12 validator: Features marked "silently ignored" in the built-in validator are fully supported when EnableJSONSchema2020() (per-schema) or EnableJSONSchema2020Validation() (document-level) is used. For OAS 3.1 documents, doc.Validate() auto-enables JSON Schema 2020-12 mode. The built-in validator handles the most common keywords (prefixItems, patternProperties, const: null) directly for use without the external dependency.

---

Known limitations (follow-up work)

1. $dynamicRef not dereferenced — $dynamicAnchor is indexed but $dynamicRef is not resolved during loading. Schemas using $dynamicRef for recursive polymorphism will not work correctly.
2. Built-in validator does not evaluate if/then/else, contains, unevaluated*, dependentSchemas, propertyNames — these require EnableJSONSchema2020(). By design for now.
3. patternProperties + additionalProperties: false edge case — additionalProperties: false may incorrectly reject properties that match a pattern property when the built-in validator is used.
4. contentMediaType/contentEncoding not validated — annotation-only per JSON Schema 2020-12 spec; no runtime validation.

---

Backward compatibility

• 100% backward compatible with OpenAPI 3.0
• ConstIsSet is a non-serialized field; existing schemas unaffected
• PathItems type is additive; existing code using Components continues to work