Skip to content

fix: resolve $ref in OpenAPI 3.1 schema fields#1120

Closed
reuvenharrison wants to merge 15 commits intogetkin:masterfrom
oasdiff:fix/resolve-refs-in-3.1-schema-fields
Closed

fix: resolve $ref in OpenAPI 3.1 schema fields#1120
reuvenharrison wants to merge 15 commits intogetkin:masterfrom
oasdiff:fix/resolve-refs-in-3.1-schema-fields

Conversation

@reuvenharrison
Copy link
Contributor

Summary

  • Fix resolveSchemaRef to resolve $ref references inside OpenAPI 3.1 / JSON Schema 2020-12 schema fields

Problem

When loading an OpenAPI 3.1 document that uses $ref inside any of the new JSON Schema 2020-12 fields, the referenced Schema.Value remained nil because resolveSchemaRef only processed pre-3.1 fields (items, properties, additionalProperties, not, allOf, anyOf, oneOf).

Example that failed:

openapi: "3.1.0"
components:
  schemas:
    StringType:
      type: string
    TupleArray:
      type: array
      prefixItems:
        - $ref: "#/components/schemas/StringType"  # This ref was not resolved

The following fields were affected:

  • prefixItems — tuple validation schemas
  • contains — array containment schema
  • patternProperties — pattern-based property schemas
  • dependentSchemas — conditional schema dependencies
  • propertyNames — property name validation schema
  • unevaluatedItems — unevaluated array items schema
  • unevaluatedProperties — unevaluated object properties schema

Solution

Add ref resolution for all OpenAPI 3.1 schema fields in resolveSchemaRef, following the same patterns already used for the existing fields.

Related

Follow-up to PR #1114 (OpenAPI 3.1 support).

Test plan

  • New test TestResolveSchemaRefsIn31Fields verifies all 7 field types resolve correctly
  • All existing tests pass

🤖 Generated with Claude Code

Chance Kirsch and others added 15 commits October 2, 2025 08:46
The implementation provides complete OpenAPI 3.1 specification compliance while maintaining 100% backward compatibility with OpenAPI 3.0.

## What Was Implemented

### 1. Schema Object Extensions (openapi3/schema.go)

Added full JSON Schema 2020-12 support with new fields:

- **`Const`** - Constant value validation
- **`Examples`** - Array of examples (replaces singular `example`)
- **`PrefixItems`** - Tuple validation for arrays
- **`Contains`, `MinContains`, `MaxContains`** - Array containment validation
- **`PatternProperties`** - Pattern-based property matching
- **`DependentSchemas`** - Conditional schema dependencies
- **`PropertyNames`** - Property name validation
- **`UnevaluatedItems`, `UnevaluatedProperties`** - Unevaluated keyword support
- **Type arrays** - Support for `["string", "null"]` notation

### 2. Document-Level Features (openapi3/openapi3.go)

- **`Webhooks`** - New field for defining webhook callbacks (OpenAPI 3.1)
- **`JSONSchemaDialect`** - Specifies default JSON Schema dialect
- **Version detection methods**:
  - `IsOpenAPI3_0()` - Returns true for 3.0.x documents
  - `IsOpenAPI3_1()` - Returns true for 3.1.x documents
  - `Version()` - Returns major.minor version string

### 3. License Object (openapi3/license.go)

- **`Identifier`** - SPDX license expression (alternative to URL)

### 4. Info Object (openapi3/info.go)

- **`Summary`** - Short summary of the API (OpenAPI 3.1)

### 5. Types Helper Methods (openapi3/schema.go)

New methods for working with type arrays:

- `IncludesNull()` - Checks if null type is included
- `IsMultiple()` - Detects type arrays (OpenAPI 3.1 feature)
- `IsSingle()` - Checks for single type
- `IsEmpty()` - Checks for unspecified types

### 6. JSON Schema 2020-12 Validator (openapi3/schema_jsonschema_validator.go)

A new opt-in validator using [santhosh-tekuri/jsonschema/v6](https://github.com/santhosh-tekuri/jsonschema):

- Full JSON Schema Draft 2020-12 compliance
- Automatic OpenAPI → JSON Schema transformation
- Converts OpenAPI 3.0 `nullable` to type arrays
- Handles `exclusiveMinimum`/`exclusiveMaximum` conversion
- Comprehensive error formatting
- Fallback to built-in validator on compilation errors
…d formatting and correcting the version logic
The ResolveRefsIn function was not resolving $ref references inside
webhooks, causing Schema.Value to be nil when a webhook operation
referenced a component schema.

This adds webhook ref resolution after the paths loop, using the same
resolvePathItemRef function since webhooks contain PathItem objects.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
In OpenAPI 3.0 (JSON Schema draft-04), exclusiveMinimum/exclusiveMaximum
are booleans that modify minimum/maximum values.

In OpenAPI 3.1 (JSON Schema 2020-12), they are numbers representing
the actual exclusive bounds.

This change introduces ExclusiveBound type that can hold either:
- Bool: for OpenAPI 3.0 style boolean modifier
- Value: for OpenAPI 3.1 style numeric bound

The validation and marshaling logic handles both formats correctly.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
…, etc.)

The loader's resolveSchemaRef only resolved $ref in pre-3.1 fields (items,
properties, additionalProperties, not, allOf, anyOf, oneOf). References
inside the new OpenAPI 3.1 / JSON Schema 2020-12 fields were silently
left unresolved, causing nil Value pointers.

This adds ref resolution for: prefixItems, contains, patternProperties,
dependentSchemas, propertyNames, unevaluatedItems, unevaluatedProperties.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@reuvenharrison
Copy link
Contributor Author

Superseded by #1125 which consolidates all OpenAPI 3.1 PRs into a single PR.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants