From 79ac3c4d3609fcc1f94e9588533dd5c3d86070a5 Mon Sep 17 00:00:00 2001 From: Pierre Fenoll Date: Mon, 19 Oct 2026 21:10:37 +0200 Subject: [PATCH 01/78] openapi3: ignore the fields next to a Reference Object's $ref in every version The Reference Object of OpenAPI 3.0, 3.1 and 3.2 alike says "any properties added SHALL be ignored". From 3.1 on only summary and description mean something there, and the loader already applies them; anything else was still reported as extra sibling fields, failing documents the specification calls valid. So validateExtras now only reports the x- extensions next to a $ref, under ProhibitExtensionsWithRef. That option was disabled for OpenAPI 3.1 schemas, only because their sibling keywords were reported together with those extensions: it now applies in every version, as documented. ExtraSiblingFieldsError is still returned for the unknown fields of inline objects. validateExtras also reported the fields next to a $ref once the $ref was gone: InternalizeRefs replaces a component that is a $ref by what it refers to, which leaves those fields out of the document, but not out of what Validate checked. Signed-off-by: Pierre Fenoll --- .github/docs/openapi3.txt | 9 +- README.md | 1 + openapi3/reference_object_siblings_test.go | 97 +++++ openapi3/refs.go | 410 ++++++--------------- openapi3/refs.tmpl | 54 +-- openapi3/refs_test.go | 34 +- openapi3/refs_test.tmpl | 6 +- openapi3/validation_options.go | 6 +- 8 files changed, 247 insertions(+), 370 deletions(-) create mode 100644 openapi3/reference_object_siblings_test.go diff --git a/.github/docs/openapi3.txt b/.github/docs/openapi3.txt index 66f9acf65..1c77fe090 100644 --- a/.github/docs/openapi3.txt +++ b/.github/docs/openapi3.txt @@ -4207,7 +4207,10 @@ func AllowExtensionsWithRef() ValidationOption func AllowExtraSiblingFields(fields ...string) ValidationOption AllowExtraSiblingFields called as AllowExtraSiblingFields("description") - makes Validate not return an error when said field appears next to a $ref. + makes Validate not return an error when said field appears where it is + not expected: as an unknown field of an object, as an OpenAPI 3.1 schema + keyword in an OpenAPI 3.0 document, or as an extension next to a $ref under + ProhibitExtensionsWithRef. Other fields next to a $ref are never an error. func DisableExamplesValidation() ValidationOption DisableExamplesValidation disables all example schema validation. @@ -4269,8 +4272,8 @@ func IsOpenAPI32OrLater() ValidationOption func ProhibitExtensionsWithRef() ValidationOption ProhibitExtensionsWithRef causes the validation to return an error if extensions (fields starting with 'x-') are found as siblings for $ref - fields, even in OpenAPI 3.0. Use AllowExtraSiblingFields to allow specific - extensions. + fields, in every OpenAPI version. Use AllowExtraSiblingFields to allow + specific extensions. func SetRegexCompiler(c RegexCompilerFunc) ValidationOption SetRegexCompiler allows to override the regex implementation used to diff --git a/README.md b/README.md index 0ba04f93d..2f2da6e6d 100644 --- a/README.md +++ b/README.md @@ -337,6 +337,7 @@ for _, path := range doc.Paths.InMatchingOrder() { * The error for a header with neither or both of `content` and `schema` reads `header must contain exactly one of content and schema`. It used to say `parameter ...` followed by a `%v` dump of the `Header` struct, which printed heap addresses: the message differed between two runs over the same document, and leaked addresses into anything that logged it. * `openapi3filter` now parses `integer` values of parameters and `application/x-www-form-urlencoded`/`multipart/form-data` bodies as base 10 only, so `010` decodes to `10` rather than `8`, and Go integer literals such as `0x10`, `0b10`, `0o10` or `1_000` are now rejected as invalid integers. * `openapi3filter.ValidateResponse` now decodes and validates response headers described with `content` rather than `schema`, with the body decoder registered for the header's media type (see `RegisterBodyDecoder`). Such a header is no longer reported missing when it is required and present, and a value that does not match its schema is now rejected. As with a response body, a media type with no registered decoder fails with `unsupported content type`. +* `Validate` no longer reports `extra sibling fields` for fields written next to a `$ref`: every version's Reference Object says they "SHALL be ignored". From OpenAPI 3.1 on, `summary` and `description` still override the referenced component's. `ExtraSiblingFieldsError` is still returned for unknown fields of inline objects, and for `x-` extensions next to a `$ref` under `ProhibitExtensionsWithRef`, which now applies to OpenAPI 3.1+ schemas too. It is no longer returned after `InternalizeRefs` for the fields that were next to a component's `$ref` it replaced, and which it leaves out. ### v0.150.0 * `openapi2.Operation.Responses` field type changed from `map[string]*Response` to `*Responses`, which keeps the Responses Object's `x-` extensions in `Responses.Extensions` instead of failing to decode them as responses. diff --git a/openapi3/reference_object_siblings_test.go b/openapi3/reference_object_siblings_test.go new file mode 100644 index 000000000..3f4941d19 --- /dev/null +++ b/openapi3/reference_object_siblings_test.go @@ -0,0 +1,97 @@ +package openapi3_test + +import ( + "fmt" + "testing" + + "github.com/stretchr/testify/require" + + "github.com/getkin/kin-openapi/openapi3" +) + +// Every version's Reference Object says "any properties added SHALL be +// ignored". From 3.1 on summary and description are fixed fields that override +// the referenced component's. +func TestReferenceObjectSiblingsAreIgnored(t *testing.T) { + t.Parallel() + for _, version := range []string{"3.0.3", "3.1.0", "3.2.0"} { + t.Run(version, func(t *testing.T) { + t.Parallel() + loader := openapi3.NewLoader() + doc, err := loader.LoadFromData(fmt.Appendf(nil, `{ + "openapi": %q, + "info": {"title": "t", "version": "1"}, + "paths": {"/x": {"get": {"responses": {"200": { + "$ref": "#/components/responses/R", + "description": "local", + "unknown": 1 + }}}}}, + "components": {"responses": {"R": {"description": "target"}}} +}`, version)) + require.NoError(t, err) + require.NoError(t, doc.Validate(t.Context())) + + want := "local" + if doc.IsOpenAPI30() { + want = "target" + } + response := doc.Paths.Value("/x").Get.Responses.Value("200").Value + require.Equal(t, want, *response.Description) + }) + } +} + +// InternalizeRefs replaces a component that is a $ref by what it refers to, +// which leaves out the fields that were next to the $ref. +func TestReferenceObjectSiblingsAreGoneOnceInternalized(t *testing.T) { + t.Parallel() + for _, version := range []string{"3.0.3", "3.1.0"} { + t.Run(version, func(t *testing.T) { + t.Parallel() + loader := openapi3.NewLoader() + doc, err := loader.LoadFromData(fmt.Appendf(nil, `{ + "openapi": %q, + "info": {"title": "t", "version": "1"}, + "paths": {}, + "components": { + "schemas": { + "A": {"type": "string"}, + "B": {"$ref": "#/components/schemas/A", "minLength": 2} + }, + "parameters": { + "P": {"name": "p", "in": "query", "schema": {"type": "string"}}, + "Q": {"$ref": "#/components/parameters/P", "description": "local", "unknown": 1} + } + } +}`, version)) + require.NoError(t, err) + require.NoError(t, doc.Validate(t.Context())) + + doc.InternalizeRefs(t.Context(), nil) + require.NoError(t, doc.Validate(t.Context())) + }) + } +} + +func TestProhibitExtensionsWithRefInEveryVersion(t *testing.T) { + t.Parallel() + for _, version := range []string{"3.0.3", "3.1.0"} { + t.Run(version, func(t *testing.T) { + t.Parallel() + loader := openapi3.NewLoader() + doc, err := loader.LoadFromData(fmt.Appendf(nil, `{ + "openapi": %q, + "info": {"title": "t", "version": "1"}, + "paths": {}, + "components": {"schemas": { + "A": {"type": "string"}, + "B": {"$ref": "#/components/schemas/A", "x-order": 1} + }} +}`, version)) + require.NoError(t, err) + require.NoError(t, doc.Validate(t.Context())) + require.ErrorContains(t, doc.Validate(t.Context(), openapi3.ProhibitExtensionsWithRef()), "extra sibling fields: [x-order]") + require.NoError(t, doc.Validate(t.Context(), openapi3.ProhibitExtensionsWithRef(), openapi3.AllowExtraSiblingFields("x-order"))) + }) + } +} diff --git a/openapi3/refs.go b/openapi3/refs.go index 44a0645c7..3f2c22706 100644 --- a/openapi3/refs.go +++ b/openapi3/refs.go @@ -102,46 +102,24 @@ func (x *CallbackRef) UnmarshalJSON(data []byte) error { return unmarshalJSON(data, &x.Value) } -// validateExtras returns an error if CallbackRef has sibling fields -// alongside $ref that are not allowed by the validation options. +// validateExtras returns an error if CallbackRef has `x-` extensions +// next to its $ref while ProhibitExtensionsWithRef is set. Every other field +// next to a $ref is not an error: every version's Reference Object says "any +// properties added SHALL be ignored", from 3.1 on summary and description +// override the referenced component's, and an OpenAPI 3.1 schema applies its +// sibling keywords alongside the referenced schema. func (x *CallbackRef) validateExtras(ctx context.Context) error { validationOpts := getValidationOptions(ctx) - var extras []string - - allowed := validationOpts.extraSiblingFieldsAllowed - if allowed == nil { - allowed = make(map[string]struct{}) - } - if x.Ref == "" && !validationOpts.isOpenAPI31OrLater { - if _, ok := allowed["description"]; x.Description != nil && !ok { - extras = append(extras, "description") - } - if _, ok := allowed["summary"]; x.Summary != nil && !ok { - extras = append(extras, "summary") - } - } - // OpenAPI 3.0 Reference Objects ignore added properties. Keep the - // explicit extension policy below and validation of inline objects. - if x.Ref == "" || validationOpts.isOpenAPI31OrLater { - for _, ex := range x.extra { - if _, ok := allowed[ex]; !ok { - if _, ok := x.Extensions[ex]; !ok { - extras = append(extras, ex) - } - // extras in the Extensions checked below - } - } + if x.Ref == "" || !validationOpts.schemaExtensionsInRefProhibited { + return nil } - if validationOpts.schemaExtensionsInRefProhibited { - for _, ex := range componentNames(x.Extensions) { - if _, ok := allowed[ex]; !ok { - extras = append(extras, ex) - } - // extras in the Extensions checked below + var extras []string + for _, ex := range componentNames(x.Extensions) { + if _, ok := validationOpts.extraSiblingFieldsAllowed[ex]; !ok { + extras = append(extras, ex) } } - if len(extras) != 0 { return newExtraSiblingFields(extras, x.Origin) } @@ -271,46 +249,24 @@ func (x *ExampleRef) UnmarshalJSON(data []byte) error { return unmarshalJSON(data, &x.Value) } -// validateExtras returns an error if ExampleRef has sibling fields -// alongside $ref that are not allowed by the validation options. +// validateExtras returns an error if ExampleRef has `x-` extensions +// next to its $ref while ProhibitExtensionsWithRef is set. Every other field +// next to a $ref is not an error: every version's Reference Object says "any +// properties added SHALL be ignored", from 3.1 on summary and description +// override the referenced component's, and an OpenAPI 3.1 schema applies its +// sibling keywords alongside the referenced schema. func (x *ExampleRef) validateExtras(ctx context.Context) error { validationOpts := getValidationOptions(ctx) - var extras []string - - allowed := validationOpts.extraSiblingFieldsAllowed - if allowed == nil { - allowed = make(map[string]struct{}) - } - if x.Ref == "" && !validationOpts.isOpenAPI31OrLater { - if _, ok := allowed["description"]; x.Description != nil && !ok { - extras = append(extras, "description") - } - if _, ok := allowed["summary"]; x.Summary != nil && !ok { - extras = append(extras, "summary") - } - } - // OpenAPI 3.0 Reference Objects ignore added properties. Keep the - // explicit extension policy below and validation of inline objects. - if x.Ref == "" || validationOpts.isOpenAPI31OrLater { - for _, ex := range x.extra { - if _, ok := allowed[ex]; !ok { - if _, ok := x.Extensions[ex]; !ok { - extras = append(extras, ex) - } - // extras in the Extensions checked below - } - } + if x.Ref == "" || !validationOpts.schemaExtensionsInRefProhibited { + return nil } - if validationOpts.schemaExtensionsInRefProhibited { - for _, ex := range componentNames(x.Extensions) { - if _, ok := allowed[ex]; !ok { - extras = append(extras, ex) - } - // extras in the Extensions checked below + var extras []string + for _, ex := range componentNames(x.Extensions) { + if _, ok := validationOpts.extraSiblingFieldsAllowed[ex]; !ok { + extras = append(extras, ex) } } - if len(extras) != 0 { return newExtraSiblingFields(extras, x.Origin) } @@ -440,46 +396,24 @@ func (x *HeaderRef) UnmarshalJSON(data []byte) error { return unmarshalJSON(data, &x.Value) } -// validateExtras returns an error if HeaderRef has sibling fields -// alongside $ref that are not allowed by the validation options. +// validateExtras returns an error if HeaderRef has `x-` extensions +// next to its $ref while ProhibitExtensionsWithRef is set. Every other field +// next to a $ref is not an error: every version's Reference Object says "any +// properties added SHALL be ignored", from 3.1 on summary and description +// override the referenced component's, and an OpenAPI 3.1 schema applies its +// sibling keywords alongside the referenced schema. func (x *HeaderRef) validateExtras(ctx context.Context) error { validationOpts := getValidationOptions(ctx) - var extras []string - - allowed := validationOpts.extraSiblingFieldsAllowed - if allowed == nil { - allowed = make(map[string]struct{}) - } - if x.Ref == "" && !validationOpts.isOpenAPI31OrLater { - if _, ok := allowed["description"]; x.Description != nil && !ok { - extras = append(extras, "description") - } - if _, ok := allowed["summary"]; x.Summary != nil && !ok { - extras = append(extras, "summary") - } - } - // OpenAPI 3.0 Reference Objects ignore added properties. Keep the - // explicit extension policy below and validation of inline objects. - if x.Ref == "" || validationOpts.isOpenAPI31OrLater { - for _, ex := range x.extra { - if _, ok := allowed[ex]; !ok { - if _, ok := x.Extensions[ex]; !ok { - extras = append(extras, ex) - } - // extras in the Extensions checked below - } - } + if x.Ref == "" || !validationOpts.schemaExtensionsInRefProhibited { + return nil } - if validationOpts.schemaExtensionsInRefProhibited { - for _, ex := range componentNames(x.Extensions) { - if _, ok := allowed[ex]; !ok { - extras = append(extras, ex) - } - // extras in the Extensions checked below + var extras []string + for _, ex := range componentNames(x.Extensions) { + if _, ok := validationOpts.extraSiblingFieldsAllowed[ex]; !ok { + extras = append(extras, ex) } } - if len(extras) != 0 { return newExtraSiblingFields(extras, x.Origin) } @@ -609,46 +543,24 @@ func (x *LinkRef) UnmarshalJSON(data []byte) error { return unmarshalJSON(data, &x.Value) } -// validateExtras returns an error if LinkRef has sibling fields -// alongside $ref that are not allowed by the validation options. +// validateExtras returns an error if LinkRef has `x-` extensions +// next to its $ref while ProhibitExtensionsWithRef is set. Every other field +// next to a $ref is not an error: every version's Reference Object says "any +// properties added SHALL be ignored", from 3.1 on summary and description +// override the referenced component's, and an OpenAPI 3.1 schema applies its +// sibling keywords alongside the referenced schema. func (x *LinkRef) validateExtras(ctx context.Context) error { validationOpts := getValidationOptions(ctx) - var extras []string - - allowed := validationOpts.extraSiblingFieldsAllowed - if allowed == nil { - allowed = make(map[string]struct{}) - } - if x.Ref == "" && !validationOpts.isOpenAPI31OrLater { - if _, ok := allowed["description"]; x.Description != nil && !ok { - extras = append(extras, "description") - } - if _, ok := allowed["summary"]; x.Summary != nil && !ok { - extras = append(extras, "summary") - } - } - // OpenAPI 3.0 Reference Objects ignore added properties. Keep the - // explicit extension policy below and validation of inline objects. - if x.Ref == "" || validationOpts.isOpenAPI31OrLater { - for _, ex := range x.extra { - if _, ok := allowed[ex]; !ok { - if _, ok := x.Extensions[ex]; !ok { - extras = append(extras, ex) - } - // extras in the Extensions checked below - } - } + if x.Ref == "" || !validationOpts.schemaExtensionsInRefProhibited { + return nil } - if validationOpts.schemaExtensionsInRefProhibited { - for _, ex := range componentNames(x.Extensions) { - if _, ok := allowed[ex]; !ok { - extras = append(extras, ex) - } - // extras in the Extensions checked below + var extras []string + for _, ex := range componentNames(x.Extensions) { + if _, ok := validationOpts.extraSiblingFieldsAllowed[ex]; !ok { + extras = append(extras, ex) } } - if len(extras) != 0 { return newExtraSiblingFields(extras, x.Origin) } @@ -778,46 +690,24 @@ func (x *ParameterRef) UnmarshalJSON(data []byte) error { return unmarshalJSON(data, &x.Value) } -// validateExtras returns an error if ParameterRef has sibling fields -// alongside $ref that are not allowed by the validation options. +// validateExtras returns an error if ParameterRef has `x-` extensions +// next to its $ref while ProhibitExtensionsWithRef is set. Every other field +// next to a $ref is not an error: every version's Reference Object says "any +// properties added SHALL be ignored", from 3.1 on summary and description +// override the referenced component's, and an OpenAPI 3.1 schema applies its +// sibling keywords alongside the referenced schema. func (x *ParameterRef) validateExtras(ctx context.Context) error { validationOpts := getValidationOptions(ctx) - var extras []string - - allowed := validationOpts.extraSiblingFieldsAllowed - if allowed == nil { - allowed = make(map[string]struct{}) - } - if x.Ref == "" && !validationOpts.isOpenAPI31OrLater { - if _, ok := allowed["description"]; x.Description != nil && !ok { - extras = append(extras, "description") - } - if _, ok := allowed["summary"]; x.Summary != nil && !ok { - extras = append(extras, "summary") - } - } - // OpenAPI 3.0 Reference Objects ignore added properties. Keep the - // explicit extension policy below and validation of inline objects. - if x.Ref == "" || validationOpts.isOpenAPI31OrLater { - for _, ex := range x.extra { - if _, ok := allowed[ex]; !ok { - if _, ok := x.Extensions[ex]; !ok { - extras = append(extras, ex) - } - // extras in the Extensions checked below - } - } + if x.Ref == "" || !validationOpts.schemaExtensionsInRefProhibited { + return nil } - if validationOpts.schemaExtensionsInRefProhibited { - for _, ex := range componentNames(x.Extensions) { - if _, ok := allowed[ex]; !ok { - extras = append(extras, ex) - } - // extras in the Extensions checked below + var extras []string + for _, ex := range componentNames(x.Extensions) { + if _, ok := validationOpts.extraSiblingFieldsAllowed[ex]; !ok { + extras = append(extras, ex) } } - if len(extras) != 0 { return newExtraSiblingFields(extras, x.Origin) } @@ -947,46 +837,24 @@ func (x *RequestBodyRef) UnmarshalJSON(data []byte) error { return unmarshalJSON(data, &x.Value) } -// validateExtras returns an error if RequestBodyRef has sibling fields -// alongside $ref that are not allowed by the validation options. +// validateExtras returns an error if RequestBodyRef has `x-` extensions +// next to its $ref while ProhibitExtensionsWithRef is set. Every other field +// next to a $ref is not an error: every version's Reference Object says "any +// properties added SHALL be ignored", from 3.1 on summary and description +// override the referenced component's, and an OpenAPI 3.1 schema applies its +// sibling keywords alongside the referenced schema. func (x *RequestBodyRef) validateExtras(ctx context.Context) error { validationOpts := getValidationOptions(ctx) - var extras []string - - allowed := validationOpts.extraSiblingFieldsAllowed - if allowed == nil { - allowed = make(map[string]struct{}) - } - if x.Ref == "" && !validationOpts.isOpenAPI31OrLater { - if _, ok := allowed["description"]; x.Description != nil && !ok { - extras = append(extras, "description") - } - if _, ok := allowed["summary"]; x.Summary != nil && !ok { - extras = append(extras, "summary") - } - } - // OpenAPI 3.0 Reference Objects ignore added properties. Keep the - // explicit extension policy below and validation of inline objects. - if x.Ref == "" || validationOpts.isOpenAPI31OrLater { - for _, ex := range x.extra { - if _, ok := allowed[ex]; !ok { - if _, ok := x.Extensions[ex]; !ok { - extras = append(extras, ex) - } - // extras in the Extensions checked below - } - } + if x.Ref == "" || !validationOpts.schemaExtensionsInRefProhibited { + return nil } - if validationOpts.schemaExtensionsInRefProhibited { - for _, ex := range componentNames(x.Extensions) { - if _, ok := allowed[ex]; !ok { - extras = append(extras, ex) - } - // extras in the Extensions checked below + var extras []string + for _, ex := range componentNames(x.Extensions) { + if _, ok := validationOpts.extraSiblingFieldsAllowed[ex]; !ok { + extras = append(extras, ex) } } - if len(extras) != 0 { return newExtraSiblingFields(extras, x.Origin) } @@ -1116,46 +984,24 @@ func (x *ResponseRef) UnmarshalJSON(data []byte) error { return unmarshalJSON(data, &x.Value) } -// validateExtras returns an error if ResponseRef has sibling fields -// alongside $ref that are not allowed by the validation options. +// validateExtras returns an error if ResponseRef has `x-` extensions +// next to its $ref while ProhibitExtensionsWithRef is set. Every other field +// next to a $ref is not an error: every version's Reference Object says "any +// properties added SHALL be ignored", from 3.1 on summary and description +// override the referenced component's, and an OpenAPI 3.1 schema applies its +// sibling keywords alongside the referenced schema. func (x *ResponseRef) validateExtras(ctx context.Context) error { validationOpts := getValidationOptions(ctx) - var extras []string - - allowed := validationOpts.extraSiblingFieldsAllowed - if allowed == nil { - allowed = make(map[string]struct{}) - } - if x.Ref == "" && !validationOpts.isOpenAPI31OrLater { - if _, ok := allowed["description"]; x.Description != nil && !ok { - extras = append(extras, "description") - } - if _, ok := allowed["summary"]; x.Summary != nil && !ok { - extras = append(extras, "summary") - } - } - // OpenAPI 3.0 Reference Objects ignore added properties. Keep the - // explicit extension policy below and validation of inline objects. - if x.Ref == "" || validationOpts.isOpenAPI31OrLater { - for _, ex := range x.extra { - if _, ok := allowed[ex]; !ok { - if _, ok := x.Extensions[ex]; !ok { - extras = append(extras, ex) - } - // extras in the Extensions checked below - } - } + if x.Ref == "" || !validationOpts.schemaExtensionsInRefProhibited { + return nil } - if validationOpts.schemaExtensionsInRefProhibited { - for _, ex := range componentNames(x.Extensions) { - if _, ok := allowed[ex]; !ok { - extras = append(extras, ex) - } - // extras in the Extensions checked below + var extras []string + for _, ex := range componentNames(x.Extensions) { + if _, ok := validationOpts.extraSiblingFieldsAllowed[ex]; !ok { + extras = append(extras, ex) } } - if len(extras) != 0 { return newExtraSiblingFields(extras, x.Origin) } @@ -1295,42 +1141,26 @@ func (x *SchemaRef) UnmarshalJSON(data []byte) error { return unmarshalJSON(data, &x.Value) } -// validateExtras returns an error if SchemaRef has sibling fields -// alongside $ref that are not allowed by the validation options. +// validateExtras returns an error if SchemaRef has `x-` extensions +// next to its $ref while ProhibitExtensionsWithRef is set. Every other field +// next to a $ref is not an error: every version's Reference Object says "any +// properties added SHALL be ignored", from 3.1 on summary and description +// override the referenced component's, and an OpenAPI 3.1 schema applies its +// sibling keywords alongside the referenced schema. func (x *SchemaRef) validateExtras(ctx context.Context) error { validationOpts := getValidationOptions(ctx) - var extras []string - - allowed := validationOpts.extraSiblingFieldsAllowed - if allowed == nil { - allowed = make(map[string]struct{}) - } - // OpenAPI 3.0 Reference Objects ignore added properties. Keep the - // explicit extension policy below and validation of inline objects. - if x.Ref == "" || validationOpts.isOpenAPI31OrLater { - for _, ex := range x.extra { - if _, ok := allowed[ex]; !ok { - if _, ok := x.Extensions[ex]; !ok { - extras = append(extras, ex) - } - // extras in the Extensions checked below - } - } + if x.Ref == "" || !validationOpts.schemaExtensionsInRefProhibited { + return nil } - if validationOpts.schemaExtensionsInRefProhibited { - for _, ex := range componentNames(x.Extensions) { - if _, ok := allowed[ex]; !ok { - extras = append(extras, ex) - } - // extras in the Extensions checked below + var extras []string + for _, ex := range componentNames(x.Extensions) { + if _, ok := validationOpts.extraSiblingFieldsAllowed[ex]; !ok { + extras = append(extras, ex) } } - if len(extras) != 0 { - if !validationOpts.isOpenAPI31OrLater { - return newExtraSiblingFields(extras, x.Origin) - } + return newExtraSiblingFields(extras, x.Origin) } return nil } @@ -1458,46 +1288,24 @@ func (x *SecuritySchemeRef) UnmarshalJSON(data []byte) error { return unmarshalJSON(data, &x.Value) } -// validateExtras returns an error if SecuritySchemeRef has sibling fields -// alongside $ref that are not allowed by the validation options. +// validateExtras returns an error if SecuritySchemeRef has `x-` extensions +// next to its $ref while ProhibitExtensionsWithRef is set. Every other field +// next to a $ref is not an error: every version's Reference Object says "any +// properties added SHALL be ignored", from 3.1 on summary and description +// override the referenced component's, and an OpenAPI 3.1 schema applies its +// sibling keywords alongside the referenced schema. func (x *SecuritySchemeRef) validateExtras(ctx context.Context) error { validationOpts := getValidationOptions(ctx) - var extras []string - - allowed := validationOpts.extraSiblingFieldsAllowed - if allowed == nil { - allowed = make(map[string]struct{}) - } - if x.Ref == "" && !validationOpts.isOpenAPI31OrLater { - if _, ok := allowed["description"]; x.Description != nil && !ok { - extras = append(extras, "description") - } - if _, ok := allowed["summary"]; x.Summary != nil && !ok { - extras = append(extras, "summary") - } - } - // OpenAPI 3.0 Reference Objects ignore added properties. Keep the - // explicit extension policy below and validation of inline objects. - if x.Ref == "" || validationOpts.isOpenAPI31OrLater { - for _, ex := range x.extra { - if _, ok := allowed[ex]; !ok { - if _, ok := x.Extensions[ex]; !ok { - extras = append(extras, ex) - } - // extras in the Extensions checked below - } - } + if x.Ref == "" || !validationOpts.schemaExtensionsInRefProhibited { + return nil } - if validationOpts.schemaExtensionsInRefProhibited { - for _, ex := range componentNames(x.Extensions) { - if _, ok := allowed[ex]; !ok { - extras = append(extras, ex) - } - // extras in the Extensions checked below + var extras []string + for _, ex := range componentNames(x.Extensions) { + if _, ok := validationOpts.extraSiblingFieldsAllowed[ex]; !ok { + extras = append(extras, ex) } } - if len(extras) != 0 { return newExtraSiblingFields(extras, x.Origin) } diff --git a/openapi3/refs.tmpl b/openapi3/refs.tmpl index e9b3aa642..e02a67591 100644 --- a/openapi3/refs.tmpl +++ b/openapi3/refs.tmpl @@ -132,56 +132,26 @@ func (x *{{ $type.Name }}Ref) UnmarshalJSON(data []byte) error { return unmarshalJSON(data, &x.Value) } -// validateExtras returns an error if {{ $type.Name }}Ref has sibling fields -// alongside $ref that are not allowed by the validation options. +// validateExtras returns an error if {{ $type.Name }}Ref has `x-` extensions +// next to its $ref while ProhibitExtensionsWithRef is set. Every other field +// next to a $ref is not an error: every version's Reference Object says "any +// properties added SHALL be ignored", from 3.1 on summary and description +// override the referenced component's, and an OpenAPI 3.1 schema applies its +// sibling keywords alongside the referenced schema. func (x *{{ $type.Name }}Ref) validateExtras(ctx context.Context) error { validationOpts := getValidationOptions(ctx) - var extras []string - - allowed := validationOpts.extraSiblingFieldsAllowed - if allowed == nil { - allowed = make(map[string]struct{}) - } - {{- if ne $type.Name "Schema" }} - if x.Ref == "" && !validationOpts.isOpenAPI31OrLater { - if _, ok := allowed["description"]; x.Description != nil && !ok { - extras = append(extras, "description") - } - if _, ok := allowed["summary"]; x.Summary != nil && !ok { - extras = append(extras, "summary") - } - } - {{- end }} - // OpenAPI 3.0 Reference Objects ignore added properties. Keep the - // explicit extension policy below and validation of inline objects. - if x.Ref == "" || validationOpts.isOpenAPI31OrLater { - for _, ex := range x.extra { - if _, ok := allowed[ex]; !ok { - if _, ok := x.Extensions[ex]; !ok { - extras = append(extras, ex) - } - // extras in the Extensions checked below - } - } + if x.Ref == "" || !validationOpts.schemaExtensionsInRefProhibited { + return nil } - if validationOpts.schemaExtensionsInRefProhibited { - for _, ex := range componentNames(x.Extensions) { - if _, ok := allowed[ex]; !ok { - extras = append(extras, ex) - } - // extras in the Extensions checked below + var extras []string + for _, ex := range componentNames(x.Extensions) { + if _, ok := validationOpts.extraSiblingFieldsAllowed[ex]; !ok { + extras = append(extras, ex) } } - if len(extras) != 0 { -{{- if eq $type.Name "Schema" }} - if !validationOpts.isOpenAPI31OrLater { - return newExtraSiblingFields(extras, x.Origin) - } -{{- else }} return newExtraSiblingFields(extras, x.Origin) -{{- end }} } return nil } diff --git a/openapi3/refs_test.go b/openapi3/refs_test.go index 2dbf6aa4c..749195504 100644 --- a/openapi3/refs_test.go +++ b/openapi3/refs_test.go @@ -41,10 +41,10 @@ func TestCallbackRef_Extensions(t *testing.T) { err = ref.Validate(t.Context(), openapi3.ProhibitExtensionsWithRef(), openapi3.AllowExtraSiblingFields("x-order")) require.ErrorContains(t, err, "found unresolved ref") - // OpenAPI 3.1 Reference Objects still reject unknown siblings; Schema + // OpenAPI 3.1 Reference Objects ignore unknown siblings too; Schema // Objects allow sibling keywords under JSON Schema semantics. err = ref.Validate(t.Context(), openapi3.IsOpenAPI31OrLater()) - require.EqualError(t, err, "extra sibling fields: [something]") + require.ErrorContains(t, err, "found unresolved ref") // Verify round trip JSON // Compare as string to make error message more readable if different @@ -98,10 +98,10 @@ func TestExampleRef_Extensions(t *testing.T) { err = ref.Validate(t.Context(), openapi3.ProhibitExtensionsWithRef(), openapi3.AllowExtraSiblingFields("x-order")) require.ErrorContains(t, err, "found unresolved ref") - // OpenAPI 3.1 Reference Objects still reject unknown siblings; Schema + // OpenAPI 3.1 Reference Objects ignore unknown siblings too; Schema // Objects allow sibling keywords under JSON Schema semantics. err = ref.Validate(t.Context(), openapi3.IsOpenAPI31OrLater()) - require.EqualError(t, err, "extra sibling fields: [something]") + require.ErrorContains(t, err, "found unresolved ref") // Verify round trip JSON // Compare as string to make error message more readable if different @@ -155,10 +155,10 @@ func TestHeaderRef_Extensions(t *testing.T) { err = ref.Validate(t.Context(), openapi3.ProhibitExtensionsWithRef(), openapi3.AllowExtraSiblingFields("x-order")) require.ErrorContains(t, err, "found unresolved ref") - // OpenAPI 3.1 Reference Objects still reject unknown siblings; Schema + // OpenAPI 3.1 Reference Objects ignore unknown siblings too; Schema // Objects allow sibling keywords under JSON Schema semantics. err = ref.Validate(t.Context(), openapi3.IsOpenAPI31OrLater()) - require.EqualError(t, err, "extra sibling fields: [something]") + require.ErrorContains(t, err, "found unresolved ref") // Verify round trip JSON // Compare as string to make error message more readable if different @@ -203,10 +203,10 @@ func TestLinkRef_Extensions(t *testing.T) { err = ref.Validate(t.Context(), openapi3.ProhibitExtensionsWithRef(), openapi3.AllowExtraSiblingFields("x-order")) require.ErrorContains(t, err, "found unresolved ref") - // OpenAPI 3.1 Reference Objects still reject unknown siblings; Schema + // OpenAPI 3.1 Reference Objects ignore unknown siblings too; Schema // Objects allow sibling keywords under JSON Schema semantics. err = ref.Validate(t.Context(), openapi3.IsOpenAPI31OrLater()) - require.EqualError(t, err, "extra sibling fields: [something]") + require.ErrorContains(t, err, "found unresolved ref") // Verify round trip JSON // Compare as string to make error message more readable if different @@ -260,10 +260,10 @@ func TestParameterRef_Extensions(t *testing.T) { err = ref.Validate(t.Context(), openapi3.ProhibitExtensionsWithRef(), openapi3.AllowExtraSiblingFields("x-order")) require.ErrorContains(t, err, "found unresolved ref") - // OpenAPI 3.1 Reference Objects still reject unknown siblings; Schema + // OpenAPI 3.1 Reference Objects ignore unknown siblings too; Schema // Objects allow sibling keywords under JSON Schema semantics. err = ref.Validate(t.Context(), openapi3.IsOpenAPI31OrLater()) - require.EqualError(t, err, "extra sibling fields: [something]") + require.ErrorContains(t, err, "found unresolved ref") // Verify round trip JSON // Compare as string to make error message more readable if different @@ -317,10 +317,10 @@ func TestRequestBodyRef_Extensions(t *testing.T) { err = ref.Validate(t.Context(), openapi3.ProhibitExtensionsWithRef(), openapi3.AllowExtraSiblingFields("x-order")) require.ErrorContains(t, err, "found unresolved ref") - // OpenAPI 3.1 Reference Objects still reject unknown siblings; Schema + // OpenAPI 3.1 Reference Objects ignore unknown siblings too; Schema // Objects allow sibling keywords under JSON Schema semantics. err = ref.Validate(t.Context(), openapi3.IsOpenAPI31OrLater()) - require.EqualError(t, err, "extra sibling fields: [something]") + require.ErrorContains(t, err, "found unresolved ref") // Verify round trip JSON // Compare as string to make error message more readable if different @@ -374,10 +374,10 @@ func TestResponseRef_Extensions(t *testing.T) { err = ref.Validate(t.Context(), openapi3.ProhibitExtensionsWithRef(), openapi3.AllowExtraSiblingFields("x-order")) require.ErrorContains(t, err, "found unresolved ref") - // OpenAPI 3.1 Reference Objects still reject unknown siblings; Schema + // OpenAPI 3.1 Reference Objects ignore unknown siblings too; Schema // Objects allow sibling keywords under JSON Schema semantics. err = ref.Validate(t.Context(), openapi3.IsOpenAPI31OrLater()) - require.EqualError(t, err, "extra sibling fields: [something]") + require.ErrorContains(t, err, "found unresolved ref") // Verify round trip JSON // Compare as string to make error message more readable if different @@ -431,7 +431,7 @@ func TestSchemaRef_Extensions(t *testing.T) { err = ref.Validate(t.Context(), openapi3.ProhibitExtensionsWithRef(), openapi3.AllowExtraSiblingFields("x-order")) require.ErrorContains(t, err, "found unresolved ref") - // OpenAPI 3.1 Reference Objects still reject unknown siblings; Schema + // OpenAPI 3.1 Reference Objects ignore unknown siblings too; Schema // Objects allow sibling keywords under JSON Schema semantics. err = ref.Validate(t.Context(), openapi3.IsOpenAPI31OrLater()) require.ErrorContains(t, err, "found unresolved ref") @@ -488,10 +488,10 @@ func TestSecuritySchemeRef_Extensions(t *testing.T) { err = ref.Validate(t.Context(), openapi3.ProhibitExtensionsWithRef(), openapi3.AllowExtraSiblingFields("x-order")) require.ErrorContains(t, err, "found unresolved ref") - // OpenAPI 3.1 Reference Objects still reject unknown siblings; Schema + // OpenAPI 3.1 Reference Objects ignore unknown siblings too; Schema // Objects allow sibling keywords under JSON Schema semantics. err = ref.Validate(t.Context(), openapi3.IsOpenAPI31OrLater()) - require.EqualError(t, err, "extra sibling fields: [something]") + require.ErrorContains(t, err, "found unresolved ref") // Verify round trip JSON // Compare as string to make error message more readable if different diff --git a/openapi3/refs_test.tmpl b/openapi3/refs_test.tmpl index 083e52207..fd97c7b15 100644 --- a/openapi3/refs_test.tmpl +++ b/openapi3/refs_test.tmpl @@ -41,14 +41,10 @@ func Test{{ $type.Name }}Ref_Extensions(t *testing.T) { err = ref.Validate(t.Context(), openapi3.ProhibitExtensionsWithRef(), openapi3.AllowExtraSiblingFields("x-order")) require.ErrorContains(t, err, "found unresolved ref") - // OpenAPI 3.1 Reference Objects still reject unknown siblings; Schema + // OpenAPI 3.1 Reference Objects ignore unknown siblings too; Schema // Objects allow sibling keywords under JSON Schema semantics. err = ref.Validate(t.Context(), openapi3.IsOpenAPI31OrLater()) -{{- if eq $type.Name "Schema" }} require.ErrorContains(t, err, "found unresolved ref") -{{- else }} - require.EqualError(t, err, "extra sibling fields: [something]") -{{- end }} // Verify round trip JSON // Compare as string to make error message more readable if different diff --git a/openapi3/validation_options.go b/openapi3/validation_options.go index 6d20d4c6f..6bb4e723f 100644 --- a/openapi3/validation_options.go +++ b/openapi3/validation_options.go @@ -23,7 +23,9 @@ type ValidationOptions struct { type validationOptionsKey struct{} -// AllowExtraSiblingFields called as AllowExtraSiblingFields("description") makes Validate not return an error when said field appears next to a $ref. +// AllowExtraSiblingFields called as AllowExtraSiblingFields("description") makes Validate not return an error when said field appears +// where it is not expected: as an unknown field of an object, as an OpenAPI 3.1 schema keyword in an OpenAPI 3.0 document, +// or as an extension next to a $ref under ProhibitExtensionsWithRef. Other fields next to a $ref are never an error. func AllowExtraSiblingFields(fields ...string) ValidationOption { return func(options *ValidationOptions) { if options.extraSiblingFieldsAllowed == nil && len(fields) != 0 { @@ -126,7 +128,7 @@ func AllowExtensionsWithRef() ValidationOption { // ProhibitExtensionsWithRef causes the validation to return an // error if extensions (fields starting with 'x-') are found as -// siblings for $ref fields, even in OpenAPI 3.0. Use AllowExtraSiblingFields +// siblings for $ref fields, in every OpenAPI version. Use AllowExtraSiblingFields // to allow specific extensions. func ProhibitExtensionsWithRef() ValidationOption { return func(options *ValidationOptions) { From 0375a5d3d59461e735dea0caf5ca30e8268bd6cb Mon Sep 17 00:00:00 2001 From: Pierre Fenoll Date: Mon, 19 Oct 2026 21:22:25 +0200 Subject: [PATCH 02/78] openapi3: apply a 3.1 schema's $ref siblings alongside the referenced schema In JSON Schema 2020-12, on which OpenAPI 3.1 bases its Schema Object, the keywords next to a $ref apply alongside it: an instance must satisfy both the referenced schema and its siblings. They were instead copied over the referenced schema's keywords of the same name, so a sibling maxLength: 10 relaxed a referenced maxLength: 3, a sibling required list dropped the referenced one, and sibling properties replaced the referenced ones. Annotations, which describe rather than constrain, still override the referenced ones. Every other sibling keyword now goes into one more allOf entry of the copy the loader makes, so Value keeps the shape of the referenced schema. #1271 reaches the same validation results by making the siblings the Value and the referenced schema an allOf entry, which leaves Value without the type or properties of the referenced schema whenever a $ref has even just a description next to it. The $refs within the siblings are now resolved before they are applied, since applyRefSiblings also runs from the callback that ends a cycle. Signed-off-by: Pierre Fenoll --- README.md | 1 + openapi3/loader.go | 70 +++++++++++++-- openapi3/schema_ref_siblings_test.go | 129 +++++++++++++++++++++++++++ 3 files changed, 193 insertions(+), 7 deletions(-) create mode 100644 openapi3/schema_ref_siblings_test.go diff --git a/README.md b/README.md index 2f2da6e6d..4bc9252e3 100644 --- a/README.md +++ b/README.md @@ -338,6 +338,7 @@ for _, path := range doc.Paths.InMatchingOrder() { * `openapi3filter` now parses `integer` values of parameters and `application/x-www-form-urlencoded`/`multipart/form-data` bodies as base 10 only, so `010` decodes to `10` rather than `8`, and Go integer literals such as `0x10`, `0b10`, `0o10` or `1_000` are now rejected as invalid integers. * `openapi3filter.ValidateResponse` now decodes and validates response headers described with `content` rather than `schema`, with the body decoder registered for the header's media type (see `RegisterBodyDecoder`). Such a header is no longer reported missing when it is required and present, and a value that does not match its schema is now rejected. As with a response body, a media type with no registered decoder fails with `unsupported content type`. * `Validate` no longer reports `extra sibling fields` for fields written next to a `$ref`: every version's Reference Object says they "SHALL be ignored". From OpenAPI 3.1 on, `summary` and `description` still override the referenced component's. `ExtraSiblingFieldsError` is still returned for unknown fields of inline objects, and for `x-` extensions next to a `$ref` under `ProhibitExtensionsWithRef`, which now applies to OpenAPI 3.1+ schemas too. It is no longer returned after `InternalizeRefs` for the fields that were next to a component's `$ref` it replaced, and which it leaves out. +* In OpenAPI 3.1+ documents, the keywords next to a schema's `$ref` now apply alongside the referenced schema, as JSON Schema 2020-12 has it, instead of replacing its keywords of the same name: `{"$ref": ..., "maxLength": 10}` next to a referenced `maxLength: 3` still rejects `"abcd"`, and sibling `required` or `properties` add to the referenced ones. The resolved `SchemaRef.Value` keeps the referenced schema's shape: annotations such as `description`, `readOnly` or `default` replace the referenced ones there, and the other sibling keywords are appended to its `AllOf`. ### v0.150.0 * `openapi2.Operation.Responses` field type changed from `map[string]*Response` to `*Responses`, which keeps the Responses Object's `x-` extensions in `Responses.Extensions` instead of failing to decode them as responses. diff --git a/openapi3/loader.go b/openapi3/loader.go index fdcf6ed84..4d612abd4 100644 --- a/openapi3/loader.go +++ b/openapi3/loader.go @@ -1053,6 +1053,14 @@ func (loader *Loader) resolveSchemaRef(doc *T, component *SchemaRef, documentPat if component.Value != nil { return nil } + if doc.IsOpenAPI31OrLater() && component.sibling != nil { + // Resolve the $refs within the siblings themselves, such as those of + // the properties they add, before applyRefSiblings shares them with + // Value: it may run from the callback below, which resolves nothing. + if err := loader.resolveSchemaRef(doc, &SchemaRef{Value: component.sibling}, documentPath, visited); err != nil { + return err + } + } if !loader.shouldVisitRef(ref, func(value any) { component.Value = value.(*Schema) refPath, _ := loader.resolveRefPath(ref, documentPath) @@ -1530,15 +1538,63 @@ func (loader *Loader) resolvePathItemRef(doc *T, pathItem *PathItem, documentPat return } -// applyRefSiblings overlays the sibling keywords of an OAS 3.1 $ref onto its -// resolved value. It works on a copy so a schema shared by other references is -// not mutated, and does nothing for OAS 3.0, where $ref replaces its object. +// refSiblingAnnotations are the keywords that, written next to a $ref, replace +// the referenced schema's own. They describe the instance rather than constrain +// it, so the one closest to where it is used wins, as summary and description +// do on a Reference Object. +var refSiblingAnnotations = map[string]struct{}{ + "$comment": {}, + "allowEmptyValue": {}, + "default": {}, + "deprecated": {}, + "description": {}, + "discriminator": {}, + "example": {}, + "examples": {}, + "externalDocs": {}, + "nullable": {}, + "readOnly": {}, + "title": {}, + "writeOnly": {}, + "xml": {}, +} + +// applyRefSiblings applies the sibling keywords of an OAS 3.1 $ref to its +// resolved value, and does nothing for OAS 3.0, where $ref replaces its object. +// +// In JSON Schema 2020-12 the keywords next to a $ref apply alongside it: an +// instance must satisfy both the referenced schema and its siblings. So the +// annotations above override the referenced schema's, while every other +// keyword is added as one more allOf entry rather than replacing the +// referenced schema's own: a sibling maxLength: 10 next to a $ref to a schema +// with maxLength: 3 still rejects "abcd". Value thus keeps the shape of the +// referenced schema, with its properties, type and so on. +// +// It works on a copy so a schema shared by other references is not mutated. func (component *SchemaRef) applyRefSiblings(doc *T) { - if doc.IsOpenAPI31OrLater() && component.sibling != nil && component.Value != nil { - schemaCopy := *component.Value - applySiblingSchemaFields(&schemaCopy, component.sibling, component.extra) - component.Value = &schemaCopy + if !doc.IsOpenAPI31OrLater() || component.sibling == nil || component.Value == nil { + return + } + var annotations, assertions []string + for _, field := range component.extra { + if _, ok := refSiblingAnnotations[field]; ok { + annotations = append(annotations, field) + } else { + assertions = append(assertions, field) + } + } + schemaCopy := *component.Value + applySiblingSchemaFields(&schemaCopy, component.sibling, annotations) + if len(assertions) != 0 { + var conjunct Schema + applySiblingSchemaFields(&conjunct, component.sibling, assertions) + if !conjunct.IsEmpty() { + allOf := make(SchemaRefs, 0, len(schemaCopy.AllOf)+1) + allOf = append(allOf, schemaCopy.AllOf...) + schemaCopy.AllOf = append(allOf, &SchemaRef{Value: &conjunct}) + } } + component.Value = &schemaCopy } func unescapeRefString(ref string) string { diff --git a/openapi3/schema_ref_siblings_test.go b/openapi3/schema_ref_siblings_test.go new file mode 100644 index 000000000..5cc07e2ea --- /dev/null +++ b/openapi3/schema_ref_siblings_test.go @@ -0,0 +1,129 @@ +package openapi3_test + +import ( + "fmt" + "testing" + + "github.com/stretchr/testify/require" + + "github.com/getkin/kin-openapi/openapi3" +) + +func loadSchemaRefSiblings(t *testing.T, version, schemas string) *openapi3.T { + t.Helper() + loader := openapi3.NewLoader() + doc, err := loader.LoadFromData(fmt.Appendf(nil, `{ + "openapi": %q, + "info": {"title": "t", "version": "1"}, + "paths": {}, + "components": {"schemas": %s} +}`, version, schemas)) + require.NoError(t, err) + require.NoError(t, doc.Validate(t.Context())) + return doc +} + +// In OpenAPI 3.1 a Schema Object is a JSON Schema 2020-12 schema, in which the +// keywords next to $ref apply alongside it: a value must satisfy both. +func TestSchemaRefSiblingsApplyAlongsideTheRef(t *testing.T) { + t.Parallel() + for _, tc := range []struct { + name string + sibling string + valid []any + invalid []any + }{{ + name: "a looser bound does not relax the referenced one", + sibling: `"maxLength": 10`, + valid: []any{"abc"}, + invalid: []any{"abcd", "abcdefghijk"}, + }, { + name: "a tighter bound applies", + sibling: `"minLength": 2`, + valid: []any{"ab"}, + invalid: []any{"a", "abcd"}, + }, { + name: "a different type matches nothing", + sibling: `"type": "integer"`, + invalid: []any{"a", 1.0}, + }} { + t.Run(tc.name, func(t *testing.T) { + t.Parallel() + doc := loadSchemaRefSiblings(t, "3.1.0", `{ + "Base": {"type": "string", "maxLength": 3}, + "S": {"properties": {"p": {"$ref": "#/components/schemas/Base", `+tc.sibling+`}}} +}`) + value := doc.Components.Schemas["S"].Value.Properties["p"].Value + for _, v := range tc.valid { + require.NoError(t, value.VisitJSON(v), "%v", v) + } + for _, v := range tc.invalid { + require.Error(t, value.VisitJSON(v), "%v", v) + } + // The referenced schema keeps its own shape, and is not changed. + require.True(t, value.Type.Is("string")) + require.Equal(t, uint64(3), *value.MaxLength) + require.Len(t, doc.Components.Schemas["Base"].Value.AllOf, 0) + }) + } + + t.Run("properties and required add to the referenced ones", func(t *testing.T) { + t.Parallel() + doc := loadSchemaRefSiblings(t, "3.1.0", `{ + "Base": {"type": "object", "properties": {"a": {"type": "string"}}, "required": ["a"]}, + "S": {"properties": {"p": { + "$ref": "#/components/schemas/Base", + "properties": {"b": {"$ref": "#/components/schemas/Int"}}, + "required": ["b"] + }}}, + "Int": {"type": "integer"} +}`) + value := doc.Components.Schemas["S"].Value.Properties["p"].Value + require.NoError(t, value.VisitJSON(map[string]any{"a": "x", "b": 1.0})) + require.Error(t, value.VisitJSON(map[string]any{"a": "x"})) + require.Error(t, value.VisitJSON(map[string]any{"b": 1.0})) + require.Error(t, value.VisitJSON(map[string]any{"a": "x", "b": "y"})) + require.Contains(t, value.Properties, "a") + }) + + t.Run("annotations override the referenced ones", func(t *testing.T) { + t.Parallel() + doc := loadSchemaRefSiblings(t, "3.1.0", `{ + "Base": {"type": "object", "description": "base", "properties": {"a": {"type": "string"}}}, + "S": {"properties": {"p": {"$ref": "#/components/schemas/Base", "description": "local", "readOnly": true}}} +}`) + value := doc.Components.Schemas["S"].Value.Properties["p"].Value + require.Equal(t, "local", value.Description) + require.True(t, value.ReadOnly) + require.Contains(t, value.Properties, "a") + require.Empty(t, value.AllOf) + require.Equal(t, "base", doc.Components.Schemas["Base"].Value.Description) + }) + + t.Run("through a cycle", func(t *testing.T) { + t.Parallel() + doc := loadSchemaRefSiblings(t, "3.1.0", `{ + "Author": {"type": "object", "properties": {"name": {"type": "string"}, "book": {"$ref": "#/components/schemas/Book", "required": ["title"]}}}, + "Book": {"type": "object", "properties": {"title": {"type": "string"}, "author": {"$ref": "#/components/schemas/Author", "required": ["name"]}}} +}`) + book := doc.Components.Schemas["Author"].Value.Properties["book"].Value + require.Error(t, book.VisitJSON(map[string]any{})) + require.NoError(t, book.VisitJSON(map[string]any{"title": "t"})) + author := doc.Components.Schemas["Book"].Value.Properties["author"].Value + require.Error(t, author.VisitJSON(map[string]any{})) + require.NoError(t, author.VisitJSON(map[string]any{"name": "n"})) + }) +} + +// In OpenAPI 3.0 a $ref is a Reference Object, whose added properties are +// ignored. +func TestSchemaRefSiblingsAreIgnoredIn30(t *testing.T) { + t.Parallel() + doc := loadSchemaRefSiblings(t, "3.0.3", `{ + "Base": {"type": "string", "maxLength": 3, "description": "base"}, + "S": {"properties": {"p": {"$ref": "#/components/schemas/Base", "maxLength": 1, "description": "local"}}} +}`) + value := doc.Components.Schemas["S"].Value.Properties["p"].Value + require.Same(t, doc.Components.Schemas["Base"].Value, value) + require.NoError(t, value.VisitJSON("abc")) +} From cb1464646ed473e9054be72c0a67101467e9fba8 Mon Sep 17 00:00:00 2001 From: Pierre Fenoll Date: Thu, 15 Oct 2026 10:17:13 +0200 Subject: [PATCH 03/78] openapi3: marshal the fields written next to a $ref They were dropped. An OpenAPI 3.1 schema's sibling keywords, which constrain the referenced schema, were lost that way, and so was every other field next to a $ref: a document did not survive a round trip. Signed-off-by: Pierre Fenoll --- README.md | 1 + openapi3/ref_siblings_marshal_test.go | 121 +++++++++++ openapi3/refs.go | 190 +++++++++++++++--- openapi3/refs.tmpl | 22 +- openapi3/refs_test.go | 72 +++++-- openapi3/refs_test.tmpl | 8 +- ...egistry_1_3_2_Final_openapi_yaml__validate | 9 +- ...ocal_registry_2_4_x_openapi_yaml__validate | 30 ++- openapi3filter/validate_response.go | 2 +- 9 files changed, 391 insertions(+), 64 deletions(-) create mode 100644 openapi3/ref_siblings_marshal_test.go diff --git a/README.md b/README.md index 4bc9252e3..6e3e66764 100644 --- a/README.md +++ b/README.md @@ -339,6 +339,7 @@ for _, path := range doc.Paths.InMatchingOrder() { * `openapi3filter.ValidateResponse` now decodes and validates response headers described with `content` rather than `schema`, with the body decoder registered for the header's media type (see `RegisterBodyDecoder`). Such a header is no longer reported missing when it is required and present, and a value that does not match its schema is now rejected. As with a response body, a media type with no registered decoder fails with `unsupported content type`. * `Validate` no longer reports `extra sibling fields` for fields written next to a `$ref`: every version's Reference Object says they "SHALL be ignored". From OpenAPI 3.1 on, `summary` and `description` still override the referenced component's. `ExtraSiblingFieldsError` is still returned for unknown fields of inline objects, and for `x-` extensions next to a `$ref` under `ProhibitExtensionsWithRef`, which now applies to OpenAPI 3.1+ schemas too. It is no longer returned after `InternalizeRefs` for the fields that were next to a component's `$ref` it replaced, and which it leaves out. * In OpenAPI 3.1+ documents, the keywords next to a schema's `$ref` now apply alongside the referenced schema, as JSON Schema 2020-12 has it, instead of replacing its keywords of the same name: `{"$ref": ..., "maxLength": 10}` next to a referenced `maxLength: 3` still rejects `"abcd"`, and sibling `required` or `properties` add to the referenced ones. The resolved `SchemaRef.Value` keeps the referenced schema's shape: annotations such as `description`, `readOnly` or `default` replace the referenced ones there, and the other sibling keywords are appended to its `AllOf`. +* Marshaling an `openapi3.*Ref` with a `$ref` now writes back the fields that were written next to it, instead of emitting a lone `{"$ref": ...}`. An OpenAPI 3.1 schema's sibling keywords, which constrain the referenced schema, were lost that way, and so was every other field next to a `$ref`. ### v0.150.0 * `openapi2.Operation.Responses` field type changed from `map[string]*Response` to `*Responses`, which keeps the Responses Object's `x-` extensions in `Responses.Extensions` instead of failing to decode them as responses. diff --git a/openapi3/ref_siblings_marshal_test.go b/openapi3/ref_siblings_marshal_test.go new file mode 100644 index 000000000..7480d370b --- /dev/null +++ b/openapi3/ref_siblings_marshal_test.go @@ -0,0 +1,121 @@ +package openapi3_test + +import ( + "testing" + + "github.com/stretchr/testify/require" + + "github.com/getkin/kin-openapi/openapi3" +) + +// TestRefSiblingsSurviveMarshal covers what a $ref carries next to it: it has +// to be written back out. +// +// For 3.1+ the loader overlays sibling keywords onto the referenced schema, +// which is what JSON Schema 2020-12 prescribes. Marshaling used to throw the +// siblings away and emit a bare {"$ref": ...}, so a document meant one thing +// before being written out and another after being read back, with nothing to +// report the change. +// +// The generated *Ref types now keep their non-extension siblings verbatim and +// copy them back over the $ref. They do not need to know the document version: +// the version decision was already made at load. +func TestRefSiblingsSurviveMarshal(t *testing.T) { + t.Parallel() + + t.Run("schema", func(t *testing.T) { + t.Parallel() + + const spec = ` +openapi: 3.1.0 +info: + title: schema sibling demo + version: "1" +paths: {} +components: + schemas: + Base: + type: string + Alias: + $ref: "#/components/schemas/Base" + description: what Alias means +` + + loader := openapi3.NewLoader() + doc, err := loader.LoadFromData([]byte(spec)) + require.NoError(t, err) + + // Alias resolves to Base's type with the sibling description layered on + // top, and Base itself is left alone. + alias := doc.Components.Schemas["Alias"] + require.Equal(t, `#/components/schemas/Base`, alias.Ref) + require.Equal(t, &openapi3.Types{"string"}, alias.Value.Type) + require.Equal(t, "what Alias means", alias.Value.Description) + require.Empty(t, doc.Components.Schemas["Base"].Value.Description, + "the overlay must not leak into the referenced schema") + + once, err := doc.MarshalJSON() + require.NoError(t, err) + require.JSONEq(t, `{ + "openapi": "3.1.0", + "info": {"title": "schema sibling demo", "version": "1"}, + "paths": {}, + "components": { + "schemas": { + "Base": {"type": "string"}, + "Alias": { + "$ref": "#/components/schemas/Base", + "description": "what Alias means" + } + } + } + }`, string(once)) + + // So the meaning of Alias survives a save/load cycle. + loader = openapi3.NewLoader() + reloaded, err := loader.LoadFromData(once) + require.NoError(t, err) + require.Equal(t, "what Alias means", + reloaded.Components.Schemas["Alias"].Value.Description) + }) + + t.Run("a sibling that is not a schema keyword is kept too", func(t *testing.T) { + t.Parallel() + + // Preserving only recognized keywords would still lose data. This is + // the shape the fuzzer reduced to; see + // testdata/fuzz/FuzzLoadFromData/schema-ref-junk-sibling. + const spec = ` +openapi: 3.0.0 +info: + title: junk sibling + version: "1" +paths: {} +components: + schemas: + Base: + type: string + Alias: + $ref: "#/components/schemas/Base" + nonsense: 1 +` + + loader := openapi3.NewLoader() + doc, err := loader.LoadFromData([]byte(spec)) + require.NoError(t, err) + + // A Reference Object ignores it. + before := doc.Validate(t.Context()) + require.NoError(t, before) + + once, err := doc.MarshalJSON() + require.NoError(t, err) + require.Contains(t, string(once), `"nonsense":1`) + + // The same document validates the same way after a round trip. + loader = openapi3.NewLoader() + reloaded, err := loader.LoadFromData(once) + require.NoError(t, err) + require.Equal(t, before, reloaded.Validate(t.Context())) + }) +} diff --git a/openapi3/refs.go b/openapi3/refs.go index 3f2c22706..83a1fb9b1 100644 --- a/openapi3/refs.go +++ b/openapi3/refs.go @@ -4,6 +4,7 @@ package openapi3 import ( "context" "encoding/json" + "maps" "net/url" "strings" @@ -24,6 +25,10 @@ type CallbackRef struct { Ref string Value *Callback extra []string + // siblingExtras holds, verbatim, the non-`x-` fields written next to $ref. + // Marshaling writes them back out, so a document survives a round trip: + // an OpenAPI 3.1 schema's sibling keywords constrain the referenced one. + siblingExtras map[string]any refPath *url.URL } @@ -54,12 +59,19 @@ func (x *CallbackRef) setRefPath(u *url.URL) { // MarshalYAML returns the YAML encoding of CallbackRef. func (x CallbackRef) MarshalYAML() (any, error) { if ref := x.Ref; ref != "" { - return &Ref{ + out, err := Ref{ Ref: ref, Extensions: x.Extensions, Summary: x.Summary, Description: x.Description, - }, nil + }.MarshalYAML() + if err != nil { + return nil, err + } + if m, ok := out.(map[string]any); ok { + maps.Copy(m, x.siblingExtras) + } + return out, nil } return x.Value.MarshalYAML() } @@ -88,8 +100,12 @@ func (x *CallbackRef) UnmarshalJSON(data []byte) error { delete(extra, "description") if len(extra) != 0 { x.extra = componentNames(extra) - for k := range extra { + for k, v := range extra { if !strings.HasPrefix(k, "x-") { + if x.siblingExtras == nil { + x.siblingExtras = make(map[string]any, len(extra)) + } + x.siblingExtras[k] = v delete(extra, k) } } @@ -171,6 +187,10 @@ type ExampleRef struct { Ref string Value *Example extra []string + // siblingExtras holds, verbatim, the non-`x-` fields written next to $ref. + // Marshaling writes them back out, so a document survives a round trip: + // an OpenAPI 3.1 schema's sibling keywords constrain the referenced one. + siblingExtras map[string]any refPath *url.URL } @@ -201,12 +221,19 @@ func (x *ExampleRef) setRefPath(u *url.URL) { // MarshalYAML returns the YAML encoding of ExampleRef. func (x ExampleRef) MarshalYAML() (any, error) { if ref := x.Ref; ref != "" { - return &Ref{ + out, err := Ref{ Ref: ref, Extensions: x.Extensions, Summary: x.Summary, Description: x.Description, - }, nil + }.MarshalYAML() + if err != nil { + return nil, err + } + if m, ok := out.(map[string]any); ok { + maps.Copy(m, x.siblingExtras) + } + return out, nil } return x.Value.MarshalYAML() } @@ -235,8 +262,12 @@ func (x *ExampleRef) UnmarshalJSON(data []byte) error { delete(extra, "description") if len(extra) != 0 { x.extra = componentNames(extra) - for k := range extra { + for k, v := range extra { if !strings.HasPrefix(k, "x-") { + if x.siblingExtras == nil { + x.siblingExtras = make(map[string]any, len(extra)) + } + x.siblingExtras[k] = v delete(extra, k) } } @@ -318,6 +349,10 @@ type HeaderRef struct { Ref string Value *Header extra []string + // siblingExtras holds, verbatim, the non-`x-` fields written next to $ref. + // Marshaling writes them back out, so a document survives a round trip: + // an OpenAPI 3.1 schema's sibling keywords constrain the referenced one. + siblingExtras map[string]any refPath *url.URL } @@ -348,12 +383,19 @@ func (x *HeaderRef) setRefPath(u *url.URL) { // MarshalYAML returns the YAML encoding of HeaderRef. func (x HeaderRef) MarshalYAML() (any, error) { if ref := x.Ref; ref != "" { - return &Ref{ + out, err := Ref{ Ref: ref, Extensions: x.Extensions, Summary: x.Summary, Description: x.Description, - }, nil + }.MarshalYAML() + if err != nil { + return nil, err + } + if m, ok := out.(map[string]any); ok { + maps.Copy(m, x.siblingExtras) + } + return out, nil } return x.Value.MarshalYAML() } @@ -382,8 +424,12 @@ func (x *HeaderRef) UnmarshalJSON(data []byte) error { delete(extra, "description") if len(extra) != 0 { x.extra = componentNames(extra) - for k := range extra { + for k, v := range extra { if !strings.HasPrefix(k, "x-") { + if x.siblingExtras == nil { + x.siblingExtras = make(map[string]any, len(extra)) + } + x.siblingExtras[k] = v delete(extra, k) } } @@ -465,6 +511,10 @@ type LinkRef struct { Ref string Value *Link extra []string + // siblingExtras holds, verbatim, the non-`x-` fields written next to $ref. + // Marshaling writes them back out, so a document survives a round trip: + // an OpenAPI 3.1 schema's sibling keywords constrain the referenced one. + siblingExtras map[string]any refPath *url.URL } @@ -495,12 +545,19 @@ func (x *LinkRef) setRefPath(u *url.URL) { // MarshalYAML returns the YAML encoding of LinkRef. func (x LinkRef) MarshalYAML() (any, error) { if ref := x.Ref; ref != "" { - return &Ref{ + out, err := Ref{ Ref: ref, Extensions: x.Extensions, Summary: x.Summary, Description: x.Description, - }, nil + }.MarshalYAML() + if err != nil { + return nil, err + } + if m, ok := out.(map[string]any); ok { + maps.Copy(m, x.siblingExtras) + } + return out, nil } return x.Value.MarshalYAML() } @@ -529,8 +586,12 @@ func (x *LinkRef) UnmarshalJSON(data []byte) error { delete(extra, "description") if len(extra) != 0 { x.extra = componentNames(extra) - for k := range extra { + for k, v := range extra { if !strings.HasPrefix(k, "x-") { + if x.siblingExtras == nil { + x.siblingExtras = make(map[string]any, len(extra)) + } + x.siblingExtras[k] = v delete(extra, k) } } @@ -612,6 +673,10 @@ type ParameterRef struct { Ref string Value *Parameter extra []string + // siblingExtras holds, verbatim, the non-`x-` fields written next to $ref. + // Marshaling writes them back out, so a document survives a round trip: + // an OpenAPI 3.1 schema's sibling keywords constrain the referenced one. + siblingExtras map[string]any refPath *url.URL } @@ -642,12 +707,19 @@ func (x *ParameterRef) setRefPath(u *url.URL) { // MarshalYAML returns the YAML encoding of ParameterRef. func (x ParameterRef) MarshalYAML() (any, error) { if ref := x.Ref; ref != "" { - return &Ref{ + out, err := Ref{ Ref: ref, Extensions: x.Extensions, Summary: x.Summary, Description: x.Description, - }, nil + }.MarshalYAML() + if err != nil { + return nil, err + } + if m, ok := out.(map[string]any); ok { + maps.Copy(m, x.siblingExtras) + } + return out, nil } return x.Value.MarshalYAML() } @@ -676,8 +748,12 @@ func (x *ParameterRef) UnmarshalJSON(data []byte) error { delete(extra, "description") if len(extra) != 0 { x.extra = componentNames(extra) - for k := range extra { + for k, v := range extra { if !strings.HasPrefix(k, "x-") { + if x.siblingExtras == nil { + x.siblingExtras = make(map[string]any, len(extra)) + } + x.siblingExtras[k] = v delete(extra, k) } } @@ -759,6 +835,10 @@ type RequestBodyRef struct { Ref string Value *RequestBody extra []string + // siblingExtras holds, verbatim, the non-`x-` fields written next to $ref. + // Marshaling writes them back out, so a document survives a round trip: + // an OpenAPI 3.1 schema's sibling keywords constrain the referenced one. + siblingExtras map[string]any refPath *url.URL } @@ -789,12 +869,19 @@ func (x *RequestBodyRef) setRefPath(u *url.URL) { // MarshalYAML returns the YAML encoding of RequestBodyRef. func (x RequestBodyRef) MarshalYAML() (any, error) { if ref := x.Ref; ref != "" { - return &Ref{ + out, err := Ref{ Ref: ref, Extensions: x.Extensions, Summary: x.Summary, Description: x.Description, - }, nil + }.MarshalYAML() + if err != nil { + return nil, err + } + if m, ok := out.(map[string]any); ok { + maps.Copy(m, x.siblingExtras) + } + return out, nil } return x.Value.MarshalYAML() } @@ -823,8 +910,12 @@ func (x *RequestBodyRef) UnmarshalJSON(data []byte) error { delete(extra, "description") if len(extra) != 0 { x.extra = componentNames(extra) - for k := range extra { + for k, v := range extra { if !strings.HasPrefix(k, "x-") { + if x.siblingExtras == nil { + x.siblingExtras = make(map[string]any, len(extra)) + } + x.siblingExtras[k] = v delete(extra, k) } } @@ -906,6 +997,10 @@ type ResponseRef struct { Ref string Value *Response extra []string + // siblingExtras holds, verbatim, the non-`x-` fields written next to $ref. + // Marshaling writes them back out, so a document survives a round trip: + // an OpenAPI 3.1 schema's sibling keywords constrain the referenced one. + siblingExtras map[string]any refPath *url.URL } @@ -936,12 +1031,19 @@ func (x *ResponseRef) setRefPath(u *url.URL) { // MarshalYAML returns the YAML encoding of ResponseRef. func (x ResponseRef) MarshalYAML() (any, error) { if ref := x.Ref; ref != "" { - return &Ref{ + out, err := Ref{ Ref: ref, Extensions: x.Extensions, Summary: x.Summary, Description: x.Description, - }, nil + }.MarshalYAML() + if err != nil { + return nil, err + } + if m, ok := out.(map[string]any); ok { + maps.Copy(m, x.siblingExtras) + } + return out, nil } return x.Value.MarshalYAML() } @@ -970,8 +1072,12 @@ func (x *ResponseRef) UnmarshalJSON(data []byte) error { delete(extra, "description") if len(extra) != 0 { x.extra = componentNames(extra) - for k := range extra { + for k, v := range extra { if !strings.HasPrefix(k, "x-") { + if x.siblingExtras == nil { + x.siblingExtras = make(map[string]any, len(extra)) + } + x.siblingExtras[k] = v delete(extra, k) } } @@ -1050,6 +1156,10 @@ type SchemaRef struct { Ref string Value *Schema extra []string + // siblingExtras holds, verbatim, the non-`x-` fields written next to $ref. + // Marshaling writes them back out, so a document survives a round trip: + // an OpenAPI 3.1 schema's sibling keywords constrain the referenced one. + siblingExtras map[string]any // sibling holds keyword siblings of a $ref (OAS 3.1 / JSON Schema 2020-12). // It is populated during unmarshal and applied to Value after $ref resolution. sibling *Schema @@ -1083,10 +1193,17 @@ func (x *SchemaRef) setRefPath(u *url.URL) { // MarshalYAML returns the YAML encoding of SchemaRef. func (x SchemaRef) MarshalYAML() (any, error) { if ref := x.Ref; ref != "" { - return &Ref{ + out, err := Ref{ Ref: ref, Extensions: x.Extensions, - }, nil + }.MarshalYAML() + if err != nil { + return nil, err + } + if m, ok := out.(map[string]any); ok { + maps.Copy(m, x.siblingExtras) + } + return out, nil } return x.Value.MarshalYAML() } @@ -1127,8 +1244,12 @@ func (x *SchemaRef) UnmarshalJSON(data []byte) error { x.sibling = &sibling } } - for k := range extra { + for k, v := range extra { if !strings.HasPrefix(k, "x-") { + if x.siblingExtras == nil { + x.siblingExtras = make(map[string]any, len(extra)) + } + x.siblingExtras[k] = v delete(extra, k) } } @@ -1210,6 +1331,10 @@ type SecuritySchemeRef struct { Ref string Value *SecurityScheme extra []string + // siblingExtras holds, verbatim, the non-`x-` fields written next to $ref. + // Marshaling writes them back out, so a document survives a round trip: + // an OpenAPI 3.1 schema's sibling keywords constrain the referenced one. + siblingExtras map[string]any refPath *url.URL } @@ -1240,12 +1365,19 @@ func (x *SecuritySchemeRef) setRefPath(u *url.URL) { // MarshalYAML returns the YAML encoding of SecuritySchemeRef. func (x SecuritySchemeRef) MarshalYAML() (any, error) { if ref := x.Ref; ref != "" { - return &Ref{ + out, err := Ref{ Ref: ref, Extensions: x.Extensions, Summary: x.Summary, Description: x.Description, - }, nil + }.MarshalYAML() + if err != nil { + return nil, err + } + if m, ok := out.(map[string]any); ok { + maps.Copy(m, x.siblingExtras) + } + return out, nil } return x.Value.MarshalYAML() } @@ -1274,8 +1406,12 @@ func (x *SecuritySchemeRef) UnmarshalJSON(data []byte) error { delete(extra, "description") if len(extra) != 0 { x.extra = componentNames(extra) - for k := range extra { + for k, v := range extra { if !strings.HasPrefix(k, "x-") { + if x.siblingExtras == nil { + x.siblingExtras = make(map[string]any, len(extra)) + } + x.siblingExtras[k] = v delete(extra, k) } } diff --git a/openapi3/refs.tmpl b/openapi3/refs.tmpl index e02a67591..a00db9614 100644 --- a/openapi3/refs.tmpl +++ b/openapi3/refs.tmpl @@ -4,6 +4,7 @@ package {{ .Package }} import ( "context" "encoding/json" + "maps" "net/url" "strings" @@ -27,6 +28,10 @@ type {{ $type.Name }}Ref struct { Ref string Value *{{ $type.Name }} extra []string + // siblingExtras holds, verbatim, the non-`x-` fields written next to $ref. + // Marshaling writes them back out, so a document survives a round trip: + // an OpenAPI 3.1 schema's sibling keywords constrain the referenced one. + siblingExtras map[string]any {{- if eq $type.Name "Schema" }} // sibling holds keyword siblings of a $ref (OAS 3.1 / JSON Schema 2020-12). // It is populated during unmarshal and applied to Value after $ref resolution. @@ -62,14 +67,21 @@ func (x *{{ $type.Name }}Ref) setRefPath(u *url.URL) { // MarshalYAML returns the YAML encoding of {{ $type.Name }}Ref. func (x {{ $type.Name }}Ref) MarshalYAML() (any, error) { if ref := x.Ref; ref != "" { - return &Ref{ + out, err := Ref{ Ref: ref, Extensions: x.Extensions, {{- if ne $type.Name "Schema" }} Summary: x.Summary, Description: x.Description, {{- end }} - }, nil + }.MarshalYAML() + if err != nil { + return nil, err + } + if m, ok := out.(map[string]any); ok { + maps.Copy(m, x.siblingExtras) + } + return out, nil } return x.Value.MarshalYAML() } @@ -118,8 +130,12 @@ func (x *{{ $type.Name }}Ref) UnmarshalJSON(data []byte) error { } } {{- end }} - for k := range extra { + for k, v := range extra { if !strings.HasPrefix(k, "x-") { + if x.siblingExtras == nil { + x.siblingExtras = make(map[string]any, len(extra)) + } + x.siblingExtras[k] = v delete(extra, k) } } diff --git a/openapi3/refs_test.go b/openapi3/refs_test.go index 749195504..44100a537 100644 --- a/openapi3/refs_test.go +++ b/openapi3/refs_test.go @@ -15,7 +15,11 @@ func TestCallbackRef_Extensions(t *testing.T) { t.Parallel() data := []byte(`{"$ref":"#/components/schemas/Pet","something":"integer","x-order":1}`) - expectMarshalJson := []byte(`{"$ref":"#/components/schemas/Pet","x-order":1}`) + // Marshaling is a round trip. `something` is not an extension and Validate + // ignores it below, but it is still written back out: a document that comes + // back missing a field it was written with means something different, and + // nothing would report the change. + expectMarshalJson := data ref := openapi3.CallbackRef{} err := json.Unmarshal(data, &ref) @@ -50,7 +54,7 @@ func TestCallbackRef_Extensions(t *testing.T) { // Compare as string to make error message more readable if different outJson, err := ref.MarshalJSON() assert.NoError(t, err) - assert.Equal(t, string(outJson), string(expectMarshalJson), "MarshalJSON output is not the same as input data") + assert.Equal(t, string(expectMarshalJson), string(outJson), "MarshalJSON output is not the same as input data") // non-extension not json lookable _, err = ref.JSONLookup("something") @@ -72,7 +76,11 @@ func TestExampleRef_Extensions(t *testing.T) { t.Parallel() data := []byte(`{"$ref":"#/components/schemas/Pet","something":"integer","x-order":1}`) - expectMarshalJson := []byte(`{"$ref":"#/components/schemas/Pet","x-order":1}`) + // Marshaling is a round trip. `something` is not an extension and Validate + // ignores it below, but it is still written back out: a document that comes + // back missing a field it was written with means something different, and + // nothing would report the change. + expectMarshalJson := data ref := openapi3.ExampleRef{} err := json.Unmarshal(data, &ref) @@ -107,7 +115,7 @@ func TestExampleRef_Extensions(t *testing.T) { // Compare as string to make error message more readable if different outJson, err := ref.MarshalJSON() assert.NoError(t, err) - assert.Equal(t, string(outJson), string(expectMarshalJson), "MarshalJSON output is not the same as input data") + assert.Equal(t, string(expectMarshalJson), string(outJson), "MarshalJSON output is not the same as input data") // non-extension not json lookable _, err = ref.JSONLookup("something") @@ -129,7 +137,11 @@ func TestHeaderRef_Extensions(t *testing.T) { t.Parallel() data := []byte(`{"$ref":"#/components/schemas/Pet","something":"integer","x-order":1}`) - expectMarshalJson := []byte(`{"$ref":"#/components/schemas/Pet","x-order":1}`) + // Marshaling is a round trip. `something` is not an extension and Validate + // ignores it below, but it is still written back out: a document that comes + // back missing a field it was written with means something different, and + // nothing would report the change. + expectMarshalJson := data ref := openapi3.HeaderRef{} err := json.Unmarshal(data, &ref) @@ -164,7 +176,7 @@ func TestHeaderRef_Extensions(t *testing.T) { // Compare as string to make error message more readable if different outJson, err := ref.MarshalJSON() assert.NoError(t, err) - assert.Equal(t, string(outJson), string(expectMarshalJson), "MarshalJSON output is not the same as input data") + assert.Equal(t, string(expectMarshalJson), string(outJson), "MarshalJSON output is not the same as input data") // non-extension not json lookable _, err = ref.JSONLookup("something") @@ -177,7 +189,11 @@ func TestLinkRef_Extensions(t *testing.T) { t.Parallel() data := []byte(`{"$ref":"#/components/schemas/Pet","something":"integer","x-order":1}`) - expectMarshalJson := []byte(`{"$ref":"#/components/schemas/Pet","x-order":1}`) + // Marshaling is a round trip. `something` is not an extension and Validate + // ignores it below, but it is still written back out: a document that comes + // back missing a field it was written with means something different, and + // nothing would report the change. + expectMarshalJson := data ref := openapi3.LinkRef{} err := json.Unmarshal(data, &ref) @@ -212,7 +228,7 @@ func TestLinkRef_Extensions(t *testing.T) { // Compare as string to make error message more readable if different outJson, err := ref.MarshalJSON() assert.NoError(t, err) - assert.Equal(t, string(outJson), string(expectMarshalJson), "MarshalJSON output is not the same as input data") + assert.Equal(t, string(expectMarshalJson), string(outJson), "MarshalJSON output is not the same as input data") // non-extension not json lookable _, err = ref.JSONLookup("something") @@ -234,7 +250,11 @@ func TestParameterRef_Extensions(t *testing.T) { t.Parallel() data := []byte(`{"$ref":"#/components/schemas/Pet","something":"integer","x-order":1}`) - expectMarshalJson := []byte(`{"$ref":"#/components/schemas/Pet","x-order":1}`) + // Marshaling is a round trip. `something` is not an extension and Validate + // ignores it below, but it is still written back out: a document that comes + // back missing a field it was written with means something different, and + // nothing would report the change. + expectMarshalJson := data ref := openapi3.ParameterRef{} err := json.Unmarshal(data, &ref) @@ -269,7 +289,7 @@ func TestParameterRef_Extensions(t *testing.T) { // Compare as string to make error message more readable if different outJson, err := ref.MarshalJSON() assert.NoError(t, err) - assert.Equal(t, string(outJson), string(expectMarshalJson), "MarshalJSON output is not the same as input data") + assert.Equal(t, string(expectMarshalJson), string(outJson), "MarshalJSON output is not the same as input data") // non-extension not json lookable _, err = ref.JSONLookup("something") @@ -291,7 +311,11 @@ func TestRequestBodyRef_Extensions(t *testing.T) { t.Parallel() data := []byte(`{"$ref":"#/components/schemas/Pet","something":"integer","x-order":1}`) - expectMarshalJson := []byte(`{"$ref":"#/components/schemas/Pet","x-order":1}`) + // Marshaling is a round trip. `something` is not an extension and Validate + // ignores it below, but it is still written back out: a document that comes + // back missing a field it was written with means something different, and + // nothing would report the change. + expectMarshalJson := data ref := openapi3.RequestBodyRef{} err := json.Unmarshal(data, &ref) @@ -326,7 +350,7 @@ func TestRequestBodyRef_Extensions(t *testing.T) { // Compare as string to make error message more readable if different outJson, err := ref.MarshalJSON() assert.NoError(t, err) - assert.Equal(t, string(outJson), string(expectMarshalJson), "MarshalJSON output is not the same as input data") + assert.Equal(t, string(expectMarshalJson), string(outJson), "MarshalJSON output is not the same as input data") // non-extension not json lookable _, err = ref.JSONLookup("something") @@ -348,7 +372,11 @@ func TestResponseRef_Extensions(t *testing.T) { t.Parallel() data := []byte(`{"$ref":"#/components/schemas/Pet","something":"integer","x-order":1}`) - expectMarshalJson := []byte(`{"$ref":"#/components/schemas/Pet","x-order":1}`) + // Marshaling is a round trip. `something` is not an extension and Validate + // ignores it below, but it is still written back out: a document that comes + // back missing a field it was written with means something different, and + // nothing would report the change. + expectMarshalJson := data ref := openapi3.ResponseRef{} err := json.Unmarshal(data, &ref) @@ -383,7 +411,7 @@ func TestResponseRef_Extensions(t *testing.T) { // Compare as string to make error message more readable if different outJson, err := ref.MarshalJSON() assert.NoError(t, err) - assert.Equal(t, string(outJson), string(expectMarshalJson), "MarshalJSON output is not the same as input data") + assert.Equal(t, string(expectMarshalJson), string(outJson), "MarshalJSON output is not the same as input data") // non-extension not json lookable _, err = ref.JSONLookup("something") @@ -405,7 +433,11 @@ func TestSchemaRef_Extensions(t *testing.T) { t.Parallel() data := []byte(`{"$ref":"#/components/schemas/Pet","something":"integer","x-order":1}`) - expectMarshalJson := []byte(`{"$ref":"#/components/schemas/Pet","x-order":1}`) + // Marshaling is a round trip. `something` is not an extension and Validate + // ignores it below, but it is still written back out: a document that comes + // back missing a field it was written with means something different, and + // nothing would report the change. + expectMarshalJson := data ref := openapi3.SchemaRef{} err := json.Unmarshal(data, &ref) @@ -440,7 +472,7 @@ func TestSchemaRef_Extensions(t *testing.T) { // Compare as string to make error message more readable if different outJson, err := ref.MarshalJSON() assert.NoError(t, err) - assert.Equal(t, string(outJson), string(expectMarshalJson), "MarshalJSON output is not the same as input data") + assert.Equal(t, string(expectMarshalJson), string(outJson), "MarshalJSON output is not the same as input data") // non-extension not json lookable _, err = ref.JSONLookup("something") @@ -462,7 +494,11 @@ func TestSecuritySchemeRef_Extensions(t *testing.T) { t.Parallel() data := []byte(`{"$ref":"#/components/schemas/Pet","something":"integer","x-order":1}`) - expectMarshalJson := []byte(`{"$ref":"#/components/schemas/Pet","x-order":1}`) + // Marshaling is a round trip. `something` is not an extension and Validate + // ignores it below, but it is still written back out: a document that comes + // back missing a field it was written with means something different, and + // nothing would report the change. + expectMarshalJson := data ref := openapi3.SecuritySchemeRef{} err := json.Unmarshal(data, &ref) @@ -497,7 +533,7 @@ func TestSecuritySchemeRef_Extensions(t *testing.T) { // Compare as string to make error message more readable if different outJson, err := ref.MarshalJSON() assert.NoError(t, err) - assert.Equal(t, string(outJson), string(expectMarshalJson), "MarshalJSON output is not the same as input data") + assert.Equal(t, string(expectMarshalJson), string(outJson), "MarshalJSON output is not the same as input data") // non-extension not json lookable _, err = ref.JSONLookup("something") diff --git a/openapi3/refs_test.tmpl b/openapi3/refs_test.tmpl index fd97c7b15..ae1b06788 100644 --- a/openapi3/refs_test.tmpl +++ b/openapi3/refs_test.tmpl @@ -15,7 +15,11 @@ func Test{{ $type.Name }}Ref_Extensions(t *testing.T) { t.Parallel() data := []byte(`{"$ref":"#/components/schemas/Pet","something":"integer","x-order":1}`) - expectMarshalJson := []byte(`{"$ref":"#/components/schemas/Pet","x-order":1}`) + // Marshaling is a round trip. `something` is not an extension and Validate + // ignores it below, but it is still written back out: a document that comes + // back missing a field it was written with means something different, and + // nothing would report the change. + expectMarshalJson := data ref := openapi3.{{ $type.Name }}Ref{} err := json.Unmarshal(data, &ref) @@ -50,7 +54,7 @@ func Test{{ $type.Name }}Ref_Extensions(t *testing.T) { // Compare as string to make error message more readable if different outJson, err := ref.MarshalJSON() assert.NoError(t, err) - assert.Equal(t, string(outJson), string(expectMarshalJson), "MarshalJSON output is not the same as input data") + assert.Equal(t, string(expectMarshalJson), string(outJson), "MarshalJSON output is not the same as input data") // non-extension not json lookable _, err = ref.JSONLookup("something") diff --git a/openapi3/testdata/apis_guru_openapi_directory/apicurio_local_registry_1_3_2_Final_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/apicurio_local_registry_1_3_2_Final_openapi_yaml__validate index 18c3ac135..16a559ed7 100644 --- a/openapi3/testdata/apis_guru_openapi_directory/apicurio_local_registry_1_3_2_Final_openapi_yaml__validate +++ b/openapi3/testdata/apis_guru_openapi_directory/apicurio_local_registry_1_3_2_Final_openapi_yaml__validate @@ -56,13 +56,16 @@ Schema: "type": "string" }, "properties": { - "$ref": "#/components/schemas/Properties" + "$ref": "#/components/schemas/Properties", + "description": "" }, "state": { - "$ref": "#/components/schemas/ArtifactState" + "$ref": "#/components/schemas/ArtifactState", + "description": "" }, "type": { - "$ref": "#/components/schemas/ArtifactType" + "$ref": "#/components/schemas/ArtifactType", + "description": "" }, "version": { "format": "int64", diff --git a/openapi3/testdata/apis_guru_openapi_directory/apicurio_local_registry_2_4_x_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/apicurio_local_registry_2_4_x_openapi_yaml__validate index 435f52950..a2d94bdd9 100644 --- a/openapi3/testdata/apis_guru_openapi_directory/apicurio_local_registry_2_4_x_openapi_yaml__validate +++ b/openapi3/testdata/apis_guru_openapi_directory/apicurio_local_registry_2_4_x_openapi_yaml__validate @@ -67,10 +67,12 @@ Schema: "type": "integer" }, "groupId": { - "$ref": "#/components/schemas/GroupId" + "$ref": "#/components/schemas/GroupId", + "description": "" }, "id": { - "$ref": "#/components/schemas/ArtifactId" + "$ref": "#/components/schemas/ArtifactId", + "description": "" }, "labels": { "items": { @@ -89,7 +91,8 @@ Schema: "type": "string" }, "properties": { - "$ref": "#/components/schemas/Properties" + "$ref": "#/components/schemas/Properties", + "description": "" }, "references": { "items": { @@ -98,10 +101,12 @@ Schema: "type": "array" }, "state": { - "$ref": "#/components/schemas/ArtifactState" + "$ref": "#/components/schemas/ArtifactState", + "description": "" }, "type": { - "$ref": "#/components/schemas/ArtifactType" + "$ref": "#/components/schemas/ArtifactType", + "description": "" }, "version": { "type": "string" @@ -208,10 +213,12 @@ Schema: "type": "integer" }, "groupId": { - "$ref": "#/components/schemas/GroupId" + "$ref": "#/components/schemas/GroupId", + "description": "" }, "id": { - "$ref": "#/components/schemas/ArtifactId" + "$ref": "#/components/schemas/ArtifactId", + "description": "" }, "labels": { "items": { @@ -230,7 +237,8 @@ Schema: "type": "string" }, "properties": { - "$ref": "#/components/schemas/Properties" + "$ref": "#/components/schemas/Properties", + "description": "" }, "references": { "items": { @@ -239,10 +247,12 @@ Schema: "type": "array" }, "state": { - "$ref": "#/components/schemas/ArtifactState" + "$ref": "#/components/schemas/ArtifactState", + "description": "" }, "type": { - "$ref": "#/components/schemas/ArtifactType" + "$ref": "#/components/schemas/ArtifactType", + "description": "" }, "version": { "type": "string" diff --git a/openapi3filter/validate_response.go b/openapi3filter/validate_response.go index 221d74ae5..eb8a30267 100644 --- a/openapi3filter/validate_response.go +++ b/openapi3filter/validate_response.go @@ -244,7 +244,7 @@ func decodeContentResponseHeader(headerName string, header *openapi3.Header, inp } schema = mt.Schema.Value _, value, err = decodeBody(strings.NewReader(values[0]), http.Header{headerCT: {mediaType}}, mt.Schema, nil) - return + return // Only one pass } return } From 11caa38d7b9067a9c91f2f79b32a1ea663ae6637 Mon Sep 17 00:00:00 2001 From: Pierre Fenoll Date: Tue, 20 Oct 2026 00:52:25 +0200 Subject: [PATCH 04/78] openapi3: tell apart a $ref being resolved as different kinds of objects The loader records the $refs it is in the middle of resolving, to close cycles: a $ref met again is filled in with the value once it is resolved. It recorded them by $ref alone, so the same $ref written for a path item and for one of its responses handed the path item to the response, which panicked with "interface conversion: interface {} is *openapi3.PathItem, not *openapi3.Response". They are now recorded by kind of object and $ref. Signed-off-by: Pierre Fenoll --- README.md | 2 + openapi3/loader.go | 89 +++++++++++++++++-------------- openapi3/loader_ref_kinds_test.go | 26 +++++++++ 3 files changed, 77 insertions(+), 40 deletions(-) create mode 100644 openapi3/loader_ref_kinds_test.go diff --git a/README.md b/README.md index 6e3e66764..6a896668e 100644 --- a/README.md +++ b/README.md @@ -340,6 +340,8 @@ for _, path := range doc.Paths.InMatchingOrder() { * `Validate` no longer reports `extra sibling fields` for fields written next to a `$ref`: every version's Reference Object says they "SHALL be ignored". From OpenAPI 3.1 on, `summary` and `description` still override the referenced component's. `ExtraSiblingFieldsError` is still returned for unknown fields of inline objects, and for `x-` extensions next to a `$ref` under `ProhibitExtensionsWithRef`, which now applies to OpenAPI 3.1+ schemas too. It is no longer returned after `InternalizeRefs` for the fields that were next to a component's `$ref` it replaced, and which it leaves out. * In OpenAPI 3.1+ documents, the keywords next to a schema's `$ref` now apply alongside the referenced schema, as JSON Schema 2020-12 has it, instead of replacing its keywords of the same name: `{"$ref": ..., "maxLength": 10}` next to a referenced `maxLength: 3` still rejects `"abcd"`, and sibling `required` or `properties` add to the referenced ones. The resolved `SchemaRef.Value` keeps the referenced schema's shape: annotations such as `description`, `readOnly` or `default` replace the referenced ones there, and the other sibling keywords are appended to its `AllOf`. * Marshaling an `openapi3.*Ref` with a `$ref` now writes back the fields that were written next to it, instead of emitting a lone `{"$ref": ...}`. An OpenAPI 3.1 schema's sibling keywords, which constrain the referenced schema, were lost that way, and so was every other field next to a `$ref`. +* The loader now resolves a Path Item Object's `$ref` even when fields are written next to it, and merges the two: it used to skip the `$ref` then, silently dropping every operation of the referenced path item and never noticing a `$ref` to nothing. The specification leaves the result undefined only for a field set on both sides, which is then taken from next to the `$ref`. Marshaling writes back the `$ref` with the fields that were next to it, which it used to drop. +* The loader no longer panics with `interface conversion` when the same `$ref` is written where two kinds of objects are expected, one nested in the other, such as a path item and one of its responses. ### v0.150.0 * `openapi2.Operation.Responses` field type changed from `map[string]*Response` to `*Responses`, which keeps the Responses Object's `x-` extensions in `Responses.Extensions` instead of failing to decode them as responses. diff --git a/openapi3/loader.go b/openapi3/loader.go index 4d612abd4..86647b3d3 100644 --- a/openapi3/loader.go +++ b/openapi3/loader.go @@ -402,29 +402,38 @@ func isSingleRefElement(ref string) bool { return !strings.Contains(ref, "#") } -func (loader *Loader) visitRef(ref string) { +// visitedRefKey identifies a $ref being resolved as an object of the given +// kind. The same $ref can be written where different kinds of objects are +// expected, as in a path item and in one of its responses: resolving one must +// not hand its value over to the other. +func visitedRefKey(kind, ref string) string { return kind + " " + ref } + +func (loader *Loader) visitRef(kind, ref string) { if loader.visitedRefs == nil { loader.visitedRefs = make(map[string]struct{}) loader.backtrack = make(map[string][]func(value any)) } - loader.visitedPath = append(loader.visitedPath, ref) - loader.visitedRefs[ref] = struct{}{} + key := visitedRefKey(kind, ref) + loader.visitedPath = append(loader.visitedPath, key) + loader.visitedRefs[key] = struct{}{} } -func (loader *Loader) unvisitRef(ref string, value any) { +func (loader *Loader) unvisitRef(kind, ref string, value any) { + key := visitedRefKey(kind, ref) if value != nil { - for _, fn := range loader.backtrack[ref] { + for _, fn := range loader.backtrack[key] { fn(value) } } - delete(loader.visitedRefs, ref) - delete(loader.backtrack, ref) + delete(loader.visitedRefs, key) + delete(loader.backtrack, key) loader.visitedPath = loader.visitedPath[:len(loader.visitedPath)-1] } -func (loader *Loader) shouldVisitRef(ref string, fn func(value any)) bool { - if _, ok := loader.visitedRefs[ref]; ok { - loader.backtrack[ref] = append(loader.backtrack[ref], fn) +func (loader *Loader) shouldVisitRef(kind, ref string, fn func(value any)) bool { + key := visitedRefKey(kind, ref) + if _, ok := loader.visitedRefs[key]; ok { + loader.backtrack[key] = append(loader.backtrack[key], fn) return false } return true @@ -745,7 +754,7 @@ func (loader *Loader) resolveHeaderRef(doc *T, component *HeaderRef, documentPat if component.Value != nil { return nil } - if !loader.shouldVisitRef(ref, func(value any) { + if !loader.shouldVisitRef("Header", ref, func(value any) { component.Value = value.(*Header) applyHeaderRefMetadata(component.Value, component, isOpenAPI31OrLater) refPath, _ := loader.resolveRefPath(ref, documentPath) @@ -753,7 +762,7 @@ func (loader *Loader) resolveHeaderRef(doc *T, component *HeaderRef, documentPat }) { return nil } - loader.visitRef(ref) + loader.visitRef("Header", ref) if isSingleRefElement(ref) { var header Header if documentPath, err = loader.loadSingleElementFromURI(ref, documentPath, &header); err != nil { @@ -776,7 +785,7 @@ func (loader *Loader) resolveHeaderRef(doc *T, component *HeaderRef, documentPat component.Value = resolved.Value component.setRefPath(resolved.RefPath()) } - defer loader.unvisitRef(ref, component.Value) + defer loader.unvisitRef("Header", ref, component.Value) applyHeaderRefMetadata(component.Value, component, isOpenAPI31OrLater) } value := component.Value @@ -816,7 +825,7 @@ func (loader *Loader) resolveParameterRef(doc *T, component *ParameterRef, docum if component.Value != nil { return nil } - if !loader.shouldVisitRef(ref, func(value any) { + if !loader.shouldVisitRef("Parameter", ref, func(value any) { component.Value = value.(*Parameter) applyParameterRefMetadata(component.Value, component, isOpenAPI31OrLater) refPath, _ := loader.resolveRefPath(ref, documentPath) @@ -824,7 +833,7 @@ func (loader *Loader) resolveParameterRef(doc *T, component *ParameterRef, docum }) { return nil } - loader.visitRef(ref) + loader.visitRef("Parameter", ref) if isSingleRefElement(ref) { var param Parameter if documentPath, err = loader.loadSingleElementFromURI(ref, documentPath, ¶m); err != nil { @@ -847,7 +856,7 @@ func (loader *Loader) resolveParameterRef(doc *T, component *ParameterRef, docum component.Value = resolved.Value component.setRefPath(resolved.RefPath()) } - defer loader.unvisitRef(ref, component.Value) + defer loader.unvisitRef("Parameter", ref, component.Value) applyParameterRefMetadata(component.Value, component, isOpenAPI31OrLater) } value := component.Value @@ -895,7 +904,7 @@ func (loader *Loader) resolveRequestBodyRef(doc *T, component *RequestBodyRef, d if component.Value != nil { return nil } - if !loader.shouldVisitRef(ref, func(value any) { + if !loader.shouldVisitRef("RequestBody", ref, func(value any) { component.Value = value.(*RequestBody) applyRequestBodyRefMetadata(component.Value, component, isOpenAPI31OrLater) refPath, _ := loader.resolveRefPath(ref, documentPath) @@ -903,7 +912,7 @@ func (loader *Loader) resolveRequestBodyRef(doc *T, component *RequestBodyRef, d }) { return nil } - loader.visitRef(ref) + loader.visitRef("RequestBody", ref) if isSingleRefElement(ref) { var requestBody RequestBody if documentPath, err = loader.loadSingleElementFromURI(ref, documentPath, &requestBody); err != nil { @@ -926,7 +935,7 @@ func (loader *Loader) resolveRequestBodyRef(doc *T, component *RequestBodyRef, d component.Value = resolved.Value component.setRefPath(resolved.RefPath()) } - defer loader.unvisitRef(ref, component.Value) + defer loader.unvisitRef("RequestBody", ref, component.Value) applyRequestBodyRefMetadata(component.Value, component, isOpenAPI31OrLater) } value := component.Value @@ -961,7 +970,7 @@ func (loader *Loader) resolveResponseRef(doc *T, component *ResponseRef, documen if component.Value != nil { return nil } - if !loader.shouldVisitRef(ref, func(value any) { + if !loader.shouldVisitRef("Response", ref, func(value any) { component.Value = value.(*Response) applyResponseRefMetadata(component.Value, component, isOpenAPI31OrLater) refPath, _ := loader.resolveRefPath(ref, documentPath) @@ -969,7 +978,7 @@ func (loader *Loader) resolveResponseRef(doc *T, component *ResponseRef, documen }) { return nil } - loader.visitRef(ref) + loader.visitRef("Response", ref) if isSingleRefElement(ref) { var resp Response if documentPath, err = loader.loadSingleElementFromURI(ref, documentPath, &resp); err != nil { @@ -992,7 +1001,7 @@ func (loader *Loader) resolveResponseRef(doc *T, component *ResponseRef, documen component.Value = resolved.Value component.setRefPath(resolved.RefPath()) } - defer loader.unvisitRef(ref, component.Value) + defer loader.unvisitRef("Response", ref, component.Value) applyResponseRefMetadata(component.Value, component, isOpenAPI31OrLater) } value := component.Value @@ -1061,7 +1070,7 @@ func (loader *Loader) resolveSchemaRef(doc *T, component *SchemaRef, documentPat return err } } - if !loader.shouldVisitRef(ref, func(value any) { + if !loader.shouldVisitRef("Schema", ref, func(value any) { component.Value = value.(*Schema) refPath, _ := loader.resolveRefPath(ref, documentPath) component.setRefPath(refPath) @@ -1072,7 +1081,7 @@ func (loader *Loader) resolveSchemaRef(doc *T, component *SchemaRef, documentPat }) { return nil } - loader.visitRef(ref) + loader.visitRef("Schema", ref) if isSingleRefElement(ref) { var schema Schema if documentPath, err = loader.loadSingleElementFromURI(ref, documentPath, &schema); err != nil { @@ -1095,7 +1104,7 @@ func (loader *Loader) resolveSchemaRef(doc *T, component *SchemaRef, documentPat component.Value = resolved.Value component.setRefPath(resolved.RefPath()) } - defer loader.unvisitRef(ref, component.Value) + defer loader.unvisitRef("Schema", ref, component.Value) // OAS 3.1 / JSON Schema 2020-12: apply sibling keywords from the original schema // object on top of the resolved $ref value. In 3.1, siblings are not ignored — @@ -1257,7 +1266,7 @@ func (loader *Loader) resolveSecuritySchemeRef(doc *T, component *SecurityScheme if component.Value != nil { return nil } - if !loader.shouldVisitRef(ref, func(value any) { + if !loader.shouldVisitRef("SecurityScheme", ref, func(value any) { component.Value = value.(*SecurityScheme) applySecuritySchemeRefMetadata(component.Value, component, isOpenAPI31OrLater) refPath, _ := loader.resolveRefPath(ref, documentPath) @@ -1265,7 +1274,7 @@ func (loader *Loader) resolveSecuritySchemeRef(doc *T, component *SecurityScheme }) { return nil } - loader.visitRef(ref) + loader.visitRef("SecurityScheme", ref) if isSingleRefElement(ref) { var scheme SecurityScheme if _, err = loader.loadSingleElementFromURI(ref, documentPath, &scheme); err != nil { @@ -1288,7 +1297,7 @@ func (loader *Loader) resolveSecuritySchemeRef(doc *T, component *SecurityScheme component.Value = resolved.Value component.setRefPath(resolved.RefPath()) } - defer loader.unvisitRef(ref, component.Value) + defer loader.unvisitRef("SecurityScheme", ref, component.Value) applySecuritySchemeRefMetadata(component.Value, component, isOpenAPI31OrLater) } return nil @@ -1318,7 +1327,7 @@ func (loader *Loader) resolveExampleRef(doc *T, component *ExampleRef, documentP if component.Value != nil { return nil } - if !loader.shouldVisitRef(ref, func(value any) { + if !loader.shouldVisitRef("Example", ref, func(value any) { component.Value = value.(*Example) applyExampleRefMetadata(component.Value, component, isOpenAPI31OrLater) refPath, _ := loader.resolveRefPath(ref, documentPath) @@ -1326,7 +1335,7 @@ func (loader *Loader) resolveExampleRef(doc *T, component *ExampleRef, documentP }) { return nil } - loader.visitRef(ref) + loader.visitRef("Example", ref) if isSingleRefElement(ref) { var example Example if _, err = loader.loadSingleElementFromURI(ref, documentPath, &example); err != nil { @@ -1349,7 +1358,7 @@ func (loader *Loader) resolveExampleRef(doc *T, component *ExampleRef, documentP component.Value = resolved.Value component.setRefPath(resolved.RefPath()) } - defer loader.unvisitRef(ref, component.Value) + defer loader.unvisitRef("Example", ref, component.Value) applyExampleRefMetadata(component.Value, component, isOpenAPI31OrLater) } return nil @@ -1364,14 +1373,14 @@ func (loader *Loader) resolveCallbackRef(doc *T, component *CallbackRef, documen if component.Value != nil { return nil } - if !loader.shouldVisitRef(ref, func(value any) { + if !loader.shouldVisitRef("Callback", ref, func(value any) { component.Value = value.(*Callback) refPath, _ := loader.resolveRefPath(ref, documentPath) component.setRefPath(refPath) }) { return nil } - loader.visitRef(ref) + loader.visitRef("Callback", ref) if isSingleRefElement(ref) { var resolved Callback if documentPath, err = loader.loadSingleElementFromURI(ref, documentPath, &resolved); err != nil { @@ -1394,7 +1403,7 @@ func (loader *Loader) resolveCallbackRef(doc *T, component *CallbackRef, documen component.Value = resolved.Value component.setRefPath(resolved.RefPath()) } - defer loader.unvisitRef(ref, component.Value) + defer loader.unvisitRef("Callback", ref, component.Value) } value := component.Value if value == nil { @@ -1430,7 +1439,7 @@ func (loader *Loader) resolveLinkRef(doc *T, component *LinkRef, documentPath *u if component.Value != nil { return nil } - if !loader.shouldVisitRef(ref, func(value any) { + if !loader.shouldVisitRef("Link", ref, func(value any) { component.Value = value.(*Link) applyLinkRefMetadata(component.Value, component, isOpenAPI31OrLater) refPath, _ := loader.resolveRefPath(ref, documentPath) @@ -1438,7 +1447,7 @@ func (loader *Loader) resolveLinkRef(doc *T, component *LinkRef, documentPath *u }) { return nil } - loader.visitRef(ref) + loader.visitRef("Link", ref) if isSingleRefElement(ref) { var link Link if _, err = loader.loadSingleElementFromURI(ref, documentPath, &link); err != nil { @@ -1461,7 +1470,7 @@ func (loader *Loader) resolveLinkRef(doc *T, component *LinkRef, documentPath *u component.Value = resolved.Value component.setRefPath(resolved.RefPath()) } - defer loader.unvisitRef(ref, component.Value) + defer loader.unvisitRef("Link", ref, component.Value) applyLinkRefMetadata(component.Value, component, isOpenAPI31OrLater) } return nil @@ -1477,12 +1486,12 @@ func (loader *Loader) resolvePathItemRef(doc *T, pathItem *PathItem, documentPat if !pathItem.isEmpty() { return } - if !loader.shouldVisitRef(ref, func(value any) { + if !loader.shouldVisitRef("PathItem", ref, func(value any) { *pathItem = *value.(*PathItem) }) { return nil } - loader.visitRef(ref) + loader.visitRef("PathItem", ref) if isSingleRefElement(ref) { var p PathItem if documentPath, err = loader.loadSingleElementFromURI(ref, documentPath, &p); err != nil { @@ -1500,7 +1509,7 @@ func (loader *Loader) resolvePathItemRef(doc *T, pathItem *PathItem, documentPat *pathItem = resolved } pathItem.Ref = ref - defer loader.unvisitRef(ref, pathItem) + defer loader.unvisitRef("PathItem", ref, pathItem) } for _, parameter := range pathItem.Parameters { diff --git a/openapi3/loader_ref_kinds_test.go b/openapi3/loader_ref_kinds_test.go new file mode 100644 index 000000000..8c48ce728 --- /dev/null +++ b/openapi3/loader_ref_kinds_test.go @@ -0,0 +1,26 @@ +package openapi3_test + +import ( + "testing" + + "github.com/stretchr/testify/require" + + "github.com/getkin/kin-openapi/openapi3" +) + +// The same $ref written where two kinds of objects are expected, one within +// the other, must not hand the value resolved for one to the other. +func TestSameRefForDifferentKindsOfObjects(t *testing.T) { + t.Parallel() + loader := openapi3.NewLoader() + require.NotPanics(t, func() { + _, _ = loader.LoadFromData([]byte(`{ + "openapi": "3.0.3", + "info": {"title": "t", "version": "1"}, + "paths": { + "/x": {"$ref": "#/paths/~1y"}, + "/y": {"get": {"responses": {"200": {"$ref": "#/paths/~1y"}}}} + } +}`)) + }) +} From c59eda0a25da1a208c408dabb2d37224fdd62632 Mon Sep 17 00:00:00 2001 From: Pierre Fenoll Date: Mon, 19 Oct 2026 21:26:30 +0200 Subject: [PATCH 05/78] openapi3: merge the fields next to a path item's $ref with the item it points to A Path Item Object's $ref is no Reference Object: the fields written next to it belong to the same path item, and every version of the specification leaves the result undefined only "in case a Path Item Object field appears both in the defined object and the referenced object". Any such field made the loader skip the $ref, silently dropping all the operations of the referenced path item, and letting a $ref to nothing go unnoticed. Both are now merged; a field set on both sides is taken from next to the $ref, as a Reference Object's summary and description are, which is what OpenAPI 3.1 says this $ref is likely to be aligned with. Marshaling writes back the $ref with the fields that were next to it, instead of the $ref alone. Signed-off-by: Pierre Fenoll --- .github/docs/openapi3.txt | 2 + openapi3/loader.go | 26 +++++-- openapi3/path_item.go | 86 +++++++++++++++++++++- openapi3/path_item_ref_siblings_test.go | 96 +++++++++++++++++++++++++ 4 files changed, 204 insertions(+), 6 deletions(-) create mode 100644 openapi3/path_item_ref_siblings_test.go diff --git a/.github/docs/openapi3.txt b/.github/docs/openapi3.txt index 1c77fe090..a77c3e95e 100644 --- a/.github/docs/openapi3.txt +++ b/.github/docs/openapi3.txt @@ -2282,6 +2282,8 @@ type PathItem struct { // Keys are case-sensitive HTTP method tokens and must not duplicate // the methods covered by the fixed fields above. AdditionalOperations map[string]*Operation `json:"additionalOperations,omitempty,case:strict" yaml:"additionalOperations,omitempty"` // OpenAPI >=3.2 + + // Has unexported fields. } PathItem is specified by OpenAPI/Swagger standard version 3. See https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#path-item-object diff --git a/openapi3/loader.go b/openapi3/loader.go index 86647b3d3..72850311a 100644 --- a/openapi3/loader.go +++ b/openapi3/loader.go @@ -1483,11 +1483,28 @@ func (loader *Loader) resolvePathItemRef(doc *T, pathItem *PathItem, documentPat } if ref := pathItem.Ref; ref != "" { - if !pathItem.isEmpty() { + if pathItem.refResolved { return } + // The fields written next to $ref used to stop it from being resolved. + // They are merged with the item it points to instead; see mergeRefSiblings. + var siblings *PathItem + if !pathItem.isEmpty() || len(pathItem.Extensions) != 0 { + local := *pathItem + local.Ref = "" + siblings = &local + } + resolvedTo := func(resolved PathItem) { + *pathItem = resolved + pathItem.Ref = ref + pathItem.refResolved = true + if siblings != nil { + pathItem.mergeRefSiblings(siblings) + pathItem.refSiblings = siblings + } + } if !loader.shouldVisitRef("PathItem", ref, func(value any) { - *pathItem = *value.(*PathItem) + resolvedTo(*value.(*PathItem)) }) { return nil } @@ -1497,7 +1514,7 @@ func (loader *Loader) resolvePathItemRef(doc *T, pathItem *PathItem, documentPat if documentPath, err = loader.loadSingleElementFromURI(ref, documentPath, &p); err != nil { return } - *pathItem = p + resolvedTo(p) } else { var resolved PathItem if doc, documentPath, err = loader.resolveComponent(doc, ref, documentPath, &resolved); err != nil { @@ -1506,9 +1523,8 @@ func (loader *Loader) resolvePathItemRef(doc *T, pathItem *PathItem, documentPat } return } - *pathItem = resolved + resolvedTo(resolved) } - pathItem.Ref = ref defer loader.unvisitRef("PathItem", ref, pathItem) } diff --git a/openapi3/path_item.go b/openapi3/path_item.go index 2ce2f5233..2f1c6edcf 100644 --- a/openapi3/path_item.go +++ b/openapi3/path_item.go @@ -35,6 +35,14 @@ type PathItem struct { // Keys are case-sensitive HTTP method tokens and must not duplicate // the methods covered by the fixed fields above. AdditionalOperations map[string]*Operation `json:"additionalOperations,omitempty,case:strict" yaml:"additionalOperations,omitempty"` // OpenAPI >=3.2 + + // refSiblings holds the fields written next to Ref, as the document had + // them: once the loader has merged the referenced path item in, they can no + // longer be told apart from it, and marshaling writes back only these. + refSiblings *PathItem + // refResolved records that the loader has merged the referenced path item + // in, so that it does not do it twice. + refResolved bool } // MethodQuery is the HTTP QUERY method, introduced as a fixed Path Item @@ -80,7 +88,19 @@ func (pathItem PathItem) MarshalJSON() ([]byte, error) { // MarshalYAML returns the YAML encoding of PathItem. func (pathItem PathItem) MarshalYAML() (any, error) { if ref := pathItem.Ref; ref != "" { - return Ref{Ref: ref}, nil + if pathItem.refResolved { + if pathItem.refSiblings == nil { + return Ref{Ref: ref}, nil + } + pathItem = *pathItem.refSiblings + } + pathItem.Ref = "" + m, err := pathItem.MarshalYAML() + if err != nil { + return nil, err + } + m.(map[string]any)["$ref"] = ref + return m, nil } m := make(map[string]any, 15+len(pathItem.Extensions)) @@ -381,6 +401,70 @@ func (pathItem *PathItem) Validate(ctx context.Context, opts ...ValidationOption } // isEmpty's introduced in 546590b1 +// mergeRefSiblings sets on pathItem, a copy of the item its $ref points to, +// the fields that siblings, the item holding that $ref, sets. +// +// The specification only defines the result when no field is set on both: "In +// case a Path Item Object field appears both in the defined object and the +// referenced object, the behavior is undefined". The sibling then wins, like +// the summary and description of a Reference Object do over those of the +// object it points to, which is what OpenAPI 3.1 says this $ref is likely to +// be aligned with. It never modifies the maps of the referenced item, which +// other path items may share. +func (pathItem *PathItem) mergeRefSiblings(siblings *PathItem) { + if len(siblings.Extensions) != 0 { + extensions := make(map[string]any, len(pathItem.Extensions)+len(siblings.Extensions)) + maps.Copy(extensions, pathItem.Extensions) + maps.Copy(extensions, siblings.Extensions) + pathItem.Extensions = extensions + } + if x := siblings.Summary; x != "" { + pathItem.Summary = x + } + if x := siblings.Description; x != "" { + pathItem.Description = x + } + if x := siblings.Connect; x != nil { + pathItem.Connect = x + } + if x := siblings.Delete; x != nil { + pathItem.Delete = x + } + if x := siblings.Get; x != nil { + pathItem.Get = x + } + if x := siblings.Head; x != nil { + pathItem.Head = x + } + if x := siblings.Options; x != nil { + pathItem.Options = x + } + if x := siblings.Patch; x != nil { + pathItem.Patch = x + } + if x := siblings.Post; x != nil { + pathItem.Post = x + } + if x := siblings.Put; x != nil { + pathItem.Put = x + } + if x := siblings.Trace; x != nil { + pathItem.Trace = x + } + if x := siblings.Query; x != nil { + pathItem.Query = x + } + if x := siblings.AdditionalOperations; len(x) != 0 { + pathItem.AdditionalOperations = x + } + if x := siblings.Servers; len(x) != 0 { + pathItem.Servers = x + } + if x := siblings.Parameters; len(x) != 0 { + pathItem.Parameters = x + } +} + func (pathItem *PathItem) isEmpty() bool { // NOTE: ignores pathItem.Extensions // NOTE: ignores pathItem.Ref diff --git a/openapi3/path_item_ref_siblings_test.go b/openapi3/path_item_ref_siblings_test.go new file mode 100644 index 000000000..aea0a7cd6 --- /dev/null +++ b/openapi3/path_item_ref_siblings_test.go @@ -0,0 +1,96 @@ +package openapi3_test + +import ( + "fmt" + "testing" + + "github.com/stretchr/testify/require" + + "github.com/getkin/kin-openapi/openapi3" +) + +func loadPathItemRefSiblings(t *testing.T, version, siblings string) (*openapi3.T, error) { + t.Helper() + loader := openapi3.NewLoader() + return loader.LoadFromData(fmt.Appendf(nil, `{ + "openapi": %q, + "info": {"title": "t", "version": "1"}, + "paths": { + "/x": {"$ref": "#/paths/~1y", %s}, + "/y": { + "summary": "target", + "get": {"responses": {"200": {"description": "target get"}}} + } + } +}`, version, siblings)) +} + +// A Path Item Object's $ref is not a Reference Object: the fields written next +// to it are part of the same path item. The specification leaves only the +// result for a field set on both sides undefined. +func TestPathItemRefSiblings(t *testing.T) { + t.Parallel() + for _, version := range []string{"3.0.3", "3.1.0", "3.2.0"} { + t.Run(version, func(t *testing.T) { + t.Parallel() + t.Run("fields set on one side only are merged", func(t *testing.T) { + t.Parallel() + doc, err := loadPathItemRefSiblings(t, version, `"post": {"responses": {"200": {"description": "local post"}}}`) + require.NoError(t, err) + require.NoError(t, doc.Validate(t.Context())) + + x := doc.Paths.Value("/x") + require.Equal(t, "target", x.Summary) + require.Equal(t, "target get", *x.Get.Responses.Value("200").Value.Description) + require.Equal(t, "local post", *x.Post.Responses.Value("200").Value.Description) + + // The referenced path item is not changed. + require.Nil(t, doc.Paths.Value("/y").Post) + }) + + t.Run("a field set on both sides is taken from next to the $ref", func(t *testing.T) { + t.Parallel() + doc, err := loadPathItemRefSiblings(t, version, `"summary": "local", "get": {"responses": {"200": {"description": "local get"}}}`) + require.NoError(t, err) + require.NoError(t, doc.Validate(t.Context())) + + x := doc.Paths.Value("/x") + require.Equal(t, "local", x.Summary) + require.Equal(t, "local get", *x.Get.Responses.Value("200").Value.Description) + + y := doc.Paths.Value("/y") + require.Equal(t, "target", y.Summary) + require.Equal(t, "target get", *y.Get.Responses.Value("200").Value.Description) + }) + + t.Run("only the fields next to the $ref are marshaled back", func(t *testing.T) { + t.Parallel() + doc, err := loadPathItemRefSiblings(t, version, `"summary": "local", "x-local": 1`) + require.NoError(t, err) + + data, err := doc.Paths.Value("/x").MarshalJSON() + require.NoError(t, err) + require.JSONEq(t, `{"$ref": "#/paths/~1y", "summary": "local", "x-local": 1}`, string(data)) + + data, err = doc.MarshalJSON() + require.NoError(t, err) + loader := openapi3.NewLoader() + reloaded, err := loader.LoadFromData(data) + require.NoError(t, err) + require.Equal(t, "local", reloaded.Paths.Value("/x").Summary) + require.NotNil(t, reloaded.Paths.Value("/x").Get) + }) + + t.Run("a $ref to nothing is reported despite the siblings", func(t *testing.T) { + t.Parallel() + loader := openapi3.NewLoader() + _, err := loader.LoadFromData(fmt.Appendf(nil, `{ + "openapi": %q, + "info": {"title": "t", "version": "1"}, + "paths": {"/x": {"$ref": "#/paths/~1nowhere", "summary": "local"}} +}`, version)) + require.Error(t, err) + }) + }) + } +} From 98fd8d4745636cef0043b00895c8ede0690f1b9a Mon Sep 17 00:00:00 2001 From: Pierre Fenoll Date: Tue, 20 Oct 2026 21:46:54 +0200 Subject: [PATCH 06/78] openapi3: internalize, version and locate the keywords next to a schema $ref Running the test cases of #1271 against the previous commits shows four ways the keywords written next to an OpenAPI 3.1 schema's $ref still go wrong: * InternalizeRefs made a component of a $ref's Value, which is a copy of the referenced schema with the siblings applied, so they leaked into every other use of that component. It now uses the referenced schema, which SchemaRef keeps for this. And the external $refs within the siblings were rewritten in memory but marshaled as they were first read, so the internalized document still pointed outside. Marshaling now takes each sibling from what the parsed siblings now hold, and falls back to what was read for the fields a Schema leaves out, such as pattern: "". * A file of bare schemas has no openapi field, so the siblings of the $refs within it were ignored as in OpenAPI 3.0, even when an OpenAPI 3.1 document referred to it. Such a file now follows the version of the document whose refs the loader resolves. * Siblings that do not form a schema, such as allOf: {type: integer}, were silently dropped. OpenAPI 3.1 reads them as a Schema Object, so loading now fails there. OpenAPI 3.0 still ignores them. * The allOf entry made of the assertion siblings had no Origin, so the errors it raised, such as for an invalid pattern, could not be located. It now shares the $ref's. Signed-off-by: Pierre Fenoll --- README.md | 4 ++++ openapi3/internalize_refs.go | 8 +++++++- openapi3/loader.go | 39 ++++++++++++++++++++++++++++++------ openapi3/refs.go | 25 +++++++++++++++++++++++ openapi3/refs.tmpl | 27 +++++++++++++++++++++++++ 5 files changed, 96 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 6a896668e..5f058ba95 100644 --- a/README.md +++ b/README.md @@ -342,6 +342,10 @@ for _, path := range doc.Paths.InMatchingOrder() { * Marshaling an `openapi3.*Ref` with a `$ref` now writes back the fields that were written next to it, instead of emitting a lone `{"$ref": ...}`. An OpenAPI 3.1 schema's sibling keywords, which constrain the referenced schema, were lost that way, and so was every other field next to a `$ref`. * The loader now resolves a Path Item Object's `$ref` even when fields are written next to it, and merges the two: it used to skip the `$ref` then, silently dropping every operation of the referenced path item and never noticing a `$ref` to nothing. The specification leaves the result undefined only for a field set on both sides, which is then taken from next to the `$ref`. Marshaling writes back the `$ref` with the fields that were next to it, which it used to drop. * The loader no longer panics with `interface conversion` when the same `$ref` is written where two kinds of objects are expected, one nested in the other, such as a path item and one of its responses. +* `InternalizeRefs` now makes a component of the schema an external `$ref` points to, rather than of that schema with the OpenAPI 3.1 keywords next to the `$ref` applied to it, which leaked them into every other use of the component. The external `$ref`s within those keywords are now rewritten in the marshaled document too. +* The keywords next to a schema's `$ref` in a file of bare schemas, which has no `openapi` field, now follow the version of the document that refers to the file: they were ignored, as in OpenAPI 3.0, even from an OpenAPI 3.1 document. +* In OpenAPI 3.1+ documents, loading now fails when the keywords next to a schema's `$ref` do not form a schema, such as `allOf: {type: integer}`, instead of silently ignoring them all. +* The errors raised by the keywords next to an OpenAPI 3.1 schema's `$ref` now carry their `Origin`. ### v0.150.0 * `openapi2.Operation.Responses` field type changed from `map[string]*Response` to `*Responses`, which keeps the Responses Object's `x-` extensions in `Responses.Extensions` instead of failing to decode them as responses. diff --git a/openapi3/internalize_refs.go b/openapi3/internalize_refs.go index 3dd99aca7..dbed548a2 100644 --- a/openapi3/internalize_refs.go +++ b/openapi3/internalize_refs.go @@ -148,7 +148,13 @@ func (doc *T) addSchemaToSpec(s *SchemaRef, refNameResolver RefNameResolver, par if doc.Components.Schemas == nil { doc.Components.Schemas = make(Schemas) } - doc.Components.Schemas[name] = s.Value.NewRef() + // A $ref with siblings has a copy of its target as Value, with the siblings + // applied: the component is the target itself. + value := s.Value + if s.target != nil { + value = s.target + } + doc.Components.Schemas[name] = value.NewRef() s.Ref = "#/components/schemas/" + name return true } diff --git a/openapi3/loader.go b/openapi3/loader.go index 72850311a..e7e422cdc 100644 --- a/openapi3/loader.go +++ b/openapi3/loader.go @@ -67,6 +67,12 @@ type Loader struct { visitedRefs map[string]struct{} visitedPath []string backtrack map[string][]func(value any) + + // rootDoc is the document whose refs are being resolved, as opposed to + // the documents it refers to, and resolvingDepth how deep in these the + // loader currently is. + rootDoc *T + resolvingDepth int } // NewLoader returns an empty Loader @@ -250,6 +256,12 @@ func (loader *Loader) ResolveRefsIn(doc *T, location *url.URL) (err error) { loader.Context = context.Background() } + if loader.resolvingDepth == 0 { + loader.rootDoc = doc + } + loader.resolvingDepth++ + defer func() { loader.resolvingDepth-- }() + if loader.visitedPathItemRefs == nil { loader.resetVisitedPathItemRefs() } @@ -1062,7 +1074,10 @@ func (loader *Loader) resolveSchemaRef(doc *T, component *SchemaRef, documentPat if component.Value != nil { return nil } - if doc.IsOpenAPI31OrLater() && component.sibling != nil { + if loader.isOpenAPI31OrLater(doc) && component.siblingErr != nil { + return fmt.Errorf("the fields next to $ref %q are not a schema: %w", ref, component.siblingErr) + } + if loader.isOpenAPI31OrLater(doc) && component.sibling != nil { // Resolve the $refs within the siblings themselves, such as those of // the properties they add, before applyRefSiblings shares them with // Value: it may run from the callback below, which resolves nothing. @@ -1077,7 +1092,7 @@ func (loader *Loader) resolveSchemaRef(doc *T, component *SchemaRef, documentPat // A $ref reached again while its target is still being resolved is // filled in here when the cycle unwinds, which can overwrite a value // that already had its siblings applied, so apply them here as well. - component.applyRefSiblings(doc) + component.applyRefSiblings(loader.isOpenAPI31OrLater(doc)) }) { return nil } @@ -1111,7 +1126,7 @@ func (loader *Loader) resolveSchemaRef(doc *T, component *SchemaRef, documentPat // they augment the referenced schema (e.g. deprecated:true alongside $ref). // Only apply for OAS 3.1+ — in 3.0 $ref replaces its entire object and siblings // are (validly) ignored. - component.applyRefSiblings(doc) + component.applyRefSiblings(loader.isOpenAPI31OrLater(doc)) } value := component.Value if value == nil { @@ -1596,10 +1611,11 @@ var refSiblingAnnotations = map[string]struct{}{ // referenced schema, with its properties, type and so on. // // It works on a copy so a schema shared by other references is not mutated. -func (component *SchemaRef) applyRefSiblings(doc *T) { - if !doc.IsOpenAPI31OrLater() || component.sibling == nil || component.Value == nil { +func (component *SchemaRef) applyRefSiblings(isOpenAPI31OrLater bool) { + if !isOpenAPI31OrLater || component.sibling == nil || component.Value == nil { return } + component.target = component.Value var annotations, assertions []string for _, field := range component.extra { if _, ok := refSiblingAnnotations[field]; ok { @@ -1611,7 +1627,8 @@ func (component *SchemaRef) applyRefSiblings(doc *T) { schemaCopy := *component.Value applySiblingSchemaFields(&schemaCopy, component.sibling, annotations) if len(assertions) != 0 { - var conjunct Schema + // The siblings sit in the same object as the $ref, so they share its origin. + conjunct := Schema{Origin: component.Origin} applySiblingSchemaFields(&conjunct, component.sibling, assertions) if !conjunct.IsEmpty() { allOf := make(SchemaRefs, 0, len(schemaCopy.AllOf)+1) @@ -1622,6 +1639,16 @@ func (component *SchemaRef) applyRefSiblings(doc *T) { component.Value = &schemaCopy } +// isOpenAPI31OrLater tells whether doc follows OAS 3.1 or later. A document +// that does not say, such as a file of bare schemas a $ref points into, follows +// the version of the document that refers to it. +func (loader *Loader) isOpenAPI31OrLater(doc *T) bool { + if doc.OpenAPI == "" && loader.rootDoc != nil { + doc = loader.rootDoc + } + return doc.IsOpenAPI31OrLater() +} + func unescapeRefString(ref string) string { return strings.ReplaceAll(strings.ReplaceAll(ref, "~1", "/"), "~0", "~") } diff --git a/openapi3/refs.go b/openapi3/refs.go index 83a1fb9b1..9fce3febf 100644 --- a/openapi3/refs.go +++ b/openapi3/refs.go @@ -1163,6 +1163,12 @@ type SchemaRef struct { // sibling holds keyword siblings of a $ref (OAS 3.1 / JSON Schema 2020-12). // It is populated during unmarshal and applied to Value after $ref resolution. sibling *Schema + // siblingErr is why the siblings could not be read as a Schema. OAS 3.1 + // reports it, while OAS 3.0 ignores the fields next to a $ref anyway. + siblingErr error + // target is the referenced schema, which Value is a copy of once siblings + // are applied to it. + target *Schema refPath *url.URL } @@ -1202,6 +1208,23 @@ func (x SchemaRef) MarshalYAML() (any, error) { } if m, ok := out.(map[string]any); ok { maps.Copy(m, x.siblingExtras) + if x.sibling != nil && len(x.siblingExtras) != 0 { + // The $refs within the siblings may have been rewritten since, as + // InternalizeRefs does, so write out what the siblings now hold. A + // field the Schema leaves out, such as an empty pattern, is still + // written as it was. + current, err := x.sibling.MarshalYAML() + if err != nil { + return nil, err + } + if current, ok := current.(map[string]any); ok { + for k := range x.siblingExtras { + if v, ok := current[k]; ok { + m[k] = v + } + } + } + } } return out, nil } @@ -1242,6 +1265,8 @@ func (x *SchemaRef) UnmarshalJSON(data []byte) error { var sibling Schema if err := unmarshalJSON(data, &sibling); err == nil { x.sibling = &sibling + } else { + x.siblingErr = err } } for k, v := range extra { diff --git a/openapi3/refs.tmpl b/openapi3/refs.tmpl index a00db9614..8398c302b 100644 --- a/openapi3/refs.tmpl +++ b/openapi3/refs.tmpl @@ -36,6 +36,12 @@ type {{ $type.Name }}Ref struct { // sibling holds keyword siblings of a $ref (OAS 3.1 / JSON Schema 2020-12). // It is populated during unmarshal and applied to Value after $ref resolution. sibling *Schema + // siblingErr is why the siblings could not be read as a Schema. OAS 3.1 + // reports it, while OAS 3.0 ignores the fields next to a $ref anyway. + siblingErr error + // target is the referenced schema, which Value is a copy of once siblings + // are applied to it. + target *Schema {{- end }} refPath *url.URL @@ -80,6 +86,25 @@ func (x {{ $type.Name }}Ref) MarshalYAML() (any, error) { } if m, ok := out.(map[string]any); ok { maps.Copy(m, x.siblingExtras) + {{- if eq $type.Name "Schema" }} + if x.sibling != nil && len(x.siblingExtras) != 0 { + // The $refs within the siblings may have been rewritten since, as + // InternalizeRefs does, so write out what the siblings now hold. A + // field the Schema leaves out, such as an empty pattern, is still + // written as it was. + current, err := x.sibling.MarshalYAML() + if err != nil { + return nil, err + } + if current, ok := current.(map[string]any); ok { + for k := range x.siblingExtras { + if v, ok := current[k]; ok { + m[k] = v + } + } + } + } + {{- end }} } return out, nil } @@ -127,6 +152,8 @@ func (x *{{ $type.Name }}Ref) UnmarshalJSON(data []byte) error { var sibling Schema if err := unmarshalJSON(data, &sibling); err == nil { x.sibling = &sibling + } else { + x.siblingErr = err } } {{- end }} From 52aade8175050135d50006822c01a95fbd2f92ec Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=94=D0=BC=D0=B8=D1=82=D1=80=D0=B8=D0=B9=20=D0=90=D0=B1?= =?UTF-8?q?=D1=80=D0=B0=D0=BC=D0=BE=D0=B2?= Date: Tue, 20 Oct 2026 21:47:02 +0200 Subject: [PATCH 07/78] openapi3: test $ref siblings with the cases of #1271 These are the test cases of #1271, which makes the keywords next to an OpenAPI 3.1 schema's $ref the Value and the referenced schema an allOf entry of it. Here Value keeps the shape of the referenced schema, so the assertions on where each keyword ends up now check what the schema accepts, or the shape it has here, instead: * Fields next to a $ref round-trip as written, where #1271 writes them out as an ordinary Schema would and so drops their zero values. * In OpenAPI 3.0, where these fields are ignored, the loader does not follow the $refs within them, so InternalizeRefs leaves them as written. #1271 internalizes them. * A cyclic Go value is no longer validated: it overflows the stack against any recursive schema, siblings or not, and decoding JSON cannot produce one. The four cases of $refs that only lead to one another are skipped. Their Value is nil, with or without siblings, as on master: JSON Schema 2020-12 leaves such infinite recursion undefined, and #1271 resolves them to the conjunction of their siblings. Adapted by Pierre Fenoll from https://github.com/getkin/kin-openapi/pull/1271 Signed-off-by: Pierre Fenoll --- openapi3/issue1271_test.go | 744 +++++++++++++++++++++++++++++++++++++ 1 file changed, 744 insertions(+) create mode 100644 openapi3/issue1271_test.go diff --git a/openapi3/issue1271_test.go b/openapi3/issue1271_test.go new file mode 100644 index 000000000..d5b700975 --- /dev/null +++ b/openapi3/issue1271_test.go @@ -0,0 +1,744 @@ +package openapi3_test + +import ( + "encoding/json" + "errors" + "fmt" + "os" + "path/filepath" + "strings" + "testing" + + "github.com/stretchr/testify/require" + + "github.com/getkin/kin-openapi/openapi3" +) + +// These cases come from https://github.com/getkin/kin-openapi/pull/1271. +// There, the keywords next to a 3.1 schema $ref become the Value and the +// referenced schema an allOf entry of it. Here Value keeps the shape of the +// referenced schema, so the cases check what a schema accepts and how it is +// written back out rather than where each keyword ends up. +// +// The skipped cases are $refs that only lead to one another, which leaves +// their Value nil, with or without siblings. JSON Schema 2020-12 leaves such +// infinite recursion undefined (§9.4.1); #1271 resolves them to the +// conjunction of their siblings. + +func TestSchemaRefSiblingIsSerializedAndAppliedAsConjunct(t *testing.T) { + t.Parallel() + loader := openapi3.NewLoader() + doc, err := loader.LoadFromData([]byte(` +openapi: 3.1.0 +info: + title: ref sibling + version: "1" +paths: {} +components: + schemas: + Base: + type: string + maxLength: 5 + Use: + $ref: '#/components/schemas/Base' + minLength: 3 + x-use-site: true +`)) + require.NoError(t, err) + + useRef := doc.Components.Schemas["Use"] + require.Equal(t, "string", useRef.Value.Type.Slice()[0]) + require.Equal(t, uint64(5), *useRef.Value.MaxLength) + require.NotContains(t, doc.Components.Schemas["Base"].Value.Extensions, "x-use-site") + require.Error(t, useRef.Value.VisitJSON("xx", openapi3.EnableJSONSchema2020())) + require.Error(t, useRef.Value.VisitJSON("xxxxxx", openapi3.EnableJSONSchema2020())) + require.NoError(t, useRef.Value.VisitJSON("xxxx", openapi3.EnableJSONSchema2020())) + + data, err := json.Marshal(useRef) + require.NoError(t, err) + require.JSONEq(t, `{ + "$ref":"#/components/schemas/Base", + "minLength":3, + "x-use-site":true +}`, string(data)) + documentData, err := json.Marshal(doc) + require.NoError(t, err) + roundTripLoader := openapi3.NewLoader() + roundTripped, err := roundTripLoader.LoadFromData(documentData) + require.NoError(t, err) + roundTrippedUse := roundTripped.Components.Schemas["Use"].Value + require.Error(t, roundTrippedUse.VisitJSON("xx", openapi3.EnableJSONSchema2020())) + require.Error(t, roundTrippedUse.VisitJSON("xxxxxx", openapi3.EnableJSONSchema2020())) + require.NoError(t, roundTrippedUse.VisitJSON("xxxx", openapi3.EnableJSONSchema2020())) + + useRef.Extensions["x-use-site"] = "changed" + useRef.Extensions["x-added"] = true + data, err = json.Marshal(useRef) + require.NoError(t, err) + require.JSONEq(t, `{ + "$ref":"#/components/schemas/Base", + "minLength":3, + "x-use-site":"changed", + "x-added":true +}`, string(data)) + delete(useRef.Extensions, "x-use-site") + data, err = json.Marshal(useRef) + require.NoError(t, err) + require.NotContains(t, string(data), "x-use-site") + + value := useRef.Value + allOf := len(value.AllOf) + for range 3 { + require.NoError(t, loader.ResolveRefsIn(doc, nil)) + require.Same(t, value, useRef.Value) + require.Len(t, useRef.Value.AllOf, allOf) + } +} + +func TestSchemaRefSiblingRoundTripsAsWritten(t *testing.T) { + t.Parallel() + data := []byte(`{ + "$ref":"#/components/schemas/Base", + "pattern":"", + "minLength":0, + "uniqueItems":false, + "required":[], + "properties":{}, + "default":null, + "maximum":0, + "x-use-site":true +}`) + var ref openapi3.SchemaRef + require.NoError(t, json.Unmarshal(data, &ref)) + + // Unlike #1271, which writes them out as an ordinary Schema would, dropping + // the zero values, the fields next to the $ref come back as written. + out, err := json.Marshal(ref) + require.NoError(t, err) + require.JSONEq(t, string(data), string(out)) +} + +func TestSchemaRefSiblingPreservesBothDynamicRefs(t *testing.T) { + t.Parallel() + loader := openapi3.NewLoader() + doc, err := loader.LoadFromData([]byte(` +openapi: 3.1.0 +info: + title: dynamic ref conjunction + version: "1" +paths: {} +components: + schemas: + Base: + $dynamicRef: '#base' + Use: + $ref: '#/components/schemas/Base' + $dynamicRef: '#use' +`)) + require.NoError(t, err) + + use := doc.Components.Schemas["Use"].Value + require.Equal(t, "#base", use.DynamicRef) + require.Len(t, use.AllOf, 1) + require.Equal(t, "#use", use.AllOf[0].Value.DynamicRef) + require.Equal(t, "#base", doc.Components.Schemas["Base"].Value.DynamicRef) +} + +func TestSchemaRefSiblingOnSelfReference(t *testing.T) { + t.Parallel() + loader := openapi3.NewLoader() + doc, err := loader.LoadFromData([]byte(` +openapi: 3.1.0 +info: + title: recursive ref sibling + version: "1" +paths: {} +components: + schemas: + Node: + type: object + required: [name] + properties: + name: + type: string + parent: + $ref: '#/components/schemas/Node' + minProperties: 2 +`)) + require.NoError(t, err) + + node := doc.Components.Schemas["Node"].Value + parent := node.Properties["parent"] + require.Error(t, parent.Value.VisitJSON(map[string]any{"name": "child"}, openapi3.EnableJSONSchema2020())) + require.NoError(t, parent.Value.VisitJSON(map[string]any{"name": "child", "extra": true}, openapi3.EnableJSONSchema2020())) + + invalidRecursiveValue := map[string]any{ + "name": "child", + "parent": map[string]any{ + "first": true, + "second": true, + }, + } + validRecursiveValue := map[string]any{ + "name": "child", + "parent": map[string]any{ + "name": "parent", + "extra": true, + }, + } + for _, opts := range [][]openapi3.SchemaValidationOption{ + nil, + {openapi3.EnableJSONSchema2020()}, + } { + require.Error(t, node.VisitJSON(invalidRecursiveValue, opts...), "the recursive target must still require name") + require.NoError(t, node.VisitJSON(validRecursiveValue, opts...)) + } + + data, err := json.Marshal(parent) + require.NoError(t, err) + require.JSONEq(t, `{ + "$ref":"#/components/schemas/Node", + "minProperties":2 +}`, string(data)) +} + +func TestSchemaRefSiblingOnSelfReferenceOutsideComponents(t *testing.T) { + t.Skip("TODO: give a value to the schemas of a cycle of $refs that never reaches a schema") + t.Parallel() + loader := openapi3.NewLoader() + doc, err := loader.LoadFromData([]byte(` +openapi: 3.1.0 +info: + title: path-local recursive ref sibling + version: "1" +paths: + /x: + post: + requestBody: + content: + application/json: + schema: + $ref: '#/paths/~1x/post/requestBody/content/application~1json/schema' + minProperties: 1 + responses: + "200": + description: ok +`)) + require.NoError(t, err) + + schemaRef := doc.Paths.Value("/x").Post.RequestBody.Value.Content["application/json"].Schema + require.NotNil(t, schemaRef.Value) + require.Error(t, schemaRef.Value.VisitJSON(map[string]any{})) + require.NoError(t, schemaRef.Value.VisitJSON(map[string]any{"value": true})) + + data, err := json.Marshal(schemaRef) + require.NoError(t, err) + require.JSONEq(t, `{ + "$ref":"#/paths/~1x/post/requestBody/content/application~1json/schema", + "minProperties":1 +}`, string(data)) +} + +func TestSchemaRefSiblingsOnLongerCycle(t *testing.T) { + t.Skip("TODO: give a value to the schemas of a cycle of $refs that never reaches a schema") + t.Parallel() + loader := openapi3.NewLoader() + doc, err := loader.LoadFromData([]byte(` +openapi: 3.1.0 +info: + title: ref-only cycle with siblings + version: "1" +paths: {} +components: + schemas: + A: + $ref: '#/components/schemas/B' + minLength: 2 + B: + $ref: '#/components/schemas/A' + maxLength: 4 +`)) + require.NoError(t, err) + + a := doc.Components.Schemas["A"].Value + b := doc.Components.Schemas["B"].Value + require.NotNil(t, a) + require.NotNil(t, b) + validationErr := a.VisitJSON("x", openapi3.EnableJSONSchema2020()) + require.Error(t, validationErr) + getErr := func() { _ = validationErr.Error() } + require.NotPanics(t, getErr, "cyclic effective schemas must remain serializable in errors") + require.Error(t, a.VisitJSON("12345", openapi3.EnableJSONSchema2020())) + require.Error(t, b.VisitJSON("x", openapi3.EnableJSONSchema2020())) + require.Error(t, b.VisitJSON("12345", openapi3.EnableJSONSchema2020())) + require.NoError(t, a.VisitJSON("1234", openapi3.EnableJSONSchema2020())) + require.NoError(t, b.VisitJSON("1234", openapi3.EnableJSONSchema2020())) + + aValue, bValue := a, b + for range 3 { + require.NoError(t, loader.ResolveRefsIn(doc, nil)) + require.Same(t, aValue, doc.Components.Schemas["A"].Value) + require.Same(t, bValue, doc.Components.Schemas["B"].Value) + } + for name, expected := range map[string]string{ + "A": `{"$ref":"#/components/schemas/B","minLength":2}`, + "B": `{"$ref":"#/components/schemas/A","maxLength":4}`, + } { + data, err := json.Marshal(doc.Components.Schemas[name]) + require.NoError(t, err) + require.JSONEq(t, expected, string(data)) + } +} + +func TestSchemaRefSiblingAnchorsPartiallyAnnotatedAliasCycle(t *testing.T) { + t.Skip("TODO: give a value to the schemas of a cycle of $refs that never reaches a schema") + t.Parallel() + loader := openapi3.NewLoader() + doc, err := loader.LoadFromData([]byte(` +openapi: 3.1.0 +info: + title: partially annotated alias cycle + version: "1" +paths: {} +components: + schemas: + A: + $ref: '#/components/schemas/B' + minLength: 2 + B: + $ref: '#/components/schemas/A' +`)) + require.NoError(t, err) + + for _, name := range []string{"A", "B"} { + value := doc.Components.Schemas[name].Value + require.NotNil(t, value) + require.Error(t, value.VisitJSON("x", openapi3.EnableJSONSchema2020())) + require.NoError(t, value.VisitJSON("xx", openapi3.EnableJSONSchema2020())) + } +} + +func TestSchemaRefSiblingsAreIgnoredOnOpenAPI30AliasCycle(t *testing.T) { + t.Skip("TODO: give a value to the schemas of a cycle of $refs that never reaches a schema") + t.Parallel() + loader := openapi3.NewLoader() + doc, err := loader.LoadFromData([]byte(` +openapi: 3.0.3 +info: + title: ref-only cycle with ignored siblings + version: "1" +paths: {} +components: + schemas: + A: + $ref: '#/components/schemas/B' + minLength: 2 + B: + $ref: '#/components/schemas/A' + maxLength: 4 +`)) + require.NoError(t, err) + + for _, name := range []string{"A", "B"} { + ref := doc.Components.Schemas[name] + require.NotNil(t, ref.Value) + require.Zero(t, ref.Value.MinLength) + require.Nil(t, ref.Value.MaxLength) + require.NoError(t, ref.Value.VisitJSON("x")) + require.NoError(t, ref.Value.VisitJSON("12345")) + } + + a, err := json.Marshal(doc.Components.Schemas["A"]) + require.NoError(t, err) + require.JSONEq(t, `{"$ref":"#/components/schemas/B","minLength":2}`, string(a)) + b, err := json.Marshal(doc.Components.Schemas["B"]) + require.NoError(t, err) + require.JSONEq(t, `{"$ref":"#/components/schemas/A","maxLength":4}`, string(b)) +} + +func TestSchemaRefSiblingErrorRetainsUseSiteOrigin(t *testing.T) { + t.Parallel() + loader := openapi3.NewLoader() + loader.IncludeOrigin = true + doc, err := loader.LoadFromData([]byte(` +openapi: 3.1.0 +info: + title: sibling origin + version: "1" +paths: {} +components: + schemas: + Base: + type: string + Use: + $ref: '#/components/schemas/Base' + pattern: '(?invalid' +`)) + require.NoError(t, err) + + use := doc.Components.Schemas["Use"] + validationErr := use.Value.VisitJSON("value", openapi3.EnableJSONSchema2020()) + var patternErr *openapi3.SchemaPatternRegexError + require.True(t, errors.As(validationErr, &patternErr)) + require.NotNil(t, patternErr.Origin) + require.NotNil(t, patternErr.Origin.Key) + require.Equal(t, 11, patternErr.Origin.Key.Line) + require.Equal(t, 7, patternErr.Origin.Fields.Get("pattern").Column) +} + +func TestSchemaRefSiblingStructuralCycleKeepsAliasTarget(t *testing.T) { + t.Parallel() + loader := openapi3.NewLoader() + doc, err := loader.LoadFromData([]byte(` +openapi: 3.1.0 +info: + title: structural sibling cycle + version: "1" +paths: {} +components: + schemas: + A: + $ref: '#/components/schemas/B' + properties: + child: + $ref: '#/components/schemas/A' + B: + type: object + required: [name] + properties: + name: + type: string +`)) + require.NoError(t, err) + + a := doc.Components.Schemas["A"].Value + require.Error(t, a.VisitJSON(map[string]any{ + "name": "root", + "child": map[string]any{"other": true}, + })) + require.NoError(t, a.VisitJSON(map[string]any{ + "name": "root", + "child": map[string]any{"name": "nested"}, + })) +} + +func TestSchemaRefSiblingInRawExternalSchemaUsesRootDialect(t *testing.T) { + t.Parallel() + dir := t.TempDir() + rootPath := filepath.Join(dir, "openapi.yaml") + externalPath := filepath.Join(dir, "schemas.yaml") + + require.NoError(t, os.WriteFile(rootPath, []byte(` +openapi: 3.1.0 +info: + title: raw external schema sibling + version: "1" +paths: {} +components: + schemas: + Use: + $ref: 'schemas.yaml#/$defs/Alias' +`), 0o600)) + require.NoError(t, os.WriteFile(externalPath, []byte(` +$defs: + Base: + type: string + Alias: + $ref: '#/$defs/Base' + minLength: 3 +`), 0o600)) + + loader := openapi3.NewLoader() + loader.IsExternalRefsAllowed = true + doc, err := loader.LoadFromFile(rootPath) + require.NoError(t, err) + + use := doc.Components.Schemas["Use"].Value + require.Error(t, use.VisitJSON("xx", openapi3.EnableJSONSchema2020())) + require.NoError(t, use.VisitJSON("xxx", openapi3.EnableJSONSchema2020())) +} + +func TestSchemaRefSiblingDoesNotMutateSharedTarget(t *testing.T) { + t.Parallel() + loader := openapi3.NewLoader() + doc, err := loader.LoadFromData([]byte(` +openapi: 3.1.0 +info: + title: independent ref siblings + version: "1" +paths: {} +components: + schemas: + Base: + type: string + maxLength: 5 + Short: + $ref: '#/components/schemas/Base' + maxLength: 3 + Long: + $ref: '#/components/schemas/Base' + minLength: 4 +`)) + require.NoError(t, err) + + base := doc.Components.Schemas["Base"].Value + short := doc.Components.Schemas["Short"].Value + long := doc.Components.Schemas["Long"].Value + require.Equal(t, uint64(5), *base.MaxLength) + require.Zero(t, base.MinLength) + require.Empty(t, base.AllOf) + require.NotSame(t, base, short) + require.NotSame(t, base, long) + require.NoError(t, base.VisitJSON("xxxxx", openapi3.EnableJSONSchema2020())) + require.Error(t, short.VisitJSON("xxxx", openapi3.EnableJSONSchema2020())) + require.Error(t, long.VisitJSON("xxx", openapi3.EnableJSONSchema2020())) + require.NoError(t, long.VisitJSON("xxxx", openapi3.EnableJSONSchema2020())) +} + +func TestSchemaRefSiblingSerializationIsIndependentOfOASVersion(t *testing.T) { + t.Parallel() + const spec = ` +openapi: %s +info: + title: versioned sibling semantics + version: "1" +paths: {} +components: + schemas: + Base: + type: string + Use: + $ref: '#/components/schemas/Base' + minLength: 3 +` + + for _, version := range []string{"3.0.3", "3.1.0"} { + t.Run(version, func(t *testing.T) { + t.Parallel() + loader := openapi3.NewLoader() + doc, err := loader.LoadFromData(fmt.Appendf(nil, spec, version)) + require.NoError(t, err) + use := doc.Components.Schemas["Use"] + data, err := json.Marshal(use) + require.NoError(t, err) + require.JSONEq(t, `{ + "$ref":"#/components/schemas/Base", + "minLength":3 +}`, string(data)) + if version == "3.0.3" { + require.NoError(t, use.Value.VisitJSON("xx")) + } else { + require.Error(t, use.Value.VisitJSON("xx")) + } + }) + } +} + +func TestMalformedSchemaRefSiblingUsesRootDialect(t *testing.T) { + t.Parallel() + const spec = ` +openapi: %s +info: + title: malformed sibling + version: "1" +paths: {} +components: + schemas: + Base: + type: string + Use: + $ref: '#/components/schemas/Base' + allOf: + type: integer +` + + loader30 := openapi3.NewLoader() + doc, err := loader30.LoadFromData(fmt.Appendf(nil, spec, "3.0.3")) + require.NoError(t, err, "OpenAPI 3.0 ignores malformed fields next to $ref") + require.Equal(t, "string", doc.Components.Schemas["Use"].Value.Type.Slice()[0]) + + loader31 := openapi3.NewLoader() + _, err = loader31.LoadFromData(fmt.Appendf(nil, spec, "3.1.0")) + require.Error(t, err, "OpenAPI 3.1 treats the adjacent fields as a Schema Object") +} + +func TestInternalizeRefsUpdatesSchemaRefSiblingFields(t *testing.T) { + t.Parallel() + dir := t.TempDir() + rootPath := filepath.Join(dir, "root.yaml") + externalPath := filepath.Join(dir, "external.yaml") + + require.NoError(t, os.WriteFile(rootPath, []byte(` +openapi: 3.1.0 +info: + title: Internalized sibling refs + version: "1.0" +paths: {} +components: + schemas: + Root: + type: object + properties: + use: + $ref: external.yaml#/Base + items: + $ref: external.yaml#/Item +`), 0o600)) + require.NoError(t, os.WriteFile(externalPath, []byte(` +Base: + type: array +Item: + type: string +`), 0o600)) + + loader := openapi3.NewLoader() + loader.IsExternalRefsAllowed = true + doc, err := loader.LoadFromFile(rootPath) + require.NoError(t, err) + + doc.InternalizeRefs(t.Context(), nil) + data, err := doc.MarshalJSON() + require.NoError(t, err) + require.NotContains(t, string(data), "external.yaml") + + use := doc.Components.Schemas["Root"].Value.Properties["use"] + require.True(t, strings.HasPrefix(use.Ref, "#/components/schemas/")) + targetName := strings.TrimPrefix(use.Ref, "#/components/schemas/") + target := doc.Components.Schemas[targetName].Value + require.Nil(t, target.Items, + "internalization must componentize the referenced target, not the schema with the siblings applied") + require.Empty(t, target.AllOf, + "internalization must componentize the referenced target, not the schema with the siblings applied") + var marshaledUse map[string]any + require.NoError(t, json.Unmarshal(mustMarshalJSON(t, use), &marshaledUse)) + items := marshaledUse["items"].(map[string]any) + require.True(t, strings.HasPrefix(items["$ref"].(string), "#/components/schemas/")) + + loader = openapi3.NewLoader() + roundTripped, err := loader.LoadFromData(data) + require.NoError(t, err, "the internalized document must not require external access") + roundTrippedUse := roundTripped.Components.Schemas["Root"].Value.Properties["use"].Value + require.NoError(t, roundTrippedUse.VisitJSON([]any{"value"}, openapi3.EnableJSONSchema2020())) + require.Error(t, roundTrippedUse.VisitJSON([]any{1}, openapi3.EnableJSONSchema2020())) +} + +// In OpenAPI 3.0 the fields next to a $ref are ignored, so the loader never +// follows the $refs within them and internalization leaves them as written. +func TestInternalizeRefsLeavesIgnoredSchemaRefSiblingFieldsInOpenAPI30(t *testing.T) { + t.Parallel() + dir := t.TempDir() + rootPath := filepath.Join(dir, "root.yaml") + externalPath := filepath.Join(dir, "external.yaml") + + require.NoError(t, os.WriteFile(rootPath, []byte(` +openapi: 3.0.3 +info: + title: Internalized OpenAPI 3.0 sibling refs + version: "1.0" +paths: {} +components: + schemas: + Root: + type: object + properties: + use: + $ref: external.yaml#/Base + items: + $ref: external.yaml#/Item +`), 0o600)) + require.NoError(t, os.WriteFile(externalPath, []byte(` +Base: + type: array +Item: + type: string +`), 0o600)) + + loader := openapi3.NewLoader() + loader.IsExternalRefsAllowed = true + doc, err := loader.LoadFromFile(rootPath) + require.NoError(t, err) + + use := doc.Components.Schemas["Root"].Value.Properties["use"] + require.Nil(t, use.Value.Items, "an OpenAPI 3.0 sibling must not affect the resolved target") + before, err := json.Marshal(use) + require.NoError(t, err) + require.Contains(t, string(before), `external.yaml#/Item`) + + doc.InternalizeRefs(t.Context(), nil) + data, err := doc.MarshalJSON() + require.NoError(t, err) + require.Nil(t, use.Value.Items, "internalization must not change OpenAPI 3.0 sibling semantics") + + var marshaledUse map[string]any + require.NoError(t, json.Unmarshal(mustMarshalJSON(t, use), &marshaledUse)) + require.True(t, strings.HasPrefix(marshaledUse["$ref"].(string), "#/components/schemas/")) + items := marshaledUse["items"].(map[string]any) + require.Equal(t, "external.yaml#/Item", items["$ref"]) + + roundTripLoader := openapi3.NewLoader() + roundTripped, err := roundTripLoader.LoadFromData(data) + require.NoError(t, err, "the internalized document must not require external access") + roundTrippedUse := roundTripped.Components.Schemas["Root"].Value.Properties["use"] + require.Nil(t, roundTrippedUse.Value.Items) +} + +func TestInternalizeRefsUpdatesSiblingFieldsWithFalseTarget(t *testing.T) { + t.Parallel() + dir := t.TempDir() + rootPath := filepath.Join(dir, "root.yaml") + externalPath := filepath.Join(dir, "external.yaml") + + require.NoError(t, os.WriteFile(rootPath, []byte(` +openapi: 3.1.0 +info: + title: Internalized false-target sibling refs + version: "1.0" +paths: {} +components: + schemas: + RejectEverything: false + Root: + type: object + properties: + use: + $ref: '#/components/schemas/RejectEverything' + items: + $ref: external.yaml#/Item +`), 0o600)) + require.NoError(t, os.WriteFile(externalPath, []byte(` +Item: + type: string +`), 0o600)) + + loader := openapi3.NewLoader() + loader.IsExternalRefsAllowed = true + doc, err := loader.LoadFromFile(rootPath) + require.NoError(t, err) + + use := doc.Components.Schemas["Root"].Value.Properties["use"] + require.Error(t, use.Value.VisitJSON([]any{"value"}, openapi3.EnableJSONSchema2020())) + + doc.InternalizeRefs(t.Context(), nil) + data, err := doc.MarshalJSON() + require.NoError(t, err) + require.NotContains(t, string(data), "external.yaml") + require.Error(t, use.Value.VisitJSON([]any{"value"}, openapi3.EnableJSONSchema2020())) +} + +func TestRecursiveSchemaDistinguishesOverlappingSlices(t *testing.T) { + t.Parallel() + schema := openapi3.NewArraySchema().WithMinItems(1) + schema.Items = &openapi3.SchemaRef{Value: schema} + + value := make([]any /*,*/, 1) + value[0] = value[:0] + require.Error(t, schema.VisitJSON(value), + "a shorter subslice with the same backing address is a distinct JSON instance") +} + +func mustMarshalJSON(t *testing.T, value any) []byte { + t.Helper() + data, err := json.Marshal(value) + require.NoError(t, err) + return data +} From 2420538c110afc6f49044be370f12b667151029a Mon Sep 17 00:00:00 2001 From: Pierre Fenoll Date: Thu, 22 Oct 2026 13:27:08 +0200 Subject: [PATCH 08/78] changelog: fixup rebased messes (#1372) Signed-off-by: Pierre Fenoll --- README.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 5f058ba95..21e4bcfba 100644 --- a/README.md +++ b/README.md @@ -329,10 +329,9 @@ for _, path := range doc.Paths.InMatchingOrder() { ## CHANGELOG: Sub-v1 breaking API changes -### v0.151.0 -* Removed the deprecated package-global `openapi3.IncludeOrigin` variable. Set the `IncludeOrigin` field of `openapi3.Loader` instead. -* `openapi3filter.UrlencodedBodyDecoder` (hence `application/x-www-form-urlencoded` request body validation) now returns a `*openapi3filter.ParseError` for a value that cannot be parsed into its property's schema type, such as `n=abc` for an `integer` property, instead of silently dropping it from the decoded body. -* `openapi3filter` now writes a query parameter's array `default` into the request URL following the parameter's `style` and `explode` (including their defaults), so an array without `explode` set is written as `?ids=1&ids=2` rather than `?ids=1,2`, and `pipeDelimited`/`spaceDelimited` arrays use their own delimiter. +### v0.152.0 +* JSON keys of OpenAPI documents only fill the field of the same case (`json:",case:strict"`) when `encoding/json` is implemented with `encoding/json/v2` (by default from Go 1.27, and on Go 1.25 and 1.26 with `GOEXPERIMENT=jsonv2`): a key such as `"Components"` (not `"components"`) is kept as an extension instead of filling `openapi3.T.Components`. Other builds still match keys case-insensitively, as `encoding/json` v1 does. +* On Go 1.27+, unless built with `GOEXPERIMENT=nojsonv2`, `openapi2` and `openapi3` decode documents with `encoding/json/v2`: objects with duplicate member names and strings with invalid UTF-8 are rejected, and decoding errors are worded differently and locate the faulty value from the root of the document, keys of paths, responses and callbacks included (e.g. `.paths.~1pets.get.responses.200.description`). On these builds `openapi2.Responses`, `openapi3.Callback`, `openapi3.Paths` and `openapi3.Responses` also implement `encoding/json/v2.UnmarshalerFrom`. * A schema with an empty `type: []` no longer marshals as `"type": null` which did not survive being read back. * The error for a header with neither or both of `content` and `schema` reads `header must contain exactly one of content and schema`. It used to say `parameter ...` followed by a `%v` dump of the `Header` struct, which printed heap addresses: the message differed between two runs over the same document, and leaked addresses into anything that logged it. * `openapi3filter` now parses `integer` values of parameters and `application/x-www-form-urlencoded`/`multipart/form-data` bodies as base 10 only, so `010` decodes to `10` rather than `8`, and Go integer literals such as `0x10`, `0b10`, `0o10` or `1_000` are now rejected as invalid integers. @@ -347,6 +346,11 @@ for _, path := range doc.Paths.InMatchingOrder() { * In OpenAPI 3.1+ documents, loading now fails when the keywords next to a schema's `$ref` do not form a schema, such as `allOf: {type: integer}`, instead of silently ignoring them all. * The errors raised by the keywords next to an OpenAPI 3.1 schema's `$ref` now carry their `Origin`. +### v0.151.0 +* Removed the deprecated package-global `openapi3.IncludeOrigin` variable. Set the `IncludeOrigin` field of `openapi3.Loader` instead. +* `openapi3filter.UrlencodedBodyDecoder` (hence `application/x-www-form-urlencoded` request body validation) now returns a `*openapi3filter.ParseError` for a value that cannot be parsed into its property's schema type, such as `n=abc` for an `integer` property, instead of silently dropping it from the decoded body. +* `openapi3filter` now writes a query parameter's array `default` into the request URL following the parameter's `style` and `explode` (including their defaults), so an array without `explode` set is written as `?ids=1&ids=2` rather than `?ids=1,2`, and `pipeDelimited`/`spaceDelimited` arrays use their own delimiter. + ### v0.150.0 * `openapi2.Operation.Responses` field type changed from `map[string]*Response` to `*Responses`, which keeps the Responses Object's `x-` extensions in `Responses.Extensions` instead of failing to decode them as responses. * `(*openapi3.Schema).VisitJSON(..)` without the `openapi3.EnableJSONSchema2020()` option no longer validates the OpenAPI 3.1 `const` and `prefixItems` keywords. Like the other 3.1-only keywords, they are validated by the JSON Schema 2020-12 validator, which `openapi3filter` enables for 3.1 documents. `items` still applies only past the `prefixItems` positions. @@ -362,8 +366,6 @@ for _, path := range doc.Paths.InMatchingOrder() { * `(*openapi3.Parameter).SerializationMethod()` (for query parameters) and `(*openapi3.Encoding).SerializationMethod()` now default `explode` to `false` for `style: spaceDelimited` and `style: pipeDelimited`, as the spec says, so `openapi3filter` splits `?ids=1|2|3` and `application/x-www-form-urlencoded` body properties such as `ids=1|2|3` instead of expecting `ids=1&ids=2&ids=3`. Set `explode: true` to keep the previous behavior. * Removed the package-global `openapi3.SchemaErrorDetailsDisabled` variable. Pass the new `openapi3.DisableSchemaErrorDetails()` option to `(*openapi3.Schema).VisitJSON(..)` instead, or add it to `openapi3filter.Options.SchemaValidationOptions`, which `openapi3filter` now also applies when validating parameters. Combined with `openapi3.EnableJSONSchema2020()` (hence with `openapi3filter` on OpenAPI 3.1+ documents), validation fails with `openapi3.ErrSchemaErrorDetailsWithJSONSchema2020`, as that validator's error messages include values. * The message customizer set with `openapi3.SetSchemaErrorMessageCustomizer(..)` (hence `(*openapi3filter.Options).WithCustomSchemaErrorFunc(..)`) now also applies to discriminator errors, to errors of patterns that fail to compile and to errors of the JSON Schema 2020-12 validator (`openapi3.EnableJSONSchema2020()`). -* JSON keys of OpenAPI documents only fill the field of the same case (`json:",case:strict"`) when `encoding/json` is implemented with `encoding/json/v2` (by default from Go 1.27, and on Go 1.25 and 1.26 with `GOEXPERIMENT=jsonv2`): a key such as `"Components"` (not `"components"`) is kept as an extension instead of filling `openapi3.T.Components`. Other builds still match keys case-insensitively, as `encoding/json` v1 does. -* On Go 1.27+, unless built with `GOEXPERIMENT=nojsonv2`, `openapi2` and `openapi3` decode documents with `encoding/json/v2`: objects with duplicate member names and strings with invalid UTF-8 are rejected, and decoding errors are worded differently and locate the faulty value from the root of the document, keys of paths, responses and callbacks included (e.g. `.paths.~1pets.get.responses.200.description`). On these builds `openapi2.Responses`, `openapi3.Callback`, `openapi3.Paths` and `openapi3.Responses` also implement `encoding/json/v2.UnmarshalerFrom`. ### v0.147.0 * `(*openapi3.PathItem).SetOperation(string, *Operation)` no longer panics on unhandled HTTP methods: these are now stored in the new `openapi3.PathItem.AdditionalOperations` field (passing a nil operation deletes the entry). From 15948ef260a97b47e1f72c877393ccc73afbda1d Mon Sep 17 00:00:00 2001 From: Pierre Fenoll Date: Thu, 22 Oct 2026 15:36:44 +0200 Subject: [PATCH 09/78] Add fuzz targets (#1373) Signed-off-by: Pierre Fenoll --- .github/workflows/fuzz.yml | 89 ++++++++++ Makefile | 37 +++-- openapi2conv/fuzz_test.go | 84 ++++++++++ openapi3/fuzz_test.go | 112 +++++++++++++ .../fuzz/FuzzLoadFromData/56b819f42562dabd | 2 + .../fuzz/FuzzLoadFromData/e9783ed365c6dc4c | 2 + openapi3filter/fuzz_test.go | 152 ++++++++++++++++++ 7 files changed, 464 insertions(+), 14 deletions(-) create mode 100644 .github/workflows/fuzz.yml create mode 100644 openapi2conv/fuzz_test.go create mode 100644 openapi3/fuzz_test.go create mode 100644 openapi3/testdata/fuzz/FuzzLoadFromData/56b819f42562dabd create mode 100644 openapi3/testdata/fuzz/FuzzLoadFromData/e9783ed365c6dc4c create mode 100644 openapi3filter/fuzz_test.go diff --git a/.github/workflows/fuzz.yml b/.github/workflows/fuzz.yml new file mode 100644 index 000000000..4c920d2ac --- /dev/null +++ b/.github/workflows/fuzz.yml @@ -0,0 +1,89 @@ +name: fuzz +on: + pull_request: + push: + branches: + - master + schedule: + # Nightly, so a long run has a chance to reach code a 90s PR run never does. + - cron: '17 3 * * *' + workflow_dispatch: + inputs: + fuzztime: + description: 'How long to fuzz each target (go test -fuzztime syntax)' + required: false + default: 30m + +permissions: + contents: read + +jobs: + fuzz: + name: ${{ matrix.target }} + runs-on: ubuntu-latest + # A budget of 15m plus corpus minimization has to fit, and a hung target + # must not hold a runner forever. + timeout-minutes: 45 + env: + GO111MODULE: 'on' + CGO_ENABLED: '0' + strategy: + # Every target reports independently: one crasher must not hide the rest. + fail-fast: false + matrix: + include: + - {package: ./openapi3, target: FuzzLoadFromData} + - {package: ./openapi3, target: FuzzSchemaVisitJSON} + - {package: ./openapi2conv, target: FuzzToV3} + - {package: ./openapi3filter, target: FuzzValidateRequest} + steps: + + - uses: actions/setup-go@v6 + with: + go-version: stable + + - uses: actions/checkout@v6 + + # The generated corpus lives under $GOCACHE/fuzz and is what makes fuzzing + # cumulative: without it every run restarts from the seed corpus. The key + # carries the run id so each run writes a fresh entry, and restore-keys + # falls back to the most recent one for this target. + - name: Fuzzing corpus cache + uses: actions/cache@v3 + with: + path: ~/.cache/go-build/fuzz + key: fuzz-${{ matrix.target }}-${{ github.run_id }} + restore-keys: fuzz-${{ matrix.target }}- + + - name: Pick a budget + id: budget + run: | + if [[ -n '${{ inputs.fuzztime }}' ]]; then + fuzztime='${{ inputs.fuzztime }}' + elif [[ '${{ github.event_name }}' = schedule ]]; then + fuzztime=15m + else + fuzztime=90s + fi + echo "fuzztime=$fuzztime" >>"$GITHUB_OUTPUT" + + # -run='^$' skips the ordinary tests: the seed corpus is already replayed by + # `go test ./...` in the go workflow, so this job only spends time fuzzing. + - name: Fuzz ${{ matrix.target }} + run: | + go test \ + -run='^$' \ + -fuzz='^${{ matrix.target }}$' \ + -fuzztime='${{ steps.budget.outputs.fuzztime }}' \ + -fuzzminimizetime=60s \ + ${{ matrix.package }} + + # A failing input is written next to the package it broke. Upload it so the + # crasher can be committed to the seed corpus, where it becomes a permanent + # regression test replayed by `go test ./...`. + - if: failure() + uses: actions/upload-artifact@v4 + with: + name: crashers-${{ matrix.target }} + path: '**/testdata/fuzz/**' + if-no-files-found: ignore diff --git a/Makefile b/Makefile index 57bab901a..8fc32f5e5 100644 --- a/Makefile +++ b/Makefile @@ -1,28 +1,37 @@ -.DEFAULT_GOAL := prepare +.DEFAULT_GOAL := all +.PHONY: help generate format test test-fast fuzz all -.PHONY: help generate format test prepare +# How long to spend on each fuzz target. Override: make fuzz FUZZTIME=10m +FUZZTIME ?= 60s -help: - @printf '%s\n' \ - 'Usage: make ' \ - '' \ - ' generate Regenerate Go code, map helpers, and API documentation.' \ - ' format Apply the repository formatters and import cleanup.' \ - ' test Run the full Go package test suite.' \ - ' prepare Run generation, formatting, and tests in sequence.' +## all: Run generation, formatting, and tests in sequence +all: generate format test +## generate: Regenerate Go code, map helpers, and API documentation generate: go generate ./... ./maps.sh ./docs.sh +## format: Apply the repository formatters and import cleanup format: go fmt ./... +## test: Run the full Go package test suite test: go test ./... -prepare: - $(MAKE) generate - $(MAKE) format - $(MAKE) test +## test-fast: Run tests skipping the slow ones +test-fast: + go test -short ./... + +## fuzz: Fuzz each target for FUZZTIME (default 60s) +fuzz: + go test -run='^$$' -fuzz='^FuzzLoadFromData$$' -fuzztime=$(FUZZTIME) ./openapi3 + go test -run='^$$' -fuzz='^FuzzSchemaVisitJSON$$' -fuzztime=$(FUZZTIME) ./openapi3 + go test -run='^$$' -fuzz='^FuzzToV3$$' -fuzztime=$(FUZZTIME) ./openapi2conv + go test -run='^$$' -fuzz='^FuzzValidateRequest$$' -fuzztime=$(FUZZTIME) ./openapi3filter + +## help: list targets +help: + @grep -E '^## ' $(MAKEFILE_LIST) | sed 's/## / make /' diff --git a/openapi2conv/fuzz_test.go b/openapi2conv/fuzz_test.go new file mode 100644 index 000000000..8443c7dd4 --- /dev/null +++ b/openapi2conv/fuzz_test.go @@ -0,0 +1,84 @@ +package openapi2conv_test + +import ( + "encoding/json" + "os" + "path/filepath" + "testing" + + "github.com/stretchr/testify/require" + + "github.com/getkin/kin-openapi/openapi2" + "github.com/getkin/kin-openapi/openapi2conv" + "github.com/getkin/kin-openapi/openapi3" +) + +// maxFuzzInput bounds fuzzer inputs so the fuzzer spends its budget on +// conversion logic rather than on allocating huge documents. +const maxFuzzInput = 32 << 10 + +// FuzzToV3 converts an arbitrary OpenAPI 2 document to OpenAPI 3 and back. +func FuzzToV3(f *testing.F) { + paths, err := filepath.Glob("../openapi2/testdata/*.json") + require.NoError(f, err) + for _, path := range paths { + data, err := os.ReadFile(path) + require.NoError(f, err) + if len(data) <= maxFuzzInput { + f.Add(data) + } + } + f.Add([]byte(`{"swagger":"2.0","info":{"title":"t","version":"1"},"paths":{}}`)) + f.Add([]byte(`{"swagger":"2.0","paths":{"/x/{id}":{"get":{"parameters":[{"name":"id","in":"path","type":"string","required":true}],"responses":{"200":{"description":"ok"}}}}}}`)) + f.Add([]byte(`{"swagger":"2.0","definitions":{"A":{"type":"object","properties":{"b":{"$ref":"#/definitions/A"}}}},"paths":{}}`)) + f.Add([]byte(`{"swagger":"2.0","consumes":["multipart/form-data"],"paths":{"/f":{"post":{"parameters":[{"name":"file","in":"formData","type":"file"}],"responses":{"200":{"description":"ok"}}}}}}`)) + + f.Fuzz(func(t *testing.T, data []byte) { + if len(data) > maxFuzzInput { + t.Skip() + } + + var doc2 openapi2.T + if err := json.Unmarshal(data, &doc2); err != nil { + t.Skip() + } + + doc3, err := openapi2conv.ToV3(&doc2) + if err != nil { + return + } + require.NotNil(t, doc3) + + roundTrip := func(doc *openapi3.T) *openapi3.T { + back2, err := openapi2conv.FromV3(doc) + if err != nil { + return nil + } + next3, err := openapi2conv.ToV3(back2) + if err != nil { + return nil + } + return next3 + } + + once := roundTrip(doc3) + if once == nil { + return + } + twice := roundTrip(once) + if twice == nil { + return + } + + if err := once.Validate(t.Context()); err != nil { + return + } + + onceJSON, err := json.Marshal(once) + require.NoError(t, err) + twiceJSON, err := json.Marshal(twice) + require.NoError(t, err) + + require.JSONEq(t, string(onceJSON), string(twiceJSON)) + }) +} diff --git a/openapi3/fuzz_test.go b/openapi3/fuzz_test.go new file mode 100644 index 000000000..2e2923417 --- /dev/null +++ b/openapi3/fuzz_test.go @@ -0,0 +1,112 @@ +package openapi3_test + +import ( + "encoding/json" + "net/url" + "os" + "path/filepath" + "testing" + + "github.com/stretchr/testify/require" + + "github.com/getkin/kin-openapi/openapi3" +) + +// maxFuzzInput bounds fuzzer inputs so the fuzzer spends its budget on +// conversion logic rather than on allocating huge documents. +const maxFuzzInput = 32 << 10 + +// maxFuzzSeed keeps the seed corpus small enough that `go test ./...` still +// replays it on every run without noticeably slowing the suite down. +const maxFuzzSeed = 16 << 10 + +func newFuzzLoader() *openapi3.Loader { + loader := openapi3.NewLoader() + loader.IsExternalRefsAllowed = true + loader.ReadFromURIFunc = func(*openapi3.Loader, *url.URL) ([]byte, error) { return []byte(`{}`), nil } // deterministic + return loader +} + +func seedFromTestdata(f *testing.F, globs ...string) { + f.Helper() + for _, glob := range globs { + paths, err := filepath.Glob(glob) + require.NoError(f, err) + for _, path := range paths { + data, err := os.ReadFile(path) + require.NoError(f, err) + if len(data) <= maxFuzzSeed { + f.Add(data) + } + } + } +} + +// enc(dec) == enc(dec(enc(dec))) +func FuzzLoadFromData(f *testing.F) { + seedFromTestdata(f, "testdata/*.yml", "testdata/*.yaml", "testdata/*.json") + + f.Fuzz(func(t *testing.T, data []byte) { + if len(data) > maxFuzzInput { + t.Skip() + } + + loader := newFuzzLoader() + doc, err := loader.LoadFromData(data) + if err != nil { + return + } + require.NotNil(t, doc) + + // Validation runs over attacker-shaped documents: it may reject them but + // must never panic nor fail to terminate. + valid := doc.Validate(t.Context()) + + once, err := doc.MarshalJSON() + require.NoError(t, err) + + loader = newFuzzLoader() + // The loader must accept its own output + reloaded, err := loader.LoadFromData(once) + require.NoError(t, err, "\nonce: %s\nvalid: %+v\ndata:\n%s", string(once), valid, string(data)) + + twice, err := reloaded.MarshalJSON() + require.NoError(t, err) + + require.JSONEq(t, string(once), string(twice)) + + // Validation should be deterministic + require.Equal(t, valid, reloaded.Validate(t.Context())) + }) +} + +// No crash when validating values against schemas +func FuzzSchemaVisitJSON(f *testing.F) { + f.Add([]byte(`{"type":"string","minLength":1,"pattern":"^a+$"}`), []byte(`"aaa"`)) + f.Add([]byte(`{"type":"integer","multipleOf":0.01,"maximum":10}`), []byte(`3`)) + f.Add([]byte(`{"type":"array","items":{"type":"number"},"uniqueItems":true}`), []byte(`[1,2,1]`)) + f.Add([]byte(`{"type":"object","required":["a"],"additionalProperties":false}`), []byte(`{"a":null,"b":1}`)) + f.Add([]byte(`{"allOf":[{"type":"string"},{"maxLength":2}]}`), []byte(`"abc"`)) + f.Add([]byte(`{"oneOf":[{"type":"string"},{"type":"number"}],"nullable":true}`), []byte(`null`)) + f.Add([]byte(`{"type":"string","format":"date-time"}`), []byte(`"not a date"`)) + + f.Fuzz(func(t *testing.T, schemaJSON, valueJSON []byte) { + if len(schemaJSON) > maxFuzzInput || len(valueJSON) > maxFuzzInput { + t.Skip() + } + + var schema openapi3.Schema + if err := schema.UnmarshalJSON(schemaJSON); err != nil { + t.Skip() + } + + var value any + if err := json.Unmarshal(valueJSON, &value); err != nil { + t.Skip() + } + + _ = schema.VisitJSON(value) + _ = schema.VisitJSON(value, openapi3.EnableFormatValidation()) + _ = schema.VisitJSON(value, openapi3.EnableJSONSchema2020()) + }) +} diff --git a/openapi3/testdata/fuzz/FuzzLoadFromData/56b819f42562dabd b/openapi3/testdata/fuzz/FuzzLoadFromData/56b819f42562dabd new file mode 100644 index 000000000..5abb93b83 --- /dev/null +++ b/openapi3/testdata/fuzz/FuzzLoadFromData/56b819f42562dabd @@ -0,0 +1,2 @@ +go test fuzz v1 +[]byte("openapi: \"3.1\"\ncomponents:\n schemas: \n 0:\n if:\n 0:\n $ref: A") diff --git a/openapi3/testdata/fuzz/FuzzLoadFromData/e9783ed365c6dc4c b/openapi3/testdata/fuzz/FuzzLoadFromData/e9783ed365c6dc4c new file mode 100644 index 000000000..25a7f3ad2 --- /dev/null +++ b/openapi3/testdata/fuzz/FuzzLoadFromData/e9783ed365c6dc4c @@ -0,0 +1,2 @@ +go test fuzz v1 +[]byte("openapi: A\ncomponents:\n schemas: \n 00: \n 0:\n $ref: 00A") diff --git a/openapi3filter/fuzz_test.go b/openapi3filter/fuzz_test.go new file mode 100644 index 000000000..4c728b114 --- /dev/null +++ b/openapi3filter/fuzz_test.go @@ -0,0 +1,152 @@ +package openapi3filter_test + +import ( + "bytes" + "net/http" + "net/url" + "os" + "path/filepath" + "strings" + "testing" + + "github.com/stretchr/testify/require" + + "github.com/getkin/kin-openapi/openapi3" + "github.com/getkin/kin-openapi/openapi3filter" + "github.com/getkin/kin-openapi/routers" + "github.com/getkin/kin-openapi/routers/gorillamux" +) + +// maxFuzzInput bounds fuzzer inputs so the fuzzer spends its budget on +// conversion logic rather than on allocating huge documents. +const maxFuzzInput = 32 << 10 + +func newFuzzLoader() *openapi3.Loader { + loader := openapi3.NewLoader() + loader.IsExternalRefsAllowed = true + loader.ReadFromURIFunc = func(*openapi3.Loader, *url.URL) ([]byte, error) { return []byte(`{}`), nil } // deterministic + return loader +} + +func FuzzValidateRequest(f *testing.F) { + paths, err := filepath.Glob("../openapi3/testdata/*.yml") + require.NoError(f, err) + for _, path := range paths { + data, err := os.ReadFile(path) + require.NoError(f, err) + if len(data) <= 16<<10 { + f.Add(data, "GET", "/", "application/json", []byte(`{}`)) + } + } + + const spec = ` +openapi: 3.0.0 +info: {title: t, version: "1"} +paths: + /items/{id}: + post: + parameters: + - {name: id, in: path, required: true, schema: {type: integer}} + - {name: q, in: query, schema: {type: array, items: {type: string}}} + requestBody: + content: + application/json: {schema: {type: object, required: [n], properties: {n: {type: number}}}} + multipart/form-data: {schema: {type: object, properties: {f: {type: string, format: binary}}}} + application/x-www-form-urlencoded: {schema: {type: object, properties: {a: {type: string}}}} + responses: {"200": {description: ok}} +` + f.Add([]byte(spec), "POST", "/items/1?q=a&q=b", "application/json", []byte(`{"n":1}`)) + f.Add([]byte(spec), "POST", "/items/x", "application/json", []byte(`{"n":"nope"}`)) + f.Add([]byte(spec), "POST", "/items/1", "application/x-www-form-urlencoded", []byte(`a=b&a=c`)) + f.Add([]byte(spec), "POST", "/items/1", "multipart/form-data; boundary=b", []byte("--b\r\nContent-Disposition: form-data; name=\"f\"\r\n\r\nx\r\n--b--\r\n")) + + f.Fuzz(func(t *testing.T, data []byte, method, target, contentType string, body []byte) { + if len(data) > maxFuzzInput || len(body) > maxFuzzInput { + t.Skip() + } + if len(method) > 64 || len(target) > 4<<10 || len(contentType) > 1<<10 { + t.Skip() + } + + loader := newFuzzLoader() + doc, err := loader.LoadFromData(data) + if err != nil { + t.Skip() + } + if err = doc.Validate(t.Context()); err != nil { + t.Skip() + } + + router, err := gorillamux.NewRouter(doc) + if err != nil { + return + } + + req, err := http.NewRequest(method, target, bytes.NewReader(body)) + if err != nil { + t.Skip() + } + req.Header.Set("Content-Type", contentType) + + route, pathParams, err := router.FindRoute(req) + if err != nil { + return + } + + // A matched route must be usable by callers: every field they dereference + // has to be populated, and every path parameter of the matched template + // has to be present. + require.NotNil(t, route) + require.NotNil(t, route.Spec) + require.NotNil(t, route.PathItem) + require.NotNil(t, route.Operation) + require.Equal(t, req.Method, route.Method) + requirePathParamsCoverTemplate(t, route, pathParams) + + // No crash in here + _ = openapi3filter.ValidateRequest(t.Context(), &openapi3filter.RequestValidationInput{ + Request: req, + PathParams: pathParams, + Route: route, + Options: &openapi3filter.Options{ + MultiError: true, + AuthenticationFunc: openapi3filter.NoopAuthenticationFunc, + }, + }) + }) +} + +func requirePathParamsCoverTemplate(t *testing.T, route *routers.Route, pathParams map[string]string) { + t.Helper() + for _, name := range muxVarNames(route.Path) { + require.Contains(t, pathParams, name, "path %q", route.Path) + } +} + +// muxVarNames extracts the variable names gorilla/mux reads out of a route +// template. It must stay in sync with mux's own parsing: braces nest, so +// "{{a}}" holds the single variable "{a}", and everything after the first +// colon is a match pattern rather than part of the name. +func muxVarNames(tpl string) (names []string) { + level, idx := 0, 0 + for i := 0; i < len(tpl); i++ { + switch tpl[i] { + case '{': + if level++; level == 1 { + idx = i + } + case '}': + if level--; level == 0 { + name, _, _ := strings.Cut(tpl[idx+1:i], ":") + names = append(names, name) + } else if level < 0 { + names = nil + return + } + } + } + if level != 0 { + names = nil + } + return +} From 454df67def35700151b6a39a75a9738a65995314 Mon Sep 17 00:00:00 2001 From: Frode Aannevik Date: Fri, 23 Oct 2026 10:20:13 +0200 Subject: [PATCH 10/78] openapi3: set the failing schema on JSON Schema 2020-12 validation errors (#1378) --- openapi3/issue741_test.go | 3 + openapi3/loader_http_error_test.go | 2 + openapi3/schema_jsonschema_validator.go | 66 +++++++--- ...om_AccountService_3_openapi_yaml__validate | 5 +- ...om_AccountService_4_openapi_yaml__validate | 5 +- ...om_AccountService_5_openapi_yaml__validate | 6 +- ...om_AccountService_6_openapi_yaml__validate | 6 +- ...n_com_FundService_3_openapi_yaml__validate | 5 +- ...egalEntityService_1_openapi_yaml__validate | 4 +- ...egalEntityService_2_openapi_yaml__validate | 4 +- ...egalEntityService_3_openapi_yaml__validate | 4 +- ...tificationService_3_openapi_yaml__validate | 10 +- ...tificationService_4_openapi_yaml__validate | 10 +- ...tificationService_5_openapi_yaml__validate | 10 +- ...tificationService_6_openapi_yaml__validate | 10 +- .../exoapi_dev_1_0_0_openapi_yaml__validate | 9 +- .../rentcast_io_1_0_openapi_yaml__validate | 124 +++++++++++++++++- .../vercel_com_0_0_1_openapi_yaml__validate | 15 ++- ...ebscraping_ai_3_0_0_openapi_yaml__validate | 7 +- openapi3filter/issue1377_test.go | 53 ++++++++ 20 files changed, 326 insertions(+), 32 deletions(-) create mode 100644 openapi3filter/issue1377_test.go diff --git a/openapi3/issue741_test.go b/openapi3/issue741_test.go index f6cd672e0..21863bfe3 100644 --- a/openapi3/issue741_test.go +++ b/openapi3/issue741_test.go @@ -29,11 +29,14 @@ func TestIssue741(t *testing.T) { ts.URL, ) + readFromURI := openapi3.URIMapCache(openapi3.ReadFromHTTP(ts.Client())) + var wg sync.WaitGroup for range 10 { wg.Go(func() { loader := openapi3.NewLoader() loader.IsExternalRefsAllowed = true + loader.ReadFromURIFunc = readFromURI doc, err := loader.LoadFromData(rootSpec) require.NoError(t, err) require.NotNil(t, doc) diff --git a/openapi3/loader_http_error_test.go b/openapi3/loader_http_error_test.go index a1e51b7a2..0f886cdc6 100644 --- a/openapi3/loader_http_error_test.go +++ b/openapi3/loader_http_error_test.go @@ -48,6 +48,7 @@ func TestLoadReferenceFromRemoteURLFailsWithHttpError(t *testing.T) { loader := openapi3.NewLoader() loader.IsExternalRefsAllowed = true + loader.ReadFromURIFunc = openapi3.ReadFromHTTP(ts.Client()) _, err := loader.LoadFromDataWithPath(spec, &url.URL{Path: "testdata/testfilename.openapi.json"}) require.EqualError(t, err, fmt.Sprintf(`error resolving reference "%s/components.openapi.json#/components/headers/CustomTestHeader": error loading "%s/components.openapi.json": request returned status code 400`, ts.URL, ts.URL)) @@ -91,6 +92,7 @@ func TestLoadFromRemoteURLFailsWithHttpError(t *testing.T) { loader := openapi3.NewLoader() loader.IsExternalRefsAllowed = true + loader.ReadFromURIFunc = openapi3.ReadFromHTTP(ts.Client()) doc, err := loader.LoadFromDataWithPath(spec, &url.URL{Path: "testdata/testfilename.openapi.json"}) require.Nil(t, doc) diff --git a/openapi3/schema_jsonschema_validator.go b/openapi3/schema_jsonschema_validator.go index 515477eb7..c52480d0d 100644 --- a/openapi3/schema_jsonschema_validator.go +++ b/openapi3/schema_jsonschema_validator.go @@ -9,6 +9,7 @@ import ( "strconv" "strings" + "github.com/go-openapi/jsonpointer" "github.com/santhosh-tekuri/jsonschema/v6" "github.com/santhosh-tekuri/jsonschema/v6/kind" ) @@ -18,6 +19,8 @@ type jsonSchemaValidator struct { compiler *jsonschema.Compiler schema *jsonschema.Schema hasInternalRefs bool + root *Schema + defs map[string]*Schema } // newJSONSchemaValidator creates a new validator using JSON Schema 2020-12 @@ -36,7 +39,8 @@ func newJSONSchemaValidator(schema *Schema, settings *schemaValidationSettings) // Boolean schemas are valid JSON Schema resources as well. schemaMap, _ := schemaDocument.(map[string]any) hasInternalRefs := containsInternalSchemaRef(schemaDocument) - if err := addInternalSchemaRefs(schemaMap, schema); err != nil { + defs, err := addInternalSchemaRefs(schemaMap, schema) + if err != nil { return nil, fmt.Errorf("failed to prepare schema references: %w", err) } @@ -63,6 +67,8 @@ func newJSONSchemaValidator(schema *Schema, settings *schemaValidationSettings) compiler: compiler, schema: compiledSchema, hasInternalRefs: hasInternalRefs, + root: schema, + defs: defs, }, nil } @@ -89,11 +95,12 @@ func containsInternalSchemaRef(node any) bool { // resolved Schema. VisitJSON receives a subtree rather than the containing // OpenAPI document, so copy each resolved target into local $defs and rewrite // its reference. This also handles references to a nested property or item. -func addInternalSchemaRefs(schemaMap map[string]any, schema *Schema) error { +func addInternalSchemaRefs(schemaMap map[string]any, schema *Schema) (map[string]*Schema, error) { if schemaMap == nil || schema == nil { - return nil + return nil, nil } refs := make(map[string]any) + values := make(map[string]*Schema) // Recursive schemas reference an already-visited target, which WalkSubtree would not report. err := NewSchemaRef("", schema).walkSubtreeRefs(func(_ string, ref *SchemaRef) error { if ref.Ref == "" || !strings.HasPrefix(ref.Ref, "#/components/schemas/") || ref.Value == nil { @@ -111,25 +118,28 @@ func addInternalSchemaRefs(schemaMap map[string]any, schema *Schema) error { return err } refs[ref.Ref] = target + values[ref.Ref] = ref.Value return nil }) if err != nil { - return err + return nil, err } if len(refs) == 0 { - return nil + return nil, nil } defs := make(map[string]any, len(refs)) ids := make(map[string]string, len(refs)) + defValues := make(map[string]*Schema, len(refs)) for ref := range refs { ids[ref] = fmt.Sprintf("ref%d", len(ids)) + defValues[ids[ref]] = values[ref] } rewriteInternalSchemaRefs(schemaMap, refs, ids, defs) if len(defs) > 0 { schemaMap["$defs"] = defs rewriteInternalSchemaRefs(defs, refs, ids, defs) } - return nil + return defValues, nil } // rewriteInternalSchemaRefs rewrites document-relative component references to @@ -252,30 +262,30 @@ func validateNumberFormat(format string, settings *schemaValidationSettings, val func (v *jsonSchemaValidator) validate(settings *schemaValidationSettings, value any) error { if err := v.schema.Validate(value); err != nil { // Convert jsonschema error to SchemaError - return convertJSONSchemaError(settings, err, value) + return v.convertJSONSchemaError(settings, err, value) } return nil } // convertJSONSchemaError converts a jsonschema validation error to OpenAPI SchemaError format. // root is the validated value, from which the failing value is looked up. -func convertJSONSchemaError(settings *schemaValidationSettings, err error, root any) error { +func (v *jsonSchemaValidator) convertJSONSchemaError(settings *schemaValidationSettings, err error, root any) error { // TODO: Go 1.26 // if err, ok := errors.AsType[*jsonschema.ValidationError](err); ok { - // return formatValidationError(settings, err, "", root) + // return v.formatValidationError(settings, err, "", root) var validationErr *jsonschema.ValidationError if errors.As(err, &validationErr) { - return formatValidationError(settings, validationErr, "", root) + return v.formatValidationError(settings, validationErr, "", root) } return err } // formatValidationError recursively formats validation errors into SchemaErrors // that carry the same structure as the ones of the built-in validator: the path -// of the failing value (JSONPointer), the failing keyword (SchemaField) and the -// failing value (Value). The jsonschema error itself stays reachable with -// errors.As. -func formatValidationError(settings *schemaValidationSettings, verr *jsonschema.ValidationError, parentPath string, root any) error { +// of the failing value (JSONPointer), the failing keyword (SchemaField), the +// failing schema (Schema) and the failing value (Value). The jsonschema error +// itself stays reachable with errors.As. +func (v *jsonSchemaValidator) formatValidationError(settings *schemaValidationSettings, verr *jsonschema.ValidationError, parentPath string, root any) error { // Build the path from InstanceLocation slice path := "/" + strings.Join(verr.InstanceLocation, "/") if parentPath != "" && path != "/" { @@ -299,7 +309,7 @@ func formatValidationError(settings *schemaValidationSettings, verr *jsonschema. } value, _ := valueAt(root, failing.InstanceLocation) - schemaErr := settings.newSchemaError(nil, value). + schemaErr := settings.newSchemaError(v.schemaAt(failing.SchemaURL), value). withReason(msg.String()). withCause(verr) for _, key := range slices.Backward(failing.InstanceLocation) { @@ -313,7 +323,7 @@ func formatValidationError(settings *schemaValidationSettings, verr *jsonschema. if len(verr.Causes) > 0 { var subErrors MultiError for _, cause := range verr.Causes { - if subErr := formatValidationError(settings, cause, path, root); subErr != nil { + if subErr := v.formatValidationError(settings, cause, path, root); subErr != nil { subErrors = append(subErrors, subErr) } } @@ -325,6 +335,30 @@ func formatValidationError(settings *schemaValidationSettings, verr *jsonschema. return schemaErr } +// schemaAt is the schema at schemaURL, the location of a schema of the +// compiled document, or nil when it is not one of v's schemas. +func (v *jsonSchemaValidator) schemaAt(schemaURL string) *Schema { + _, fragment, _ := strings.Cut(schemaURL, "#") + root := v.root + if rest, ok := strings.CutPrefix(fragment, "/$defs/"); ok { + id, rest, _ := strings.Cut(rest, "/") + if root = v.defs[id]; root == nil { + return nil + } + fragment = strings.TrimSuffix("/"+rest, "/") + } + ptr, err := jsonpointer.New(fragment) + if err != nil { + return nil + } + found, _, err := ptr.Get(root) + if err != nil { + return nil + } + schema, _ := found.(*Schema) + return schema +} + // isWrapperErrorKind reports whether k only groups the errors of its causes. func isWrapperErrorKind(k jsonschema.ErrorKind) bool { switch k.(type) { diff --git a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_AccountService_3_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_AccountService_3_openapi_yaml__validate index 9e1d679e8..a85b907dd 100644 --- a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_AccountService_3_openapi_yaml__validate +++ b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_AccountService_3_openapi_yaml__validate @@ -1,6 +1,9 @@ invalid paths: invalid path /closeAccount: invalid operation POST: invalid example: example generic: validation failed due to: error at "/errorCode": at '/errorCode': got number, want string Schema: - null + { + "description": "The error code mapped to the error message.", + "type": "string" + } Value: 10003 diff --git a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_AccountService_4_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_AccountService_4_openapi_yaml__validate index 9e1d679e8..a85b907dd 100644 --- a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_AccountService_4_openapi_yaml__validate +++ b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_AccountService_4_openapi_yaml__validate @@ -1,6 +1,9 @@ invalid paths: invalid path /closeAccount: invalid operation POST: invalid example: example generic: validation failed due to: error at "/errorCode": at '/errorCode': got number, want string Schema: - null + { + "description": "The error code mapped to the error message.", + "type": "string" + } Value: 10003 diff --git a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_AccountService_5_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_AccountService_5_openapi_yaml__validate index aca52ea9d..919417f97 100644 --- a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_AccountService_5_openapi_yaml__validate +++ b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_AccountService_5_openapi_yaml__validate @@ -1,6 +1,10 @@ invalid paths: invalid path /checkAccountHolder: invalid operation POST: invalid example: example basic: validation failed due to: error at "/tier": at '/tier': got string, want integer Schema: - null + { + "description": "The tier required for the account holder.", + "format": "int32", + "type": "integer" + } Value: "2" diff --git a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_AccountService_6_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_AccountService_6_openapi_yaml__validate index aca52ea9d..919417f97 100644 --- a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_AccountService_6_openapi_yaml__validate +++ b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_AccountService_6_openapi_yaml__validate @@ -1,6 +1,10 @@ invalid paths: invalid path /checkAccountHolder: invalid operation POST: invalid example: example basic: validation failed due to: error at "/tier": at '/tier': got string, want integer Schema: - null + { + "description": "The tier required for the account holder.", + "format": "int32", + "type": "integer" + } Value: "2" diff --git a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_FundService_3_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_FundService_3_openapi_yaml__validate index d4a06941f..231dd5261 100644 --- a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_FundService_3_openapi_yaml__validate +++ b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_FundService_3_openapi_yaml__validate @@ -1,6 +1,9 @@ invalid paths: invalid path /debitAccountHolder: invalid operation POST: invalid example: example debit-account-holder: validation failed due to: error at "/submittedAsync": at '/submittedAsync': got string, want boolean Schema: - null + { + "description": "Indicates whether the request is processed asynchronously. Depending on the request's platform settings, the following scenarios may be applied:\n* **true**: The request is queued and will be executed when the providing service is available in the order in which the requests are received.\n* **false**: The processing of the request is immediately attempted; it may result in an error if the providing service is unavailable.", + "type": "boolean" + } Value: "false" diff --git a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_LegalEntityService_1_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_LegalEntityService_1_openapi_yaml__validate index dca7a33dc..2e436140e 100644 --- a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_LegalEntityService_1_openapi_yaml__validate +++ b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_LegalEntityService_1_openapi_yaml__validate @@ -1,6 +1,8 @@ invalid paths: invalid path /documents: invalid operation POST: invalid example: validation failed due to: at '': got number, want string Schema: - null + { + "type": "string" + } Value: 13008 diff --git a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_LegalEntityService_2_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_LegalEntityService_2_openapi_yaml__validate index dca7a33dc..2e436140e 100644 --- a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_LegalEntityService_2_openapi_yaml__validate +++ b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_LegalEntityService_2_openapi_yaml__validate @@ -1,6 +1,8 @@ invalid paths: invalid path /documents: invalid operation POST: invalid example: validation failed due to: at '': got number, want string Schema: - null + { + "type": "string" + } Value: 13008 diff --git a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_LegalEntityService_3_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_LegalEntityService_3_openapi_yaml__validate index dca7a33dc..2e436140e 100644 --- a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_LegalEntityService_3_openapi_yaml__validate +++ b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_LegalEntityService_3_openapi_yaml__validate @@ -1,6 +1,8 @@ invalid paths: invalid path /documents: invalid operation POST: invalid example: validation failed due to: at '': got number, want string Schema: - null + { + "type": "string" + } Value: 13008 diff --git a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_MarketPayNotificationService_3_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_MarketPayNotificationService_3_openapi_yaml__validate index 77e3029b9..5c83785e4 100644 --- a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_MarketPayNotificationService_3_openapi_yaml__validate +++ b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_MarketPayNotificationService_3_openapi_yaml__validate @@ -1,6 +1,14 @@ invalid webhooks: webhook "/ACCOUNT_CLOSED": invalid operation POST: invalid example: example accountClosed: validation failed due to: at '': got string, want object Schema: - null + { + "properties": { + "notificationResponse": { + "description": "Set this parameter to **[accepted]** to acknowledge that you received a notification from Adyen.", + "type": "string" + } + }, + "type": "object" + } Value: "[accepted]" diff --git a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_MarketPayNotificationService_4_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_MarketPayNotificationService_4_openapi_yaml__validate index 77e3029b9..5c83785e4 100644 --- a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_MarketPayNotificationService_4_openapi_yaml__validate +++ b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_MarketPayNotificationService_4_openapi_yaml__validate @@ -1,6 +1,14 @@ invalid webhooks: webhook "/ACCOUNT_CLOSED": invalid operation POST: invalid example: example accountClosed: validation failed due to: at '': got string, want object Schema: - null + { + "properties": { + "notificationResponse": { + "description": "Set this parameter to **[accepted]** to acknowledge that you received a notification from Adyen.", + "type": "string" + } + }, + "type": "object" + } Value: "[accepted]" diff --git a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_MarketPayNotificationService_5_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_MarketPayNotificationService_5_openapi_yaml__validate index 77e3029b9..5c83785e4 100644 --- a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_MarketPayNotificationService_5_openapi_yaml__validate +++ b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_MarketPayNotificationService_5_openapi_yaml__validate @@ -1,6 +1,14 @@ invalid webhooks: webhook "/ACCOUNT_CLOSED": invalid operation POST: invalid example: example accountClosed: validation failed due to: at '': got string, want object Schema: - null + { + "properties": { + "notificationResponse": { + "description": "Set this parameter to **[accepted]** to acknowledge that you received a notification from Adyen.", + "type": "string" + } + }, + "type": "object" + } Value: "[accepted]" diff --git a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_MarketPayNotificationService_6_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_MarketPayNotificationService_6_openapi_yaml__validate index 77e3029b9..5c83785e4 100644 --- a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_MarketPayNotificationService_6_openapi_yaml__validate +++ b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_MarketPayNotificationService_6_openapi_yaml__validate @@ -1,6 +1,14 @@ invalid webhooks: webhook "/ACCOUNT_CLOSED": invalid operation POST: invalid example: example accountClosed: validation failed due to: at '': got string, want object Schema: - null + { + "properties": { + "notificationResponse": { + "description": "Set this parameter to **[accepted]** to acknowledge that you received a notification from Adyen.", + "type": "string" + } + }, + "type": "object" + } Value: "[accepted]" diff --git a/openapi3/testdata/apis_guru_openapi_directory/exoapi_dev_1_0_0_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/exoapi_dev_1_0_0_openapi_yaml__validate index 3c74aa999..c701924a1 100644 --- a/openapi3/testdata/apis_guru_openapi_directory/exoapi_dev_1_0_0_openapi_yaml__validate +++ b/openapi3/testdata/apis_guru_openapi_directory/exoapi_dev_1_0_0_openapi_yaml__validate @@ -1,6 +1,13 @@ invalid paths: invalid path /html-renderer: invalid operation POST: invalid default: validation failed due to: at '': got number, want string Schema: - null + { + "default": 0, + "description": "PDF page margin (in px, mm, in or cm)", + "examples": [ + "1in" + ], + "type": "string" + } Value: 0 diff --git a/openapi3/testdata/apis_guru_openapi_directory/rentcast_io_1_0_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/rentcast_io_1_0_openapi_yaml__validate index ee3b991c4..4ba23441f 100644 --- a/openapi3/testdata/apis_guru_openapi_directory/rentcast_io_1_0_openapi_yaml__validate +++ b/openapi3/testdata/apis_guru_openapi_directory/rentcast_io_1_0_openapi_yaml__validate @@ -1,6 +1,128 @@ invalid paths: invalid path /avm/rent/long-term: invalid operation GET: invalid example: example Response: validation failed due to: at '': got string, want object Schema: - null + { + "properties": { + "comparables": { + "items": { + "properties": { + "addressLine1": { + "example": "7410 Adaja Riv", + "type": "string" + }, + "bathrooms": { + "default": 0, + "example": 2, + "type": "integer" + }, + "bedrooms": { + "default": 0, + "example": 4, + "type": "integer" + }, + "city": { + "example": "San Antonio", + "type": "string" + }, + "correlation": { + "default": 0, + "example": 0.988, + "type": "number" + }, + "county": { + "example": "Bexar", + "type": "string" + }, + "daysOld": { + "default": 0, + "example": 11, + "type": "integer" + }, + "distance": { + "default": 0, + "example": 0.5282, + "type": "number" + }, + "formattedAddress": { + "example": "7410 Adaja Riv, San Antonio, TX 78244", + "type": "string" + }, + "id": { + "example": "7410-Adaja-Riv,-San-Antonio,-TX-78244", + "type": "string" + }, + "lastSeenDate": { + "example": "2023-02-17T00:00:00.000Z", + "type": "string" + }, + "latitude": { + "default": 0, + "example": 29.481005, + "type": "number" + }, + "listedDate": { + "example": "2023-01-22T00:00:00.000Z", + "type": "string" + }, + "longitude": { + "default": 0, + "example": -98.344856, + "type": "number" + }, + "price": { + "default": 0, + "example": 1850, + "type": "integer" + }, + "propertyType": { + "example": "Single Family", + "type": "string" + }, + "squareFootage": { + "default": 0, + "example": 1627, + "type": "integer" + }, + "state": { + "example": "TX", + "type": "string" + }, + "zipCode": { + "example": "78244", + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + }, + "latitude": { + "default": 0, + "example": 29.475962, + "type": "number" + }, + "longitude": { + "default": 0, + "example": -98.351442, + "type": "number" + }, + "rent": { + "default": 0, + "example": 1800, + "type": "integer" + }, + "rentRangeHigh": { + "default": 0, + "example": 1860, + "type": "integer" + }, + "rentRangeLow": { + "default": 0, + "example": 1740, + "type": "integer" + } + }, + "type": "object" + } Value: "{\"rent\":1800,\"rentRangeLow\":1740,\"rentRangeHigh\":1860,\"longitude\":-98.351442,\"latitude\":29.475962,\"comparables\":[{\"id\":\"7410-Adaja-Riv,-San-Antonio,-TX-78244\",\"formattedAddress\":\"7410 Adaja Riv, San Antonio, TX 78244\",\"addressLine1\":\"7410 Adaja Riv\",\"city\":\"San Antonio\",\"state\":\"TX\",\"zipCode\":\"78244\",\"county\":\"Bexar\",\"longitude\":-98.344856,\"latitude\":29.481005,\"propertyType\":\"Single Family\",\"bedrooms\":4,\"bathrooms\":2,\"squareFootage\":1627,\"price\":1850,\"listedDate\":\"2023-01-22T00:00:00.000Z\",\"lastSeenDate\":\"2023-02-17T00:00:00.000Z\",\"daysOld\":11,\"distance\":0.5282,\"correlation\":0.988},{\"id\":\"7303-Avila-Vis,-San-Antonio,-TX-78244\",\"formattedAddress\":\"7303 Avila Vis, San Antonio, TX 78244\",\"addressLine1\":\"7303 Avila Vis\",\"city\":\"San Antonio\",\"state\":\"TX\",\"zipCode\":\"78244\",\"county\":\"Bexar\",\"longitude\":-98.34565,\"latitude\":29.483196,\"propertyType\":\"Single Family\",\"bedrooms\":4,\"bathrooms\":2,\"squareFootage\":1627,\"price\":1850,\"listedDate\":\"2023-02-03T00:00:00.000Z\",\"lastSeenDate\":\"2023-02-17T00:00:00.000Z\",\"daysOld\":11,\"distance\":0.6099,\"correlation\":0.9867},{\"id\":\"7331-Avila-Vis,-San-Antonio,-TX-78244\",\"formattedAddress\":\"7331 Avila Vis, San Antonio, TX 78244\",\"addressLine1\":\"7331 Avila Vis\",\"city\":\"San Antonio\",\"state\":\"TX\",\"zipCode\":\"78244\",\"county\":\"Bexar\",\"longitude\":-98.34481,\"latitude\":29.482922,\"propertyType\":\"Single Family\",\"bedrooms\":4,\"bathrooms\":2,\"squareFootage\":1627,\"price\":1810,\"listedDate\":\"2023-02-21T00:00:00.000Z\",\"lastSeenDate\":\"2023-02-27T00:00:00.000Z\",\"daysOld\":1,\"distance\":0.6255,\"correlation\":0.9865},{\"id\":\"7411-Avila-Vis,-San-Antonio,-TX-78244\",\"formattedAddress\":\"7411 Avila Vis, San Antonio, TX 78244\",\"addressLine1\":\"7411 Avila Vis\",\"city\":\"San Antonio\",\"state\":\"TX\",\"zipCode\":\"78244\",\"county\":\"Bexar\",\"longitude\":-98.344398,\"latitude\":29.482676,\"propertyType\":\"Single Family\",\"bedrooms\":4,\"bathrooms\":2,\"squareFootage\":1627,\"price\":1815,\"listedDate\":\"2023-01-16T00:00:00.000Z\",\"lastSeenDate\":\"2023-02-10T00:00:00.000Z\",\"daysOld\":18,\"distance\":0.629,\"correlation\":0.9864},{\"id\":\"7327-Plata-Cir,-San-Antonio,-TX-78244\",\"formattedAddress\":\"7327 Plata Cir, San Antonio, TX 78244\",\"addressLine1\":\"7327 Plata Cir\",\"city\":\"San Antonio\",\"state\":\"TX\",\"zipCode\":\"78244\",\"county\":\"Bexar\",\"longitude\":-98.344406,\"latitude\":29.480621,\"propertyType\":\"Single Family\",\"bedrooms\":4,\"bathrooms\":2,\"squareFootage\":1492,\"price\":1680,\"listedDate\":\"2023-01-12T00:00:00.000Z\",\"lastSeenDate\":\"2023-02-08T00:00:00.000Z\",\"daysOld\":20,\"distance\":0.5323,\"correlation\":0.9758}]}" diff --git a/openapi3/testdata/apis_guru_openapi_directory/vercel_com_0_0_1_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/vercel_com_0_0_1_openapi_yaml__validate index 95868ff6c..0b2671730 100644 --- a/openapi3/testdata/apis_guru_openapi_directory/vercel_com_0_0_1_openapi_yaml__validate +++ b/openapi3/testdata/apis_guru_openapi_directory/vercel_com_0_0_1_openapi_yaml__validate @@ -1,6 +1,19 @@ invalid paths: invalid path /v1/teams/{teamId}/members/{uid}: invalid operation PATCH: invalid default: validation failed due to: at '': got array, want string Schema: - null + { + "default": [ + "MEMBER", + "VIEWER" + ], + "description": "The role in the team of the member.", + "examples": [ + [ + "MEMBER", + "VIEWER" + ] + ], + "type": "string" + } Value: [ diff --git a/openapi3/testdata/apis_guru_openapi_directory/webscraping_ai_3_0_0_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/webscraping_ai_3_0_0_openapi_yaml__validate index ce3debc9b..871764345 100644 --- a/openapi3/testdata/apis_guru_openapi_directory/webscraping_ai_3_0_0_openapi_yaml__validate +++ b/openapi3/testdata/apis_guru_openapi_directory/webscraping_ai_3_0_0_openapi_yaml__validate @@ -1,6 +1,11 @@ invalid components: parameter "headers": invalid example: validation failed due to: at '': got string, want object Schema: - null + { + "additionalProperties": { + "type": "string" + }, + "type": "object" + } Value: "{\"Cookie\":\"session=some_id\"}" diff --git a/openapi3filter/issue1377_test.go b/openapi3filter/issue1377_test.go new file mode 100644 index 000000000..b1aebb183 --- /dev/null +++ b/openapi3filter/issue1377_test.go @@ -0,0 +1,53 @@ +package openapi3filter + +import ( + "net/http" + "strings" + "testing" + + "github.com/stretchr/testify/require" +) + +func TestIssue1377(t *testing.T) { + t.Parallel() + + const spec = ` +openapi: 3.1.0 +info: {title: repro, version: "1"} +paths: + /config: + put: + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + interval: + type: string + enum: [day, week] + responses: + "204": {description: ok} +` + + req, err := http.NewRequest(http.MethodPut, "/config", strings.NewReader(`{"interval":"hour"}`)) + require.NoError(t, err) + req.Header.Set(headerCT, "application/json") + + router := setupTestRouter(t, spec) + route, pathParams, err := router.FindRoute(req) + require.NoError(t, err) + + err = ValidateRequest(t.Context(), &RequestValidationInput{ + Request: req, + PathParams: pathParams, + Route: route, + }) + require.Error(t, err) + + verr := ConvertErrors(err).(*ValidationError) + require.Equal(t, http.StatusUnprocessableEntity, verr.Status) + require.Equal(t, &ValidationErrorSource{Pointer: "/interval"}, verr.Source) + require.Equal(t, "value hour at /interval must be one of: day, week", verr.Detail) +} From 7dd0f6c49979f1e646f83fcf6d888990da6d17b4 Mon Sep 17 00:00:00 2001 From: Luis Figueroa <62305361+LuisFigueroaG@users.noreply.github.com> Date: Sat, 24 Oct 2026 20:15:14 -0300 Subject: [PATCH 11/78] openapi3filter: parse number values as decimal only (#1366) --- README.md | 3 +++ openapi3filter/req_resp_decoder.go | 6 +++++ openapi3filter/req_resp_decoder_test.go | 35 +++++++++++++++++++++++++ 3 files changed, 44 insertions(+) diff --git a/README.md b/README.md index 21e4bcfba..661a1e767 100644 --- a/README.md +++ b/README.md @@ -329,6 +329,9 @@ for _, path := range doc.Paths.InMatchingOrder() { ## CHANGELOG: Sub-v1 breaking API changes +### v0.153.0 +* `openapi3filter` now parses `number` values of parameters and `application/x-www-form-urlencoded`/`multipart/form-data` bodies as decimal numbers only, so Go float literals such as `0x1p4`, `1_000`, `Inf`, `-infinity` or `NaN` are now rejected as invalid numbers. + ### v0.152.0 * JSON keys of OpenAPI documents only fill the field of the same case (`json:",case:strict"`) when `encoding/json` is implemented with `encoding/json/v2` (by default from Go 1.27, and on Go 1.25 and 1.26 with `GOEXPERIMENT=jsonv2`): a key such as `"Components"` (not `"components"`) is kept as an extension instead of filling `openapi3.T.Components`. Other builds still match keys case-insensitively, as `encoding/json` v1 does. * On Go 1.27+, unless built with `GOEXPERIMENT=nojsonv2`, `openapi2` and `openapi3` decode documents with `encoding/json/v2`: objects with duplicate member names and strings with invalid UTF-8 are rejected, and decoding errors are worded differently and locate the faulty value from the root of the document, keys of paths, responses and callbacks included (e.g. `.paths.~1pets.get.responses.200.description`). On these builds `openapi2.Responses`, `openapi3.Callback`, `openapi3.Paths` and `openapi3.Responses` also implement `encoding/json/v2.UnmarshalerFrom`. diff --git a/openapi3filter/req_resp_decoder.go b/openapi3filter/req_resp_decoder.go index 3bcfd4931..d734c6c4d 100644 --- a/openapi3filter/req_resp_decoder.go +++ b/openapi3filter/req_resp_decoder.go @@ -1259,6 +1259,12 @@ func parsePrimitiveCase(raw string, schema *openapi3.SchemaRef, typ string) (any } return v, nil case "number": + // strconv.ParseFloat also accepts Go float literals that are not decimal + // numbers: hexadecimal (0x1p4), digits separated by underscores (1_000), + // infinities and NaN. + if strings.ContainsFunc(raw, func(r rune) bool { return !strings.ContainsRune("+-.0123456789eE", r) }) { + return nil, &ParseError{Kind: KindInvalidFormat, Value: raw, Reason: "an invalid " + typ, Cause: strconv.ErrSyntax} + } v, err := strconv.ParseFloat(raw, 64) if err != nil { return nil, &ParseError{Kind: KindInvalidFormat, Value: raw, Reason: "an invalid " + typ, Cause: err.(*strconv.NumError).Err} diff --git a/openapi3filter/req_resp_decoder_test.go b/openapi3filter/req_resp_decoder_test.go index c62a9dfb3..26eac74a9 100644 --- a/openapi3filter/req_resp_decoder_test.go +++ b/openapi3filter/req_resp_decoder_test.go @@ -767,6 +767,41 @@ func TestDecodeParameter(t *testing.T) { found: true, err: &ParseError{Kind: KindInvalidFormat, Value: "foo"}, }, + { + name: "number exponent", + param: &openapi3.Parameter{Name: "param", In: "query", Schema: numberSchema}, + query: "param=-1.5E+3", + want: -1500.0, + found: true, + }, + { + name: "number hexadecimal", + param: &openapi3.Parameter{Name: "param", In: "query", Schema: numberSchema}, + query: "param=0x1p4", + found: true, + err: &ParseError{Kind: KindInvalidFormat, Value: "0x1p4"}, + }, + { + name: "number underscores", + param: &openapi3.Parameter{Name: "param", In: "query", Schema: numberSchema}, + query: "param=1_000.5", + found: true, + err: &ParseError{Kind: KindInvalidFormat, Value: "1_000.5"}, + }, + { + name: "number infinity", + param: &openapi3.Parameter{Name: "param", In: "query", Schema: numberSchema}, + query: "param=-Inf", + found: true, + err: &ParseError{Kind: KindInvalidFormat, Value: "-Inf"}, + }, + { + name: "number NaN", + param: &openapi3.Parameter{Name: "param", In: "query", Schema: numberSchema}, + query: "param=NaN", + found: true, + err: &ParseError{Kind: KindInvalidFormat, Value: "NaN"}, + }, { name: "boolean", param: &openapi3.Parameter{Name: "param", In: "query", Schema: booleanSchema}, From 5c5819ec17df42dd7c525bdaf593fe6239c24d78 Mon Sep 17 00:00:00 2001 From: Pierre Fenoll Date: Sun, 25 Oct 2026 23:05:29 +0100 Subject: [PATCH 12/78] openapi3: marshal a ref holding neither $ref nor a value as null --- openapi3/null_ref_test.go | 37 +++++++++++++++++++++++++++++++++++++ openapi3/refs.go | 27 +++++++++++++++++++++++++++ openapi3/refs.tmpl | 3 +++ 3 files changed, 67 insertions(+) create mode 100644 openapi3/null_ref_test.go diff --git a/openapi3/null_ref_test.go b/openapi3/null_ref_test.go new file mode 100644 index 000000000..2383164bf --- /dev/null +++ b/openapi3/null_ref_test.go @@ -0,0 +1,37 @@ +package openapi3_test + +import ( + "encoding/json" + "testing" + + "github.com/stretchr/testify/require" + + "github.com/getkin/kin-openapi/openapi3" +) + +// A null where a component belongs decodes to a ref with neither $ref nor a +// value. The loader rejects it, but a document unmarshaled directly holds it, +// and it must marshal back to null rather than dereference the missing value. +func TestRefs_NullValueMarshalsAsNull(t *testing.T) { + spec := []byte(`{ + "openapi": "3.0.0", + "info": {"title": "t", "version": "1"}, + "paths": {"/a": {"get": {"parameters": [null], "responses": {"200": null}}}}, + "components": { + "schemas": {"A": null}, + "responses": {"R": null}, + "parameters": {"P": null} + } + }`) + var doc openapi3.T + require.NoError(t, json.Unmarshal(spec, &doc)) + + once, err := json.Marshal(&doc) + require.NoError(t, err) + + var reloaded openapi3.T + require.NoError(t, json.Unmarshal(once, &reloaded)) + twice, err := json.Marshal(&reloaded) + require.NoError(t, err) + require.JSONEq(t, string(once), string(twice)) +} diff --git a/openapi3/refs.go b/openapi3/refs.go index 9fce3febf..085f85c1f 100644 --- a/openapi3/refs.go +++ b/openapi3/refs.go @@ -73,6 +73,9 @@ func (x CallbackRef) MarshalYAML() (any, error) { } return out, nil } + if x.Value == nil { + return nil, nil + } return x.Value.MarshalYAML() } @@ -235,6 +238,9 @@ func (x ExampleRef) MarshalYAML() (any, error) { } return out, nil } + if x.Value == nil { + return nil, nil + } return x.Value.MarshalYAML() } @@ -397,6 +403,9 @@ func (x HeaderRef) MarshalYAML() (any, error) { } return out, nil } + if x.Value == nil { + return nil, nil + } return x.Value.MarshalYAML() } @@ -559,6 +568,9 @@ func (x LinkRef) MarshalYAML() (any, error) { } return out, nil } + if x.Value == nil { + return nil, nil + } return x.Value.MarshalYAML() } @@ -721,6 +733,9 @@ func (x ParameterRef) MarshalYAML() (any, error) { } return out, nil } + if x.Value == nil { + return nil, nil + } return x.Value.MarshalYAML() } @@ -883,6 +898,9 @@ func (x RequestBodyRef) MarshalYAML() (any, error) { } return out, nil } + if x.Value == nil { + return nil, nil + } return x.Value.MarshalYAML() } @@ -1045,6 +1063,9 @@ func (x ResponseRef) MarshalYAML() (any, error) { } return out, nil } + if x.Value == nil { + return nil, nil + } return x.Value.MarshalYAML() } @@ -1228,6 +1249,9 @@ func (x SchemaRef) MarshalYAML() (any, error) { } return out, nil } + if x.Value == nil { + return nil, nil + } return x.Value.MarshalYAML() } @@ -1404,6 +1428,9 @@ func (x SecuritySchemeRef) MarshalYAML() (any, error) { } return out, nil } + if x.Value == nil { + return nil, nil + } return x.Value.MarshalYAML() } diff --git a/openapi3/refs.tmpl b/openapi3/refs.tmpl index 8398c302b..84076b991 100644 --- a/openapi3/refs.tmpl +++ b/openapi3/refs.tmpl @@ -108,6 +108,9 @@ func (x {{ $type.Name }}Ref) MarshalYAML() (any, error) { } return out, nil } + if x.Value == nil { + return nil, nil + } return x.Value.MarshalYAML() } From c5fa9405c759e1a0f46c6d9b517cbf72bc4774e9 Mon Sep 17 00:00:00 2001 From: Pierre Fenoll Date: Sun, 25 Oct 2026 23:05:29 +0100 Subject: [PATCH 13/78] openapi2conv: fix nil dereferences and input mutation in FromV3 Found by seeding FuzzToV3 with the APIs-guru corpus. --- openapi2conv/openapi2_conv.go | 34 +++++++++++-------- openapi2conv/schema_conv_test.go | 56 ++++++++++++++++++++++++++++++++ 2 files changed, 77 insertions(+), 13 deletions(-) create mode 100644 openapi2conv/schema_conv_test.go diff --git a/openapi2conv/openapi2_conv.go b/openapi2conv/openapi2_conv.go index c77072af0..38fee0cf5 100644 --- a/openapi2conv/openapi2_conv.go +++ b/openapi2conv/openapi2_conv.go @@ -565,7 +565,7 @@ func ToV3SchemaRef(schema *openapi2.SchemaRef) *openapi3.SchemaRef { } v3Schema := &openapi3.Schema{ - Extensions: schema.Value.Extensions, + Extensions: maps.Clone(schema.Value.Extensions), Type: schema.Value.Type, Title: schema.Value.Title, Format: schema.Value.Format, @@ -746,11 +746,16 @@ func ToV3SecurityScheme(securityScheme *openapi2.SecurityScheme) (*openapi3.Secu // FromV3 converts an OpenAPIv3 spec to an OpenAPIv2 spec func FromV3(doc3 *openapi3.T) (*openapi2.T, error) { - doc2Responses, err := FromV3Responses(doc3.Components.Responses, doc3.Components) + // A document need not declare components. + components := doc3.Components + if components == nil { + components = &openapi3.Components{} + } + doc2Responses, err := FromV3Responses(components.Responses, components) if err != nil { return nil, err } - schemas, parameters := FromV3Schemas(doc3.Components.Schemas, doc3.Components) + schemas, parameters := FromV3Schemas(components.Schemas, components) doc2 := &openapi2.T{ Swagger: "2.0", Info: *doc3.Info, @@ -809,7 +814,7 @@ func FromV3(doc3 *openapi3.T) (*openapi2.T, error) { } params := openapi2.Parameters{} for _, param := range pathItem.Parameters { - p, err := FromV3Parameter(param, doc3.Components) + p, err := FromV3Parameter(param, components) if err != nil { return nil, err } @@ -819,14 +824,14 @@ func FromV3(doc3 *openapi3.T) (*openapi2.T, error) { doc2.Paths[path].Parameters = params } - for name, param := range doc3.Components.Parameters { - if doc2.Parameters[name], err = FromV3Parameter(param, doc3.Components); err != nil { + for name, param := range components.Parameters { + if doc2.Parameters[name], err = FromV3Parameter(param, components); err != nil { return nil, err } } - for name, requestBodyRef := range doc3.Components.RequestBodies { - bodyOrRefParameters, formDataParameters, consumes, err := fromV3RequestBodies(name, requestBodyRef, doc3.Components) + for name, requestBodyRef := range components.RequestBodies { + bodyOrRefParameters, formDataParameters, consumes, err := fromV3RequestBodies(name, requestBodyRef, components) if err != nil { return nil, err } @@ -845,7 +850,7 @@ func FromV3(doc3 *openapi3.T) (*openapi2.T, error) { } } - if m := doc3.Components.SecuritySchemes; m != nil { + if m := components.SecuritySchemes; m != nil { doc2SecuritySchemes := make(map[string]*openapi2.SecurityScheme) for id, securityScheme := range m { v, err := FromV3SecurityScheme(securityScheme) @@ -927,6 +932,10 @@ func FromV3Schemas(schemas map[string]*openapi3.SchemaRef, components *openapi3. } func FromV3SchemaRef(schema *openapi3.SchemaRef, components *openapi3.Components) (*openapi2.SchemaRef, *openapi2.Parameter) { + // A media type need not carry a schema. + if schema == nil { + return nil, nil + } if ref := schema.Ref; ref != "" { // FromV3RequestBodyFormData (and other recursive call sites in // this file) pass components=nil when recursing into array @@ -938,7 +947,7 @@ func FromV3SchemaRef(schema *openapi3.SchemaRef, components *openapi3.Components // schema is not known locally': emit a plain $ref and move on. name := getParameterNameFromNewRef(ref) if components != nil { - if val, ok := components.Schemas[name]; ok { + if val, ok := components.Schemas[name]; ok && val != nil && val.Value != nil { if val.Value.Format == "binary" { v2Ref := strings.Replace(ref, "#/components/schemas/", "#/parameters/", 1) return nil, &openapi2.Parameter{Ref: v2Ref} @@ -987,7 +996,7 @@ func FromV3SchemaRef(schema *openapi3.SchemaRef, components *openapi3.Components } v2Schema := &openapi2.Schema{ - Extensions: schema.Value.Extensions, + Extensions: maps.Clone(schema.Value.Extensions), Type: schema.Value.Type, Title: schema.Value.Title, Format: schema.Value.Format, @@ -1040,8 +1049,7 @@ func FromV3SchemaRef(schema *openapi3.SchemaRef, components *openapi3.Components v2Schema.AllOf[i], _ = FromV3SchemaRef(v, components) } if schema.Value.PermitsNull() { - schema.Value.Nullable = false - if schema.Value.Extensions == nil { + if v2Schema.Extensions == nil { v2Schema.Extensions = make(map[string]any) } v2Schema.Extensions["x-nullable"] = true diff --git a/openapi2conv/schema_conv_test.go b/openapi2conv/schema_conv_test.go new file mode 100644 index 000000000..b215f7fba --- /dev/null +++ b/openapi2conv/schema_conv_test.go @@ -0,0 +1,56 @@ +package openapi2conv_test + +import ( + "encoding/json" + "testing" + + "github.com/stretchr/testify/require" + + "github.com/getkin/kin-openapi/openapi2" + "github.com/getkin/kin-openapi/openapi2conv" + "github.com/getkin/kin-openapi/openapi3" +) + +// A media type need not carry a schema. +func TestFromV3_MediaTypeWithoutSchema(t *testing.T) { + var doc3 openapi3.T + require.NoError(t, json.Unmarshal([]byte(`{ + "openapi": "3.0.0", + "info": {"title": "t", "version": "1"}, + "paths": {"/a": {"get": {"responses": {"200": { + "description": "ok", + "content": {"application/json": {}} + }}}}} + }`), &doc3)) + + doc2, err := openapi2conv.FromV3(&doc3) + require.NoError(t, err) + require.Nil(t, doc2.Paths["/a"].Get.Responses.Value("200").Schema) +} + +// Converting a nullable schema either way leaves the source document as it +// was: converting it again gives the same result. +func TestSchemaConversion_LeavesSourceUnchanged(t *testing.T) { + var doc2 openapi2.T + require.NoError(t, json.Unmarshal([]byte(`{ + "swagger": "2.0", + "info": {"title": "t", "version": "1"}, + "paths": {}, + "definitions": {"A": {"type": "string", "x-nullable": true, "x-other": 1}} + }`), &doc2)) + + doc3, err := openapi2conv.ToV3(&doc2) + require.NoError(t, err) + require.Equal(t, true, doc2.Definitions["A"].Value.Extensions["x-nullable"]) + require.True(t, doc3.Components.Schemas["A"].Value.Nullable) + + back, err := openapi2conv.FromV3(doc3) + require.NoError(t, err) + require.Equal(t, true, back.Definitions["A"].Value.Extensions["x-nullable"]) + require.True(t, doc3.Components.Schemas["A"].Value.Nullable) + require.NotContains(t, doc3.Components.Schemas["A"].Value.Extensions, "x-nullable") + + again, err := openapi2conv.FromV3(doc3) + require.NoError(t, err) + require.Equal(t, back.Definitions, again.Definitions) +} From 5a3af7827b759e81bfc62a3ee580f21754e34930 Mon Sep 17 00:00:00 2001 From: Pierre Fenoll Date: Sun, 25 Oct 2026 23:05:30 +0100 Subject: [PATCH 14/78] fuzz: seed from all of testdata and the APIs-guru corpus, cover the YAML path Seeds: - Walk testdata trees rather than globbing their top level, so specs in origin/, issue*/, relativeDocs/ and the like seed the fuzzers too: FuzzLoadFromData goes from 51 seeds to 161. - Add the APIs-guru corpus documents under 16 KiB (about 280 OpenAPI 3 and 550 Swagger 2) when the TestV{2,3}ApisGuruOpenapiDirectory tests have downloaded it, outside -short. FuzzLoadFromData reaches 449. - Add YAML-specific seeds: anchors and aliases, merge keys, tags, block scalars, YAML 1.1 implicit resolution, flow style and CRLF. Targets: - FuzzLoadWithOrigins: asking for origins changes nothing about the document, and every recorded position lies inside the input. - FuzzYAMLMatchesJSON: a JSON document decodes the same through the YAML path, and any document survives being re-encoded as YAML. - FuzzUnmarshalFromData: an openapi2 document loads back to itself from its own JSON and YAML forms. internal/fuzzing holds what targets in several packages share: finding seeds, and telling which documents the YAML emitter cannot write back. The fuzz workflow runs the new targets and restores the corpus from the go workflow's cache, fetching it when that is missing. --- .github/workflows/fuzz.yml | 23 ++++ Makefile | 3 + internal/fuzzing/fuzzing.go | 119 ++++++++++++++++++++ openapi2/fuzz_test.go | 78 +++++++++++++ openapi2conv/fuzz_test.go | 9 ++ openapi3/fuzz_test.go | 141 ++++++++++++++++++++--- openapi3/yaml_fuzz_test.go | 218 ++++++++++++++++++++++++++++++++++++ openapi3filter/fuzz_test.go | 15 +-- 8 files changed, 578 insertions(+), 28 deletions(-) create mode 100644 internal/fuzzing/fuzzing.go create mode 100644 openapi2/fuzz_test.go create mode 100644 openapi3/yaml_fuzz_test.go diff --git a/.github/workflows/fuzz.yml b/.github/workflows/fuzz.yml index 4c920d2ac..c9202215a 100644 --- a/.github/workflows/fuzz.yml +++ b/.github/workflows/fuzz.yml @@ -25,6 +25,8 @@ jobs: # must not hold a runner forever. timeout-minutes: 45 env: + # Keep in sync with the go workflow, whose cache this restores. + APISGURU_COMMIT: f7207cf0a5c56081d275ebae4cf615249323385d GO111MODULE: 'on' CGO_ENABLED: '0' strategy: @@ -33,7 +35,10 @@ jobs: matrix: include: - {package: ./openapi3, target: FuzzLoadFromData} + - {package: ./openapi3, target: FuzzLoadWithOrigins} + - {package: ./openapi3, target: FuzzYAMLMatchesJSON} - {package: ./openapi3, target: FuzzSchemaVisitJSON} + - {package: ./openapi2, target: FuzzUnmarshalFromData} - {package: ./openapi2conv, target: FuzzToV3} - {package: ./openapi3filter, target: FuzzValidateRequest} steps: @@ -44,6 +49,24 @@ jobs: - uses: actions/checkout@v6 + # The APIs-guru corpus seeds the fuzzers alongside testdata. The go + # workflow caches it, so fetch it only when that cache is missing. + - name: APIs-guru corpus cache + id: apisguru + uses: actions/cache/restore@v4 + with: + path: | + openapi2/testdata/APIs-guru-openapi-directory-* + openapi3/testdata/APIs-guru-openapi-directory-* + key: suite-${{ env.APISGURU_COMMIT }} + + - name: Fetch APIs-guru corpus + if: steps.apisguru.outputs.cache-hit != 'true' + run: | + dir=openapi3/testdata/APIs-guru-openapi-directory-${APISGURU_COMMIT:0:7} + mkdir -p "$dir" + curl -fsSL "https://github.com/APIs-guru/openapi-directory/tarball/$APISGURU_COMMIT" | tar -xz -C "$dir" + # The generated corpus lives under $GOCACHE/fuzz and is what makes fuzzing # cumulative: without it every run restarts from the seed corpus. The key # carries the run id so each run writes a fresh entry, and restore-keys diff --git a/Makefile b/Makefile index 8fc32f5e5..2978ca959 100644 --- a/Makefile +++ b/Makefile @@ -28,7 +28,10 @@ test-fast: ## fuzz: Fuzz each target for FUZZTIME (default 60s) fuzz: go test -run='^$$' -fuzz='^FuzzLoadFromData$$' -fuzztime=$(FUZZTIME) ./openapi3 + go test -run='^$$' -fuzz='^FuzzLoadWithOrigins$$' -fuzztime=$(FUZZTIME) ./openapi3 + go test -run='^$$' -fuzz='^FuzzYAMLMatchesJSON$$' -fuzztime=$(FUZZTIME) ./openapi3 go test -run='^$$' -fuzz='^FuzzSchemaVisitJSON$$' -fuzztime=$(FUZZTIME) ./openapi3 + go test -run='^$$' -fuzz='^FuzzUnmarshalFromData$$' -fuzztime=$(FUZZTIME) ./openapi2 go test -run='^$$' -fuzz='^FuzzToV3$$' -fuzztime=$(FUZZTIME) ./openapi2conv go test -run='^$$' -fuzz='^FuzzValidateRequest$$' -fuzztime=$(FUZZTIME) ./openapi3filter diff --git a/internal/fuzzing/fuzzing.go b/internal/fuzzing/fuzzing.go new file mode 100644 index 000000000..ad8bf19d9 --- /dev/null +++ b/internal/fuzzing/fuzzing.go @@ -0,0 +1,119 @@ +// Package fuzzing holds what the fuzz targets share: finding the documents +// they seed their corpus with, and telling which documents survive YAML. +package fuzzing + +import ( + "bytes" + "os" + "path/filepath" + "strings" + "testing" +) + +// MaxSize keeps the seed corpus small enough that `go test ./...` still +// replays it on every run without noticeably slowing the suite down. +const MaxSize = 16 << 10 + +// Testdata returns every spec under the given testdata roots, however deep, +// so documents kept beside the tests that load them seed the fuzzers too. +// Fuzz corpora are skipped, and so is the downloaded APIs-guru directory, +// which APIsGuru reads. +func Testdata(tb testing.TB, roots ...string) [][]byte { + tb.Helper() + var seeds [][]byte + for _, root := range roots { + seeds = append(seeds, walk(tb, root, func(name string) bool { + return name == "fuzz" || strings.HasPrefix(name, apisGuruPrefix) + }, nil)...) + } + return seeds +} + +const apisGuruPrefix = "APIs-guru-openapi-directory-" + +// APIsGuru returns the documents of the APIs-guru corpus under testdata whose +// top-level keys include marker, e.g. "openapi:" or "swagger:". The corpus is +// downloaded by the TestV{2,3}ApisGuruOpenapiDirectory tests, and when it is +// absent this returns nothing. Under -short, which skips those tests, it +// returns nothing either, keeping the short suite short. +func APIsGuru(tb testing.TB, testdata, marker string) [][]byte { + tb.Helper() + if testing.Short() { + return nil + } + dirs, err := filepath.Glob(filepath.Join(testdata, apisGuruPrefix+"*")) + if err != nil { + tb.Fatal(err) + } + var seeds [][]byte + for _, dir := range dirs { + // The tarball's own top-level directory carries the same name. + root := filepath.Join(dir, filepath.Base(dir), "APIs") + seeds = append(seeds, walk(tb, root, nil, func(data []byte) bool { + return bytes.HasPrefix(data, []byte(marker)) || bytes.Contains(data, []byte("\n"+marker)) + })...) + } + return seeds +} + +func walk(tb testing.TB, root string, skipDir func(string) bool, keep func([]byte) bool) [][]byte { + tb.Helper() + var seeds [][]byte + if err := filepath.WalkDir(root, func(path string, d os.DirEntry, err error) error { + if err != nil { + return err + } + if d.IsDir() { + if path != root && skipDir != nil && skipDir(d.Name()) { + return filepath.SkipDir + } + return nil + } + switch filepath.Ext(path) { + case ".yml", ".yaml", ".json": + default: + return nil + } + if info, err := d.Info(); err != nil || info.Size() > MaxSize { + return err + } + data, err := os.ReadFile(path) + if err != nil { + return err + } + if keep == nil || keep(data) { + seeds = append(seeds, data) + } + return nil + }); err != nil { + tb.Fatal(err) + } + return seeds +} + +// LosesInYAML reports whether v, decoded from JSON, holds something the YAML +// emitter does not write back faithfully, so a round trip through YAML text +// cannot be expected to preserve it: +// +// - a "<<" key, which is written unquoted and so reads back as a merge; +// - a string starting with a line break, which is written as a block +// scalar that drops it. +func LosesInYAML(v any) bool { + switch v := v.(type) { + case string: + return strings.HasPrefix(v, "\n") || strings.HasPrefix(v, "\r") + case map[string]any: + for k, e := range v { + if k == "<<" || LosesInYAML(k) || LosesInYAML(e) { + return true + } + } + case []any: + for _, e := range v { + if LosesInYAML(e) { + return true + } + } + } + return false +} diff --git a/openapi2/fuzz_test.go b/openapi2/fuzz_test.go new file mode 100644 index 000000000..764a961ce --- /dev/null +++ b/openapi2/fuzz_test.go @@ -0,0 +1,78 @@ +package openapi2 + +import ( + "encoding/json" + "testing" + + "github.com/oasdiff/yaml" + "github.com/stretchr/testify/require" + + "github.com/getkin/kin-openapi/internal/fuzzing" +) + +// maxFuzzInput bounds fuzzer inputs so the fuzzer spends its budget on +// decoding rather than on allocating huge documents. +const maxFuzzInput = 32 << 10 + +// A swagger document, JSON or YAML, loads back to itself from its own JSON and +// YAML forms. +func FuzzUnmarshalFromData(f *testing.F) { + for _, seed := range fuzzing.Testdata(f, "testdata") { + f.Add(seed) + } + // Read from openapi3, the one copy the fuzz workflow fetches. + for _, seed := range fuzzing.APIsGuru(f, "../openapi3/testdata", "swagger:") { + f.Add(seed) + } + f.Add([]byte(`swagger: "2.0" +info: {title: t, version: "1.0"} +x-date: 2020-06-11 +paths: + /a/{id}: + get: + parameters: + - &id {name: id, in: path, required: true, type: string} + responses: + 200: &ok {description: ok, schema: {type: integer, enum: [0x2A, 4_2]}} + 201: *ok + /b: + <<: {get: {responses: {default: {description: d}}}} +definitions: + A: + type: object + x-keys: {18_24: a, 1.5: b} + properties: {b: {$ref: '#/definitions/A'}} +`)) + + f.Fuzz(func(t *testing.T, data []byte) { + if len(data) > maxFuzzInput { + t.Skip() + } + + var doc T + if unmarshal(data, &doc) != nil { + return + } + once, err := json.Marshal(&doc) + require.NoError(t, err) + + var fromJSON T + require.NoError(t, unmarshal(once, &fromJSON), "json:\n%s", once) + twice, err := json.Marshal(&fromJSON) + require.NoError(t, err) + require.JSONEq(t, string(once), string(twice)) + + var generic any + require.NoError(t, json.Unmarshal(once, &generic)) + if fuzzing.LosesInYAML(generic) { + return + } + y, err := yaml.Marshal(&doc) + require.NoError(t, err) + var fromYAML T + require.NoError(t, unmarshal(y, &fromYAML), "yaml:\n%s", y) + thrice, err := json.Marshal(&fromYAML) + require.NoError(t, err) + require.JSONEq(t, string(once), string(thrice), "yaml:\n%s", y) + }) +} diff --git a/openapi2conv/fuzz_test.go b/openapi2conv/fuzz_test.go index 8443c7dd4..3d214d312 100644 --- a/openapi2conv/fuzz_test.go +++ b/openapi2conv/fuzz_test.go @@ -6,8 +6,10 @@ import ( "path/filepath" "testing" + "github.com/oasdiff/yaml" "github.com/stretchr/testify/require" + "github.com/getkin/kin-openapi/internal/fuzzing" "github.com/getkin/kin-openapi/openapi2" "github.com/getkin/kin-openapi/openapi2conv" "github.com/getkin/kin-openapi/openapi3" @@ -28,6 +30,13 @@ func FuzzToV3(f *testing.F) { f.Add(data) } } + // The corpus is YAML, which this target does not decode, so it goes in as + // JSON. It is read from openapi3, the one copy the fuzz workflow fetches. + for _, seed := range fuzzing.APIsGuru(f, "../openapi3/testdata", "swagger:") { + if data, err := yaml.YAMLToJSON(seed); err == nil && len(data) <= maxFuzzInput { + f.Add(data) + } + } f.Add([]byte(`{"swagger":"2.0","info":{"title":"t","version":"1"},"paths":{}}`)) f.Add([]byte(`{"swagger":"2.0","paths":{"/x/{id}":{"get":{"parameters":[{"name":"id","in":"path","type":"string","required":true}],"responses":{"200":{"description":"ok"}}}}}}`)) f.Add([]byte(`{"swagger":"2.0","definitions":{"A":{"type":"object","properties":{"b":{"$ref":"#/definitions/A"}}}},"paths":{}}`)) diff --git a/openapi3/fuzz_test.go b/openapi3/fuzz_test.go index 2e2923417..c87c875c7 100644 --- a/openapi3/fuzz_test.go +++ b/openapi3/fuzz_test.go @@ -3,12 +3,13 @@ package openapi3_test import ( "encoding/json" "net/url" - "os" - "path/filepath" + "reflect" + "strings" "testing" "github.com/stretchr/testify/require" + "github.com/getkin/kin-openapi/internal/fuzzing" "github.com/getkin/kin-openapi/openapi3" ) @@ -16,10 +17,6 @@ import ( // conversion logic rather than on allocating huge documents. const maxFuzzInput = 32 << 10 -// maxFuzzSeed keeps the seed corpus small enough that `go test ./...` still -// replays it on every run without noticeably slowing the suite down. -const maxFuzzSeed = 16 << 10 - func newFuzzLoader() *openapi3.Loader { loader := openapi3.NewLoader() loader.IsExternalRefsAllowed = true @@ -27,24 +24,24 @@ func newFuzzLoader() *openapi3.Loader { return loader } -func seedFromTestdata(f *testing.F, globs ...string) { +// seedFromTestdata adds the YAML-specific seeds and the specs under testdata, +// then those of the APIs-guru corpus when it has been downloaded. +func seedFromTestdata(f *testing.F) { f.Helper() - for _, glob := range globs { - paths, err := filepath.Glob(glob) - require.NoError(f, err) - for _, path := range paths { - data, err := os.ReadFile(path) - require.NoError(f, err) - if len(data) <= maxFuzzSeed { - f.Add(data) - } - } + for _, seed := range openapi3.YAMLFuzzSeeds { + f.Add([]byte(seed)) + } + for _, seed := range fuzzing.Testdata(f, "testdata") { + f.Add(seed) + } + for _, seed := range fuzzing.APIsGuru(f, "testdata", "openapi:") { + f.Add(seed) } } // enc(dec) == enc(dec(enc(dec))) func FuzzLoadFromData(f *testing.F) { - seedFromTestdata(f, "testdata/*.yml", "testdata/*.yaml", "testdata/*.json") + seedFromTestdata(f) f.Fuzz(func(t *testing.T, data []byte) { if len(data) > maxFuzzInput { @@ -80,6 +77,114 @@ func FuzzLoadFromData(f *testing.F) { }) } +// Asking for origins changes nothing about the document, and every recorded +// position lies inside the input. +func FuzzLoadWithOrigins(f *testing.F) { + seedFromTestdata(f) + + f.Fuzz(func(t *testing.T, data []byte) { + if len(data) > maxFuzzInput { + t.Skip() + } + + plain, plainErr := newFuzzLoader().LoadFromData(data) + + loader := newFuzzLoader() + loader.IncludeOrigin = true + withOrigins, err := loader.LoadFromData(data) + require.Equal(t, plainErr == nil, err == nil, "without origins: %v\nwith origins: %v", plainErr, err) + if err != nil { + return + } + + a, err := plain.MarshalJSON() + require.NoError(t, err) + b, err := withOrigins.MarshalJSON() + require.NoError(t, err) + require.JSONEq(t, string(a), string(b)) + + lines := yamlLines(data) + checkLocation := func(what string, loc openapi3.Location) { + if loc.File != "" || loc.Line == 0 { + return // another document, or not recorded + } + require.GreaterOrEqual(t, loc.Line, 1, what) + require.LessOrEqual(t, loc.Line, lines, what) + require.GreaterOrEqual(t, loc.Column, 1, what) + if loc.EndLine != 0 { + require.GreaterOrEqual(t, loc.EndLine, loc.Line, "%s: %+v", what, loc) + require.LessOrEqual(t, loc.EndLine, lines, "%s: %+v", what, loc) + require.GreaterOrEqual(t, loc.EndColumn, 1, "%s: %+v", what, loc) + } + } + walkOrigins(withOrigins, func(o *openapi3.Origin) { + if o.Key != nil { + checkLocation("key", *o.Key) + } + for _, loc := range o.Fields { + checkLocation("field "+loc.Name, loc) + } + for name, locs := range o.Sequences { + for _, loc := range locs { + checkLocation("sequence "+name, loc) + } + } + }) + }) +} + +// yamlLines counts lines the way the YAML parser numbers them, which breaks +// on CR, LF, CRLF, NEL, LS and PS alike. +func yamlLines(data []byte) int { + s := strings.ReplaceAll(string(data), "\r\n", "\n") + return 1 + strings.Count(s, "\n") + strings.Count(s, "\r") + + strings.Count(s, "\u0085") + strings.Count(s, "\u2028") + strings.Count(s, "\u2029") +} + +var originType = reflect.TypeFor[openapi3.Origin]() + +// walkOrigins calls fn on every *Origin reachable from v, unexported fields +// included since that is where Paths and Responses keep their entries. A +// resolved document is a graph, so each pointer is visited once. +func walkOrigins(v any, fn func(*openapi3.Origin)) { + seen := make(map[uintptr]struct{}) + var walk func(reflect.Value) + walk = func(v reflect.Value) { + switch v.Kind() { + case reflect.Pointer: + if v.IsNil() { + return + } + if _, ok := seen[v.Pointer()]; ok { + return + } + seen[v.Pointer()] = struct{}{} + if v.Type().Elem() == originType { + fn((*openapi3.Origin)(v.UnsafePointer())) + return + } + walk(v.Elem()) + case reflect.Interface: + if !v.IsNil() { + walk(v.Elem()) + } + case reflect.Struct: + for i := range v.NumField() { + walk(v.Field(i)) + } + case reflect.Slice, reflect.Array: + for i := range v.Len() { + walk(v.Index(i)) + } + case reflect.Map: + for it := v.MapRange(); it.Next(); { + walk(it.Value()) + } + } + } + walk(reflect.ValueOf(v)) +} + // No crash when validating values against schemas func FuzzSchemaVisitJSON(f *testing.F) { f.Add([]byte(`{"type":"string","minLength":1,"pattern":"^a+$"}`), []byte(`"aaa"`)) diff --git a/openapi3/yaml_fuzz_test.go b/openapi3/yaml_fuzz_test.go new file mode 100644 index 000000000..d3c5f5a2f --- /dev/null +++ b/openapi3/yaml_fuzz_test.go @@ -0,0 +1,218 @@ +package openapi3 + +import ( + "encoding/json" + "testing" + + "github.com/oasdiff/yaml" + "github.com/stretchr/testify/require" + + "github.com/getkin/kin-openapi/internal/fuzzing" +) + +// maxYAMLFuzzInput bounds fuzzer inputs, see maxFuzzInput. +const maxYAMLFuzzInput = 32 << 10 + +// yamlFuzzSeeds exercise what only the YAML decode path sees: anchors and +// aliases, merge keys, tags, block scalars, non-string keys and YAML 1.1 +// implicit resolution. Shared by every fuzz target that loads documents. +var yamlFuzzSeeds = []string{ + // Anchors and aliases, on a schema, a parameter and a $ref. + `openapi: 3.0.0 +info: {title: t, version: "1"} +paths: + /a/{id}: + parameters: + - &id {name: id, in: path, required: true, schema: {type: string}} + get: + parameters: [*id] + responses: + 200: &ok + description: ok + content: + application/json: + schema: &s {type: object, properties: {a: {type: integer}}} + 201: *ok +components: + schemas: + A: *s + B: {$ref: &r '#/components/schemas/A'} + C: {$ref: *r} +`, + // Merge keys: in a path item, in Paths itself, from a sequence of sources. + `openapi: 3.0.0 +info: {title: t, version: "1"} +x-base: &base + description: base + responses: {"200": {description: ok}} +x-more: &more + summary: more + description: overridden +paths: + /m: + get: + <<: [*base, *more] + operationId: m + <<: {/n: {get: {responses: {default: {description: d}}}}} +components: + schemas: + S: + <<: {type: object, required: [a]} + properties: {a: {type: string}} +`, + // Block scalars, including one ending the block, and comments. + `openapi: 3.0.0 +info: + title: t + version: "1" + description: | + line one + + line three +paths: + /b: + get: + responses: + "200": + description: >- + folded + text # not a comment + # trailing comment +`, + // YAML 1.1 implicit resolution: timestamps, hex, underscores, bools, + // non-string keys and a tagged scalar. + `openapi: 3.0.0 +info: {title: t, version: 1.0} +paths: {} +components: + schemas: + T: + type: string + format: date-time + example: 2020-06-11T16:32:50-03:00 + x-ts: !!timestamp 2001-01-01 + x-keys: {18_24: a, 0x2A: b, 1.5: c, true: d} + I: + type: integer + enum: [0x2A, 4_2, 052, 42] + example: 42 + default: 0x2A + nullable: yes + maximum: 1e3 +`, + // OpenAPI 3.1: boolean schemas, type lists, exclusive bounds as numbers, + // explicitly null responses, webhooks. + `openapi: 3.1.0 +info: {title: t, version: "1"} +paths: + /w: + get: + responses: ~ +webhooks: + hook: + post: + requestBody: + content: + application/json: + schema: + type: [object, "null"] + additionalProperties: false + unevaluatedProperties: true + properties: + n: {type: number, exclusiveMinimum: 0, exclusiveMaximum: 10} + any: true + none: false +`, + // Flow style, CRLF line endings, a document marker. + "---\r\n{openapi: 3.0.0, info: {title: t, version: \"1\"},\r\n paths: {/f: {get: {responses: {\"200\": {description: ok}}}}}}\r\n", + // $ref siblings and extensions on maplike collections. + `openapi: 3.1.0 +info: {title: t, version: "1"} +paths: + x-p: 1 + /r: + $ref: '#/components/pathItems/R' + summary: s +components: + pathItems: + R: + get: + responses: + x-r: 2 + "200": {$ref: '#/components/responses/OK', description: d} + callbacks: + cb: + x-c: 3 + '{$request.body#/u}': {post: {responses: {"200": {description: ok}}}} + responses: + OK: {description: ok} +`, +} + +// decodeYAML decodes data the way unmarshal does once JSON has refused it. +func decodeYAML(data []byte, v any) error { + _, err := yaml.Unmarshal(data, v, yaml.DecodeOpts{DisableTimestamps: true}) + return err +} + +func requireSameDoc(t *testing.T, expected, actual *T, msgAndArgs ...any) { + t.Helper() + e, err := expected.MarshalJSON() + require.NoError(t, err) + a, err := actual.MarshalJSON() + require.NoError(t, err) + require.JSONEq(t, string(e), string(a), msgAndArgs...) +} + +// The YAML decode path must agree with the JSON one: +// - a JSON document both paths accept decodes to the same thing, and +// - any document, re-encoded as block YAML, decodes back to itself. +func FuzzYAMLMatchesJSON(f *testing.F) { + for _, seed := range yamlFuzzSeeds { + f.Add([]byte(seed)) + } + for _, seed := range fuzzing.Testdata(f, "testdata") { + f.Add(seed) + } + for _, seed := range fuzzing.APIsGuru(f, "testdata", "openapi:") { + f.Add(seed) + } + f.Add([]byte(`{"openapi":"3.0.0","info":{"title":"t","version":"1"},"paths":{"/a":{"get":{"responses":{"200":{"description":"ok"}}}}}}`)) + f.Add([]byte(`{"openapi":"3.0.0","paths":{"x-a":{"<<":1},"/x":{}},"components":{"schemas":{"<<":{"type":"string"}}}}`)) + f.Add([]byte(`{"openapi":"3.1.0","components":{"schemas":{"a":{"enum":[1,1.5,"1",true,null],"example":12345678901234567890,"x-e":{"1":[{}]}}}}}`)) + f.Add([]byte(`{"openapi":"3.0.0","info":{"title":"é\/\t","version":"2020-01-01"},"paths":{}}`)) + + f.Fuzz(func(t *testing.T, data []byte) { + if len(data) > maxYAMLFuzzInput { + t.Skip() + } + + if json.Valid(data) { + var viaJSON, viaYAML T + if unmarshalJSON(data, &viaJSON) == nil && decodeYAML(data, &viaYAML) == nil { + requireSameDoc(t, &viaJSON, &viaYAML, "data:\n%s", data) + } + } + + var doc T + if decodeYAML(data, &doc) != nil { + return + } + j, err := doc.MarshalJSON() + require.NoError(t, err) + var generic any + require.NoError(t, json.Unmarshal(j, &generic)) + if fuzzing.LosesInYAML(generic) { + return + } + y, err := yaml.JSONToYAML(j) + require.NoError(t, err) + + var back T + require.NoError(t, decodeYAML(y, &back), "yaml:\n%s", y) + requireSameDoc(t, &doc, &back, "yaml:\n%s\ndata:\n%s", y, data) + }) +} + +// YAMLFuzzSeeds exposes yamlFuzzSeeds to the external test package. +var YAMLFuzzSeeds = yamlFuzzSeeds diff --git a/openapi3filter/fuzz_test.go b/openapi3filter/fuzz_test.go index 4c728b114..5f257dde8 100644 --- a/openapi3filter/fuzz_test.go +++ b/openapi3filter/fuzz_test.go @@ -4,13 +4,12 @@ import ( "bytes" "net/http" "net/url" - "os" - "path/filepath" "strings" "testing" "github.com/stretchr/testify/require" + "github.com/getkin/kin-openapi/internal/fuzzing" "github.com/getkin/kin-openapi/openapi3" "github.com/getkin/kin-openapi/openapi3filter" "github.com/getkin/kin-openapi/routers" @@ -29,14 +28,10 @@ func newFuzzLoader() *openapi3.Loader { } func FuzzValidateRequest(f *testing.F) { - paths, err := filepath.Glob("../openapi3/testdata/*.yml") - require.NoError(f, err) - for _, path := range paths { - data, err := os.ReadFile(path) - require.NoError(f, err) - if len(data) <= 16<<10 { - f.Add(data, "GET", "/", "application/json", []byte(`{}`)) - } + seeds := fuzzing.Testdata(f, "../openapi3/testdata", "testdata") + seeds = append(seeds, fuzzing.APIsGuru(f, "../openapi3/testdata", "openapi:")...) + for _, seed := range seeds { + f.Add(seed, "GET", "/", "application/json", []byte(`{}`)) } const spec = ` From 8424c1606adf2b5b044b45787606e08a8d1ba825 Mon Sep 17 00:00:00 2001 From: Yi-111-a Date: Thu, 22 Oct 2026 12:47:08 +0800 Subject: [PATCH 15/78] openapi3filter: decode query, path, header and cookie params with typeless const/enum schemas Closes #1367 --- openapi3filter/issue1367_test.go | 137 +++++++++++++++++++++++++++++ openapi3filter/req_resp_decoder.go | 59 ++++++++++++- 2 files changed, 195 insertions(+), 1 deletion(-) create mode 100644 openapi3filter/issue1367_test.go diff --git a/openapi3filter/issue1367_test.go b/openapi3filter/issue1367_test.go new file mode 100644 index 000000000..e30ba877e --- /dev/null +++ b/openapi3filter/issue1367_test.go @@ -0,0 +1,137 @@ +package openapi3filter + +import ( + "net/http" + "testing" + + "github.com/stretchr/testify/require" +) + +func TestIssue1367TypelessConstAndEnumPrimitives(t *testing.T) { + t.Parallel() + + const spec = ` +openapi: 3.1.0 +info: + title: repro + version: 1.0.0 +paths: + /items: + get: + parameters: + - name: kind + in: query + required: true + schema: + const: widget + - name: withenum + in: query + schema: + enum: [widget] + responses: + '200': + description: ok +` + + testcases := []struct { + url string + fail bool + }{{ + url: "?kind=widget", + }, { + url: "?kind=widget&withenum=widget", + }, { + url: "?kind=widget&withenum=gadget", + fail: true, + }, { + url: "?kind=gadget", + fail: true, + }, { + url: "?kind=widget&withenum=", + fail: true, + }} + for _, tc := range testcases { + t.Run(tc.url, func(t *testing.T) { + req, err := http.NewRequest(http.MethodGet, "/items"+tc.url, nil) + require.NoError(t, err) + + router := setupTestRouter(t, spec) + require.NoError(t, err) + route, pathParams, err := router.FindRoute(req) + require.NoError(t, err) + + err = ValidateRequest(t.Context(), &RequestValidationInput{ + Request: req, + PathParams: pathParams, + Route: route, + }) + if tc.fail { + require.Error(t, err) + } else { + require.NoError(t, err) + } + }) + } +} + +func TestIssue1367TypelessConstAndEnumNumberAndBoolean(t *testing.T) { + t.Parallel() + + const spec = ` +openapi: 3.1.0 +info: + title: repro + version: 1.0.0 +paths: + /picked: + get: + parameters: + - name: rank + in: query + required: true + schema: + enum: [1, 2, 3] + - name: flag + in: query + schema: + const: true + responses: + '200': + description: ok +` + + testcases := []struct { + url string + fail bool + }{{ + url: "?rank=2&flag=true", + }, { + url: "?rank=2&flag=false", + fail: true, + }, { + url: "?rank=9&flag=true", + fail: true, + }} + for _, tc := range testcases { + t.Run(tc.url, func(t *testing.T) { + req, err := http.NewRequest(http.MethodGet, "/picked"+tc.url, nil) + require.NoError(t, err) + + router := setupTestRouter(t, spec) + require.NoError(t, err) + route, pathParams, err := router.FindRoute(req) + require.NoError(t, err) + + err = ValidateRequest(t.Context(), &RequestValidationInput{ + Request: req, + PathParams: pathParams, + Route: route, + }) + if tc.fail { + require.Error(t, err) + } else { + require.NoError(t, err) + } + }) + } +} diff --git a/openapi3filter/req_resp_decoder.go b/openapi3filter/req_resp_decoder.go index d734c6c4d..51b2ff050 100644 --- a/openapi3filter/req_resp_decoder.go +++ b/openapi3filter/req_resp_decoder.go @@ -338,6 +338,14 @@ func decodeValueGuarded(dec valueDecoder, param string, sm *openapi3.Serializati return nil, found, errors.New("not implemented: decoding 'not'") } + if schema.Value.Type == nil && (schema.Value.Const != nil || len(schema.Value.Enum) > 0) { + // A schema without `type` is valid in OpenAPI 3.0 and 3.1; with + // only `const`/`enum` the schema types the value on its own (see + // #1367). Parameter values are strings, so decode as a primitive + // and let schema validation apply the constrained values. + return dec.DecodePrimitive(param, sm, schema) + } + if schema.Value.Type != nil { var decodeFn func(param string, sm *openapi3.SerializationMethod, schema *openapi3.SchemaRef) (any, bool, error) switch { @@ -1232,7 +1240,17 @@ func parseArray(raw []string, schemaRef *openapi3.SchemaRef) ([]any, error) { // that is specified by a schema. The function returns nil when the source string is empty and the type is not "string". // The function panics when a schema has a non-primitive type. func parsePrimitive(raw string, schema *openapi3.SchemaRef) (v any, err error) { - for _, typ := range schema.Value.Type.Slice() { + typs := schema.Value.Type.Slice() + constrainedTypeless := len(typs) == 0 && (schema.Value.Const != nil || len(schema.Value.Enum) > 0) + if constrainedTypeless { + // A typeless schema constrained by `const`/`enum` types the value + // on its own (the raw string must still be parsed so that a + // numeric/boolean constant is compared to the same Go type). + if t := constraintPrimitiveType(schema); t != "" { + typs = []string{t} + } + } + for _, typ := range typs { if raw == "" && typ != openapi3.TypeString { return nil, nil } @@ -1240,9 +1258,48 @@ func parsePrimitive(raw string, schema *openapi3.SchemaRef) (v any, err error) { return } } + if constrainedTypeless { + // Values of mixed kinds cannot be parsed to a single primitive + // type; keep the raw string and let schema validation decide. + return raw, nil + } return } +// constraintPrimitiveType returns the primitive type implied by the +// `const`/`enum` values of a typeless schema, or "" when that does not +// resolve to a single primitive type (mixed kinds, nested values). +func constraintPrimitiveType(schema *openapi3.SchemaRef) string { + var values []any + if schema.Value.Const != nil { + values = append(values, schema.Value.Const) + } + values = append(values, schema.Value.Enum...) + if len(values) == 0 { + return "" + } + typ := "" + for _, value := range values { + var t string + switch value.(type) { + case bool: + t = openapi3.TypeBoolean + case float64, float32, int, int32, int64: + t = openapi3.TypeNumber + case string: + t = openapi3.TypeString + default: + return "" + } + if typ == "" { + typ = t + } else if typ != t { + return "" + } + } + return typ +} + func parsePrimitiveCase(raw string, schema *openapi3.SchemaRef, typ string) (any, error) { switch typ { case "integer": From 44f4af5890137c52cf0efd75e0b574f166b35007 Mon Sep 17 00:00:00 2001 From: Yi-111-a Date: Thu, 22 Oct 2026 22:57:04 +0800 Subject: [PATCH 16/78] openapi3filter: typeless const/enum decode with a slice of types, external _test pkg --- openapi3filter/issue1367_test.go | 131 +++++++++++++++++++++-------- openapi3filter/req_resp_decoder.go | 64 ++++++++------ 2 files changed, 132 insertions(+), 63 deletions(-) diff --git a/openapi3filter/issue1367_test.go b/openapi3filter/issue1367_test.go index e30ba877e..ba618a087 100644 --- a/openapi3filter/issue1367_test.go +++ b/openapi3filter/issue1367_test.go @@ -1,12 +1,54 @@ -package openapi3filter +package openapi3filter_test import ( "net/http" "testing" "github.com/stretchr/testify/require" + + "github.com/getkin/kin-openapi/openapi3" + "github.com/getkin/kin-openapi/openapi3filter" + "github.com/getkin/kin-openapi/routers" + "github.com/getkin/kin-openapi/routers/gorillamux" ) +func setupTestRouter(t *testing.T, spec string) routers.Router { + t.Helper() + loader := openapi3.NewLoader() + doc, err := loader.LoadFromData([]byte(spec)) + require.NoError(t, err) + + err = doc.Validate(loader.Context) + require.NoError(t, err) + + router, err := gorillamux.NewRouter(doc) + require.NoError(t, err) + + return router +} + +func testIssue1367Request(t *testing.T, spec, url string, fail bool) { + t.Helper() + + req, err := http.NewRequest(http.MethodGet, url, nil) + require.NoError(t, err) + + router := setupTestRouter(t, spec) + route, pathParams, err := router.FindRoute(req) + require.NoError(t, err) + + err = openapi3filter.ValidateRequest(t.Context(), &openapi3filter.RequestValidationInput{ + Request: req, + PathParams: pathParams, + Route: route, + }) + if fail { + require.Error(t, err) + } else { + require.NoError(t, err) + } +} + func TestIssue1367TypelessConstAndEnumPrimitives(t *testing.T) { t.Parallel() @@ -32,6 +74,7 @@ paths: '200': description: ok ` + const rootURL = "http://example.com/items" testcases := []struct { url string @@ -52,24 +95,7 @@ paths: }} for _, tc := range testcases { t.Run(tc.url, func(t *testing.T) { - req, err := http.NewRequest(http.MethodGet, "/items"+tc.url, nil) - require.NoError(t, err) - - router := setupTestRouter(t, spec) - require.NoError(t, err) - route, pathParams, err := router.FindRoute(req) - require.NoError(t, err) - - err = ValidateRequest(t.Context(), &RequestValidationInput{ - Request: req, - PathParams: pathParams, - Route: route, - }) - if tc.fail { - require.Error(t, err) - } else { - require.NoError(t, err) - } + testIssue1367Request(t, spec, rootURL+tc.url, tc.fail) }) } } @@ -99,6 +125,7 @@ paths: '200': description: ok ` + const rootURL = "http://example.com/picked" testcases := []struct { url string @@ -114,24 +141,54 @@ paths: }} for _, tc := range testcases { t.Run(tc.url, func(t *testing.T) { - req, err := http.NewRequest(http.MethodGet, "/picked"+tc.url, nil) - require.NoError(t, err) - - router := setupTestRouter(t, spec) - require.NoError(t, err) - route, pathParams, err := router.FindRoute(req) - require.NoError(t, err) - - err = ValidateRequest(t.Context(), &RequestValidationInput{ - Request: req, - PathParams: pathParams, - Route: route, - }) - if tc.fail { - require.Error(t, err) - } else { - require.NoError(t, err) - } + testIssue1367Request(t, spec, rootURL+tc.url, tc.fail) + }) + } +} + +// The accept set of a typeless `enum`/`const` may mix kinds, so the +// decoder works with a slice of types rather than a single one; a +// numeric-looking raw string still decodes to the enum's number even +// when a string member exists, and an array member can never be +// produced from a parameter value. +func TestIssue1367TypelessEnumMixedKinds(t *testing.T) { + t.Parallel() + + const spec = ` +openapi: 3.1.0 +info: + title: repro + version: 1.0.0 +paths: + /mid: + get: + parameters: + - name: mid + in: query + required: true + schema: + enum: [42, "42", [42]] + responses: + '200': + description: ok +` + const rootURL = "http://example.com/mid" + + testcases := []struct { + url string + fail bool + }{{ + url: "?mid=42", + }, { + url: "?mid=gadget", + fail: true, + }, { + url: "?mid=%5B42%5D", + fail: true, + }} + for _, tc := range testcases { + t.Run(tc.url, func(t *testing.T) { + testIssue1367Request(t, spec, rootURL+tc.url, tc.fail) }) } } diff --git a/openapi3filter/req_resp_decoder.go b/openapi3filter/req_resp_decoder.go index 51b2ff050..01832db9b 100644 --- a/openapi3filter/req_resp_decoder.go +++ b/openapi3filter/req_resp_decoder.go @@ -1245,10 +1245,10 @@ func parsePrimitive(raw string, schema *openapi3.SchemaRef) (v any, err error) { if constrainedTypeless { // A typeless schema constrained by `const`/`enum` types the value // on its own (the raw string must still be parsed so that a - // numeric/boolean constant is compared to the same Go type). - if t := constraintPrimitiveType(schema); t != "" { - typs = []string{t} - } + // numeric/boolean constant is compared to the same Go type, see + // #1367). Its accept set may mix kinds, so decode with a slice of + // types, one per present member kind. + typs = constraintTypes(schema) } for _, typ := range typs { if raw == "" && typ != openapi3.TypeString { @@ -1259,45 +1259,57 @@ func parsePrimitive(raw string, schema *openapi3.SchemaRef) (v any, err error) { } } if constrainedTypeless { - // Values of mixed kinds cannot be parsed to a single primitive - // type; keep the raw string and let schema validation decide. + // No member kind parses a raw string (only array/object members + // are present); keep the raw string and let schema validation + // decide. return raw, nil } return } -// constraintPrimitiveType returns the primitive type implied by the -// `const`/`enum` values of a typeless schema, or "" when that does not -// resolve to a single primitive type (mixed kinds, nested values). -func constraintPrimitiveType(schema *openapi3.SchemaRef) string { +// constraintTypes returns the types implied by the `const`/`enum` values +// of a typeless schema, in a fixed priority order (boolean before number +// before string, so that a numeric raw string is not shadowed by the +// string case, and string last, so that `"42"` in +// `enum: [42, "42", [42]]` does not hide `42`), or an empty slice when +// the schema has no such values. +func constraintTypes(schema *openapi3.SchemaRef) []string { var values []any if schema.Value.Const != nil { values = append(values, schema.Value.Const) } values = append(values, schema.Value.Enum...) if len(values) == 0 { - return "" + return nil } - typ := "" + present := make(map[string]bool, len(values)) for _, value := range values { - var t string switch value.(type) { case bool: - t = openapi3.TypeBoolean + present[openapi3.TypeBoolean] = true case float64, float32, int, int32, int64: - t = openapi3.TypeNumber + present[openapi3.TypeNumber] = true case string: - t = openapi3.TypeString - default: - return "" - } - if typ == "" { - typ = t - } else if typ != t { - return "" - } - } - return typ + present[openapi3.TypeString] = true + case []any: + present[openapi3.TypeArray] = true + case map[string]any: + present[openapi3.TypeObject] = true + } + } + typs := make([]string, 0, len(present)) + for _, typ := range []string{ + openapi3.TypeBoolean, + openapi3.TypeNumber, + openapi3.TypeString, + openapi3.TypeArray, + openapi3.TypeObject, + } { + if present[typ] { + typs = append(typs, typ) + } + } + return typs } func parsePrimitiveCase(raw string, schema *openapi3.SchemaRef, typ string) (any, error) { From 0d96dffb29ba3014eb68dec5de06d7e3c0e7dc85 Mon Sep 17 00:00:00 2001 From: Yi-111-a Date: Mon, 26 Oct 2026 12:47:50 +0800 Subject: [PATCH 17/78] openapi3filter: simplify typeless const/enum type derivation, name subtests and assert errors --- openapi3filter/issue1367_test.go | 86 +++++++++++++++++------------- openapi3filter/req_resp_decoder.go | 70 ++++++++++-------------- 2 files changed, 76 insertions(+), 80 deletions(-) diff --git a/openapi3filter/issue1367_test.go b/openapi3filter/issue1367_test.go index ba618a087..14ad5d6c6 100644 --- a/openapi3filter/issue1367_test.go +++ b/openapi3filter/issue1367_test.go @@ -27,7 +27,7 @@ func setupTestRouter(t *testing.T, spec string) routers.Router { return router } -func testIssue1367Request(t *testing.T, spec, url string, fail bool) { +func testIssue1367Request(t *testing.T, spec, url, errContains string) { t.Helper() req, err := http.NewRequest(http.MethodGet, url, nil) @@ -42,8 +42,8 @@ func testIssue1367Request(t *testing.T, spec, url string, fail bool) { PathParams: pathParams, Route: route, }) - if fail { - require.Error(t, err) + if errContains != "" { + require.ErrorContains(t, err, errContains) } else { require.NoError(t, err) } @@ -77,25 +77,31 @@ paths: const rootURL = "http://example.com/items" testcases := []struct { - url string - fail bool + name string + url string + errContains string }{{ - url: "?kind=widget", + name: "const matches", + url: "?kind=widget", }, { - url: "?kind=widget&withenum=widget", + name: "const and enum match", + url: "?kind=widget&withenum=widget", }, { - url: "?kind=widget&withenum=gadget", - fail: true, + name: "enum mismatch", + url: "?kind=widget&withenum=gadget", + errContains: "parameter \"withenum\" in query has an error: validation failed due to: at '': value must be 'widget'", }, { - url: "?kind=gadget", - fail: true, + name: "const mismatch", + url: "?kind=gadget", + errContains: "parameter \"kind\" in query has an error: validation failed due to: at '': value must be 'widget'", }, { - url: "?kind=widget&withenum=", - fail: true, + name: "empty enum value", + url: "?kind=widget&withenum=", + errContains: "parameter \"withenum\" in query has an error: validation failed due to: at '': value must be 'widget'", }} for _, tc := range testcases { - t.Run(tc.url, func(t *testing.T) { - testIssue1367Request(t, spec, rootURL+tc.url, tc.fail) + t.Run(tc.name, func(t *testing.T) { + testIssue1367Request(t, spec, rootURL+tc.url, tc.errContains) }) } } @@ -128,29 +134,29 @@ paths: const rootURL = "http://example.com/picked" testcases := []struct { - url string - fail bool + name string + url string + errContains string }{{ - url: "?rank=2&flag=true", + name: "number enum and boolean const match", + url: "?rank=2&flag=true", }, { - url: "?rank=2&flag=false", - fail: true, + name: "boolean const mismatch", + url: "?rank=2&flag=false", + errContains: "parameter \"flag\" in query has an error: validation failed due to: at '': value must be true", }, { - url: "?rank=9&flag=true", - fail: true, + name: "number enum mismatch", + url: "?rank=9&flag=true", + errContains: "parameter \"rank\" in query has an error: validation failed due to: at '': value must be one of 1, 2, 3", }} for _, tc := range testcases { - t.Run(tc.url, func(t *testing.T) { - testIssue1367Request(t, spec, rootURL+tc.url, tc.fail) + t.Run(tc.name, func(t *testing.T) { + testIssue1367Request(t, spec, rootURL+tc.url, tc.errContains) }) } } -// The accept set of a typeless `enum`/`const` may mix kinds, so the -// decoder works with a slice of types rather than a single one; a -// numeric-looking raw string still decodes to the enum's number even -// when a string member exists, and an array member can never be -// produced from a parameter value. +// A typeless enum may mix kinds; a numeric string still decodes to the number. func TestIssue1367TypelessEnumMixedKinds(t *testing.T) { t.Parallel() @@ -175,20 +181,24 @@ paths: const rootURL = "http://example.com/mid" testcases := []struct { - url string - fail bool + name string + url string + errContains string }{{ - url: "?mid=42", + name: "numeric string decodes to number", + url: "?mid=42", }, { - url: "?mid=gadget", - fail: true, + name: "no member matches", + url: "?mid=gadget", + errContains: "parameter \"mid\" in query has an error: validation failed due to: at '': 'enum' failed", }, { - url: "?mid=%5B42%5D", - fail: true, + name: "array member never matches", + url: "?mid=%5B42%5D", + errContains: "parameter \"mid\" in query has an error: validation failed due to: at '': 'enum' failed", }} for _, tc := range testcases { - t.Run(tc.url, func(t *testing.T) { - testIssue1367Request(t, spec, rootURL+tc.url, tc.fail) + t.Run(tc.name, func(t *testing.T) { + testIssue1367Request(t, spec, rootURL+tc.url, tc.errContains) }) } } diff --git a/openapi3filter/req_resp_decoder.go b/openapi3filter/req_resp_decoder.go index 01832db9b..8e0ad765b 100644 --- a/openapi3filter/req_resp_decoder.go +++ b/openapi3filter/req_resp_decoder.go @@ -339,10 +339,7 @@ func decodeValueGuarded(dec valueDecoder, param string, sm *openapi3.Serializati } if schema.Value.Type == nil && (schema.Value.Const != nil || len(schema.Value.Enum) > 0) { - // A schema without `type` is valid in OpenAPI 3.0 and 3.1; with - // only `const`/`enum` the schema types the value on its own (see - // #1367). Parameter values are strings, so decode as a primitive - // and let schema validation apply the constrained values. + // Typeless const/enum schema (#1367): decode as a primitive. return dec.DecodePrimitive(param, sm, schema) } @@ -1243,11 +1240,7 @@ func parsePrimitive(raw string, schema *openapi3.SchemaRef) (v any, err error) { typs := schema.Value.Type.Slice() constrainedTypeless := len(typs) == 0 && (schema.Value.Const != nil || len(schema.Value.Enum) > 0) if constrainedTypeless { - // A typeless schema constrained by `const`/`enum` types the value - // on its own (the raw string must still be parsed so that a - // numeric/boolean constant is compared to the same Go type, see - // #1367). Its accept set may mix kinds, so decode with a slice of - // types, one per present member kind. + // No type: derive the candidate types from the const/enum values (#1367). typs = constraintTypes(schema) } for _, typ := range typs { @@ -1259,45 +1252,19 @@ func parsePrimitive(raw string, schema *openapi3.SchemaRef) (v any, err error) { } } if constrainedTypeless { - // No member kind parses a raw string (only array/object members - // are present); keep the raw string and let schema validation - // decide. return raw, nil } return } -// constraintTypes returns the types implied by the `const`/`enum` values -// of a typeless schema, in a fixed priority order (boolean before number -// before string, so that a numeric raw string is not shadowed by the -// string case, and string last, so that `"42"` in -// `enum: [42, "42", [42]]` does not hide `42`), or an empty slice when -// the schema has no such values. +// constraintTypes returns the types of the const/enum values of a schema, +// with boolean and number before string so that "42" decodes to 42. func constraintTypes(schema *openapi3.SchemaRef) []string { - var values []any + values := schema.Value.Enum if schema.Value.Const != nil { - values = append(values, schema.Value.Const) + values = append([]any{schema.Value.Const}, values...) } - values = append(values, schema.Value.Enum...) - if len(values) == 0 { - return nil - } - present := make(map[string]bool, len(values)) - for _, value := range values { - switch value.(type) { - case bool: - present[openapi3.TypeBoolean] = true - case float64, float32, int, int32, int64: - present[openapi3.TypeNumber] = true - case string: - present[openapi3.TypeString] = true - case []any: - present[openapi3.TypeArray] = true - case map[string]any: - present[openapi3.TypeObject] = true - } - } - typs := make([]string, 0, len(present)) + var typs []string for _, typ := range []string{ openapi3.TypeBoolean, openapi3.TypeNumber, @@ -1305,13 +1272,32 @@ func constraintTypes(schema *openapi3.SchemaRef) []string { openapi3.TypeArray, openapi3.TypeObject, } { - if present[typ] { - typs = append(typs, typ) + for _, value := range values { + if valueType(value) == typ { + typs = append(typs, typ) + break + } } } return typs } +func valueType(value any) string { + switch value.(type) { + case bool: + return openapi3.TypeBoolean + case float32, float64, int, int8, int16, int32, int64, uint, uint8, uint16, uint32, uint64, json.Number: + return openapi3.TypeNumber + case string: + return openapi3.TypeString + case []any: + return openapi3.TypeArray + case map[string]any: + return openapi3.TypeObject + } + return "" +} + func parsePrimitiveCase(raw string, schema *openapi3.SchemaRef, typ string) (any, error) { switch typ { case "integer": From b8b4f18c653391c235f5155a6bbc8e9fa98c046e Mon Sep 17 00:00:00 2001 From: Yi-111-a <153097222+Yi-111-a@users.noreply.github.com> Date: Mon, 26 Oct 2026 19:01:44 +0800 Subject: [PATCH 18/78] openapi3filter: derive typeless const/enum candidate types in O(values) --- openapi3filter/req_resp_decoder.go | 70 ++++++++++++++++-------------- 1 file changed, 37 insertions(+), 33 deletions(-) diff --git a/openapi3filter/req_resp_decoder.go b/openapi3filter/req_resp_decoder.go index 8e0ad765b..0cbb99b4b 100644 --- a/openapi3filter/req_resp_decoder.go +++ b/openapi3filter/req_resp_decoder.go @@ -1259,45 +1259,49 @@ func parsePrimitive(raw string, schema *openapi3.SchemaRef) (v any, err error) { // constraintTypes returns the types of the const/enum values of a schema, // with boolean and number before string so that "42" decodes to 42. +// It makes a single pass over the values, then keeps the seen types only, +// reducing the worst case from O(5 x values) hash lookups to O(values). func constraintTypes(schema *openapi3.SchemaRef) []string { - values := schema.Value.Enum + seen := make(map[string]struct{}, 5) + consider := func(value any) { + switch value.(type) { + case bool: + seen[openapi3.TypeBoolean] = struct{}{} + case float32, float64, int, int8, int16, int32, int64, uint, uint8, uint16, uint32, uint64, json.Number: + seen[openapi3.TypeNumber] = struct{}{} + case string: + seen[openapi3.TypeString] = struct{}{} + case []any: + seen[openapi3.TypeArray] = struct{}{} + case map[string]any: + seen[openapi3.TypeObject] = struct{}{} + } + } + for _, value := range schema.Value.Enum { + consider(value) + } if schema.Value.Const != nil { - values = append([]any{schema.Value.Const}, values...) - } - var typs []string - for _, typ := range []string{ - openapi3.TypeBoolean, - openapi3.TypeNumber, - openapi3.TypeString, - openapi3.TypeArray, - openapi3.TypeObject, - } { - for _, value := range values { - if valueType(value) == typ { - typs = append(typs, typ) - break - } - } + consider(schema.Value.Const) + } + typs := make([]string, 0, 5) + if _, ok := seen[openapi3.TypeBoolean]; ok { + typs = append(typs, openapi3.TypeBoolean) + } + if _, ok := seen[openapi3.TypeNumber]; ok { + typs = append(typs, openapi3.TypeNumber) + } + if _, ok := seen[openapi3.TypeString]; ok { + typs = append(typs, openapi3.TypeString) + } + if _, ok := seen[openapi3.TypeArray]; ok { + typs = append(typs, openapi3.TypeArray) + } + if _, ok := seen[openapi3.TypeObject]; ok { + typs = append(typs, openapi3.TypeObject) } return typs } -func valueType(value any) string { - switch value.(type) { - case bool: - return openapi3.TypeBoolean - case float32, float64, int, int8, int16, int32, int64, uint, uint8, uint16, uint32, uint64, json.Number: - return openapi3.TypeNumber - case string: - return openapi3.TypeString - case []any: - return openapi3.TypeArray - case map[string]any: - return openapi3.TypeObject - } - return "" -} - func parsePrimitiveCase(raw string, schema *openapi3.SchemaRef, typ string) (any, error) { switch typ { case "integer": From 21622f0888b57a703b7f1d868c85191fe3cff1cd Mon Sep 17 00:00:00 2001 From: Reuven Harrison Date: Mon, 26 Oct 2026 16:50:02 +0200 Subject: [PATCH 19/78] openapi2conv: handle some nil derefs (#1384) Co-authored-by: Claude Opus 5 --- openapi2conv/nil_collections_test.go | 64 +++++++++++++++++++ openapi2conv/openapi2_conv.go | 40 +++++++++--- .../testdata/fuzz/FuzzToV3/2915761dc93996a1 | 2 + 3 files changed, 98 insertions(+), 8 deletions(-) create mode 100644 openapi2conv/nil_collections_test.go create mode 100644 openapi2conv/testdata/fuzz/FuzzToV3/2915761dc93996a1 diff --git a/openapi2conv/nil_collections_test.go b/openapi2conv/nil_collections_test.go new file mode 100644 index 000000000..0793695d4 --- /dev/null +++ b/openapi2conv/nil_collections_test.go @@ -0,0 +1,64 @@ +package openapi2conv_test + +import ( + "encoding/json" + "testing" + + "github.com/stretchr/testify/require" + + "github.com/getkin/kin-openapi/openapi2" + "github.com/getkin/kin-openapi/openapi2conv" +) + +// A Swagger document can write null wherever an object belongs, and every +// collection that accepts one reached a dereference. Converting such a +// document reports it rather than panicking: the member stays nil and the +// resulting document says so when validated. +func TestToV3NullMembers(t *testing.T) { + t.Parallel() + + for _, doc2 := range []string{ + `{"paths":{"0":null}}`, + `{"paths":{"0":{"get":{"responses":{"":null}}}}}`, + `{"paths":{"0":{"get":{"responses":{"200":{"description":"d","headers":{"h":null}}}}}}}`, + `{"paths":{"0":{"get":{"parameters":[null]}}}}`, + `{"paths":{"0":{"parameters":[null],"get":{"responses":{"200":{"description":"d"}}}}}}`, + `{"responses":{"x":null}}`, + `{"parameters":{"x":null}}`, + `{"definitions":{"x":null}}`, + `{"securityDefinitions":{"x":null}}`, + } { + t.Run(doc2, func(t *testing.T) { + t.Parallel() + + var doc openapi2.T + require.NoError(t, json.Unmarshal([]byte(doc2), &doc)) + + // Whatever comes back, nothing dereferences a null on the way. + doc3, err := openapi2conv.ToV3(&doc) + if err != nil { + return + } + _, err = doc3.MarshalJSON() + require.NoError(t, err) + }) + } +} + +// Converting a document leaves it as it was: a v3 header drops the in and name +// a v2 header carries, and the copy being converted is where that happens. +func TestToV3HeadersLeavesInputAlone(t *testing.T) { + t.Parallel() + + const spec = `{"paths":{"/a":{"get":{"responses":{"200":{"description":"d","headers":{"h":{"type":"string"}}}}}}}}` + + var doc openapi2.T + require.NoError(t, json.Unmarshal([]byte(spec), &doc)) + header := doc.Paths["/a"].Get.Responses.Value("200").Headers["h"] + header.Name, header.In = "h", "header" + + _, err := openapi2conv.ToV3(&doc) + require.NoError(t, err) + require.Equal(t, "h", header.Name) + require.Equal(t, "header", header.In) +} diff --git a/openapi2conv/openapi2_conv.go b/openapi2conv/openapi2_conv.go index 38fee0cf5..954534f6a 100644 --- a/openapi2conv/openapi2_conv.go +++ b/openapi2conv/openapi2_conv.go @@ -127,6 +127,9 @@ func ToV3WithLoader(doc2 *openapi2.T, loader *openapi3.Loader, location *url.URL } func ToV3PathItem(doc2 *openapi2.T, components *openapi3.Components, pathItem *openapi2.PathItem, consumes []string) (*openapi3.PathItem, error) { + if pathItem == nil { + return nil, nil + } doc3 := &openapi3.PathItem{ Extensions: stripNonExtensions(pathItem.Extensions), } @@ -245,7 +248,11 @@ func inheritedRequestBodyParams(components *openapi3.Components, pathItem *opena // parameterIdentity returns the key a parameter is known by inside a path item: // a reference keeps its reference, an inline parameter its location and name. +// A parameter written as null has no identity and overrides nothing. func parameterIdentity(parameter *openapi2.Parameter) string { + if parameter == nil { + return "" + } if parameter.Ref != "" { return parameter.Ref } @@ -260,6 +267,9 @@ func getParameterNameFromOldRef(ref string) string { } func ToV3Parameter(components *openapi3.Components, parameter *openapi2.Parameter, consumes []string) (*openapi3.ParameterRef, *openapi3.RequestBodyRef, map[string]*openapi3.SchemaRef, error) { + if parameter == nil { + return nil, nil, nil, nil + } if ref := parameter.Ref; ref != "" { if strings.HasPrefix(ref, "#/parameters/") { name := getParameterNameFromOldRef(ref) @@ -487,6 +497,9 @@ func onlyOneReqBodyParam(bodies []*openapi3.RequestBodyRef, formDataSchemas map[ } func ToV3Response(response *openapi2.Response, produces []string) (*openapi3.ResponseRef, error) { + if response == nil { + return nil, nil + } if ref := response.Ref; ref != "" { return &openapi3.ResponseRef{Ref: ToV3Ref(ref)}, nil } @@ -527,16 +540,27 @@ func ToV3Response(response *openapi2.Response, produces []string) (*openapi3.Res func ToV3Headers(defs map[string]*openapi2.Header) openapi3.Headers { headers := make(openapi3.Headers, len(defs)) for name, header := range defs { - header.In = "" - header.Name = "" - if ref := header.Ref; ref != "" { + if header == nil { + headers[name] = nil + continue + } + // On a copy: a header's in and name are dropped on the way to a + // v3 header, and the document being converted keeps its own. + h := *header + h.In = "" + h.Name = "" + if ref := h.Ref; ref != "" { headers[name] = &openapi3.HeaderRef{Ref: ToV3Ref(ref)} - } else { - parameter, _, _, _ := ToV3Parameter(nil, &header.Parameter, nil) - headers[name] = &openapi3.HeaderRef{Value: &openapi3.Header{ - Parameter: *parameter.Value, - }} + continue + } + parameter, _, _, _ := ToV3Parameter(nil, &h.Parameter, nil) + if parameter == nil || parameter.Value == nil { + headers[name] = nil + continue } + headers[name] = &openapi3.HeaderRef{Value: &openapi3.Header{ + Parameter: *parameter.Value, + }} } return headers } diff --git a/openapi2conv/testdata/fuzz/FuzzToV3/2915761dc93996a1 b/openapi2conv/testdata/fuzz/FuzzToV3/2915761dc93996a1 new file mode 100644 index 000000000..c3ae52221 --- /dev/null +++ b/openapi2conv/testdata/fuzz/FuzzToV3/2915761dc93996a1 @@ -0,0 +1,2 @@ +go test fuzz v1 +[]byte("{\"paths\":{\"0\":{\"get\":{\"responses\":{\"\":null}}}}}") From 4b868cedd0959a90dee6de65ad765435ee62f46c Mon Sep 17 00:00:00 2001 From: Reuven Harrison Date: Mon, 26 Oct 2026 17:38:32 +0200 Subject: [PATCH 20/78] ci: a minimize budget the minimizer can finish in (#1385) Co-authored-by: Claude Opus 5 --- .github/workflows/fuzz.yml | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/.github/workflows/fuzz.yml b/.github/workflows/fuzz.yml index c9202215a..836f85d10 100644 --- a/.github/workflows/fuzz.yml +++ b/.github/workflows/fuzz.yml @@ -92,13 +92,20 @@ jobs: # -run='^$' skips the ordinary tests: the seed corpus is already replayed by # `go test ./...` in the go workflow, so this job only spends time fuzzing. + # + # The minimize budget is small on purpose. A minimize that cannot finish + # inside it writes the candidate it had and the job fails with "fuzzing + # process hung or terminated unexpectedly while minimizing", whose + # candidate then passes on replay: a red build and nothing to act on. The + # budget only decides how small the saved input gets, so spending less of + # it costs a larger seed and buys a signal that means what it says. - name: Fuzz ${{ matrix.target }} run: | go test \ -run='^$' \ -fuzz='^${{ matrix.target }}$' \ -fuzztime='${{ steps.budget.outputs.fuzztime }}' \ - -fuzzminimizetime=60s \ + -fuzzminimizetime=10s \ ${{ matrix.package }} # A failing input is written next to the package it broke. Upload it so the From 9ff7e379b537173038ffbd39af312b606554cf4c Mon Sep 17 00:00:00 2001 From: Reuven Harrison Date: Mon, 26 Oct 2026 18:20:58 +0200 Subject: [PATCH 21/78] openapi3: return a typed error for a disallowed external $ref (#1370) Co-authored-by: Claude Opus 5 --- .github/docs/openapi3.txt | 13 ++++++ openapi3/loader.go | 21 ++++++++-- .../loader_disallowed_external_ref_test.go | 42 +++++++++++++++++++ 3 files changed, 73 insertions(+), 3 deletions(-) create mode 100644 openapi3/loader_disallowed_external_ref_test.go diff --git a/.github/docs/openapi3.txt b/.github/docs/openapi3.txt index a77c3e95e..90b98c3db 100644 --- a/.github/docs/openapi3.txt +++ b/.github/docs/openapi3.txt @@ -739,6 +739,19 @@ func (e *DependentSchemasFieldFor31Plus) As(target any) bool func (e *DependentSchemasFieldFor31Plus) Code() string +type DisallowedExternalRefError struct { + // Ref is the $ref value as it appears in the document, e.g. + // "other.yaml#/components/schemas/Thing". + Ref string +} + DisallowedExternalRefError is returned for a $ref to another document + encountered while Loader.IsExternalRefsAllowed is false. A caller that tells + a refused $ref apart from a document that failed to load for another reason, + to report the setting as the remedy or to map it to its own error, matches + this type with errors.As rather than the message text. + +func (e *DisallowedExternalRefError) Error() string + type Discriminator struct { Extensions map[string]any `json:"-" yaml:"-"` Origin *Origin `json:"-" yaml:"-"` diff --git a/openapi3/loader.go b/openapi3/loader.go index e7e422cdc..d62b68059 100644 --- a/openapi3/loader.go +++ b/openapi3/loader.go @@ -109,11 +109,26 @@ func (loader *Loader) loadFromURIInternal(location *url.URL) (*T, error) { return loader.loadFromDataWithPathInternal(data, location) } -func (loader *Loader) allowsExternalRefs(ref string) (err error) { +// DisallowedExternalRefError is returned for a $ref to another document +// encountered while Loader.IsExternalRefsAllowed is false. A caller that tells +// a refused $ref apart from a document that failed to load for another reason, +// to report the setting as the remedy or to map it to its own error, matches +// this type with errors.As rather than the message text. +type DisallowedExternalRefError struct { + // Ref is the $ref value as it appears in the document, e.g. + // "other.yaml#/components/schemas/Thing". + Ref string +} + +func (e *DisallowedExternalRefError) Error() string { + return fmt.Sprintf("encountered disallowed external reference: %q", e.Ref) +} + +func (loader *Loader) allowsExternalRefs(ref string) error { if !loader.IsExternalRefsAllowed { - err = fmt.Errorf("encountered disallowed external reference: %q", ref) + return &DisallowedExternalRefError{Ref: ref} } - return + return nil } func (loader *Loader) loadSingleElementFromURI(ref string, rootPath *url.URL, element any) (*url.URL, error) { diff --git a/openapi3/loader_disallowed_external_ref_test.go b/openapi3/loader_disallowed_external_ref_test.go new file mode 100644 index 000000000..73d1d698e --- /dev/null +++ b/openapi3/loader_disallowed_external_ref_test.go @@ -0,0 +1,42 @@ +package openapi3_test + +import ( + "fmt" + "testing" + + "github.com/stretchr/testify/require" + + "github.com/getkin/kin-openapi/openapi3" +) + +// A $ref naming a whole document and a $ref with a fragment take different +// paths through the loader, and each applies IsExternalRefsAllowed on its own. +func TestDisallowedExternalRefError(t *testing.T) { + t.Parallel() + + for _, ref := range []string{"other.yaml", "other.yaml#/components/schemas/Thing"} { + t.Run(ref, func(t *testing.T) { + t.Parallel() + + spec := fmt.Appendf(nil, ` +openapi: 3.0.0 +info: + title: Test + version: '1.0' +paths: {} +components: + schemas: + Thing: + $ref: %q +`, ref) + + loader := openapi3.NewLoader() + _, err := loader.LoadFromData(spec) + require.Error(t, err) + + var refused *openapi3.DisallowedExternalRefError + require.ErrorAs(t, err, &refused) + require.Equal(t, ref, refused.Ref) + }) + } +} From 8d12901d6685c498ae4ffadee3870eaebd7c052b Mon Sep 17 00:00:00 2001 From: Luis Figueroa <62305361+LuisFigueroaG@users.noreply.github.com> Date: Tue, 27 Oct 2026 11:56:54 -0300 Subject: [PATCH 22/78] openapi3: reject a multipleOf of zero or less in Schema.Validate (#1379) --- .github/docs/openapi3.txt | 16 +++++++++++ README.md | 1 + openapi3/schema.go | 6 ++++ openapi3/validation_code.go | 4 +++ openapi3/validation_code_test.go | 1 + openapi3/validation_error.go | 15 ++++++++++ openapi3/validation_error_test.go | 47 +++++++++++++++++++++++++++++++ 7 files changed, 90 insertions(+) diff --git a/.github/docs/openapi3.txt b/.github/docs/openapi3.txt index 90b98c3db..01dec0307 100644 --- a/.github/docs/openapi3.txt +++ b/.github/docs/openapi3.txt @@ -3179,6 +3179,22 @@ func (e *SchemaItemsRequired) As(target any) bool func (e *SchemaItemsRequired) Code() string +type SchemaMultipleOfNotPositiveError struct { + // MultipleOf is the rejected `multipleOf` value. + MultipleOf float64 + // Origin is the source location of the offending schema when the + // document was loaded with Loader.IncludeOrigin = true. + Origin *Origin +} + SchemaMultipleOfNotPositiveError clusters "multipleOf must be greater + than zero" failures. The value of a schema's `multipleOf` MUST be strictly + greater than 0 (JSON Schema 2020-12 §6.2.1 for OpenAPI 3.1, draft-04 for + OpenAPI 3.0). + +func (e *SchemaMultipleOfNotPositiveError) Code() string + +func (e *SchemaMultipleOfNotPositiveError) Error() string + type SchemaPatternRegexError struct { // Pattern is the schema's `pattern:` value that failed to compile. Pattern string diff --git a/README.md b/README.md index 661a1e767..0c997f735 100644 --- a/README.md +++ b/README.md @@ -331,6 +331,7 @@ for _, path := range doc.Paths.InMatchingOrder() { ### v0.153.0 * `openapi3filter` now parses `number` values of parameters and `application/x-www-form-urlencoded`/`multipart/form-data` bodies as decimal numbers only, so Go float literals such as `0x1p4`, `1_000`, `Inf`, `-infinity` or `NaN` are now rejected as invalid numbers. +* `(*openapi3.Schema).Validate(..)` (hence `(*openapi3.T).Validate(..)`) now rejects a `multipleOf` of zero or less (`openapi3.SchemaMultipleOfNotPositiveError`), as JSON Schema requires it to be strictly greater than 0. Such a schema used to pass validation and then reject every value with `multipleOf must be greater than zero`. ### v0.152.0 * JSON keys of OpenAPI documents only fill the field of the same case (`json:",case:strict"`) when `encoding/json` is implemented with `encoding/json/v2` (by default from Go 1.27, and on Go 1.25 and 1.26 with `GOEXPERIMENT=jsonv2`): a key such as `"Components"` (not `"components"`) is kept as an extension instead of filling `openapi3.T.Components`. Other builds still match keys case-insensitively, as `encoding/json` v1 does. diff --git a/openapi3/schema.go b/openapi3/schema.go index 9405d8a6b..79dcad465 100644 --- a/openapi3/schema.go +++ b/openapi3/schema.go @@ -1572,6 +1572,12 @@ func (schema *Schema) validate(ctx context.Context, visited map[*Schema]struct{} } } + // The value of `multipleOf` MUST be strictly greater than 0 (JSON Schema + // 2020-12 §6.2.1 for OAS 3.1, draft-04 for OAS 3.0). + if x := schema.MultipleOf; x != nil && *x <= 0 { + return visited, &SchemaMultipleOfNotPositiveError{MultipleOf: *x, Origin: schema.Origin} + } + // Reject fields that only exist in OAS 3.1 / JSON Schema 2020-12 when the // document is OAS 3.0. Fields explicitly allowed via AllowExtraSiblingFields // are skipped (opt-in escape hatch for 3.0 docs that reference external diff --git a/openapi3/validation_code.go b/openapi3/validation_code.go index 6bacdee55..185092acb 100644 --- a/openapi3/validation_code.go +++ b/openapi3/validation_code.go @@ -150,6 +150,9 @@ func (e *SchemaAdditionalPropertiesBothForms) Code() string { func (e *SchemaFieldFor31Plus) Code() string { return "schema-field-for-3-1-plus" } func (e *SchemaItemsRequired) Code() string { return "schema-items-required" } func (e *SchemaPatternRegexError) Code() string { return "schema-pattern-regex-invalid" } +func (e *SchemaMultipleOfNotPositiveError) Code() string { + return "schema-multiple-of-not-positive" +} func (e *SchemaReadOnlyWriteOnlyExclusive) Code() string { return "read-only-write-only-mutually-exclusive" } @@ -273,6 +276,7 @@ var validationErrorCodes = []string{ "responses-required", "schema-field-for-3-1-plus", "schema-items-required", + "schema-multiple-of-not-positive", "schema-pattern-regex-invalid", "schema-type-unsupported", "security-requirement-scheme-undefined", diff --git a/openapi3/validation_code_test.go b/openapi3/validation_code_test.go index 2b446cce7..110a3987b 100644 --- a/openapi3/validation_code_test.go +++ b/openapi3/validation_code_test.go @@ -101,6 +101,7 @@ func codedErrorInventory() []openapi3.CodedError { &openapi3.SchemaAdditionalPropertiesBothForms{}, &openapi3.SchemaFieldFor31Plus{}, &openapi3.SchemaItemsRequired{}, + &openapi3.SchemaMultipleOfNotPositiveError{}, &openapi3.SchemaPatternRegexError{}, &openapi3.SchemaReadOnlyWriteOnlyExclusive{}, &openapi3.SchemaBooleanFieldsExclusive{}, diff --git a/openapi3/validation_error.go b/openapi3/validation_error.go index 77a4f6c0a..fef444728 100644 --- a/openapi3/validation_error.go +++ b/openapi3/validation_error.go @@ -653,6 +653,21 @@ func (e *DuplicateRequiredFieldError) Error() string { return fmt.Sprintf("duplicate field %q in required", e.Field) } +// SchemaMultipleOfNotPositiveError clusters "multipleOf must be greater than +// zero" failures. The value of a schema's `multipleOf` MUST be strictly greater +// than 0 (JSON Schema 2020-12 §6.2.1 for OpenAPI 3.1, draft-04 for OpenAPI 3.0). +type SchemaMultipleOfNotPositiveError struct { + // MultipleOf is the rejected `multipleOf` value. + MultipleOf float64 + // Origin is the source location of the offending schema when the + // document was loaded with Loader.IncludeOrigin = true. + Origin *Origin +} + +func (e *SchemaMultipleOfNotPositiveError) Error() string { + return fmt.Sprintf("multipleOf must be greater than zero, got %g", e.MultipleOf) +} + // DuplicateTagError clusters "more than one tag has name X" failures. Each tag // name in the document-root `tags` list MUST be unique (OpenAPI Object). type DuplicateTagError struct { diff --git a/openapi3/validation_error_test.go b/openapi3/validation_error_test.go index b67038137..2c96d83ef 100644 --- a/openapi3/validation_error_test.go +++ b/openapi3/validation_error_test.go @@ -2404,6 +2404,53 @@ components: require.ErrorContains(t, dup, `duplicate field "id" in required`) } +func TestValidationError_SchemaMultipleOfNotPositiveError(t *testing.T) { + t.Parallel() + + for _, tc := range []struct { + version string + multipleOf string + expected float64 + }{ + {version: "3.0.3", multipleOf: "0", expected: 0}, + {version: "3.0.3", multipleOf: "-2", expected: -2}, + {version: "3.1.0", multipleOf: "0", expected: 0}, + {version: "3.1.0", multipleOf: "-0.5", expected: -0.5}, + } { + t.Run(tc.version+" "+tc.multipleOf, func(t *testing.T) { + doc := loadDocFromYAML(t, ` +openapi: `+tc.version+` +info: { title: t, version: "1" } +paths: {} +components: + schemas: + Bad: + type: number + multipleOf: `+tc.multipleOf+` +`) + err := doc.Validate(t.Context()) + require.Error(t, err) + + var nonPositive *openapi3.SchemaMultipleOfNotPositiveError + require.True(t, errors.As(err, &nonPositive)) + require.Equal(t, tc.expected, nonPositive.MultipleOf) + require.ErrorContains(t, nonPositive, "multipleOf must be greater than zero, got "+tc.multipleOf) + }) + } + + doc := loadDocFromYAML(t, ` +openapi: 3.0.3 +info: { title: t, version: "1" } +paths: {} +components: + schemas: + Good: + type: number + multipleOf: 0.01 +`) + require.NoError(t, doc.Validate(t.Context())) +} + func TestValidationError_DuplicateTagError(t *testing.T) { t.Parallel() From 2e311b6f4fe21e7abc563376d10748aec2b57477 Mon Sep 17 00:00:00 2001 From: Luis Figueroa <62305361+LuisFigueroaG@users.noreply.github.com> Date: Tue, 27 Oct 2026 16:58:23 -0300 Subject: [PATCH 23/78] openapi3filter: treat a handler that writes no status as a 200 in Validator.Middleware (#1389) --- openapi3filter/middleware.go | 11 ++++++-- openapi3filter/middleware_test.go | 47 +++++++++++++++++++++++++++++++ 2 files changed, 56 insertions(+), 2 deletions(-) diff --git a/openapi3filter/middleware.go b/openapi3filter/middleware.go index d20889ed9..94a888a29 100644 --- a/openapi3filter/middleware.go +++ b/openapi3filter/middleware.go @@ -173,7 +173,8 @@ type responseWrapper interface { // not yet been written. flushBodyContents() error - // statusCode returns the response status code, 0 if not set yet. + // statusCode returns the response status code, 200 if not set, as + // net/http sends for a handler that writes neither a status nor a body. statusCode() int // bodyContents returns the buffered @@ -234,6 +235,9 @@ func (wr *warnResponseWrapper) flushBodyContents() error { } func (wr *warnResponseWrapper) statusCode() int { + if !wr.headerWritten { + return http.StatusOK + } return wr.status } @@ -270,12 +274,15 @@ func (wr *strictResponseWrapper) Header() http.Header { } func (wr *strictResponseWrapper) flushBodyContents() error { - wr.w.WriteHeader(wr.status) + wr.w.WriteHeader(wr.statusCode()) _, err := wr.w.Write(wr.body.Bytes()) return err } func (wr *strictResponseWrapper) statusCode() int { + if !wr.headerWritten { + return http.StatusOK + } return wr.status } diff --git a/openapi3filter/middleware_test.go b/openapi3filter/middleware_test.go index c9aa61788..a58101970 100644 --- a/openapi3filter/middleware_test.go +++ b/openapi3filter/middleware_test.go @@ -401,6 +401,53 @@ func TestValidator(t *testing.T) { } } +func TestValidatorHandlerWithoutStatus(t *testing.T) { + t.Parallel() + + loader := openapi3.NewLoader() + doc, err := loader.LoadFromData([]byte(` +openapi: 3.0.0 +info: + title: 'Validator' + version: '0.0.0' +paths: + /ping: + get: + responses: + '200': + description: pong +`[1:])) + require.NoError(t, err) + require.NoError(t, doc.Validate(loader.Context)) + + router, err := gorillamux.NewRouter(doc) + require.NoError(t, err) + + // net/http sends a 200 for a handler that writes neither a status nor a body. + handler := http.HandlerFunc(func(http.ResponseWriter, *http.Request) {}) + + for _, strict := range []bool{true, false} { + for _, includeResponseStatus := range []bool{true, false} { + t.Run(fmt.Sprintf("strict=%v includeResponseStatus=%v", strict, includeResponseStatus), func(t *testing.T) { + var logged []string + v := openapi3filter.NewValidator(router, + openapi3filter.Strict(strict), + openapi3filter.ValidationOptions(openapi3filter.Options{IncludeResponseStatus: includeResponseStatus}), + openapi3filter.OnLog(func(_ context.Context, message string, err error) { + logged = append(logged, fmt.Sprintf("%s: %v", message, err)) + }), + ) + + w := httptest.NewRecorder() + v.Middleware(handler).ServeHTTP(w, httptest.NewRequest(http.MethodGet, "/ping", nil)) + require.Empty(t, logged) + require.Equal(t, http.StatusOK, w.Code) + require.Empty(t, w.Body.String()) + }) + } + } +} + func ExampleValidator() { // OpenAPI specification for a simple service that squares integers, with // some limitations. From b95938808d0aeb56ecfe5fa4c3c27e4fb705648e Mon Sep 17 00:00:00 2001 From: Reuven Harrison Date: Wed, 28 Oct 2026 18:38:27 +0200 Subject: [PATCH 24/78] deps: update oasdiff/yaml to v0.1.3 (#1387) --- go.mod | 4 ++-- go.sum | 8 ++++---- .../adyen_com_CheckoutService_37_openapi_yaml__load | 1 - ...dyen_com_CheckoutService_37_openapi_yaml__validate | 9 +++++++++ .../adyen_com_CheckoutService_40_openapi_yaml__load | 1 - ...dyen_com_CheckoutService_40_openapi_yaml__validate | 9 +++++++++ .../adyen_com_CheckoutService_41_openapi_yaml__load | 1 - ...dyen_com_CheckoutService_41_openapi_yaml__validate | 9 +++++++++ .../adyen_com_CheckoutService_46_openapi_yaml__load | 1 - ...dyen_com_CheckoutService_46_openapi_yaml__validate | 9 +++++++++ .../adyen_com_CheckoutService_49_openapi_yaml__load | 1 - ...dyen_com_CheckoutService_49_openapi_yaml__validate | 9 +++++++++ .../adyen_com_CheckoutService_50_openapi_yaml__load | 1 - ...dyen_com_CheckoutService_50_openapi_yaml__validate | 9 +++++++++ .../adyen_com_CheckoutService_51_openapi_yaml__load | 1 - ...dyen_com_CheckoutService_51_openapi_yaml__validate | 9 +++++++++ .../adyen_com_CheckoutService_52_openapi_yaml__load | 1 - ...dyen_com_CheckoutService_52_openapi_yaml__validate | 9 +++++++++ .../adyen_com_CheckoutService_53_openapi_yaml__load | 1 - ...dyen_com_CheckoutService_53_openapi_yaml__validate | 9 +++++++++ .../adyen_com_CheckoutService_64_openapi_yaml__load | 1 - ...dyen_com_CheckoutService_64_openapi_yaml__validate | 9 +++++++++ .../adyen_com_CheckoutService_65_openapi_yaml__load | 1 - ...dyen_com_CheckoutService_65_openapi_yaml__validate | 9 +++++++++ .../adyen_com_CheckoutService_66_openapi_yaml__load | 1 - ...dyen_com_CheckoutService_66_openapi_yaml__validate | 9 +++++++++ .../adyen_com_CheckoutService_67_openapi_yaml__load | 1 - ...dyen_com_CheckoutService_67_openapi_yaml__validate | 9 +++++++++ .../adyen_com_CheckoutService_68_openapi_yaml__load | 1 - ...dyen_com_CheckoutService_68_openapi_yaml__validate | 9 +++++++++ .../adyen_com_CheckoutService_69_openapi_yaml__load | 1 - ...dyen_com_CheckoutService_69_openapi_yaml__validate | 9 +++++++++ .../adyen_com_CheckoutService_70_openapi_yaml__load | 1 - ...dyen_com_CheckoutService_70_openapi_yaml__validate | 9 +++++++++ ...dyen_com_CheckoutService_v71_71_openapi_yaml__load | 1 - ..._com_CheckoutService_v71_71_openapi_yaml__validate | 9 +++++++++ .../adyen_com_PaymentService_25_openapi_yaml__load | 1 - .../adyen_com_PaymentService_30_openapi_yaml__load | 1 - .../adyen_com_PaymentService_40_openapi_yaml__load | 1 - .../adyen_com_PaymentService_46_openapi_yaml__load | 1 - .../adyen_com_PaymentService_49_openapi_yaml__load | 1 - .../adyen_com_PaymentService_50_openapi_yaml__load | 1 - .../adyen_com_PaymentService_51_openapi_yaml__load | 1 - .../adyen_com_PaymentService_52_openapi_yaml__load | 1 - .../adyen_com_PaymentService_64_openapi_yaml__load | 1 - .../adyen_com_PaymentService_67_openapi_yaml__load | 1 - .../adyen_com_PaymentService_68_openapi_yaml__load | 1 - .../adyen_com_PayoutService_46_openapi_yaml__load | 1 - .../adyen_com_PayoutService_46_openapi_yaml__validate | 10 ++++++++++ .../adyen_com_PayoutService_49_openapi_yaml__load | 1 - .../adyen_com_PayoutService_49_openapi_yaml__validate | 10 ++++++++++ ...s_com_amadeus_trip_parser_3_0_1_openapi_yaml__load | 1 - ...m_amadeus_trip_parser_3_0_1_openapi_yaml__validate | 11 +++++++++++ .../codat_io_accounting_2_1_0_openapi_yaml__load | 2 +- .../fuzz/FuzzLoadFromData/merge-unhashable-key | 2 ++ .../fuzz/FuzzLoadWithOrigins/explicit-key-no-value | 2 ++ 56 files changed, 195 insertions(+), 38 deletions(-) delete mode 100644 openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_37_openapi_yaml__load create mode 100644 openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_37_openapi_yaml__validate delete mode 100644 openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_40_openapi_yaml__load create mode 100644 openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_40_openapi_yaml__validate delete mode 100644 openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_41_openapi_yaml__load create mode 100644 openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_41_openapi_yaml__validate delete mode 100644 openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_46_openapi_yaml__load create mode 100644 openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_46_openapi_yaml__validate delete mode 100644 openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_49_openapi_yaml__load create mode 100644 openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_49_openapi_yaml__validate delete mode 100644 openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_50_openapi_yaml__load create mode 100644 openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_50_openapi_yaml__validate delete mode 100644 openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_51_openapi_yaml__load create mode 100644 openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_51_openapi_yaml__validate delete mode 100644 openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_52_openapi_yaml__load create mode 100644 openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_52_openapi_yaml__validate delete mode 100644 openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_53_openapi_yaml__load create mode 100644 openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_53_openapi_yaml__validate delete mode 100644 openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_64_openapi_yaml__load create mode 100644 openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_64_openapi_yaml__validate delete mode 100644 openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_65_openapi_yaml__load create mode 100644 openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_65_openapi_yaml__validate delete mode 100644 openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_66_openapi_yaml__load create mode 100644 openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_66_openapi_yaml__validate delete mode 100644 openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_67_openapi_yaml__load create mode 100644 openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_67_openapi_yaml__validate delete mode 100644 openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_68_openapi_yaml__load create mode 100644 openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_68_openapi_yaml__validate delete mode 100644 openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_69_openapi_yaml__load create mode 100644 openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_69_openapi_yaml__validate delete mode 100644 openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_70_openapi_yaml__load create mode 100644 openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_70_openapi_yaml__validate delete mode 100644 openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_v71_71_openapi_yaml__load create mode 100644 openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_v71_71_openapi_yaml__validate delete mode 100644 openapi3/testdata/apis_guru_openapi_directory/adyen_com_PaymentService_25_openapi_yaml__load delete mode 100644 openapi3/testdata/apis_guru_openapi_directory/adyen_com_PaymentService_30_openapi_yaml__load delete mode 100644 openapi3/testdata/apis_guru_openapi_directory/adyen_com_PaymentService_40_openapi_yaml__load delete mode 100644 openapi3/testdata/apis_guru_openapi_directory/adyen_com_PaymentService_46_openapi_yaml__load delete mode 100644 openapi3/testdata/apis_guru_openapi_directory/adyen_com_PaymentService_49_openapi_yaml__load delete mode 100644 openapi3/testdata/apis_guru_openapi_directory/adyen_com_PaymentService_50_openapi_yaml__load delete mode 100644 openapi3/testdata/apis_guru_openapi_directory/adyen_com_PaymentService_51_openapi_yaml__load delete mode 100644 openapi3/testdata/apis_guru_openapi_directory/adyen_com_PaymentService_52_openapi_yaml__load delete mode 100644 openapi3/testdata/apis_guru_openapi_directory/adyen_com_PaymentService_64_openapi_yaml__load delete mode 100644 openapi3/testdata/apis_guru_openapi_directory/adyen_com_PaymentService_67_openapi_yaml__load delete mode 100644 openapi3/testdata/apis_guru_openapi_directory/adyen_com_PaymentService_68_openapi_yaml__load delete mode 100644 openapi3/testdata/apis_guru_openapi_directory/adyen_com_PayoutService_46_openapi_yaml__load create mode 100644 openapi3/testdata/apis_guru_openapi_directory/adyen_com_PayoutService_46_openapi_yaml__validate delete mode 100644 openapi3/testdata/apis_guru_openapi_directory/adyen_com_PayoutService_49_openapi_yaml__load create mode 100644 openapi3/testdata/apis_guru_openapi_directory/adyen_com_PayoutService_49_openapi_yaml__validate delete mode 100644 openapi3/testdata/apis_guru_openapi_directory/amadeus_com_amadeus_trip_parser_3_0_1_openapi_yaml__load create mode 100644 openapi3/testdata/apis_guru_openapi_directory/amadeus_com_amadeus_trip_parser_3_0_1_openapi_yaml__validate create mode 100644 openapi3/testdata/fuzz/FuzzLoadFromData/merge-unhashable-key create mode 100644 openapi3/testdata/fuzz/FuzzLoadWithOrigins/explicit-key-no-value diff --git a/go.mod b/go.mod index b1b1528d1..9de04f453 100644 --- a/go.mod +++ b/go.mod @@ -5,8 +5,8 @@ go 1.25 require ( github.com/go-openapi/jsonpointer v0.22.5 github.com/gorilla/mux v1.8.0 - github.com/oasdiff/yaml v0.1.1 - github.com/oasdiff/yaml3 v0.0.14 + github.com/oasdiff/yaml v0.1.3 + github.com/oasdiff/yaml3 v0.0.16 github.com/santhosh-tekuri/jsonschema/v6 v6.0.3 github.com/stretchr/testify v1.9.0 ) diff --git a/go.sum b/go.sum index afadd341f..df9986795 100644 --- a/go.sum +++ b/go.sum @@ -17,10 +17,10 @@ github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ= github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI= github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY= github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE= -github.com/oasdiff/yaml v0.1.1 h1:6nHx+pn9gBRM6YpBlFZFQGCCd1nuvqOBtTD3KKTgGxY= -github.com/oasdiff/yaml v0.1.1/go.mod h1:EYJNoyktvWMJ0Hmhx+6qTaqMOsalUaRGT8Sj1hNcegU= -github.com/oasdiff/yaml3 v0.0.14 h1:aLJee3hxBK2H5wdXd9iPcIXb93Nty1Ge0pT171eHtkw= -github.com/oasdiff/yaml3 v0.0.14/go.mod h1:csto2xfDjYccdUn/yw/bPjj/cYTdp6HtFA0J4TWG+gg= +github.com/oasdiff/yaml v0.1.3 h1:TdwO8e1G1F+bN++LzHj6IWExcuqMjQ1xK8KRYWTffWE= +github.com/oasdiff/yaml v0.1.3/go.mod h1:vxzaFi+b+l+FWC/2NZMm+yD4DzyzwPCwaeLj1x1XfMg= +github.com/oasdiff/yaml3 v0.0.16 h1:NlDF/1oIOhmOvrEb9eH6Sbuubp3gZNS4A+MKST5/p0Q= +github.com/oasdiff/yaml3 v0.0.16/go.mod h1:csto2xfDjYccdUn/yw/bPjj/cYTdp6HtFA0J4TWG+gg= github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM= github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4= github.com/santhosh-tekuri/jsonschema/v6 v6.0.3 h1:1EYB5IzjZawrrnELUi78f9fPu57HuXjmddZPjrls/28= diff --git a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_37_openapi_yaml__load b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_37_openapi_yaml__load deleted file mode 100644 index a1a6687fc..000000000 --- a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_37_openapi_yaml__load +++ /dev/null @@ -1 +0,0 @@ -failed to unmarshal data: json error: jsontext: invalid character 'o' at start of value, yaml error: error converting YAML to JSON: yaml: line 4971: found a tab character where an indentation space is expected diff --git a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_37_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_37_openapi_yaml__validate new file mode 100644 index 000000000..5db7cdee5 --- /dev/null +++ b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_37_openapi_yaml__validate @@ -0,0 +1,9 @@ +invalid paths: invalid path /cancels: invalid operation POST: invalid example: example generic: validation failed due to: error at "/errorCode": at '/errorCode': got number, want string +Schema: + { + "description": "The error code mapped to the error message.", + "type": "string" + } + +Value: + 14030 diff --git a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_40_openapi_yaml__load b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_40_openapi_yaml__load deleted file mode 100644 index 5ec602e08..000000000 --- a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_40_openapi_yaml__load +++ /dev/null @@ -1 +0,0 @@ -failed to unmarshal data: json error: jsontext: invalid character 'o' at start of value, yaml error: error converting YAML to JSON: yaml: line 5279: found a tab character where an indentation space is expected diff --git a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_40_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_40_openapi_yaml__validate new file mode 100644 index 000000000..5db7cdee5 --- /dev/null +++ b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_40_openapi_yaml__validate @@ -0,0 +1,9 @@ +invalid paths: invalid path /cancels: invalid operation POST: invalid example: example generic: validation failed due to: error at "/errorCode": at '/errorCode': got number, want string +Schema: + { + "description": "The error code mapped to the error message.", + "type": "string" + } + +Value: + 14030 diff --git a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_41_openapi_yaml__load b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_41_openapi_yaml__load deleted file mode 100644 index 4947bf2ca..000000000 --- a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_41_openapi_yaml__load +++ /dev/null @@ -1 +0,0 @@ -failed to unmarshal data: json error: jsontext: invalid character 'o' at start of value, yaml error: error converting YAML to JSON: yaml: line 5364: found a tab character where an indentation space is expected diff --git a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_41_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_41_openapi_yaml__validate new file mode 100644 index 000000000..5db7cdee5 --- /dev/null +++ b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_41_openapi_yaml__validate @@ -0,0 +1,9 @@ +invalid paths: invalid path /cancels: invalid operation POST: invalid example: example generic: validation failed due to: error at "/errorCode": at '/errorCode': got number, want string +Schema: + { + "description": "The error code mapped to the error message.", + "type": "string" + } + +Value: + 14030 diff --git a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_46_openapi_yaml__load b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_46_openapi_yaml__load deleted file mode 100644 index 169959c1f..000000000 --- a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_46_openapi_yaml__load +++ /dev/null @@ -1 +0,0 @@ -failed to unmarshal data: json error: jsontext: invalid character 'o' at start of value, yaml error: error converting YAML to JSON: yaml: line 5365: found a tab character where an indentation space is expected diff --git a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_46_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_46_openapi_yaml__validate new file mode 100644 index 000000000..5db7cdee5 --- /dev/null +++ b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_46_openapi_yaml__validate @@ -0,0 +1,9 @@ +invalid paths: invalid path /cancels: invalid operation POST: invalid example: example generic: validation failed due to: error at "/errorCode": at '/errorCode': got number, want string +Schema: + { + "description": "The error code mapped to the error message.", + "type": "string" + } + +Value: + 14030 diff --git a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_49_openapi_yaml__load b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_49_openapi_yaml__load deleted file mode 100644 index 7b02b8bcc..000000000 --- a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_49_openapi_yaml__load +++ /dev/null @@ -1 +0,0 @@ -failed to unmarshal data: json error: jsontext: invalid character 'o' at start of value, yaml error: error converting YAML to JSON: yaml: line 5375: found a tab character where an indentation space is expected diff --git a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_49_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_49_openapi_yaml__validate new file mode 100644 index 000000000..5db7cdee5 --- /dev/null +++ b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_49_openapi_yaml__validate @@ -0,0 +1,9 @@ +invalid paths: invalid path /cancels: invalid operation POST: invalid example: example generic: validation failed due to: error at "/errorCode": at '/errorCode': got number, want string +Schema: + { + "description": "The error code mapped to the error message.", + "type": "string" + } + +Value: + 14030 diff --git a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_50_openapi_yaml__load b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_50_openapi_yaml__load deleted file mode 100644 index 0135742f2..000000000 --- a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_50_openapi_yaml__load +++ /dev/null @@ -1 +0,0 @@ -failed to unmarshal data: json error: jsontext: invalid character 'o' at start of value, yaml error: error converting YAML to JSON: yaml: line 5433: found a tab character where an indentation space is expected diff --git a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_50_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_50_openapi_yaml__validate new file mode 100644 index 000000000..5db7cdee5 --- /dev/null +++ b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_50_openapi_yaml__validate @@ -0,0 +1,9 @@ +invalid paths: invalid path /cancels: invalid operation POST: invalid example: example generic: validation failed due to: error at "/errorCode": at '/errorCode': got number, want string +Schema: + { + "description": "The error code mapped to the error message.", + "type": "string" + } + +Value: + 14030 diff --git a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_51_openapi_yaml__load b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_51_openapi_yaml__load deleted file mode 100644 index 6a6fc8a33..000000000 --- a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_51_openapi_yaml__load +++ /dev/null @@ -1 +0,0 @@ -failed to unmarshal data: json error: jsontext: invalid character 'o' at start of value, yaml error: error converting YAML to JSON: yaml: line 5435: found a tab character where an indentation space is expected diff --git a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_51_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_51_openapi_yaml__validate new file mode 100644 index 000000000..5db7cdee5 --- /dev/null +++ b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_51_openapi_yaml__validate @@ -0,0 +1,9 @@ +invalid paths: invalid path /cancels: invalid operation POST: invalid example: example generic: validation failed due to: error at "/errorCode": at '/errorCode': got number, want string +Schema: + { + "description": "The error code mapped to the error message.", + "type": "string" + } + +Value: + 14030 diff --git a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_52_openapi_yaml__load b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_52_openapi_yaml__load deleted file mode 100644 index 834eb34f7..000000000 --- a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_52_openapi_yaml__load +++ /dev/null @@ -1 +0,0 @@ -failed to unmarshal data: json error: jsontext: invalid character 'o' at start of value, yaml error: error converting YAML to JSON: yaml: line 5441: found a tab character where an indentation space is expected diff --git a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_52_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_52_openapi_yaml__validate new file mode 100644 index 000000000..5db7cdee5 --- /dev/null +++ b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_52_openapi_yaml__validate @@ -0,0 +1,9 @@ +invalid paths: invalid path /cancels: invalid operation POST: invalid example: example generic: validation failed due to: error at "/errorCode": at '/errorCode': got number, want string +Schema: + { + "description": "The error code mapped to the error message.", + "type": "string" + } + +Value: + 14030 diff --git a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_53_openapi_yaml__load b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_53_openapi_yaml__load deleted file mode 100644 index 834eb34f7..000000000 --- a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_53_openapi_yaml__load +++ /dev/null @@ -1 +0,0 @@ -failed to unmarshal data: json error: jsontext: invalid character 'o' at start of value, yaml error: error converting YAML to JSON: yaml: line 5441: found a tab character where an indentation space is expected diff --git a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_53_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_53_openapi_yaml__validate new file mode 100644 index 000000000..5db7cdee5 --- /dev/null +++ b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_53_openapi_yaml__validate @@ -0,0 +1,9 @@ +invalid paths: invalid path /cancels: invalid operation POST: invalid example: example generic: validation failed due to: error at "/errorCode": at '/errorCode': got number, want string +Schema: + { + "description": "The error code mapped to the error message.", + "type": "string" + } + +Value: + 14030 diff --git a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_64_openapi_yaml__load b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_64_openapi_yaml__load deleted file mode 100644 index 834eb34f7..000000000 --- a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_64_openapi_yaml__load +++ /dev/null @@ -1 +0,0 @@ -failed to unmarshal data: json error: jsontext: invalid character 'o' at start of value, yaml error: error converting YAML to JSON: yaml: line 5441: found a tab character where an indentation space is expected diff --git a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_64_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_64_openapi_yaml__validate new file mode 100644 index 000000000..5db7cdee5 --- /dev/null +++ b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_64_openapi_yaml__validate @@ -0,0 +1,9 @@ +invalid paths: invalid path /cancels: invalid operation POST: invalid example: example generic: validation failed due to: error at "/errorCode": at '/errorCode': got number, want string +Schema: + { + "description": "The error code mapped to the error message.", + "type": "string" + } + +Value: + 14030 diff --git a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_65_openapi_yaml__load b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_65_openapi_yaml__load deleted file mode 100644 index 0ccf23e32..000000000 --- a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_65_openapi_yaml__load +++ /dev/null @@ -1 +0,0 @@ -failed to unmarshal data: json error: jsontext: invalid character 'o' at start of value, yaml error: error converting YAML to JSON: yaml: line 5456: found a tab character where an indentation space is expected diff --git a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_65_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_65_openapi_yaml__validate new file mode 100644 index 000000000..5db7cdee5 --- /dev/null +++ b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_65_openapi_yaml__validate @@ -0,0 +1,9 @@ +invalid paths: invalid path /cancels: invalid operation POST: invalid example: example generic: validation failed due to: error at "/errorCode": at '/errorCode': got number, want string +Schema: + { + "description": "The error code mapped to the error message.", + "type": "string" + } + +Value: + 14030 diff --git a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_66_openapi_yaml__load b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_66_openapi_yaml__load deleted file mode 100644 index 0ccf23e32..000000000 --- a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_66_openapi_yaml__load +++ /dev/null @@ -1 +0,0 @@ -failed to unmarshal data: json error: jsontext: invalid character 'o' at start of value, yaml error: error converting YAML to JSON: yaml: line 5456: found a tab character where an indentation space is expected diff --git a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_66_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_66_openapi_yaml__validate new file mode 100644 index 000000000..5db7cdee5 --- /dev/null +++ b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_66_openapi_yaml__validate @@ -0,0 +1,9 @@ +invalid paths: invalid path /cancels: invalid operation POST: invalid example: example generic: validation failed due to: error at "/errorCode": at '/errorCode': got number, want string +Schema: + { + "description": "The error code mapped to the error message.", + "type": "string" + } + +Value: + 14030 diff --git a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_67_openapi_yaml__load b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_67_openapi_yaml__load deleted file mode 100644 index 3ca4d0fd1..000000000 --- a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_67_openapi_yaml__load +++ /dev/null @@ -1 +0,0 @@ -failed to unmarshal data: json error: jsontext: invalid character 'o' at start of value, yaml error: error converting YAML to JSON: yaml: line 5410: found a tab character where an indentation space is expected diff --git a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_67_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_67_openapi_yaml__validate new file mode 100644 index 000000000..5db7cdee5 --- /dev/null +++ b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_67_openapi_yaml__validate @@ -0,0 +1,9 @@ +invalid paths: invalid path /cancels: invalid operation POST: invalid example: example generic: validation failed due to: error at "/errorCode": at '/errorCode': got number, want string +Schema: + { + "description": "The error code mapped to the error message.", + "type": "string" + } + +Value: + 14030 diff --git a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_68_openapi_yaml__load b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_68_openapi_yaml__load deleted file mode 100644 index 27cdc5e24..000000000 --- a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_68_openapi_yaml__load +++ /dev/null @@ -1 +0,0 @@ -failed to unmarshal data: json error: jsontext: invalid character 'o' at start of value, yaml error: error converting YAML to JSON: yaml: line 4685: found a tab character where an indentation space is expected diff --git a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_68_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_68_openapi_yaml__validate new file mode 100644 index 000000000..5db7cdee5 --- /dev/null +++ b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_68_openapi_yaml__validate @@ -0,0 +1,9 @@ +invalid paths: invalid path /cancels: invalid operation POST: invalid example: example generic: validation failed due to: error at "/errorCode": at '/errorCode': got number, want string +Schema: + { + "description": "The error code mapped to the error message.", + "type": "string" + } + +Value: + 14030 diff --git a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_69_openapi_yaml__load b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_69_openapi_yaml__load deleted file mode 100644 index 1c5b3634b..000000000 --- a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_69_openapi_yaml__load +++ /dev/null @@ -1 +0,0 @@ -failed to unmarshal data: json error: jsontext: invalid character 'o' at start of value, yaml error: error converting YAML to JSON: yaml: line 4730: found a tab character where an indentation space is expected diff --git a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_69_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_69_openapi_yaml__validate new file mode 100644 index 000000000..5db7cdee5 --- /dev/null +++ b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_69_openapi_yaml__validate @@ -0,0 +1,9 @@ +invalid paths: invalid path /cancels: invalid operation POST: invalid example: example generic: validation failed due to: error at "/errorCode": at '/errorCode': got number, want string +Schema: + { + "description": "The error code mapped to the error message.", + "type": "string" + } + +Value: + 14030 diff --git a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_70_openapi_yaml__load b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_70_openapi_yaml__load deleted file mode 100644 index c63f88db9..000000000 --- a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_70_openapi_yaml__load +++ /dev/null @@ -1 +0,0 @@ -failed to unmarshal data: json error: jsontext: invalid character 'o' at start of value, yaml error: error converting YAML to JSON: yaml: line 4776: found a tab character where an indentation space is expected diff --git a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_70_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_70_openapi_yaml__validate new file mode 100644 index 000000000..5db7cdee5 --- /dev/null +++ b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_70_openapi_yaml__validate @@ -0,0 +1,9 @@ +invalid paths: invalid path /cancels: invalid operation POST: invalid example: example generic: validation failed due to: error at "/errorCode": at '/errorCode': got number, want string +Schema: + { + "description": "The error code mapped to the error message.", + "type": "string" + } + +Value: + 14030 diff --git a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_v71_71_openapi_yaml__load b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_v71_71_openapi_yaml__load deleted file mode 100644 index 9529289ce..000000000 --- a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_v71_71_openapi_yaml__load +++ /dev/null @@ -1 +0,0 @@ -failed to unmarshal data: json error: jsontext: invalid character 'o' at start of value, yaml error: error converting YAML to JSON: yaml: line 4772: found a tab character where an indentation space is expected diff --git a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_v71_71_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_v71_71_openapi_yaml__validate new file mode 100644 index 000000000..5db7cdee5 --- /dev/null +++ b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_CheckoutService_v71_71_openapi_yaml__validate @@ -0,0 +1,9 @@ +invalid paths: invalid path /cancels: invalid operation POST: invalid example: example generic: validation failed due to: error at "/errorCode": at '/errorCode': got number, want string +Schema: + { + "description": "The error code mapped to the error message.", + "type": "string" + } + +Value: + 14030 diff --git a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_PaymentService_25_openapi_yaml__load b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_PaymentService_25_openapi_yaml__load deleted file mode 100644 index 77b330a2e..000000000 --- a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_PaymentService_25_openapi_yaml__load +++ /dev/null @@ -1 +0,0 @@ -failed to unmarshal data: json error: jsontext: invalid character 'o' at start of value, yaml error: error converting YAML to JSON: yaml: line 964: found a tab character where an indentation space is expected diff --git a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_PaymentService_30_openapi_yaml__load b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_PaymentService_30_openapi_yaml__load deleted file mode 100644 index e76554e11..000000000 --- a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_PaymentService_30_openapi_yaml__load +++ /dev/null @@ -1 +0,0 @@ -failed to unmarshal data: json error: jsontext: invalid character 'o' at start of value, yaml error: error converting YAML to JSON: yaml: line 1158: found a tab character where an indentation space is expected diff --git a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_PaymentService_40_openapi_yaml__load b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_PaymentService_40_openapi_yaml__load deleted file mode 100644 index 0d49afad8..000000000 --- a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_PaymentService_40_openapi_yaml__load +++ /dev/null @@ -1 +0,0 @@ -failed to unmarshal data: json error: jsontext: invalid character 'o' at start of value, yaml error: error converting YAML to JSON: yaml: line 1562: found a tab character where an indentation space is expected diff --git a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_PaymentService_46_openapi_yaml__load b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_PaymentService_46_openapi_yaml__load deleted file mode 100644 index 0d49afad8..000000000 --- a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_PaymentService_46_openapi_yaml__load +++ /dev/null @@ -1 +0,0 @@ -failed to unmarshal data: json error: jsontext: invalid character 'o' at start of value, yaml error: error converting YAML to JSON: yaml: line 1562: found a tab character where an indentation space is expected diff --git a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_PaymentService_49_openapi_yaml__load b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_PaymentService_49_openapi_yaml__load deleted file mode 100644 index 0d49afad8..000000000 --- a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_PaymentService_49_openapi_yaml__load +++ /dev/null @@ -1 +0,0 @@ -failed to unmarshal data: json error: jsontext: invalid character 'o' at start of value, yaml error: error converting YAML to JSON: yaml: line 1562: found a tab character where an indentation space is expected diff --git a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_PaymentService_50_openapi_yaml__load b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_PaymentService_50_openapi_yaml__load deleted file mode 100644 index ef908225a..000000000 --- a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_PaymentService_50_openapi_yaml__load +++ /dev/null @@ -1 +0,0 @@ -failed to unmarshal data: json error: jsontext: invalid character 'o' at start of value, yaml error: error converting YAML to JSON: yaml: line 1575: found a tab character where an indentation space is expected diff --git a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_PaymentService_51_openapi_yaml__load b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_PaymentService_51_openapi_yaml__load deleted file mode 100644 index ebacdebdb..000000000 --- a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_PaymentService_51_openapi_yaml__load +++ /dev/null @@ -1 +0,0 @@ -failed to unmarshal data: json error: jsontext: invalid character 'o' at start of value, yaml error: error converting YAML to JSON: yaml: line 1647: found a tab character where an indentation space is expected diff --git a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_PaymentService_52_openapi_yaml__load b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_PaymentService_52_openapi_yaml__load deleted file mode 100644 index ebacdebdb..000000000 --- a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_PaymentService_52_openapi_yaml__load +++ /dev/null @@ -1 +0,0 @@ -failed to unmarshal data: json error: jsontext: invalid character 'o' at start of value, yaml error: error converting YAML to JSON: yaml: line 1647: found a tab character where an indentation space is expected diff --git a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_PaymentService_64_openapi_yaml__load b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_PaymentService_64_openapi_yaml__load deleted file mode 100644 index ebacdebdb..000000000 --- a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_PaymentService_64_openapi_yaml__load +++ /dev/null @@ -1 +0,0 @@ -failed to unmarshal data: json error: jsontext: invalid character 'o' at start of value, yaml error: error converting YAML to JSON: yaml: line 1647: found a tab character where an indentation space is expected diff --git a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_PaymentService_67_openapi_yaml__load b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_PaymentService_67_openapi_yaml__load deleted file mode 100644 index ebacdebdb..000000000 --- a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_PaymentService_67_openapi_yaml__load +++ /dev/null @@ -1 +0,0 @@ -failed to unmarshal data: json error: jsontext: invalid character 'o' at start of value, yaml error: error converting YAML to JSON: yaml: line 1647: found a tab character where an indentation space is expected diff --git a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_PaymentService_68_openapi_yaml__load b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_PaymentService_68_openapi_yaml__load deleted file mode 100644 index 95c0d1d8c..000000000 --- a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_PaymentService_68_openapi_yaml__load +++ /dev/null @@ -1 +0,0 @@ -failed to unmarshal data: json error: jsontext: invalid character 'o' at start of value, yaml error: error converting YAML to JSON: yaml: line 1808: found a tab character where an indentation space is expected diff --git a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_PayoutService_46_openapi_yaml__load b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_PayoutService_46_openapi_yaml__load deleted file mode 100644 index ad9d6c220..000000000 --- a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_PayoutService_46_openapi_yaml__load +++ /dev/null @@ -1 +0,0 @@ -failed to unmarshal data: json error: jsontext: invalid character 'o' at start of value, yaml error: error converting YAML to JSON: yaml: line 541: found a tab character where an indentation space is expected diff --git a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_PayoutService_46_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_PayoutService_46_openapi_yaml__validate new file mode 100644 index 000000000..39c452e08 --- /dev/null +++ b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_PayoutService_46_openapi_yaml__validate @@ -0,0 +1,10 @@ +invalid components: schema "BrowserInfo": invalid default: value must be a boolean +Schema: + { + "default": "true", + "description": "Boolean value indicating if the shopper's browser is able to execute JavaScript. A default 'true' value is assumed if the field is not present.", + "type": "boolean" + } + +Value: + "true" diff --git a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_PayoutService_49_openapi_yaml__load b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_PayoutService_49_openapi_yaml__load deleted file mode 100644 index ad9d6c220..000000000 --- a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_PayoutService_49_openapi_yaml__load +++ /dev/null @@ -1 +0,0 @@ -failed to unmarshal data: json error: jsontext: invalid character 'o' at start of value, yaml error: error converting YAML to JSON: yaml: line 541: found a tab character where an indentation space is expected diff --git a/openapi3/testdata/apis_guru_openapi_directory/adyen_com_PayoutService_49_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_PayoutService_49_openapi_yaml__validate new file mode 100644 index 000000000..39c452e08 --- /dev/null +++ b/openapi3/testdata/apis_guru_openapi_directory/adyen_com_PayoutService_49_openapi_yaml__validate @@ -0,0 +1,10 @@ +invalid components: schema "BrowserInfo": invalid default: value must be a boolean +Schema: + { + "default": "true", + "description": "Boolean value indicating if the shopper's browser is able to execute JavaScript. A default 'true' value is assumed if the field is not present.", + "type": "boolean" + } + +Value: + "true" diff --git a/openapi3/testdata/apis_guru_openapi_directory/amadeus_com_amadeus_trip_parser_3_0_1_openapi_yaml__load b/openapi3/testdata/apis_guru_openapi_directory/amadeus_com_amadeus_trip_parser_3_0_1_openapi_yaml__load deleted file mode 100644 index b62a6a241..000000000 --- a/openapi3/testdata/apis_guru_openapi_directory/amadeus_com_amadeus_trip_parser_3_0_1_openapi_yaml__load +++ /dev/null @@ -1 +0,0 @@ -failed to unmarshal data: json error: jsontext: invalid character 'o' at start of value, yaml error: error converting YAML to JSON: yaml: line 275: found a tab character where an indentation space is expected diff --git a/openapi3/testdata/apis_guru_openapi_directory/amadeus_com_amadeus_trip_parser_3_0_1_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/amadeus_com_amadeus_trip_parser_3_0_1_openapi_yaml__validate new file mode 100644 index 000000000..492e1e113 --- /dev/null +++ b/openapi3/testdata/apis_guru_openapi_directory/amadeus_com_amadeus_trip_parser_3_0_1_openapi_yaml__validate @@ -0,0 +1,11 @@ +invalid components: schema "car": invalid example: string doesn't match the regular expression "{0-9]{1,15}" +Schema: + { + "description": "Phone number. Composed of digits only. The number of digits depends on the country.", + "example": "0336123123", + "pattern": "{0-9]{1,15}", + "type": "string" + } + +Value: + "0336123123" diff --git a/openapi3/testdata/apis_guru_openapi_directory/codat_io_accounting_2_1_0_openapi_yaml__load b/openapi3/testdata/apis_guru_openapi_directory/codat_io_accounting_2_1_0_openapi_yaml__load index 726d322af..1161b0993 100644 --- a/openapi3/testdata/apis_guru_openapi_directory/codat_io_accounting_2_1_0_openapi_yaml__load +++ b/openapi3/testdata/apis_guru_openapi_directory/codat_io_accounting_2_1_0_openapi_yaml__load @@ -1 +1 @@ -failed to unmarshal data: json error: jsontext: invalid character 'o' at start of value, yaml error: error converting YAML to JSON: yaml: line 43981: found a tab character where an indentation space is expected +bad data in "#/components/schemas/Item/definitions/itemType" (expecting ref to schema object) diff --git a/openapi3/testdata/fuzz/FuzzLoadFromData/merge-unhashable-key b/openapi3/testdata/fuzz/FuzzLoadFromData/merge-unhashable-key new file mode 100644 index 000000000..2cc7d6efd --- /dev/null +++ b/openapi3/testdata/fuzz/FuzzLoadFromData/merge-unhashable-key @@ -0,0 +1,2 @@ +go test fuzz v1 +[]byte("<<:\n ? [1]\n : v\n1: x\n") diff --git a/openapi3/testdata/fuzz/FuzzLoadWithOrigins/explicit-key-no-value b/openapi3/testdata/fuzz/FuzzLoadWithOrigins/explicit-key-no-value new file mode 100644 index 000000000..61659bf59 --- /dev/null +++ b/openapi3/testdata/fuzz/FuzzLoadWithOrigins/explicit-key-no-value @@ -0,0 +1,2 @@ +go test fuzz v1 +[]byte("? 00") From f074d9a7f4979a9979af603a881a2710b70bd620 Mon Sep 17 00:00:00 2001 From: Luis Figueroa <62305361+LuisFigueroaG@users.noreply.github.com> Date: Thu, 29 Oct 2026 05:13:25 -0300 Subject: [PATCH 25/78] openapi3: validate the pattern of a schema without type in Schema.Validate (#1398) --- README.md | 1 + openapi3/schema.go | 21 ++++++++------ openapi3/validation_error_test.go | 48 +++++++++++++++++++++++++++++++ 3 files changed, 61 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 0c997f735..f366e42cb 100644 --- a/README.md +++ b/README.md @@ -332,6 +332,7 @@ for _, path := range doc.Paths.InMatchingOrder() { ### v0.153.0 * `openapi3filter` now parses `number` values of parameters and `application/x-www-form-urlencoded`/`multipart/form-data` bodies as decimal numbers only, so Go float literals such as `0x1p4`, `1_000`, `Inf`, `-infinity` or `NaN` are now rejected as invalid numbers. * `(*openapi3.Schema).Validate(..)` (hence `(*openapi3.T).Validate(..)`) now rejects a `multipleOf` of zero or less (`openapi3.SchemaMultipleOfNotPositiveError`), as JSON Schema requires it to be strictly greater than 0. Such a schema used to pass validation and then reject every value with `multipleOf must be greater than zero`. +* `(*openapi3.Schema).Validate(..)` now also compiles the `pattern` of a schema without `type`, as it does for `type: string`, and rejects one that does not compile with `openapi3.SchemaPatternRegexError`. Such a schema used to pass validation and then fail on every string value it was given. ### v0.152.0 * JSON keys of OpenAPI documents only fill the field of the same case (`json:",case:strict"`) when `encoding/json` is implemented with `encoding/json/v2` (by default from Go 1.27, and on Go 1.25 and 1.26 with `GOEXPERIMENT=jsonv2`): a key such as `"Components"` (not `"components"`) is kept as an extension instead of filling `openapi3.T.Components`. Other builds still match keys case-insensitively, as `encoding/json` v1 does. diff --git a/openapi3/schema.go b/openapi3/schema.go index 79dcad465..892556af3 100644 --- a/openapi3/schema.go +++ b/openapi3/schema.go @@ -1861,15 +1861,6 @@ func (schema *Schema) validate(ctx context.Context, visited map[*Schema]struct{} } } } - if !validationOpts.schemaPatternValidationDisabled && schema.Pattern != "" { - // Only successfully compiled patterns are cached. - // The cache does not record which compiler was used, so a custom one always compiles. - if _, ok := compiledPatterns.Load(schema.Pattern); !ok || validationOpts.regexCompilerFunc != nil { - if _, err := schema.compilePattern(nil, validationOpts.regexCompilerFunc); err != nil { - return visited, err - } - } - } case TypeArray: if schema.Items == nil && !validationOpts.jsonSchema2020ValidationEnabled && len(schema.PrefixItems) == 0 { return visited, newSchemaItemsRequired(schema.Origin) @@ -1884,6 +1875,18 @@ func (schema *Schema) validate(ctx context.Context, visited map[*Schema]struct{} } } + // `pattern` applies to every string value, also when `type` is omitted. + if !validationOpts.schemaPatternValidationDisabled && schema.Pattern != "" && + (schema.Type.IsEmpty() || schema.Type.Includes(TypeString)) { + // Only successfully compiled patterns are cached. + // The cache does not record which compiler was used, so a custom one always compiles. + if _, ok := compiledPatterns.Load(schema.Pattern); !ok || validationOpts.regexCompilerFunc != nil { + if _, err := schema.compilePattern(nil, validationOpts.regexCompilerFunc); err != nil { + return visited, err + } + } + } + if ref := schema.Items; ref != nil { if err := ref.validateExtras(ctx); err != nil { return visited, err diff --git a/openapi3/validation_error_test.go b/openapi3/validation_error_test.go index 2c96d83ef..1588dcf6d 100644 --- a/openapi3/validation_error_test.go +++ b/openapi3/validation_error_test.go @@ -1317,6 +1317,54 @@ components: require.Equal(t, "pattern", se.SchemaField) } +// `pattern` applies to string values whether or not `type` says string, so +// an uncompilable one is rejected on any schema that accepts strings. +func TestValidationError_SchemaPatternRegex_WithoutStringType(t *testing.T) { + t.Parallel() + + for _, tc := range []struct { + version string + typ string + }{ + {version: "3.0.3"}, + {version: "3.1.0"}, + {version: "3.1.0", typ: "type: [string, 'null']"}, + {version: "3.1.0", typ: "type: [integer, string]"}, + } { + t.Run(tc.version+" "+tc.typ, func(t *testing.T) { + doc := loadDocFromYAML(t, ` +openapi: `+tc.version+` +info: { title: t, version: "1" } +paths: {} +components: + schemas: + Bad: + `+tc.typ+` + pattern: "(?!foo)bar" +`) + err := doc.Validate(t.Context()) + require.Error(t, err) + + var spre *openapi3.SchemaPatternRegexError + require.True(t, errors.As(err, &spre)) + require.Equal(t, "(?!foo)bar", spre.Pattern) + }) + } + + // A schema that never sees a string never runs its pattern. + doc := loadDocFromYAML(t, ` +openapi: 3.0.3 +info: { title: t, version: "1" } +paths: {} +components: + schemas: + Number: + type: integer + pattern: "(?!foo)bar" +`) + require.NoError(t, doc.Validate(t.Context())) +} + // Origin tracking for SchemaPatternRegexError. func TestValidationError_SchemaPatternRegex_CarriesOrigin(t *testing.T) { t.Parallel() From f58588be4df051bc721fcbce4a1ca8f5bde9cc9c Mon Sep 17 00:00:00 2001 From: Luis Figueroa <62305361+LuisFigueroaG@users.noreply.github.com> Date: Thu, 29 Oct 2026 09:40:38 -0300 Subject: [PATCH 26/78] openapi3: set maxLength in Schema.WithMaxLengthDecodedBase64 (#1401) --- README.md | 1 + openapi3/schema.go | 3 ++- openapi3/schema_test.go | 38 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 41 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index f366e42cb..610de68e5 100644 --- a/README.md +++ b/README.md @@ -333,6 +333,7 @@ for _, path := range doc.Paths.InMatchingOrder() { * `openapi3filter` now parses `number` values of parameters and `application/x-www-form-urlencoded`/`multipart/form-data` bodies as decimal numbers only, so Go float literals such as `0x1p4`, `1_000`, `Inf`, `-infinity` or `NaN` are now rejected as invalid numbers. * `(*openapi3.Schema).Validate(..)` (hence `(*openapi3.T).Validate(..)`) now rejects a `multipleOf` of zero or less (`openapi3.SchemaMultipleOfNotPositiveError`), as JSON Schema requires it to be strictly greater than 0. Such a schema used to pass validation and then reject every value with `multipleOf must be greater than zero`. * `(*openapi3.Schema).Validate(..)` now also compiles the `pattern` of a schema without `type`, as it does for `type: string`, and rejects one that does not compile with `openapi3.SchemaPatternRegexError`. Such a schema used to pass validation and then fail on every string value it was given. +* `(*openapi3.Schema).WithMaxLengthDecodedBase64(..)` now sets `maxLength`. It used to set `minLength` instead, overwriting any minimum and leaving the length unbounded. ### v0.152.0 * JSON keys of OpenAPI documents only fill the field of the same case (`json:",case:strict"`) when `encoding/json` is implemented with `encoding/json/v2` (by default from Go 1.27, and on Go 1.25 and 1.26 with `GOEXPERIMENT=jsonv2`): a key such as `"Components"` (not `"components"`) is kept as an extension instead of filling `openapi3.T.Components`. Other builds still match keys case-insensitively, as `encoding/json` v1 does. diff --git a/openapi3/schema.go b/openapi3/schema.go index 892556af3..e01f5d7ba 100644 --- a/openapi3/schema.go +++ b/openapi3/schema.go @@ -1284,7 +1284,8 @@ func (schema *Schema) WithMinLengthDecodedBase64(i int64) *Schema { func (schema *Schema) WithMaxLengthDecodedBase64(i int64) *Schema { n := uint64(i) - schema.MinLength = (n*8 + 5) / 6 + v := (n*8 + 5) / 6 + schema.MaxLength = &v return schema } diff --git a/openapi3/schema_test.go b/openapi3/schema_test.go index 805b85431..65abc3fbe 100644 --- a/openapi3/schema_test.go +++ b/openapi3/schema_test.go @@ -1651,3 +1651,41 @@ func TestSchemaMultipleOfAcrossMagnitudes(t *testing.T) { require.Equal(t, "number must be a multiple of 0.01", schemaErr.Reason) }) } + +func TestSchemaLengthDecodedBase64(t *testing.T) { + t.Parallel() + + encoded := func(n int) string { return base64.RawStdEncoding.EncodeToString(make([]byte, n)) } + + t.Run("min", func(t *testing.T) { + schema := NewBytesSchema().WithMinLengthDecodedBase64(3) + require.Equal(t, uint64(4), schema.MinLength) + require.Nil(t, schema.MaxLength) + require.NoError(t, schema.VisitJSON(encoded(3))) + require.ErrorContains(t, schema.VisitJSON(encoded(2)), "minimum string length is 4") + }) + + t.Run("max", func(t *testing.T) { + schema := NewBytesSchema().WithMaxLengthDecodedBase64(3) + require.Zero(t, schema.MinLength) + require.NotNil(t, schema.MaxLength) + require.Equal(t, uint64(4), *schema.MaxLength) + require.NoError(t, schema.VisitJSON(encoded(3))) + require.NoError(t, schema.VisitJSON("")) + require.ErrorContains(t, schema.VisitJSON(encoded(6)), "maximum string length is 4") + }) + + t.Run("min and max", func(t *testing.T) { + schema := NewBytesSchema().WithMinLengthDecodedBase64(1).WithMaxLengthDecodedBase64(3) + require.Equal(t, uint64(2), schema.MinLength) + require.NotNil(t, schema.MaxLength) + require.Equal(t, uint64(4), *schema.MaxLength) + }) + + t.Run("exact", func(t *testing.T) { + schema := NewBytesSchema().WithLengthDecodedBase64(3) + require.Equal(t, uint64(4), schema.MinLength) + require.NotNil(t, schema.MaxLength) + require.Equal(t, uint64(4), *schema.MaxLength) + }) +} From aaf4e27ba69d3e024dca757bdc452fc93bae9950 Mon Sep 17 00:00:00 2001 From: Pierre Fenoll Date: Thu, 29 Oct 2026 18:43:27 +0100 Subject: [PATCH 27/78] openapi2conv: FromV3 no longer turns a binary header into a form field (#1403) --- openapi2conv/binary_parameter_test.go | 92 +++++++++++++++++++ openapi2conv/from_v3_parameter_test.go | 32 ++++++- openapi2conv/openapi2_conv.go | 36 +++++++- .../FuzzToV3/binary-param-outside-formdata | 2 + openapi3/schema_test.go | 2 +- 5 files changed, 161 insertions(+), 3 deletions(-) create mode 100644 openapi2conv/binary_parameter_test.go create mode 100644 openapi2conv/testdata/fuzz/FuzzToV3/binary-param-outside-formdata diff --git a/openapi2conv/binary_parameter_test.go b/openapi2conv/binary_parameter_test.go new file mode 100644 index 000000000..b66a29e89 --- /dev/null +++ b/openapi2conv/binary_parameter_test.go @@ -0,0 +1,92 @@ +package openapi2conv_test + +import ( + "encoding/json" + "testing" + + "github.com/stretchr/testify/require" + + "github.com/getkin/kin-openapi/openapi2" + "github.com/getkin/kin-openapi/openapi2conv" + "github.com/getkin/kin-openapi/openapi3" +) + +// A binary schema outside formData used to come back from FromV3 as an +// unnamed formData file, so a header became a form field and a round trip +// lost the parameter altogether. +func TestBinaryParameterOutsideFormData(t *testing.T) { + t.Parallel() + + t.Run("v3 header and response header", func(t *testing.T) { + t.Parallel() + + spec := []byte(`{ + "openapi": "3.0.3", + "info": {"title": "t", "version": "1"}, + "paths": {"/f": {"get": { + "parameters": [{"in": "header", "name": "X-Blob", "required": true, "schema": {"type": "string", "format": "binary"}}], + "responses": {"200": { + "description": "ok", + "headers": {"X-Blob": {"schema": {"type": "string", "format": "binary"}}} + }} + }}} +}`) + loader := openapi3.NewLoader() + doc3, err := loader.LoadFromData(spec) + require.NoError(t, err) + + doc2, err := openapi2conv.FromV3(doc3) + require.NoError(t, err) + op := doc2.Paths["/f"].Get + require.Len(t, op.Parameters, 1) + require.Equal(t, &openapi2.Parameter{ + In: "header", + Name: "X-Blob", + Required: true, + Type: &openapi3.Types{"string"}, + Format: "binary", + }, op.Parameters[0]) + header := op.Responses.Value("200").Headers["X-Blob"] + require.NotNil(t, header) + require.Equal(t, &openapi3.Types{"string"}, header.Type) + require.Equal(t, "binary", header.Format) + + back3, err := openapi2conv.ToV3(doc2) + require.NoError(t, err) + param := back3.Paths.Value("/f").Get.Parameters[0].Value + require.Equal(t, "header", param.In) + require.Equal(t, "X-Blob", param.Name) + require.True(t, param.Required) + require.Equal(t, "binary", param.Schema.Value.Format) + require.Nil(t, back3.Paths.Value("/f").Get.RequestBody) + }) + + t.Run("v2 file outside formData round-trips", func(t *testing.T) { + t.Parallel() + + spec := []byte(`{"swagger":"2.0","paths":{"/f":{"post":{ + "consumes":["multipart/form-data"], + "parameters":[{"in":"firmData","name":"file","type":"file"}], + "responses":{"200":{"description":"ok"}} +}}}}`) + var doc2 openapi2.T + require.NoError(t, json.Unmarshal(spec, &doc2)) + + roundTrip := func(doc *openapi3.T) []byte { + back2, err := openapi2conv.FromV3(doc) + require.NoError(t, err) + next3, err := openapi2conv.ToV3(back2) + require.NoError(t, err) + data, err := json.Marshal(next3) + require.NoError(t, err) + return data + } + + doc3, err := openapi2conv.ToV3(&doc2) + require.NoError(t, err) + first, err := json.Marshal(doc3) + require.NoError(t, err) + once := roundTrip(doc3) + require.JSONEq(t, string(first), string(once)) + }) +} diff --git a/openapi2conv/from_v3_parameter_test.go b/openapi2conv/from_v3_parameter_test.go index 794618580..21e6954cb 100644 --- a/openapi2conv/from_v3_parameter_test.go +++ b/openapi2conv/from_v3_parameter_test.go @@ -26,7 +26,37 @@ func TestFromV3ParameterSchemas(t *testing.T) { }} got, err := openapi2conv.FromV3Parameter(param, components) require.NoError(t, err) - require.Equal(t, &openapi2.Parameter{Ref: "#/parameters/File"}, got) + require.Equal(t, &openapi2.Parameter{ + Name: "file", + In: "query", + Type: &openapi3.Types{"string"}, + Format: "binary", + }, got) + }) + + t.Run("binary header keeps its location and name", func(t *testing.T) { + t.Parallel() + + param := &openapi3.ParameterRef{Value: &openapi3.Parameter{ + Name: "X-Blob", + In: "header", + Required: true, + Schema: &openapi3.SchemaRef{Value: &openapi3.Schema{ + Type: &openapi3.Types{"string"}, + Format: "binary", + MaxLength: openapi3.Ptr(uint64(64)), + }}, + }} + got, err := openapi2conv.FromV3Parameter(param, nil) + require.NoError(t, err) + require.Equal(t, &openapi2.Parameter{ + Name: "X-Blob", + In: "header", + Required: true, + Type: &openapi3.Types{"string"}, + Format: "binary", + MaxLength: openapi3.Ptr(uint64(64)), + }, got) }) t.Run("schema without a value", func(t *testing.T) { diff --git a/openapi2conv/openapi2_conv.go b/openapi2conv/openapi2_conv.go index 954534f6a..ba8dfb8de 100644 --- a/openapi2conv/openapi2_conv.go +++ b/openapi2conv/openapi2_conv.go @@ -1306,7 +1306,13 @@ func FromV3Parameter(ref *openapi3.ParameterRef, components *openapi3.Components if schemaRef := parameter.Schema; schemaRef != nil { schemaRefV2, parameterV2 := FromV3SchemaRef(schemaRef, components) if schemaRefV2 == nil { - return parameterV2, nil + if parameter.In == "formData" { + return parameterV2, nil + } + // A binary schema converts to a formData file, which only a + // request body property may become. Anywhere else the parameter + // keeps its location and name and stays a binary string. + return fromV3BinaryParameter(result, schemaRef, components), nil } if ref := schemaRefV2.Ref; ref != "" { result.Schema = &openapi2.SchemaRef{Ref: FromV3Ref(ref)} @@ -1340,6 +1346,34 @@ func FromV3Parameter(ref *openapi3.ParameterRef, components *openapi3.Components return result, nil } +// fromV3BinaryParameter fills result, a parameter outside formData, from its +// binary schema. Swagger 2.0 allows type file only in formData, so the schema +// is kept as a string of format binary. +func fromV3BinaryParameter(result *openapi2.Parameter, schemaRef *openapi3.SchemaRef, components *openapi3.Components) *openapi2.Parameter { + schema := schemaRef.Value + if schema == nil && components != nil { + if val, ok := components.Schemas[getParameterNameFromNewRef(schemaRef.Ref)]; ok && val != nil { + schema = val.Value + } + } + result.Type = &openapi3.Types{"string"} + result.Format = "binary" + if schema == nil { + return result + } + result.Enum = schema.Enum + result.Minimum = effectiveMin(schema.Min, schema.ExclusiveMin) + result.Maximum = effectiveMax(schema.Max, schema.ExclusiveMax) + result.ExclusiveMin = exclusiveBoundToBool(schema.ExclusiveMin) + result.ExclusiveMax = exclusiveBoundToBool(schema.ExclusiveMax) + result.MinLength = schema.MinLength + result.MaxLength = schema.MaxLength + result.Pattern = schema.Pattern + result.Default = schema.Default + result.AllowEmptyValue = schema.AllowEmptyValue + return result +} + // fromV3QueryStyle maps a query parameter's explicit style and explode to the equivalent collectionFormat. func fromV3QueryStyle(parameter *openapi3.Parameter) string { if parameter.Style == "" && parameter.Explode == nil { diff --git a/openapi2conv/testdata/fuzz/FuzzToV3/binary-param-outside-formdata b/openapi2conv/testdata/fuzz/FuzzToV3/binary-param-outside-formdata new file mode 100644 index 000000000..03d4a10dd --- /dev/null +++ b/openapi2conv/testdata/fuzz/FuzzToV3/binary-param-outside-formdata @@ -0,0 +1,2 @@ +go test fuzz v1 +[]byte("{\"definitions\":{\"CollectionLinks\":{\"example\":{\"\":\"\"},\"properties\":{\"s\":{\"$ref\":\"#/definitions/CollectionLinks\"}},\"title\":\"\"},\"Error\":{\"properties\":{\"\":{\"description\":\"\",\"type\":\"integer\"},\"l\":{\"description\":\"’\",\"type\":\"string\"},\"n\":{\"description\":\"\",\"format\":\"\",\"type\":\"string\"},\"e\":{\"$ref\":\"#/definitions/ErrorSource\"},\"s\":{\"description\":\"\",\"type\":\"integer\"},\"title\":{\"description\":\"\",\"type\":\"string\"}},\"required\":[\"status\",\"code\",\"title\"]},\"Error400\":{\"properties\":{\"\":{\"items\":{\"$ref\":\"#/definitions/Error\"},\"type\":\"array\"}},\"required\":[\"\"]},\"Error401\":{\"example\":{\"errors\":[{\"code\":0,\"l\":\"\",\"status\":4,\"title\":\"\"}]},\"properties\":{\"errors\":{\"items\":{\"$ref\":\"#/definitions/Error\"},\"type\":\"array\"}},\"required\":[\"errors\"]},\"Error500\":{\"\":{\"\":[{\"\":1,\"s\":5,\"e\":\"\"}]},\"s\":{\"\":{\"\":{\"\":\"\"},\"e\":\"\"}},\"d\":[\"\"]},\"ErrorSource\":{\"properties\":{\"\":{\"description\":\"\",\"type\":\"string\"},\"r\":{\"description\":\"\",\"type\":\"string\"},\"e\":{\"description\":\"\",\"type\":\"string\"}}},\"HotelSentiment\":{\"\":{\"\":{\"\":\"\",\"e\":\"\",\"p\":\"\"},\"s\":{\"\":0,\"e\":\"\"},\"w\":{\"\":2,\"e\":\"\"},\"g\":{\"\":\"\"},\"t\":{\"\":\"\",\"s\":{\"\":{\"\":\"\"},\"s\":{\"\":\"\"},\"t\":{\"\":\"\"},\"n\":{\"\":\"\"},\"st\":{\"\":\"\"},\"ts\":{\"\":\"\"},\"e\":{\"\":\"\"},\"y\":{\"\":\"\"},\"f\":{\"\":\"\"},\"l\":{\"\":\"\"},\"ey\":{\"\":\"\"}},\"e\":\"\"},\"e\":{\"\":\"\",\"e\":\"\"}},\"d\":[\"\",\"\",\"\",\"\",\"\"],\"e\":\"\"},\"e\":{\"\":\"\",\"e\":2,\"p\":\"\"},\"Warning\":{\"\":{\"\":{\"\":\"\",\"e\":\"\"},\"l\":{\"\":\"’\",\"e\":\"\"},\"n\":{\"\":\"\",\"t\":\"\",\"e\":\"\"},\"e\":{\"\":\"\"},\"le\":{\"\":\"\",\"e\":\"\"}},\"d\":[\"\",\"\"]},\"WarningNotFound\":{\"\":[{\"\":\"\"}],\"e\":{\"\":3,\"l\":\"\",\"e\":{\"\":\"\",\"r\":\"\"},\"le\":\"\"}}},\"t\":\"\",\"o\":{\"\":\"\",\"e\":\"\",\"n\":\"\",\"o\":{\"\":\"\"},\"i\":[{\"\":\"\",\"l\":\"\",\"n\":\"\"}],\"m\":\"\",\"me\":\"\"},\"s\":{\"\":{\"\":{\"\":\"\",\"d\":\"\",\"s\":[{\"\":\"\",\"n\":\"\",\"s\":{\"\":\"\"},\"m\":1,\"ms\":1,\"e\":\"\",\"d\":true,\"p\":\"\",\"l\":[\"\"]}],\"e\":{\"\":{\"\":\"\"},\"0\":{\"\":\"\"},\"1\":{\"\":\"\"},\"t\":{\"\":\"\"}},\"y\":\"\",\"g\":[\"\"]}}},\"e\":[\"\"],\"es\":{\"\":{\"\":\"\",\"a\":{\"\":\"\"}},\"1\":{\"\":\"\",\"a\":{\"\":\"\"}},\"0\":{\"\":\"\",\"a\":{\"\":\"\"}},\"s\":{\"\":\"\",\"a\":{\"\":{\"\":[{\"\":\"\",\"s\":8,\"w\":8,\"g\":3,\"t\":{\"\":9,\"s\":0,\"n\":8,\"t\":1,\"ts\":2,\"e\":8,\"y\":7,\"f\":1,\"ey\":7},\"e\":\"\"},{\"\":\"\",\"s\":6,\"w\":7,\"g\":1,\"t\":{\"\":1,\"s\":5,\"t\":2,\"n\":9,\"st\":1,\"ts\":7,\"e\":0,\"y\":8,\"f\":9,\"ey\":5},\"e\":\"\"}],\"a\":{\"\":1,\"s\":{\"\":\"\"}},\"s\":[{\"\":3,\"l\":\"\",\"e\":{\"\":\"\",\"r\":\"\"},\"le\":\"\"}]},\"s\":{\"\":{\"\":{\"\":\"\"},\"e\":\"\"},\"a\":{\"\":\"\"},\"s\":{\"\":{\"\":\"\"},\"e\":\"\"}},\"d\":[\"\"],\"e\":\"\"}}},\"m\":[\"\"],\"r\":\"\",\"g\":[{\"\":\"\",\"e\":\"\"}]{") diff --git a/openapi3/schema_test.go b/openapi3/schema_test.go index 65abc3fbe..014716b33 100644 --- a/openapi3/schema_test.go +++ b/openapi3/schema_test.go @@ -1655,7 +1655,7 @@ func TestSchemaMultipleOfAcrossMagnitudes(t *testing.T) { func TestSchemaLengthDecodedBase64(t *testing.T) { t.Parallel() - encoded := func(n int) string { return base64.RawStdEncoding.EncodeToString(make([]byte, n)) } + encoded := func(n int) string { return base64.RawStdEncoding.EncodeToString(make([]byte /*,*/, n)) } t.Run("min", func(t *testing.T) { schema := NewBytesSchema().WithMinLengthDecodedBase64(3) From 3fbcfc9cc81bb9e8bdbea5ee984b2cc535301462 Mon Sep 17 00:00:00 2001 From: Kashif Manzer <101617606+KashifManzer@users.noreply.github.com> Date: Fri, 30 Oct 2026 04:01:28 -0400 Subject: [PATCH 28/78] openapi3: internalize webhook references (#1408) --- openapi3/internalize_refs.go | 1 + openapi3/issue1392_test.go | 169 +++++++++++++++++++++++++++++++++++ 2 files changed, 170 insertions(+) create mode 100644 openapi3/issue1392_test.go diff --git a/openapi3/internalize_refs.go b/openapi3/internalize_refs.go index dbed548a2..fd8c18fbc 100644 --- a/openapi3/internalize_refs.go +++ b/openapi3/internalize_refs.go @@ -561,4 +561,5 @@ func (doc *T) InternalizeRefs(ctx context.Context, refNameResolver func(*T, Comp } doc.derefPaths(doc.Paths.Map(), refNameResolver, false) + doc.derefPaths(doc.Webhooks, refNameResolver, false) } diff --git a/openapi3/issue1392_test.go b/openapi3/issue1392_test.go new file mode 100644 index 000000000..61d3192e0 --- /dev/null +++ b/openapi3/issue1392_test.go @@ -0,0 +1,169 @@ +package openapi3_test + +import ( + "os" + "path/filepath" + "testing" + + "github.com/stretchr/testify/require" + + "github.com/getkin/kin-openapi/openapi3" +) + +func TestInternalizeRefsWebhooks(t *testing.T) { + t.Parallel() + + const operation = ` +post: + requestBody: + content: + application/json: + schema: + $ref: ./Item.yaml + responses: + '200': + description: OK +` + for _, test := range []struct { + name string + document string + schemaName string + }{ + { + name: "external path control", + document: `paths: + /ping: + $ref: ./ping.yaml +`, + schemaName: "Item", + }, + { + name: "external webhook without paths", + document: `webhooks: + ping: + $ref: ./ping.yaml +`, + schemaName: "Item", + }, + { + name: "inline webhook", + document: `paths: {} +webhooks: + ping: + post: + requestBody: + content: + application/json: + schema: + $ref: ./Item.yaml + responses: + '200': + description: OK +`, + schemaName: "Item", + }, + { + name: "external webhook with local component reference", + document: `webhooks: + ping: + $ref: ./external.yaml#/paths/~1ping +`, + schemaName: "external_Item", + }, + { + name: "path and webhook sharing references", + document: `paths: + /ping: + $ref: ./ping.yaml +webhooks: + ping: + $ref: ./ping.yaml +`, + schemaName: "Item", + }, + } { + for _, prefix := range []string{"", "custom_"} { + t.Run(test.name+"/"+prefix, func(t *testing.T) { + t.Parallel() + dir := t.TempDir() + for name, content := range map[string]string{ + "root.yaml": "openapi: 3.1.0\ninfo: {title: t, version: '1'}\n" + test.document, + "ping.yaml": operation, + "Item.yaml": "type: object\nproperties:\n child:\n $ref: ./Child.yaml\n", + "Child.yaml": "type: integer\n", + "external.yaml": `openapi: 3.1.0 +info: {title: external, version: '1'} +paths: + /ping: + post: + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Item' + responses: + '200': + description: OK +components: + schemas: + Item: + type: object + properties: + child: + $ref: ./Child.yaml +`, + } { + require.NoError(t, os.WriteFile(filepath.Join(dir, name), []byte(content), 0o600)) + } + + loader := openapi3.NewLoader() + loader.IsExternalRefsAllowed = true + doc, err := loader.LoadFromFile(filepath.Join(dir, "root.yaml")) + require.NoError(t, err) + require.NoError(t, doc.Validate(t.Context())) + + var resolver openapi3.RefNameResolver + if prefix != "" { + resolver = func(doc *openapi3.T, ref openapi3.ComponentRef) string { + return prefix + openapi3.DefaultRefNameResolver(doc, ref) + } + } + doc.InternalizeRefs(t.Context(), resolver) + require.NoError(t, doc.Validate(t.Context())) + + for _, item := range []*openapi3.PathItem{doc.Webhooks["ping"], doc.Paths.Value("/ping")} { + if item == nil { + continue + } + require.Empty(t, item.Ref) + schema := item.Post.RequestBody.Value.Content["application/json"].Schema + require.Equal(t, "#/components/schemas/"+prefix+test.schemaName, schema.Ref) + require.Equal(t, schema.Value, doc.Components.Schemas[prefix+test.schemaName].Value) + require.Equal(t, "#/components/schemas/"+prefix+"Child", schema.Value.Properties["child"].Ref) + } + require.Len(t, doc.Components.Schemas, 2) + + data, err := doc.MarshalJSON() + require.NoError(t, err) + loader = openapi3.NewLoader() + reloaded, err := loader.LoadFromData(data) + require.NoError(t, err, "internalized webhooks must not require external access") + require.NoError(t, reloaded.Validate(t.Context())) + + doc.InternalizeRefs(t.Context(), resolver) + again, err := doc.MarshalJSON() + require.NoError(t, err) + require.JSONEq(t, string(data), string(again)) + }) + } + } +} + +func TestInternalizeRefsEmptyWebhooks(t *testing.T) { + t.Parallel() + for _, webhooks := range []map[string]*openapi3.PathItem{nil, {}} { + doc := &openapi3.T{Webhooks: webhooks} + require.NotPanics(t, func() { doc.InternalizeRefs(t.Context(), nil) }) + require.Nil(t, doc.Components) + } +} From 5aa7973e40d8f0b3b2335e4548378f3660cdf103 Mon Sep 17 00:00:00 2001 From: Reuven Harrison Date: Fri, 30 Oct 2026 10:03:39 +0200 Subject: [PATCH 29/78] openapi2conv: keep required and format on a converted form field (#1405) Co-authored-by: Claude Opus 5 --- openapi2conv/form_data_test.go | 122 +++++++++++++++++++++++++++++ openapi2conv/openapi2_conv.go | 42 ++++++++-- openapi2conv/openapi2_conv_test.go | 4 +- 3 files changed, 158 insertions(+), 10 deletions(-) create mode 100644 openapi2conv/form_data_test.go diff --git a/openapi2conv/form_data_test.go b/openapi2conv/form_data_test.go new file mode 100644 index 000000000..9dad4434b --- /dev/null +++ b/openapi2conv/form_data_test.go @@ -0,0 +1,122 @@ +package openapi2conv_test + +import ( + "encoding/json" + "testing" + + "github.com/stretchr/testify/require" + + "github.com/getkin/kin-openapi/openapi2" + "github.com/getkin/kin-openapi/openapi2conv" + "github.com/getkin/kin-openapi/openapi3" +) + +const formDataSpecV2 = `{ + "swagger": "2.0", + "info": {"title": "Example", "version": "1"}, + "paths": { + "/upload": { + "post": { + "consumes": ["multipart/form-data"], + "parameters": [ + {"name": "file", "in": "formData", "type": "file", "required": true}, + {"name": "taken", "in": "formData", "type": "string", "format": "date"}, + {"name": "note", "in": "formData", "type": "string"} + ], + "responses": {"200": {"description": "OK"}} + } + } + } +}` + +func formDataParams(t *testing.T, doc2 *openapi2.T) map[string]*openapi2.Parameter { + t.Helper() + + byName := map[string]*openapi2.Parameter{} + for _, parameter := range doc2.Paths["/upload"].Post.Parameters { + require.Equal(t, "formData", parameter.In) + byName[parameter.Name] = parameter + } + return byName +} + +// TestFormDataRoundTrip covers the fields of a form field that the conversion +// back from OpenAPI 3 used to drop: whether the field is required, which is +// recorded on the object holding the properties, and its format. +func TestFormDataRoundTrip(t *testing.T) { + t.Parallel() + + var doc2 openapi2.T + require.NoError(t, json.Unmarshal([]byte(formDataSpecV2), &doc2)) + + doc3, err := openapi2conv.ToV3(&doc2) + require.NoError(t, err) + + // The required field is named on the object, as OpenAPI 3 requires. + body := doc3.Paths.Value("/upload").Post.RequestBody.Value + require.Equal(t, []string{"file"}, body.Content["multipart/form-data"].Schema.Value.Required) + + back, err := openapi2conv.FromV3(doc3) + require.NoError(t, err) + params := formDataParams(t, back) + require.Len(t, params, 3) + + require.True(t, params["file"].Required, "a required upload stays required") + require.Equal(t, &openapi3.Types{"file"}, params["file"].Type) + require.Empty(t, params["file"].Format, "type file spends the format naming the type") + + require.Equal(t, "date", params["taken"].Format, "a format on a form field survives") + require.Equal(t, &openapi3.Types{"string"}, params["taken"].Type) + require.False(t, params["taken"].Required) + + require.Empty(t, params["note"].Format) + require.False(t, params["note"].Required) +} + +// TestFormDataRequiredOnTheObject pins that required is read from the object +// holding the properties, which is where a document not written by this +// package records it. +func TestFormDataRequiredOnTheObject(t *testing.T) { + t.Parallel() + + mediaType := &openapi3.MediaType{Schema: &openapi3.SchemaRef{Value: &openapi3.Schema{ + Type: &openapi3.Types{"object"}, + Required: []string{"file"}, + Properties: openapi3.Schemas{ + "file": {Value: &openapi3.Schema{Type: &openapi3.Types{"string"}, Format: "binary"}}, + "note": {Value: &openapi3.Schema{Type: &openapi3.Types{"string"}}}, + }, + }}} + + byName := map[string]*openapi2.Parameter{} + for _, parameter := range openapi2conv.FromV3RequestBodyFormData(mediaType) { + byName[parameter.Name] = parameter + } + require.True(t, byName["file"].Required) + require.False(t, byName["note"].Required) +} + +// TestFormDataNameMarkerStaysInternal pins that x-formData-name, which carries +// the field name into OpenAPI 3 where it has nowhere else to live, does not +// come back out in the converted document, and that converting leaves the +// schema it was read from as it was. +func TestFormDataNameMarkerStaysInternal(t *testing.T) { + t.Parallel() + + extensions := map[string]any{"x-formData-name": "file", "x-mimetype": "text/plain", "unknown": true} + schema := &openapi3.Schema{ + Type: &openapi3.Types{"string"}, + Format: "binary", + Extensions: extensions, + } + mediaType := &openapi3.MediaType{Schema: &openapi3.SchemaRef{Value: &openapi3.Schema{ + Type: &openapi3.Types{"object"}, + Properties: openapi3.Schemas{"file": {Value: schema}}, + }}} + + params := openapi2conv.FromV3RequestBodyFormData(mediaType) + require.Len(t, params, 1) + require.Equal(t, map[string]any{"x-mimetype": "text/plain"}, params[0].Extensions) + + require.Equal(t, extensions, schema.Extensions, "the schema keeps its own extensions") +} diff --git a/openapi2conv/openapi2_conv.go b/openapi2conv/openapi2_conv.go index ba8dfb8de..723505072 100644 --- a/openapi2conv/openapi2_conv.go +++ b/openapi2conv/openapi2_conv.go @@ -1159,18 +1159,27 @@ nameSearch: func FromV3RequestBodyFormData(mediaType *openapi3.MediaType) openapi2.Parameters { parameters := openapi2.Parameters{} - for propName, schemaRef := range mediaType.Schema.Value.Properties { + schema := mediaType.Schema.Value + for propName, schemaRef := range schema.Properties { if ref := schemaRef.Ref; ref != "" { v2Ref := strings.Replace(ref, "#/components/schemas/", "#/parameters/", 1) parameters = append(parameters, &openapi2.Parameter{Ref: v2Ref}) continue } val := schemaRef.Value - typ := val.Type + typ, format := val.Type, val.Format if val.Format == "binary" { - typ = &openapi3.Types{"file"} - } - required := slices.Contains(val.Required, propName) + // Swagger 2.0 writes a file upload as type file, which has no + // format of its own, so the format is spent on naming the type. + typ, format = &openapi3.Types{"file"}, "" + } + // required lists the names of the required properties and belongs to + // the object holding them, which is where ToV3 puts it. Reading only + // the property's own list therefore lost the flag on the way back. A + // document that does carry it on the property is still honoured, as + // that is how a form field kept in components records it. + required := slices.Contains(schema.Required, propName) || + slices.Contains(val.Required, propName) var v2Items *openapi2.SchemaRef if val.Items != nil { @@ -1181,7 +1190,7 @@ func FromV3RequestBodyFormData(mediaType *openapi3.MediaType) openapi2.Parameter Description: val.Description, Type: typ, In: "formData", - Extensions: stripNonExtensions(val.Extensions), + Extensions: formFieldExtensions(val.Extensions), Enum: val.Enum, ExclusiveMin: exclusiveBoundToBool(val.ExclusiveMin), ExclusiveMax: exclusiveBoundToBool(val.ExclusiveMax), @@ -1194,8 +1203,8 @@ func FromV3RequestBodyFormData(mediaType *openapi3.MediaType) openapi2.Parameter Maximum: effectiveMax(val.Max, val.ExclusiveMax), Minimum: effectiveMin(val.Min, val.ExclusiveMin), Pattern: val.Pattern, + Format: format, // CollectionFormat: val.CollectionFormat, - // Format: val.Format, AllowEmptyValue: val.AllowEmptyValue, Required: required, UniqueItems: val.UniqueItems, @@ -1529,6 +1538,25 @@ var attemptedBodyParameterNames = []string{ } // stripNonExtensions removes invalid extensions: those not prefixed by "x-" and returns them +// formFieldExtensions returns the extensions of a form field without +// x-formData-name, which names the field for the conversion to OpenAPI 3, +// where the name has nowhere else to live, and is not part of the document +// being converted. A field kept in components keeps the marker, as the +// conversion back reads the name from it. +// +// The map is built fresh rather than filtered in place, so the schema the +// extensions came from keeps its own. +func formFieldExtensions(extensions map[string]any) map[string]any { + result := make(map[string]any, len(extensions)) + for name, value := range extensions { + if !strings.HasPrefix(name, "x-") || name == "x-formData-name" { + continue + } + result[name] = value + } + return result +} + func stripNonExtensions(extensions map[string]any) map[string]any { for extName := range extensions { if !strings.HasPrefix(extName, "x-") { diff --git a/openapi2conv/openapi2_conv_test.go b/openapi2conv/openapi2_conv_test.go index eec57db96..d9a5e594d 100644 --- a/openapi2conv/openapi2_conv_test.go +++ b/openapi2conv/openapi2_conv_test.go @@ -525,7 +525,6 @@ const exampleV2 = ` "in": "formData", "name": "fileUpload", "type": "file", - "x-formData-name": "fileUpload", "x-mimetype": "text/plain" }, { @@ -538,8 +537,7 @@ const exampleV2 = ` "description": "Description of file contents", "in": "formData", "name": "note", - "type": "integer", - "x-formData-name": "note" + "type": "integer" } ], "responses": { From 7c95f0a535486fa6e04c9f8b771a84bb17d01493 Mon Sep 17 00:00:00 2001 From: Reuven Harrison Date: Fri, 30 Oct 2026 10:05:27 +0200 Subject: [PATCH 30/78] openapi2conv: escape a base path converted to a server of its own (#1404) Co-authored-by: Claude Opus 5 --- openapi2conv/openapi2_conv.go | 37 ++++++--- openapi2conv/server_base_path_test.go | 78 +++++++++++++++++++ .../fuzz/FuzzToV3/relative-server-base-path | 2 + 3 files changed, 106 insertions(+), 11 deletions(-) create mode 100644 openapi2conv/server_base_path_test.go create mode 100644 openapi2conv/testdata/fuzz/FuzzToV3/relative-server-base-path diff --git a/openapi2conv/openapi2_conv.go b/openapi2conv/openapi2_conv.go index 723505072..681cadf43 100644 --- a/openapi2conv/openapi2_conv.go +++ b/openapi2conv/openapi2_conv.go @@ -57,7 +57,13 @@ func ToV3WithLoader(doc2 *openapi2.T, loader *openapi3.Loader, location *url.URL // allows a relative server URL. Emit the base path on its own rather // than dropping it: with no servers the default server URL of "/" is // assumed, so `/v1` used to disappear (issue #1284). - doc3.AddServer(&openapi3.Server{URL: basePath}) + // + // The path goes through url.URL, as it does when there is a host, so + // that it is escaped the same way in both cases. Written out as it + // came, a base path holding a percent-escape or a control character + // made a server URL that reads back as a different path, or as no + // path at all because it no longer parses. + doc3.AddServer(&openapi3.Server{URL: (&url.URL{Path: basePath}).String()}) } doc3.Components.Schemas = make(map[string]*openapi3.SchemaRef) @@ -795,18 +801,27 @@ func FromV3(doc3 *openapi3.T) (*openapi2.T, error) { isHTTP := false servers := doc3.Servers for i, server := range servers { - if parsedURL, err := url.Parse(server.URL); err == nil { - switch parsedURL.Scheme { - case "https": - isHTTPS = true - case "http": - isHTTP = true - } - // The first server is assumed to provide the base path + parsedURL, err := url.Parse(server.URL) + if err != nil { + // A URL that does not parse is still the only thing said about + // where the API lives, and basePath is the one field of the two + // that can hold it as it was written. Dropping it lost the server + // altogether, and converting back then produced no server at all. if i == 0 { - doc2.Host = parsedURL.Host - doc2.BasePath = parsedURL.Path + doc2.BasePath = server.URL } + continue + } + switch parsedURL.Scheme { + case "https": + isHTTPS = true + case "http": + isHTTP = true + } + // The first server is assumed to provide the base path + if i == 0 { + doc2.Host = parsedURL.Host + doc2.BasePath = parsedURL.Path } } diff --git a/openapi2conv/server_base_path_test.go b/openapi2conv/server_base_path_test.go new file mode 100644 index 000000000..816e57a07 --- /dev/null +++ b/openapi2conv/server_base_path_test.go @@ -0,0 +1,78 @@ +package openapi2conv_test + +import ( + "testing" + + "github.com/stretchr/testify/require" + + "github.com/getkin/kin-openapi/openapi2" + "github.com/getkin/kin-openapi/openapi2conv" + "github.com/getkin/kin-openapi/openapi3" +) + +// TestToV3BasePathEscaping covers the base path of a document with no host, +// which becomes a server URL of its own. The URL is read back as a URL, so a +// base path that is not already one has to be escaped on the way out, or the +// path that comes back differs from the path that went in. +func TestToV3BasePathEscaping(t *testing.T) { + t.Parallel() + + for _, tc := range []struct { + name string + basePath string + url string + }{ + {name: "plain", basePath: "/v1", url: "/v1"}, + {name: "percent escape", basePath: "0%00", url: "0%2500"}, + {name: "control character", basePath: "0\x00", url: "0%00"}, + {name: "space", basePath: "/a b", url: "/a%20b"}, + } { + t.Run(tc.name, func(t *testing.T) { + t.Parallel() + + doc2 := &openapi2.T{ + Swagger: "2.0", + Info: openapi3.Info{Title: "t", Version: "1"}, + BasePath: tc.basePath, + } + + doc3, err := openapi2conv.ToV3(doc2) + require.NoError(t, err) + require.Len(t, doc3.Servers, 1) + require.Equal(t, tc.url, doc3.Servers[0].URL) + + // The base path has to come back as it was written, and the + // conversion has to settle: the server URL of the second pass is + // the server URL of the first. + back, err := openapi2conv.FromV3(doc3) + require.NoError(t, err) + require.Equal(t, tc.basePath, back.BasePath) + require.Empty(t, back.Host) + + again, err := openapi2conv.ToV3(back) + require.NoError(t, err) + require.Len(t, again.Servers, 1) + require.Equal(t, tc.url, again.Servers[0].URL) + }) + } +} + +// TestFromV3UnparseableServer pins that a server URL which is not a URL is +// kept rather than dropped. basePath is the one field that can hold it as it +// was written, and dropping it left the document with no server at all. +func TestFromV3UnparseableServer(t *testing.T) { + t.Parallel() + + doc3 := &openapi3.T{ + OpenAPI: "3.0.3", + Info: &openapi3.Info{Title: "t", Version: "1"}, + Servers: openapi3.Servers{{URL: "ht tp://example.com/v1"}}, + Paths: openapi3.NewPaths(), + } + + back, err := openapi2conv.FromV3(doc3) + require.NoError(t, err) + require.Equal(t, "ht tp://example.com/v1", back.BasePath) + require.Empty(t, back.Host) + require.Empty(t, back.Schemes) +} diff --git a/openapi2conv/testdata/fuzz/FuzzToV3/relative-server-base-path b/openapi2conv/testdata/fuzz/FuzzToV3/relative-server-base-path new file mode 100644 index 000000000..08a44941e --- /dev/null +++ b/openapi2conv/testdata/fuzz/FuzzToV3/relative-server-base-path @@ -0,0 +1,2 @@ +go test fuzz v1 +[]byte("{\"basePath\":\"0%00\",\"info\":{\"title\":\"0\",\"version\":\"0\"},\"paths\":{\"/\":{}}}") From 74727a2c2510ac59479396ce1db7b6bc080b8aa1 Mon Sep 17 00:00:00 2001 From: Reuven Harrison Date: Fri, 30 Oct 2026 10:14:34 +0200 Subject: [PATCH 31/78] internal: add nodeindex (decoding YAML natively 1/3) (#1382) Co-authored-by: Claude Opus 5 Co-authored-by: Pierre Fenoll --- .github/workflows/fuzz.yml | 1 + Makefile | 1 + internal/nodeindex/fuzz_test.go | 91 ++++++ internal/nodeindex/nodeindex.go | 268 ++++++++++++++++++ internal/nodeindex/nodeindex_test.go | 140 +++++++++ .../testdata/fuzz/FuzzNew/3a92fc51140972a8 | 2 + .../testdata/fuzz/FuzzNew/75c986f1e6252964 | 2 + .../testdata/fuzz/FuzzNew/ef854579488f3d3f | 2 + .../testdata/fuzz/FuzzNew/explicit-key-null | 2 + .../nodeindex/testdata/fuzz/FuzzNew/lone-cr | 2 + 10 files changed, 511 insertions(+) create mode 100644 internal/nodeindex/fuzz_test.go create mode 100644 internal/nodeindex/nodeindex.go create mode 100644 internal/nodeindex/nodeindex_test.go create mode 100644 internal/nodeindex/testdata/fuzz/FuzzNew/3a92fc51140972a8 create mode 100644 internal/nodeindex/testdata/fuzz/FuzzNew/75c986f1e6252964 create mode 100644 internal/nodeindex/testdata/fuzz/FuzzNew/ef854579488f3d3f create mode 100644 internal/nodeindex/testdata/fuzz/FuzzNew/explicit-key-null create mode 100644 internal/nodeindex/testdata/fuzz/FuzzNew/lone-cr diff --git a/.github/workflows/fuzz.yml b/.github/workflows/fuzz.yml index 836f85d10..68ba5f3b4 100644 --- a/.github/workflows/fuzz.yml +++ b/.github/workflows/fuzz.yml @@ -39,6 +39,7 @@ jobs: - {package: ./openapi3, target: FuzzYAMLMatchesJSON} - {package: ./openapi3, target: FuzzSchemaVisitJSON} - {package: ./openapi2, target: FuzzUnmarshalFromData} + - {package: ./internal/nodeindex, target: FuzzNew} - {package: ./openapi2conv, target: FuzzToV3} - {package: ./openapi3filter, target: FuzzValidateRequest} steps: diff --git a/Makefile b/Makefile index 2978ca959..2e6dd0569 100644 --- a/Makefile +++ b/Makefile @@ -32,6 +32,7 @@ fuzz: go test -run='^$$' -fuzz='^FuzzYAMLMatchesJSON$$' -fuzztime=$(FUZZTIME) ./openapi3 go test -run='^$$' -fuzz='^FuzzSchemaVisitJSON$$' -fuzztime=$(FUZZTIME) ./openapi3 go test -run='^$$' -fuzz='^FuzzUnmarshalFromData$$' -fuzztime=$(FUZZTIME) ./openapi2 + go test -run='^$$' -fuzz='^FuzzNew$$' -fuzztime=$(FUZZTIME) ./internal/nodeindex go test -run='^$$' -fuzz='^FuzzToV3$$' -fuzztime=$(FUZZTIME) ./openapi2conv go test -run='^$$' -fuzz='^FuzzValidateRequest$$' -fuzztime=$(FUZZTIME) ./openapi3filter diff --git a/internal/nodeindex/fuzz_test.go b/internal/nodeindex/fuzz_test.go new file mode 100644 index 000000000..041aef7ab --- /dev/null +++ b/internal/nodeindex/fuzz_test.go @@ -0,0 +1,91 @@ +package nodeindex_test + +import ( + "testing" + + yaml "github.com/oasdiff/yaml3" + "github.com/stretchr/testify/require" + + "github.com/getkin/kin-openapi/internal/fuzzing" + "github.com/getkin/kin-openapi/internal/nodeindex" +) + +// A block ends no earlier than it starts, no later than the input does, no +// earlier than any block it contains, and, in a block collection, before the +// next entry starts. +func FuzzNew(f *testing.F) { + f.Add([]byte("a:\n b: 1\n c: |\n x\n\n y\n\nd: [1,\n 2]\n")) + f.Add([]byte("- name: id\n in: path\n- &a {x: 1}\n- *a\n- <<: *a\n y: 2\n")) + f.Add([]byte("a: >-\n folded\n # not a comment\nb:\n# comment\n c: 1\n")) + f.Add([]byte("a:\r\n b: 1\r\n c:\r\n - 1\r\n")) + f.Add([]byte("--- &r\nk: \"multi\n line\"\n? complex\n: key\n")) + f.Add([]byte("a:\n\tb\n")) + for _, seed := range fuzzing.Testdata(f, "../../openapi3/testdata") { + f.Add(seed) + } + for _, seed := range fuzzing.APIsGuru(f, "../../openapi3/testdata", "") { + f.Add(seed) + } + + f.Fuzz(func(t *testing.T, data []byte) { + if len(data) > 32<<10 { + t.Skip() + } + var root yaml.Node + if yaml.Unmarshal(data, &root) != nil { + return + } + ix := nodeindex.New(&root, data) + lines := countLines(data) + + var walk func(n *yaml.Node) int + walk = func(n *yaml.Node) int { + require.True(t, ix.Has(n)) + end, col := ix.EndOf(n) + if end != 0 { + require.LessOrEqual(t, end, lines) + require.GreaterOrEqual(t, col, 1) + if n.Line <= lines { + require.GreaterOrEqual(t, end, n.Line, "node at %d:%d", n.Line, n.Column) + } + } + for _, c := range n.Content { + if childEnd := walk(c); end != 0 && childEnd != 0 { + require.GreaterOrEqual(t, end, childEnd, "node at %d:%d ends before its child at %d:%d", n.Line, n.Column, c.Line, c.Column) + } + } + if n.Style&yaml.FlowStyle == 0 && (n.Kind == yaml.MappingNode || n.Kind == yaml.SequenceNode) { + for i := 0; i+1 < len(n.Content); i++ { + if n.Kind == yaml.MappingNode && i%2 == 0 { + continue // a key and its own value + } + cur, next := n.Content[i], n.Content[i+1] + if curEnd, _ := ix.EndOf(cur); curEnd != 0 && next.Line > cur.Line { + require.Less(t, curEnd, next.Line, "node at %d:%d runs into its sibling at %d:%d", cur.Line, cur.Column, next.Line, next.Column) + } + } + } + return end + } + walk(&root) + }) +} + +// countLines counts lines the way the parser does: a line feed, a carriage +// return, or the two together each end one. Counting line feeds alone reads a +// lone carriage return as ordinary text and comes up short. +func countLines(data []byte) int { + lines := 1 + for i := 0; i < len(data); i++ { + switch data[i] { + case '\n': + lines++ + case '\r': + if i+1 < len(data) && data[i+1] == '\n' { + continue + } + lines++ + } + } + return lines +} diff --git a/internal/nodeindex/nodeindex.go b/internal/nodeindex/nodeindex.go new file mode 100644 index 000000000..2e7cd4e55 --- /dev/null +++ b/internal/nodeindex/nodeindex.go @@ -0,0 +1,268 @@ +// Package nodeindex derives, from a YAML node tree and the text it was parsed +// from, the two things the parser does not report: where the block headed by a +// node ends, and which key an anchor was defined under. +// +// The first half is interim. https://github.com/yaml/go-yaml/pull/391 records +// end positions on the node, which is where they belong and which they are +// exact at; this derives them instead, and agrees on 99.98% of blocks. +// +// The import is the yaml fork this module already depends on rather than the +// stock package, whose Node is the same type: nothing here needs the fork, and +// the switch to stock yaml belongs to the change that removes the fork. +package nodeindex + +import ( + "bytes" + "unicode/utf8" + + yaml "github.com/oasdiff/yaml3" +) + +// Index answers where the block headed by a key ends. +// +// The parser reports where every node starts and nothing about where it stops, +// so the end is derived, in two passes over the tree. +// +// measure takes the largest line among a node's descendants. Reading that off +// the tree rather than from indentation is what makes a sequence item work: a +// parameter's key location is the item's first key, at the same column as the +// keys following it, so no column comparison can tell the end of the item from +// the start of its own second field. +// +// extend then grows that over lines belonging to the block that carry no node, +// which is the body of a block scalar. Together they agree with a parser's own +// end positions on 99.98% of blocks across a 4,240-file corpus; measure alone +// agrees on 99.60%, the difference being blocks that end in a `description: |`. +// +// Trailing blank and comment lines fall outside. +type Index struct { + end map[*yaml.Node]int + // anchorKey is the key heading each anchored node, so an alias can report + // where the content it points at is defined. + anchorKey map[*yaml.Node]*yaml.Node + // lineLen is each line's length in characters, giving the column a block's + // last line stops at: the parser counts a column per character, not per + // byte, so a line holding any multi-byte one would otherwise end past its + // own width. indent is its leading-space count, or -1 when the line holds + // nothing, which is what extend walks. + lineLen []int + indent []int +} + +// New indexes data's node tree. Ends are derived per file: a $ref into another +// document is decoded separately, against its own text. +func New(root *yaml.Node, data []byte) *Index { + if root == nil { + return nil + } + ix := &Index{end: map[*yaml.Node]int{}, anchorKey: map[*yaml.Node]*yaml.Node{}} + for _, line := range splitLines(data) { + ix.lineLen = append(ix.lineLen, utf8.RuneCount(line)) + if t := bytes.TrimRight(line, " \t"); len(t) == 0 { + ix.indent = append(ix.indent, -1) + } else { + ix.indent = append(ix.indent, len(t)-len(bytes.TrimLeft(t, " "))) + } + } + ix.measure(root) + _ = ix.extend(root) + ix.separate(root) + return ix +} + +// separate holds each entry of a block collection to its own lines: an entry +// ends before the next one starts. +// +// measure and extend work from a node and the lines under it, which is enough +// for the common document and not enough in general: a flow collection written +// across lines, an entry whose value is indented back to the key's column, a +// comment between entries. Rather than keep refining what the two passes guess, +// the bound they must respect is applied here, because an entry that runs into +// its sibling is wrong whatever produced it, and a shorter end is the safe +// direction. A flow collection is exempt, its entries sharing lines by design. +func (ix *Index) separate(n *yaml.Node) { + for _, c := range n.Content { + ix.separate(c) + } + if n.Style&yaml.FlowStyle != 0 { + return + } + if n.Kind != yaml.MappingNode && n.Kind != yaml.SequenceNode { + return + } + step := 1 + if n.Kind == yaml.MappingNode { + step = 2 // a key and its value belong to the same entry + } + for i := 0; i+step < len(n.Content); i += step { + cur, next := n.Content[i], n.Content[i+step] + if next.Line <= cur.Line { + continue + } + for _, part := range n.Content[i : i+step] { + ix.clamp(part, next.Line-1) + } + } +} + +// clamp holds n and everything inside it to line at the latest. A bound on an +// entry binds its contents too, or the entry would end before what it contains. +func (ix *Index) clamp(n *yaml.Node, line int) { + if end, ok := ix.end[n]; ok && end > line { + ix.end[n] = line + } + for _, c := range n.Content { + ix.clamp(c, line) + } +} + +// splitLines cuts data where the parser does. YAML breaks a line on a line +// feed, a carriage return, or the two together, so splitting on line feeds +// alone counts a lone carriage return as ordinary text and every line after it +// is then numbered one too low. A break is not part of the line it ends. +func splitLines(data []byte) [][]byte { + var lines [][]byte + start := 0 + for i := 0; i < len(data); i++ { + switch data[i] { + case '\n': + case '\r': + if i+1 < len(data) && data[i+1] == '\n' { + continue // the pair is one break, taken on the line feed + } + default: + continue + } + end := i + if data[i] == '\n' && end > start && data[end-1] == '\r' { + end-- // the carriage return of a CRLF pair ends the line, it is not on it + } + lines = append(lines, data[start:end]) + start = i + 1 + } + return append(lines, data[start:]) +} + +// extend grows each node's end over lines that belong to it but hang off no +// node of their own. +// +// measure can only see lines a descendant starts on, and the body of a block +// scalar has no nodes at all: `description: |` produces one scalar whose Line +// is where it starts, so a block ending in one is cut short. Since those lines +// are indented deeper than the block itself, indentation finds them. +// +// A blank line is included only when the block resumes below it, which is what +// separates a gap inside a block scalar from the gap after the block. +func (ix *Index) extend(n *yaml.Node) int { + if isImplicitNull(n) { + // No text, so no extent: growing from nothing would hand it the lines + // above the position the parser gave it. + return 0 + } + e := ix.end[n] + // A child's extended end carries up: measure took the largest line among + // descendants, but extend can push a child past it, and a node cannot end + // before what it contains. The node's own column decides nothing here, + // which matters for a tagged node, whose column is the tag's and can sit + // deeper than the block it heads. + for _, c := range n.Content { + if ce := ix.extend(c); ce > e { + e = ce + } + } + for { + if ind := ix.indentOf(e); ind > n.Column-1 { // line e+1 is index e + e++ + continue + } else if ind == -1 { + j := e + for j < len(ix.indent) && ix.indentOf(j) == -1 { + j++ + } + if ix.indentOf(j) > n.Column-1 { + e = j + 1 + continue + } + } + break + } + ix.end[n] = e + return e +} + +// indentOf returns the indentation of the given 0-based line, or -1 when the +// line holds nothing or is past the end of the file. +func (ix *Index) indentOf(i int) int { + if i < 0 || i >= len(ix.indent) { + return -1 + } + return ix.indent[i] +} + +// measure records each node's last line, bottom up, and returns it. +func (ix *Index) measure(n *yaml.Node) int { + if n == nil { + return 0 + } + last := n.Line + if isImplicitNull(n) { + // The parser gives a value that was never written the position of the + // next token, which can be past everything the block contains, and in + // a block collection that is where the next entry starts. A node with + // no text of its own extends nothing. + last = 0 + } + if n.Kind == yaml.MappingNode { + for i := 0; i+1 < len(n.Content); i += 2 { + if v := n.Content[i+1]; v.Anchor != "" { + ix.anchorKey[v] = n.Content[i] + } + } + } + for _, c := range n.Content { + if l := ix.measure(c); l > last { + last = l + } + } + ix.end[n] = last + return last +} + +// isImplicitNull reports whether n is a value the document never wrote: the +// parser represents it as an empty null scalar. One written as null or ~ has +// text, and a position of its own. +func isImplicitNull(n *yaml.Node) bool { + return n.Kind == yaml.ScalarNode && n.Tag == "!!null" && n.Value == "" +} + +// EndOf returns the last line and column of the block node occupies. +func (ix *Index) EndOf(node *yaml.Node) (int, int) { + if ix == nil || node == nil { + return 0, 0 + } + line, ok := ix.end[node] + if !ok || line < 1 || line > len(ix.lineLen) { + return 0, 0 + } + // The column just past the last character, matching how a parser reports + // the position it stopped at. + return line, ix.lineLen[line-1] + 1 +} + +// AnchorKey returns the key the anchored node was defined under. +func (ix *Index) AnchorKey(anchored *yaml.Node) (*yaml.Node, bool) { + if ix == nil { + return nil, false + } + k, ok := ix.anchorKey[anchored] + return k, ok +} + +// Has reports whether node is part of the tree this index was built from. +func (ix *Index) Has(node *yaml.Node) bool { + if ix == nil || node == nil { + return false + } + _, ok := ix.end[node] + return ok +} diff --git a/internal/nodeindex/nodeindex_test.go b/internal/nodeindex/nodeindex_test.go new file mode 100644 index 000000000..527ed9db0 --- /dev/null +++ b/internal/nodeindex/nodeindex_test.go @@ -0,0 +1,140 @@ +package nodeindex_test + +import ( + "strings" + "testing" + + yaml "github.com/oasdiff/yaml3" + "github.com/stretchr/testify/require" + + "github.com/getkin/kin-openapi/internal/nodeindex" +) + +func parse(t *testing.T, src string) *yaml.Node { + t.Helper() + + var root yaml.Node + require.NoError(t, yaml.Unmarshal([]byte(src), &root)) + return &root +} + +// The end of a block is the last line of its deepest descendant, grown over +// the lines of a block scalar, which carry no node of their own. +func TestEndOf(t *testing.T) { + t.Parallel() + + const src = "a:\n b: 1\n c: |\n text\n more\nd: 2\n" + root := parse(t, src) + ix := nodeindex.New(root, []byte(src)) + + mapping := root.Content[0] + aValue := mapping.Content[1] + line, column := ix.EndOf(aValue) + require.Equal(t, 5, line, lastLineOfTheBlockScalar) + require.Equal(t, 9, column, pastTheLastCharacter) + + line, _ = ix.EndOf(mapping.Content[3]) + require.Equal(t, 6, line) +} + +const ( + lastLineOfTheBlockScalar = "the block ends at the last line of its scalar" + pastTheLastCharacter = "the column is one past the last character" + aTreeThisIndexNeverSaw = "a node from another tree is not in this index" +) + +// A node the index never saw gets nothing, which is how a decode tells its own +// tree from another one. +func TestHas(t *testing.T) { + t.Parallel() + + const src = "a: 1\n" + ix := nodeindex.New(parse(t, src), []byte(src)) + + foreign := parse(t, src) + require.False(t, ix.Has(foreign.Content[0]), aTreeThisIndexNeverSaw) + require.False(t, ix.Has(nil)) + + root := parse(t, src) + own := nodeindex.New(root, []byte(src)) + require.True(t, own.Has(root.Content[0])) +} + +// An alias reports the key its anchor was defined under, not where it is used. +func TestAnchorKey(t *testing.T) { + t.Parallel() + + const src = "base: &anchor\n x: 1\nuse: *anchor\n" + root := parse(t, src) + ix := nodeindex.New(root, []byte(src)) + + mapping := root.Content[0] + anchored := mapping.Content[1] + key, ok := ix.AnchorKey(anchored) + require.True(t, ok) + require.Equal(t, 1, key.Line) + + _, ok = ix.AnchorKey(mapping.Content[0]) + require.False(t, ok) +} + +// Every method is safe on a nil index, which is what a decode without origins +// carries. +func TestNilIndex(t *testing.T) { + t.Parallel() + + var ix *nodeindex.Index + line, column := ix.EndOf(parse(t, "a: 1\n")) + require.Zero(t, line) + require.Zero(t, column) + require.False(t, ix.Has(parse(t, "a: 1\n"))) + _, ok := ix.AnchorKey(parse(t, "a: 1\n")) + require.False(t, ok) + require.Nil(t, nodeindex.New(nil, nil)) +} + +// A column counts characters, as the parser's own columns do, so a multi-byte +// character does not push the end of a block past the width of its line. +func TestEndOfCountsCharactersNotBytes(t *testing.T) { + t.Parallel() + + for name, src := range map[string]string{ + "ascii": "a: \"hello\"\nb: 2\n", + "multi-byte": "a: \"h\u00e9llo\"\nb: 2\n", + } { + t.Run(name, func(t *testing.T) { + t.Parallel() + + root := parse(t, src) + ix := nodeindex.New(root, []byte(src)) + + line, column := ix.EndOf(root.Content[0].Content[1]) + require.Equal(t, 1, line) + require.Equal(t, 11, column, pastTheLastCharacter) + }) + } +} + +// A line break is not a character on the line it ends, so the same document +// ends its nodes in the same place with either ending. Git checks files out +// with CRLF endings on Windows. +func TestEndOfWithEitherLineEnding(t *testing.T) { + t.Parallel() + + const src = "a:\n c: |\n text\n\n more\nb: 2\n" + for ending, text := range map[string]string{ + "lf": src, + "crlf": strings.ReplaceAll(src, "\n", "\r\n"), + } { + t.Run(ending, func(t *testing.T) { + t.Parallel() + + root := parse(t, text) + ix := nodeindex.New(root, []byte(text)) + + line, column := ix.EndOf(root.Content[0].Content[1]) + require.Equal(t, 5, line, lastLineOfTheBlockScalar) + require.Equal(t, 9, column, pastTheLastCharacter) + }) + } +} diff --git a/internal/nodeindex/testdata/fuzz/FuzzNew/3a92fc51140972a8 b/internal/nodeindex/testdata/fuzz/FuzzNew/3a92fc51140972a8 new file mode 100644 index 000000000..d620df785 --- /dev/null +++ b/internal/nodeindex/testdata/fuzz/FuzzNew/3a92fc51140972a8 @@ -0,0 +1,2 @@ +go test fuzz v1 +[]byte(" &a\n- #0") diff --git a/internal/nodeindex/testdata/fuzz/FuzzNew/75c986f1e6252964 b/internal/nodeindex/testdata/fuzz/FuzzNew/75c986f1e6252964 new file mode 100644 index 000000000..8fda598bb --- /dev/null +++ b/internal/nodeindex/testdata/fuzz/FuzzNew/75c986f1e6252964 @@ -0,0 +1,2 @@ +go test fuzz v1 +[]byte(" !0\n0: 0\n 0") diff --git a/internal/nodeindex/testdata/fuzz/FuzzNew/ef854579488f3d3f b/internal/nodeindex/testdata/fuzz/FuzzNew/ef854579488f3d3f new file mode 100644 index 000000000..45103ad1d --- /dev/null +++ b/internal/nodeindex/testdata/fuzz/FuzzNew/ef854579488f3d3f @@ -0,0 +1,2 @@ +go test fuzz v1 +[]byte(" 0: [\n0]\n 0:") diff --git a/internal/nodeindex/testdata/fuzz/FuzzNew/explicit-key-null b/internal/nodeindex/testdata/fuzz/FuzzNew/explicit-key-null new file mode 100644 index 000000000..bb3c1c27a --- /dev/null +++ b/internal/nodeindex/testdata/fuzz/FuzzNew/explicit-key-null @@ -0,0 +1,2 @@ +go test fuzz v1 +[]byte("a:\n ? k\nb: 1\n") diff --git a/internal/nodeindex/testdata/fuzz/FuzzNew/lone-cr b/internal/nodeindex/testdata/fuzz/FuzzNew/lone-cr new file mode 100644 index 000000000..990e8fe21 --- /dev/null +++ b/internal/nodeindex/testdata/fuzz/FuzzNew/lone-cr @@ -0,0 +1,2 @@ +go test fuzz v1 +[]byte(" \r0:\n0: 00\n 00") From 545c898fa791586240920028951b7ccfc430bc4c Mon Sep 17 00:00:00 2001 From: Reuven Harrison Date: Fri, 30 Oct 2026 18:40:37 +0200 Subject: [PATCH 32/78] openapi3: UnmarshalYAML for the types (decoding YAML natively 2/3) (#1383) Co-authored-by: Claude Opus 5 --- .github/docs/openapi3.txt | 130 ++++ .github/workflows/go.yml | 4 +- go.mod | 1 + go.sum | 2 + openapi3/native_scalars_test.go | 176 ++++++ openapi3/native_yaml.go | 575 ++++++++++++++++++ openapi3/native_yaml_direct_test.go | 32 + openapi3/native_yaml_normalization_test.go | 302 +++++++++ openapi3/native_yaml_refs.go | 77 +++ openapi3/native_yaml_shadow.go | 244 ++++++++ openapi3/native_yaml_special.go | 184 ++++++ openapi3/native_yaml_test.go | 99 +++ openapi3/nativeyaml.tmpl | 25 + openapi3/nativeyamlgenerator.go | 72 +++ openapi3/refs.go | 91 +++ openapi3/refs.tmpl | 29 + .../fuzz/FuzzYAMLMatchesJSON/dd86b380d656a764 | 2 + .../null-in-string-sequence | 2 + openapi3/yaml_fuzz_test.go | 17 +- 19 files changed, 2057 insertions(+), 7 deletions(-) create mode 100644 openapi3/native_scalars_test.go create mode 100644 openapi3/native_yaml.go create mode 100644 openapi3/native_yaml_direct_test.go create mode 100644 openapi3/native_yaml_normalization_test.go create mode 100644 openapi3/native_yaml_refs.go create mode 100644 openapi3/native_yaml_shadow.go create mode 100644 openapi3/native_yaml_special.go create mode 100644 openapi3/native_yaml_test.go create mode 100644 openapi3/nativeyaml.tmpl create mode 100644 openapi3/nativeyamlgenerator.go create mode 100644 openapi3/testdata/fuzz/FuzzYAMLMatchesJSON/dd86b380d656a764 create mode 100644 openapi3/testdata/fuzz/FuzzYAMLMatchesJSON/null-in-string-sequence diff --git a/.github/docs/openapi3.txt b/.github/docs/openapi3.txt index 01dec0307..133814dfd 100644 --- a/.github/docs/openapi3.txt +++ b/.github/docs/openapi3.txt @@ -36,6 +36,9 @@ Version detection is available via helper methods: // Handle OpenAPI 3.2 specific features } +Code generated by go generate using nativeyaml.tmpl; DO NOT EDIT +native_yaml_shadow.go. + Code generated by go generate using refs.tmpl; DO NOT EDIT refs.go. CONSTANTS @@ -393,6 +396,9 @@ func (bs BoolSchema) MarshalYAML() (any, error) func (bs *BoolSchema) UnmarshalJSON(data []byte) error UnmarshalJSON sets BoolSchema to a copy of data. +func (bs *BoolSchema) UnmarshalYAML(node *yaml.Node) error + BoolSchema is `true`/`false` or a schema. + type BooleanSchemaFor31Plus struct{ ValidationError } func (e *BooleanSchemaFor31Plus) As(target any) bool @@ -448,6 +454,8 @@ func (callback *Callback) UnmarshalJSONFrom(dec *jsontext.Decoder) error Decoding each member from dec (rather than from a copy of its bytes) keeps the member's key in the path of any error. +func (callback *Callback) UnmarshalYAML(node *yaml.Node) error + func (callback *Callback) Validate(ctx context.Context, opts ...ValidationOption) error Validate returns an error if Callback does not comply with the OpenAPI spec. @@ -494,6 +502,9 @@ func (x *CallbackRef) RefString() string func (x *CallbackRef) UnmarshalJSON(data []byte) error UnmarshalJSON sets CallbackRef to a copy of data. +func (x *CallbackRef) UnmarshalYAML(node *yaml.Node) error + UnmarshalYAML sets CallbackRef from node. + func (x *CallbackRef) Validate(ctx context.Context, opts ...ValidationOption) error Validate returns an error if CallbackRef does not comply with the OpenAPI spec. @@ -587,6 +598,9 @@ func (components Components) MarshalYAML() (any, error) func (components *Components) UnmarshalJSON(data []byte) error UnmarshalJSON sets Components to a copy of data. +func (components *Components) UnmarshalYAML(node *yaml.Node) error + UnmarshalYAML sets Components from node. + func (components *Components) Validate(ctx context.Context, opts ...ValidationOption) error Validate returns an error if Components does not comply with the OpenAPI spec. @@ -634,6 +648,9 @@ func (contact Contact) MarshalYAML() (any, error) func (contact *Contact) UnmarshalJSON(data []byte) error UnmarshalJSON sets Contact to a copy of data. +func (contact *Contact) UnmarshalYAML(node *yaml.Node) error + UnmarshalYAML sets Contact from node. + func (contact *Contact) Validate(ctx context.Context, opts ...ValidationOption) error Validate returns an error if Contact does not comply with the OpenAPI spec. @@ -771,6 +788,9 @@ func (discriminator Discriminator) MarshalYAML() (any, error) func (discriminator *Discriminator) UnmarshalJSON(data []byte) error UnmarshalJSON sets Discriminator to a copy of data. +func (discriminator *Discriminator) UnmarshalYAML(node *yaml.Node) error + UnmarshalYAML sets Discriminator from node. + func (discriminator *Discriminator) Validate(ctx context.Context, opts ...ValidationOption) error Validate returns an error if Discriminator does not comply with the OpenAPI spec. @@ -916,6 +936,9 @@ func (encoding *Encoding) SerializationMethod() *SerializationMethod func (encoding *Encoding) UnmarshalJSON(data []byte) error UnmarshalJSON sets Encoding to a copy of data. +func (encoding *Encoding) UnmarshalYAML(node *yaml.Node) error + UnmarshalYAML sets Encoding from node. + func (encoding *Encoding) Validate(ctx context.Context, opts ...ValidationOption) error Validate returns an error if Encoding does not comply with the OpenAPI spec. @@ -967,6 +990,9 @@ func (example Example) MarshalYAML() (any, error) func (example *Example) UnmarshalJSON(data []byte) error UnmarshalJSON sets Example to a copy of data. +func (example *Example) UnmarshalYAML(node *yaml.Node) error + UnmarshalYAML sets Example from node. + func (example *Example) Validate(ctx context.Context, opts ...ValidationOption) error Validate returns an error if Example does not comply with the OpenAPI spec. @@ -1010,6 +1036,9 @@ func (x *ExampleRef) RefString() string func (x *ExampleRef) UnmarshalJSON(data []byte) error UnmarshalJSON sets ExampleRef to a copy of data. +func (x *ExampleRef) UnmarshalYAML(node *yaml.Node) error + UnmarshalYAML sets ExampleRef from node. + func (x *ExampleRef) Validate(ctx context.Context, opts ...ValidationOption) error Validate returns an error if ExampleRef does not comply with the OpenAPI spec. @@ -1072,6 +1101,10 @@ func (eb ExclusiveBound) MarshalYAML() (any, error) func (eb *ExclusiveBound) UnmarshalJSON(data []byte) error UnmarshalJSON sets ExclusiveBound to a copy of data. +func (eb *ExclusiveBound) UnmarshalYAML(node *yaml.Node) error + ExclusiveBound is a bool in OAS 3.0, where it modifies minimum/maximum, + or a number in 3.1, where it is the bound itself. + type ExclusiveBoundBooleanBefore31 struct{ ValidationError } func (e *ExclusiveBoundBooleanBefore31) As(target any) bool @@ -1103,6 +1136,9 @@ func (e ExternalDocs) MarshalYAML() (any, error) func (e *ExternalDocs) UnmarshalJSON(data []byte) error UnmarshalJSON sets ExternalDocs to a copy of data. +func (e *ExternalDocs) UnmarshalYAML(node *yaml.Node) error + UnmarshalYAML sets ExternalDocs from node. + func (e *ExternalDocs) Validate(ctx context.Context, opts ...ValidationOption) error Validate returns an error if ExternalDocs does not comply with the OpenAPI spec. @@ -1256,6 +1292,9 @@ func (header *Header) SerializationMethod() (*SerializationMethod, error) func (header *Header) UnmarshalJSON(data []byte) error UnmarshalJSON sets Header to a copy of data. +func (header *Header) UnmarshalYAML(node *yaml.Node) error + Header embeds Parameter and carries no fields of its own. + func (header *Header) Validate(ctx context.Context, opts ...ValidationOption) error Validate returns an error if Header does not comply with the OpenAPI spec. @@ -1335,6 +1374,9 @@ func (x *HeaderRef) RefString() string func (x *HeaderRef) UnmarshalJSON(data []byte) error UnmarshalJSON sets HeaderRef to a copy of data. +func (x *HeaderRef) UnmarshalYAML(node *yaml.Node) error + UnmarshalYAML sets HeaderRef from node. + func (x *HeaderRef) Validate(ctx context.Context, opts ...ValidationOption) error Validate returns an error if HeaderRef does not comply with the OpenAPI spec. @@ -1383,6 +1425,9 @@ func (info *Info) MarshalYAML() (any, error) func (info *Info) UnmarshalJSON(data []byte) error UnmarshalJSON sets Info to a copy of data. +func (info *Info) UnmarshalYAML(node *yaml.Node) error + UnmarshalYAML sets Info from node. + func (info *Info) Validate(ctx context.Context, opts ...ValidationOption) error Validate returns an error if Info does not comply with the OpenAPI spec. @@ -1543,6 +1588,9 @@ func (license License) MarshalYAML() (any, error) func (license *License) UnmarshalJSON(data []byte) error UnmarshalJSON sets License to a copy of data. +func (license *License) UnmarshalYAML(node *yaml.Node) error + UnmarshalYAML sets License from node. + func (license *License) Validate(ctx context.Context, opts ...ValidationOption) error Validate returns an error if License does not comply with the OpenAPI spec. @@ -1587,6 +1635,9 @@ func (link Link) MarshalYAML() (any, error) func (link *Link) UnmarshalJSON(data []byte) error UnmarshalJSON sets Link to a copy of data. +func (link *Link) UnmarshalYAML(node *yaml.Node) error + UnmarshalYAML sets Link from node. + func (link *Link) Validate(ctx context.Context, opts ...ValidationOption) error Validate returns an error if Link does not comply with the OpenAPI spec. @@ -1642,6 +1693,9 @@ func (x *LinkRef) RefString() string func (x *LinkRef) UnmarshalJSON(data []byte) error UnmarshalJSON sets LinkRef to a copy of data. +func (x *LinkRef) UnmarshalYAML(node *yaml.Node) error + UnmarshalYAML sets LinkRef from node. + func (x *LinkRef) Validate(ctx context.Context, opts ...ValidationOption) error Validate returns an error if LinkRef does not comply with the OpenAPI spec. @@ -1769,6 +1823,9 @@ func (mediaType MediaType) MarshalYAML() (any, error) func (mediaType *MediaType) UnmarshalJSON(data []byte) error UnmarshalJSON sets MediaType to a copy of data. +func (mediaType *MediaType) UnmarshalYAML(node *yaml.Node) error + UnmarshalYAML sets MediaType from node. + func (mediaType *MediaType) Validate(ctx context.Context, opts ...ValidationOption) error Validate returns an error if MediaType does not comply with the OpenAPI spec. @@ -1897,6 +1954,9 @@ func (flow OAuthFlow) MarshalYAML() (any, error) func (flow *OAuthFlow) UnmarshalJSON(data []byte) error UnmarshalJSON sets OAuthFlow to a copy of data. +func (flow *OAuthFlow) UnmarshalYAML(node *yaml.Node) error + UnmarshalYAML sets OAuthFlow from node. + func (flow *OAuthFlow) Validate(ctx context.Context, opts ...ValidationOption) error Validate returns an error if OAuthFlows does not comply with the OpenAPI spec. @@ -1978,6 +2038,9 @@ func (flows OAuthFlows) MarshalYAML() (any, error) func (flows *OAuthFlows) UnmarshalJSON(data []byte) error UnmarshalJSON sets OAuthFlows to a copy of data. +func (flows *OAuthFlows) UnmarshalYAML(node *yaml.Node) error + UnmarshalYAML sets OAuthFlows from node. + func (flows *OAuthFlows) Validate(ctx context.Context, opts ...ValidationOption) error Validate returns an error if OAuthFlows does not comply with the OpenAPI spec. @@ -2055,6 +2118,12 @@ func (operation Operation) MarshalYAML() (any, error) func (operation *Operation) UnmarshalJSON(data []byte) error UnmarshalJSON sets Operation to a copy of data. +func (operation *Operation) UnmarshalYAML(node *yaml.Node) error + Operation distinguishes an omitted responses from an explicitly null one: + the first is allowed in OAS 3.1 and later, the second never is. A null node + decodes to an empty Responses, which is indistinguishable from `{}` without + the flag. + func (operation *Operation) Validate(ctx context.Context, opts ...ValidationOption) error Validate returns an error if Operation does not comply with the OpenAPI spec. @@ -2146,6 +2215,9 @@ func (parameter *Parameter) SerializationMethod() (*SerializationMethod, error) func (parameter *Parameter) UnmarshalJSON(data []byte) error UnmarshalJSON sets Parameter to a copy of data. +func (parameter *Parameter) UnmarshalYAML(node *yaml.Node) error + UnmarshalYAML sets Parameter from node. + func (parameter *Parameter) Validate(ctx context.Context, opts ...ValidationOption) error Validate returns an error if Parameter does not comply with the OpenAPI spec. @@ -2246,6 +2318,9 @@ func (x *ParameterRef) RefString() string func (x *ParameterRef) UnmarshalJSON(data []byte) error UnmarshalJSON sets ParameterRef to a copy of data. +func (x *ParameterRef) UnmarshalYAML(node *yaml.Node) error + UnmarshalYAML sets ParameterRef from node. + func (x *ParameterRef) Validate(ctx context.Context, opts ...ValidationOption) error Validate returns an error if ParameterRef does not comply with the OpenAPI spec. @@ -2320,6 +2395,9 @@ func (pathItem *PathItem) SetOperation(method string, operation *Operation) func (pathItem *PathItem) UnmarshalJSON(data []byte) error UnmarshalJSON sets PathItem to a copy of data. +func (pathItem *PathItem) UnmarshalYAML(node *yaml.Node) error + UnmarshalYAML sets PathItem from node. + func (pathItem *PathItem) Validate(ctx context.Context, opts ...ValidationOption) error Validate returns an error if PathItem does not comply with the OpenAPI spec. @@ -2459,6 +2537,8 @@ func (paths *Paths) UnmarshalJSONFrom(dec *jsontext.Decoder) error Decoding each member from dec (rather than from a copy of its bytes) keeps the member's key in the path of any error. +func (paths *Paths) UnmarshalYAML(node *yaml.Node) error + func (paths *Paths) Validate(ctx context.Context, opts ...ValidationOption) error Validate returns an error if Paths does not comply with the OpenAPI spec. @@ -2580,6 +2660,9 @@ func (requestBody RequestBody) MarshalYAML() (any, error) func (requestBody *RequestBody) UnmarshalJSON(data []byte) error UnmarshalJSON sets RequestBody to a copy of data. +func (requestBody *RequestBody) UnmarshalYAML(node *yaml.Node) error + UnmarshalYAML sets RequestBody from node. + func (requestBody *RequestBody) Validate(ctx context.Context, opts ...ValidationOption) error Validate returns an error if RequestBody does not comply with the OpenAPI spec. @@ -2648,6 +2731,9 @@ func (x *RequestBodyRef) RefString() string func (x *RequestBodyRef) UnmarshalJSON(data []byte) error UnmarshalJSON sets RequestBodyRef to a copy of data. +func (x *RequestBodyRef) UnmarshalYAML(node *yaml.Node) error + UnmarshalYAML sets RequestBodyRef from node. + func (x *RequestBodyRef) Validate(ctx context.Context, opts ...ValidationOption) error Validate returns an error if RequestBodyRef does not comply with the OpenAPI spec. @@ -2702,6 +2788,9 @@ func (response Response) MarshalYAML() (any, error) func (response *Response) UnmarshalJSON(data []byte) error UnmarshalJSON sets Response to a copy of data. +func (response *Response) UnmarshalYAML(node *yaml.Node) error + UnmarshalYAML sets Response from node. + func (response *Response) Validate(ctx context.Context, opts ...ValidationOption) error Validate returns an error if Response does not comply with the OpenAPI spec. @@ -2765,6 +2854,9 @@ func (x *ResponseRef) RefString() string func (x *ResponseRef) UnmarshalJSON(data []byte) error UnmarshalJSON sets ResponseRef to a copy of data. +func (x *ResponseRef) UnmarshalYAML(node *yaml.Node) error + UnmarshalYAML sets ResponseRef from node. + func (x *ResponseRef) Validate(ctx context.Context, opts ...ValidationOption) error Validate returns an error if ResponseRef does not comply with the OpenAPI spec. @@ -2828,6 +2920,8 @@ func (responses *Responses) UnmarshalJSONFrom(dec *jsontext.Decoder) error Decoding each member from dec (rather than from a copy of its bytes) keeps the member's key in the path of any error. +func (responses *Responses) UnmarshalYAML(node *yaml.Node) error + func (responses *Responses) Validate(ctx context.Context, opts ...ValidationOption) error Validate returns an error if Responses does not comply with the OpenAPI spec. @@ -3008,6 +3102,13 @@ func (schema *Schema) PermitsNull(opts ...SchemaValidationOption) bool func (schema *Schema) UnmarshalJSON(data []byte) error UnmarshalJSON sets Schema to a copy of data. +func (schema *Schema) UnmarshalYAML(node *yaml.Node) error + Schema is `true`/`false` or a mapping. JSON Schema 2020-12, which OpenAPI + 3.1 adopts, allows a boolean wherever a schema is expected. + + The mapping branch is what the generator emits for the other declared-field + types; only the scalar case is particular to Schema. + func (schema *Schema) Validate(ctx context.Context, opts ...ValidationOption) error Validate returns an error if Schema does not comply with the OpenAPI spec. @@ -3267,6 +3368,9 @@ func (x *SchemaRef) RefString() string func (x *SchemaRef) UnmarshalJSON(data []byte) error UnmarshalJSON sets SchemaRef to a copy of data. +func (x *SchemaRef) UnmarshalYAML(node *yaml.Node) error + UnmarshalYAML sets SchemaRef from node. + func (x *SchemaRef) Validate(ctx context.Context, opts ...ValidationOption) error Validate returns an error if SchemaRef does not comply with the OpenAPI spec. @@ -3468,6 +3572,12 @@ func NewSecurityRequirement() SecurityRequirement func (security SecurityRequirement) Authenticate(provider string, scopes ...string) SecurityRequirement +func (sr *SecurityRequirement) UnmarshalYAML(node *yaml.Node) error + UnmarshalYAML sets SecurityRequirement from node. + + A scheme's scopes are a list of strings, and decoding one directly drops a + null from it rather than keeping its place, which is what stringList is for. + func (security *SecurityRequirement) Validate(ctx context.Context, opts ...ValidationOption) error Validate returns an error if SecurityRequirement does not comply with the OpenAPI spec. @@ -3534,6 +3644,9 @@ func (ss SecurityScheme) MarshalYAML() (any, error) func (ss *SecurityScheme) UnmarshalJSON(data []byte) error UnmarshalJSON sets SecurityScheme to a copy of data. +func (ss *SecurityScheme) UnmarshalYAML(node *yaml.Node) error + UnmarshalYAML sets SecurityScheme from node. + func (ss *SecurityScheme) Validate(ctx context.Context, opts ...ValidationOption) error Validate returns an error if SecurityScheme does not comply with the OpenAPI spec. @@ -3631,6 +3744,9 @@ func (x *SecuritySchemeRef) RefString() string func (x *SecuritySchemeRef) UnmarshalJSON(data []byte) error UnmarshalJSON sets SecuritySchemeRef to a copy of data. +func (x *SecuritySchemeRef) UnmarshalYAML(node *yaml.Node) error + UnmarshalYAML sets SecuritySchemeRef from node. + func (x *SecuritySchemeRef) Validate(ctx context.Context, opts ...ValidationOption) error Validate returns an error if SecuritySchemeRef does not comply with the OpenAPI spec. @@ -3676,6 +3792,9 @@ func (server Server) ParameterNames() ([]string, error) func (server *Server) UnmarshalJSON(data []byte) error UnmarshalJSON sets Server to a copy of data. +func (server *Server) UnmarshalYAML(node *yaml.Node) error + UnmarshalYAML sets Server from node. + func (server *Server) Validate(ctx context.Context, opts ...ValidationOption) error Validate returns an error if Server does not comply with the OpenAPI spec. @@ -3735,6 +3854,9 @@ func (serverVariable ServerVariable) MarshalYAML() (any, error) func (serverVariable *ServerVariable) UnmarshalJSON(data []byte) error UnmarshalJSON sets ServerVariable to a copy of data. +func (serverVariable *ServerVariable) UnmarshalYAML(node *yaml.Node) error + UnmarshalYAML sets ServerVariable from node. + func (serverVariable *ServerVariable) Validate(ctx context.Context, opts ...ValidationOption) error Validate returns an error if ServerVariable does not comply with the OpenAPI spec. @@ -3891,6 +4013,8 @@ func (doc *T) SetStringFormatValidators(validators map[string]StringFormatValida func (doc *T) UnmarshalJSON(data []byte) error UnmarshalJSON sets T to a copy of data. +func (doc *T) UnmarshalYAML(node *yaml.Node) error + func (doc *T) Validate(ctx context.Context, opts ...ValidationOption) error Validate returns an error if T does not comply with the OpenAPI spec. Validations Options can be provided to modify the validation behavior. @@ -3955,6 +4079,9 @@ func (t Tag) MarshalYAML() (any, error) func (t *Tag) UnmarshalJSON(data []byte) error UnmarshalJSON sets Tag to a copy of data. +func (t *Tag) UnmarshalYAML(node *yaml.Node) error + UnmarshalYAML sets Tag from node. + func (t *Tag) Validate(ctx context.Context, opts ...ValidationOption) error Validate returns an error if Tag does not comply with the OpenAPI spec. @@ -4403,6 +4530,9 @@ func (xml XML) MarshalYAML() (any, error) func (xml *XML) UnmarshalJSON(data []byte) error UnmarshalJSON sets XML to a copy of data. +func (xml *XML) UnmarshalYAML(node *yaml.Node) error + UnmarshalYAML sets XML from node. + func (xml *XML) Validate(ctx context.Context, opts ...ValidationOption) error Validate returns an error if XML does not comply with the OpenAPI spec. diff --git a/.github/workflows/go.yml b/.github/workflows/go.yml index 9395acb85..46cd71a89 100644 --- a/.github/workflows/go.yml +++ b/.github/workflows/go.yml @@ -117,9 +117,9 @@ jobs: ! git grep -IErn '\s$' - if: runner.os == 'Linux' - name: Ensure use of unmarshal + name: Ensure yaml stays inside the decode layer run: | - [[ "$(git grep -F yaml. -- openapi3/ | grep -v _test.go | grep -v origin.go | wc -l)" = 2 ]] + [[ "$(git grep -F yaml. -- openapi3/ | grep -v _test.go | grep -vE 'openapi3/(origin|marsh|refs|loader|native_yaml.*|nativeyaml.*)[.](go|tmpl)' | wc -l)" -eq 0 ]] - if: runner.os == 'Linux' name: Use `loader := NewLoader(); loader.Load ...` diff --git a/go.mod b/go.mod index 9de04f453..99b358918 100644 --- a/go.mod +++ b/go.mod @@ -9,6 +9,7 @@ require ( github.com/oasdiff/yaml3 v0.0.16 github.com/santhosh-tekuri/jsonschema/v6 v6.0.3 github.com/stretchr/testify v1.9.0 + go.yaml.in/yaml/v3 v3.0.5 ) require ( diff --git a/go.sum b/go.sum index df9986795..d3b97759b 100644 --- a/go.sum +++ b/go.sum @@ -27,6 +27,8 @@ github.com/santhosh-tekuri/jsonschema/v6 v6.0.3 h1:1EYB5IzjZawrrnELUi78f9fPu57Hu github.com/santhosh-tekuri/jsonschema/v6 v6.0.3/go.mod h1:JXeL+ps8p7/KNMjDQk3TCwPpBy0wYklyWTfbkIzdIFU= github.com/stretchr/testify v1.9.0 h1:HtqpIVDClZ4nwg75+f6Lvsy/wHu+3BoSGCbBAcpTsTg= github.com/stretchr/testify v1.9.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY= +go.yaml.in/yaml/v3 v3.0.5 h1:N6y/pJk8buWs9NY5ERU2HSMfm+IuD/OtfdAnq6kESPw= +go.yaml.in/yaml/v3 v3.0.5/go.mod h1:HVTZu1O7/Vkt2N+BFy8Zza+lnLsABggaTM2ZpNIGuKg= golang.org/x/text v0.14.0 h1:ScX5w1eTa3QqT8oi6+ziP7dTV1S2+ALU0bI+0zXKWiQ= golang.org/x/text v0.14.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU= gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0= diff --git a/openapi3/native_scalars_test.go b/openapi3/native_scalars_test.go new file mode 100644 index 000000000..637c7e415 --- /dev/null +++ b/openapi3/native_scalars_test.go @@ -0,0 +1,176 @@ +package openapi3 + +import ( + "testing" + + "github.com/stretchr/testify/require" + goyaml "go.yaml.in/yaml/v3" +) + +// YAML resolves more scalar forms than JSON does, so a value reaching an +// any-typed field must not carry a type that depends on its notation. +func TestNativeScalars_AnyValuesAreJSONShaped(t *testing.T) { + const src = ` +type: object +x-dec: 42 +x-hex: 0x2A +x-underscore: 4_2 +x-float: 1.5 +x-str: "42" +x-bool: true +x-nested: {n: 7, list: [1, 2]} +example: 42 +default: 0x10 +` + var node goyaml.Node + require.NoError(t, goyaml.Unmarshal([]byte(src), &node)) + require.NoError(t, prepareScalars(&node)) + + var s Schema + require.NoError(t, node.Content[0].Decode(&s)) + + // Every integer notation lands as float64, as it would through JSON. + for _, k := range []string{"x-dec", "x-hex", "x-underscore", "x-float"} { + require.IsType(t, float64(0), s.Extensions[k], "%s", k) + } + require.EqualValues(t, 42, s.Extensions["x-dec"]) + require.EqualValues(t, 42, s.Extensions["x-hex"], "hex resolves to its value, not its text") + require.EqualValues(t, 42, s.Extensions["x-underscore"]) + + // Other types are untouched. + require.Equal(t, "42", s.Extensions["x-str"]) + require.Equal(t, true, s.Extensions["x-bool"]) + + // Nested maps and lists too. + n := s.Extensions["x-nested"].(map[string]any) + require.IsType(t, float64(0), n["n"]) + require.IsType(t, float64(0), n["list"].([]any)[0]) + + // The any-typed struct fields the decoder fills directly. + require.IsType(t, float64(0), s.Example) + require.IsType(t, float64(0), s.Default) + require.EqualValues(t, 16, s.Default) +} + +// A declared integer field keeps its own type and full range: normalising +// those too would cost precision beyond 2^53, which the previous decode path +// did not. +func TestNativeScalars_DeclaredIntegerFieldsKeepPrecision(t *testing.T) { + const src = "type: integer\nmaxLength: 9007199254740993\n" + var node goyaml.Node + require.NoError(t, goyaml.Unmarshal([]byte(src), &node)) + + var s Schema + require.NoError(t, node.Content[0].Decode(&s)) + require.NotNil(t, s.MaxLength) + require.Equal(t, uint64(9007199254740993), *s.MaxLength, "must not round-trip through float64") +} + +// Date-shaped scalars stay strings, tagged or not: JSON has no timestamp, and +// a time.Time would marshal to text that reads back as a string. +func TestNativeScalars_Timestamps(t *testing.T) { + const src = "example: 2020-06-11T16:32:50Z\n" + var node goyaml.Node + require.NoError(t, goyaml.Unmarshal([]byte(src), &node)) + require.NoError(t, prepareScalars(&node)) + + var s Schema + require.NoError(t, node.Content[0].Decode(&s)) + require.IsType(t, "", s.Example, "a date-shaped example stays a string") + + const tagged = "example: !!timestamp 2020-06-11T16:32:50Z\n" + var taggedNode goyaml.Node + require.NoError(t, goyaml.Unmarshal([]byte(tagged), &taggedNode)) + require.NoError(t, prepareScalars(&taggedNode)) + + var ts Schema + require.NoError(t, taggedNode.Content[0].Decode(&ts)) + require.IsType(t, "", ts.Example, "a tagged one too, the json path doing the same") +} + +// decodeNative decodes src the way the loader's native path does. +func decodeNative(t *testing.T, src string, v any) error { + t.Helper() + + var node goyaml.Node + require.NoError(t, goyaml.Unmarshal([]byte(src), &node)) + if err := prepareScalars(&node); err != nil { + return err + } + return node.Content[0].Decode(v) +} + +// A string cannot hold nil, so the decoder drops a null from a list of them +// and the list comes back shorter than the document. The json path keeps the +// place of the null as an empty string, and so does this. +func TestNativeScalars_NullKeepsItsPlaceInAListOfStrings(t *testing.T) { + var s Schema + require.NoError(t, decodeNative(t, "required: [a, null, b]\ntype: [string, null]\n", &s)) + require.Equal(t, []string{"a", "", "b"}, s.Required) + require.Equal(t, Types{"string", ""}, *s.Type) + + var op Operation + require.NoError(t, decodeNative(t, "tags: [a, null]\n", &op)) + require.Equal(t, []string{"a", ""}, op.Tags) + + var v ServerVariable + require.NoError(t, decodeNative(t, "default: d\nenum: [a, null]\n", &v)) + require.Equal(t, []string{"a", ""}, v.Enum) + + var sr SecurityRequirement + require.NoError(t, decodeNative(t, "scheme: [read, null]\n", &sr)) + require.Equal(t, []string{"read", ""}, sr["scheme"]) +} + +// A scalar's text is not a string where the scalar resolved to something else: +// `title: 1` is a number, which the json path refuses rather than reading as +// "1". +func TestNativeScalars_StringFieldsTakeStringsOnly(t *testing.T) { + for _, test := range []struct { + name, src, want string + }{ + {"an integer", "title: 1\nversion: \"1\"\n", `cannot unmarshal !!int into string field "title"`}, + {"a float", "title: t\nversion: 1.0\n", `cannot unmarshal !!float into string field "version"`}, + {"a boolean", "title: true\nversion: \"1\"\n", `cannot unmarshal !!bool into string field "title"`}, + } { + t.Run(test.name, func(t *testing.T) { + var info Info + require.ErrorContains(t, decodeNative(t, test.src, &info), test.want) + }) + } + + var s Schema + require.ErrorContains(t, decodeNative(t, "required: [1]\n", &s), + `cannot unmarshal !!int into string field "required"`) + require.ErrorContains(t, decodeNative(t, "discriminator: {propertyName: p, mapping: {a: 1}}\n", &s), + `cannot unmarshal !!int into string field "a"`) + + // A null is the empty string, as it is on the json path, and a date-shaped + // scalar is a string in this document's data model. + var info Info + require.NoError(t, decodeNative(t, "title: null\nversion: 2020-01-01\n", &info)) + require.Equal(t, "", info.Title) + require.Equal(t, "2020-01-01", info.Version) +} + +// YAML allows any scalar as a key and a document's names are strings, so a +// scalar key is spelled out. A null key spells nothing, and the json path has +// no key to decode it into, so the document is refused. +func TestNativeScalars_NullKeyNamesNothing(t *testing.T) { + var extension, example Schema + require.ErrorContains(t, decodeNative(t, "x-k: {null: a}\n", &extension), "mapping key is null") + require.ErrorContains(t, decodeNative(t, "example: {null: a}\n", &example), "mapping key is null") + + // Every other scalar has a name. + var named Schema + require.NoError(t, decodeNative(t, "x-k: {1: a, true: b, 1.5: c, 0x2A: d}\n", &named)) + require.Equal(t, map[string]any{"1": "a", "true": "b", "1.5": "c", "42": "d"}, named.Extensions["x-k"]) +} + +// A requirement written as an alias is the mapping it points at, so a null in +// its scopes keeps its place there too. +func TestNativeScalars_NullKeepsItsPlaceThroughAnAlias(t *testing.T) { + var doc T + require.NoError(t, decodeNative(t, "x-s: &s {scheme: [read, null]}\nsecurity: [*s]\n", &doc)) + require.Equal(t, []string{"read", ""}, doc.Security[0]["scheme"]) +} diff --git a/openapi3/native_yaml.go b/openapi3/native_yaml.go new file mode 100644 index 000000000..7a96fa82c --- /dev/null +++ b/openapi3/native_yaml.go @@ -0,0 +1,575 @@ +package openapi3 + +//go:generate go run nativeyamlgenerator.go + +import ( + "errors" + "fmt" + "reflect" + "strings" + "sync" + + yaml "go.yaml.in/yaml/v3" +) + +var knownYAMLFieldsCache sync.Map // reflect.Type -> map[string]struct{} + +// knownYAMLFields returns the yaml keys a struct type declares, skipping "-". +func knownYAMLFields(t reflect.Type) map[string]struct{} { + if v, ok := knownYAMLFieldsCache.Load(t); ok { + return v.(map[string]struct{}) + } + known := make(map[string]struct{}, t.NumField()) + for i := range t.NumField() { + f := t.Field(i) + if !f.IsExported() { + continue + } + if name := yamlKey(f); name != "-" { + known[name] = struct{}{} + } + } + knownYAMLFieldsCache.Store(t, known) + return known +} + +// yamlKey is the document key a struct field is written under. +func yamlKey(f reflect.StructField) string { + name, _, _ := strings.Cut(f.Tag.Get("yaml"), ",") + if name == "" { + name = strings.ToLower(f.Name) + } + return name +} + +// normalizeDecoded gives a decoded any the shape the JSON round trip used to +// guarantee, so a consumer's type switch does not depend on YAML notation: +// +// - integers widen to float64. JSON has one number type, so a value reaching +// an any-typed field carried a float64 whichever notation the source used. +// YAML resolves 42, 0x2A and 4_2 to an int. +// - non-string map keys become strings. YAML allows any scalar as a key, so +// an unquoted 1: becomes map[any]any, which json.Marshal rejects outright. +// +// Applied only to any-typed values. A declared integer field keeps its own +// type and its full range, which a blanket conversion would cost beyond 2^53. +func normalizeDecoded(v any) (any, error) { + switch t := v.(type) { + case int: + return float64(t), nil + case int64: + return float64(t), nil + case uint64: + return float64(t), nil + case map[string]any: + for k, e := range t { + n, err := normalizeDecoded(e) + if err != nil { + return nil, err + } + t[k] = n + } + case map[any]any: + m := make(map[string]any, len(t)) + for k, e := range t { + name, err := keyName(k) + if err != nil { + return nil, err + } + n, err := normalizeDecoded(e) + if err != nil { + return nil, err + } + m[name] = n + } + return m, nil + case []any: + for i, e := range t { + n, err := normalizeDecoded(e) + if err != nil { + return nil, err + } + t[i] = n + } + } + return v, nil +} + +// keyName is the name a non-string key is written under. YAML resolves a key +// the way it resolves any scalar, and a document's names are strings, so a +// scalar key is spelled out. +// +// A null key spells nothing. It names no member of the document, and the json +// path has no key to decode it into, so a document that uses one is refused +// rather than given a made-up name. +func keyName(k any) (string, error) { + if k == nil { + return "", errors.New("mapping key is null, so it names nothing") + } + return fmt.Sprintf("%v", k), nil +} + +// mappingPairs returns node's effective key/value node pairs, applying YAML +// merge keys. +// +// Only Decode applies a merge, and these helpers read node.Content directly, so +// a << key arrives here unexpanded. Ignoring it drops whatever the merge brought +// in; treating it as an ordinary key records "<<" as an extension on a struct +// and as a member on a collection. Both corrupt the document, so the merge is +// resolved here instead, giving every raw-key pass the same view Decode has. +// +// Merge semantics: an explicit key wins over a merged one, and among merged +// sources an earlier one wins, per the YAML merge key spec. +// +// Interim: https://github.com/yaml/go-yaml/issues/451 asks the parser for a +// mapping's effective pairs, which is this function and the cycle guard below +// it. Reimplementing the rules here is also what the self-merge crasher came +// from. +func mappingPairs(node *yaml.Node) [][2]*yaml.Node { + return mappingPairsOf(node, nil) +} + +// mappingPairsOf is mappingPairs carrying the mappings whose merges are being +// expanded, so a mapping that merges itself through an alias contributes +// nothing instead of recursing until the stack ends. The set is allocated only +// for a mapping that has a merge key at all. +func mappingPairsOf(node *yaml.Node, expanding map[*yaml.Node]struct{}) [][2]*yaml.Node { + pairs := make([][2]*yaml.Node, 0, len(node.Content)/2) + var merged [][2]*yaml.Node + seen := make(map[string]struct{}, len(node.Content)/2) + + for i := 0; i+1 < len(node.Content); i += 2 { + k, v := node.Content[i], node.Content[i+1] + if isMergeKey(k) { + if expanding == nil { + expanding = make(map[*yaml.Node]struct{}, 1) + } + expanding[node] = struct{}{} + merged = append(merged, mergeSourcePairs(v, expanding)...) + continue + } + pairs = append(pairs, [2]*yaml.Node{k, v}) + seen[k.Value] = struct{}{} + } + + for _, kv := range merged { + if _, ok := seen[kv[0].Value]; ok { + continue + } + seen[kv[0].Value] = struct{}{} + pairs = append(pairs, kv) + } + return pairs +} + +// mappingValue returns the value node for key, or nil. +func mappingValue(node *yaml.Node, key string) *yaml.Node { + _, v := mappingEntry(node, key) + return v +} + +// mappingEntry returns both halves of a mapping entry. Merge keys are applied, +// so a field a merge brought in is found here the same as one written in place. +func mappingEntry(node *yaml.Node, key string) (*yaml.Node, *yaml.Node) { + if node.Kind != yaml.MappingNode { + return nil, nil + } + for _, kv := range mappingPairs(node) { + if kv[0].Value == key { + return kv[0], kv[1] + } + } + return nil, nil +} + +// isMergeKey reports whether k is a merge key rather than an ordinary one. +// Only a plain << merges; quoted, it is a member actually named "<<", which +// the json path keeps and so must this. +func isMergeKey(k *yaml.Node) bool { + if k.Tag == mergeKeyTag { + return true + } + return k.Value == mergeKey && k.Style == 0 && (k.Tag == "" || k.Tag == strTag) +} + +// mergeSourcePairs returns the pairs a merge key's value contributes: one +// mapping, or a sequence of them in precedence order. Anything else is not a +// valid merge source and contributes nothing. +func mergeSourcePairs(v *yaml.Node, expanding map[*yaml.Node]struct{}) [][2]*yaml.Node { + if v.Kind == yaml.AliasNode { + v = v.Alias + } + if v == nil { + return nil + } + switch v.Kind { + case yaml.MappingNode: + if _, ok := expanding[v]; ok { + return nil + } + return mappingPairsOf(v, expanding) + case yaml.SequenceNode: + var out [][2]*yaml.Node + for _, e := range v.Content { + out = append(out, mergeSourcePairs(e, expanding)...) + } + return out + } + return nil +} + +const ( + mergeKey = "<<" + mergeKeyTag = "!!merge" + strTag = "!!str" + nullTag = "!!null" + timestampTag = "!!timestamp" +) + +// decodeAny decodes a value node into an any and normalizes it. Every path that +// puts a decoded value behind an any must come through here, so none of them can +// omit a normalization by forgetting to call it. +func decodeAny(node *yaml.Node) (any, error) { + var v any + if err := node.Decode(&v); err != nil { + return nil, err + } + return normalizeDecoded(v) +} + +// collectExtensions returns the mapping keys of node that known does not +// declare, decoded and normalized, along with their names in document order. +// The names are every undeclared sibling, including x- ones; callers that keep +// only extensions filter the map, and callers that validate siblings read the +// names. +func collectExtensions(node *yaml.Node, known map[string]struct{}) (map[string]any, []string, error) { + if node.Kind != yaml.MappingNode { + return nil, nil, nil + } + var ext map[string]any + var names []string + for _, kv := range mappingPairs(node) { + key := kv[0].Value + if _, ok := known[key]; ok { + continue + } + v, err := decodeAny(kv[1]) + if err != nil { + return nil, nil, err + } + if ext == nil { + ext = make(map[string]any) + } + ext[key] = v + names = append(names, key) + } + return ext, names, nil +} + +// normalizeAnyFields applies normalizeNumbers to a struct's any-typed fields, +// which the decoder fills directly: Example and Default, but also Enum, whose +// element type is any. Missing the slice case left an integer example as a +// float64 and the enum it must match as an int, so a schema failed against its +// own allowed values. +func normalizeAnyFields(out any) error { + v := reflect.ValueOf(out) + for v.Kind() == reflect.Pointer { + if v.IsNil() { + return nil + } + v = v.Elem() + } + if v.Kind() != reflect.Struct { + return nil + } + for i := range v.NumField() { + f := v.Field(i) + if !f.CanSet() { + continue + } + switch f.Kind() { + case reflect.Interface: + if f.IsNil() { + continue + } + n, err := normalizeDecoded(f.Interface()) + if err != nil { + return err + } + f.Set(reflect.ValueOf(n)) + case reflect.Slice, reflect.Map: + // []any and map[string]any: normalise the elements in place. + if f.Type().Elem().Kind() != reflect.Interface || f.IsNil() { + continue + } + if f.Kind() == reflect.Slice { + for j := range f.Len() { + e := f.Index(j) + if e.IsNil() { + continue + } + n, err := normalizeDecoded(e.Interface()) + if err != nil { + return err + } + e.Set(reflect.ValueOf(n)) + } + continue + } + for _, k := range f.MapKeys() { + e := f.MapIndex(k) + if e.IsNil() { + continue + } + n, err := normalizeDecoded(e.Interface()) + if err != nil { + return err + } + f.SetMapIndex(k, reflect.ValueOf(n)) + } + } + } + return nil +} + +// decodeMapping decodes node into a method-less view of the target, supplied by +// the caller as a locally-declared shadow type, and returns the keys the target +// does not declare. T is the target itself, named so that an error reports the +// type the document was read into. +func decodeMapping[T, S any](node *yaml.Node, shadow *S) (map[string]any, error) { + ext, err := decodeStructWithExtensions(node, shadow) + if err != nil { + return nil, targetTypeError[T, S](err) + } + return ext, nil +} + +// targetTypeError names T where a decoder error names the shadow type S, which +// exists only to stop the decode recursing and means nothing to a reader. +func targetTypeError[T, S any](err error) error { + var typeErr *yaml.TypeError + if !errors.As(err, &typeErr) { + return err + } + shadow, target := reflect.TypeFor[S]().String(), reflect.TypeFor[T]().String() + for i, message := range typeErr.Errors { + typeErr.Errors[i] = strings.ReplaceAll(message, shadow, target) + } + return typeErr +} + +// decodeStructWithExtensions decodes node into out and returns the mapping keys +// out does not declare, which are the extensions. Returns nil rather than an +// empty map when there are none. +// +// The declared set comes from out's yaml tags, so adding a field to a struct is +// enough to stop it being collected as an extension. +func decodeStructWithExtensions(node *yaml.Node, out any) (map[string]any, error) { + if err := node.Decode(out); err != nil { + return nil, err + } + if node.Kind != yaml.MappingNode { + return nil, nil + } + if err := checkDeclaredFields(node, out); err != nil { + return nil, err + } + ext, _, err := collectExtensions(node, knownYAMLFields(reflect.TypeOf(out).Elem())) + if err != nil { + return nil, err + } + if err := normalizeAnyFields(out); err != nil { + return nil, err + } + return ext, nil +} + +// checkDeclaredFields holds out's declared fields to the values a JSON +// document would carry, which the decoder is laxer than on two counts. +// +// A scalar's text goes into a string field whatever the scalar resolved to, so +// `title: 1` reads as "1" where the json path refuses the document. And a +// sequence element the target cannot hold is dropped, so `required: [a, null, +// b]` reads as two entries where the json path keeps the null's place as an +// empty string. A document that changes meaning with the decoder is worse than +// one that is refused, so a scalar that resolved to something other than a +// string is refused here, and a null in a list of strings keeps its place. +// +// Only out's own fields. A field whose type has an UnmarshalYAML of its own is +// held to this when the decoder reaches that type. +func checkDeclaredFields(node *yaml.Node, out any) error { + if node.Kind != yaml.MappingNode { + return nil + } + v := reflect.ValueOf(out).Elem() + t := v.Type() + for i := range t.NumField() { + f := t.Field(i) + if !f.IsExported() { + continue + } + key := yamlKey(f) + if key == "-" { + continue + } + value := mappingValue(node, key) + if value == nil { + continue + } + if err := checkFieldValue(v.Field(i), value, key); err != nil { + return err + } + } + return nil +} + +// checkFieldValue applies checkDeclaredFields to one field: the string slots +// are a string field, a list of strings, and a map whose values are written as +// text. Anything else is the decoder's business. +func checkFieldValue(field reflect.Value, node *yaml.Node, key string) error { + for field.Kind() == reflect.Pointer { + if field.IsNil() { + return nil + } + field = field.Elem() + } + switch { + case field.Kind() == reflect.String: + return requireStringScalar(node, key) + case field.Kind() == reflect.Slice && field.Type().Elem().Kind() == reflect.String: + return setStringList(field, node, key) + case field.Kind() == reflect.Map && writtenAsText(field.Type().Elem()): + for _, kv := range mappingPairs(node) { + if err := requireStringScalar(kv[1], kv[0].Value); err != nil { + return err + } + } + } + return nil +} + +// writtenAsText reports whether a value of type t is written as a scalar +// string, either because it is one or because it decodes from text. +func writtenAsText(t reflect.Type) bool { + if t.Kind() == reflect.String { + return true + } + return reflect.PointerTo(t).Implements(reflect.TypeFor[interface{ UnmarshalText(text []byte) error }]()) +} + +// setStringList sets a list of strings from node. The field may be any type +// whose underlying type is a list of strings, such as Types. +func setStringList(field reflect.Value, node *yaml.Node, key string) error { + list, ok, err := stringList(node, key) + if err != nil || !ok { + return err + } + field.Set(reflect.ValueOf(list).Convert(field.Type())) + return nil +} + +// stringList is the list of strings node holds, keeping the place of a null as +// the empty string. The decoder drops such an element, since a string cannot +// hold nil, which shortens the list without saying so. +// +// ok is false for a node that is not a sequence: one value where a list is +// allowed, as in `type: string`, and anything the decode reports itself. +func stringList(node *yaml.Node, key string) ([]string, bool, error) { + if node.Kind == yaml.AliasNode { + node = node.Alias + } + if node.Kind == yaml.ScalarNode { + return nil, false, requireStringScalar(node, key) + } + if node.Kind != yaml.SequenceNode { + return nil, false, nil + } + + list := make([]string, len(node.Content)) + for i, e := range node.Content { + if e.Kind == yaml.AliasNode { + e = e.Alias + } + if err := requireStringScalar(e, key); err != nil { + return nil, false, err + } + if e.Kind != yaml.ScalarNode { + return nil, false, nil + } + if e.Tag != nullTag { + list[i] = e.Value + } + } + return list, true, nil +} + +// requireStringScalar refuses a scalar that resolved to something other than a +// string where a string belongs. +// +// A null is allowed: a string cannot hold nil, so the json path reads it as the +// empty string, and so does setStringList. A date-shaped scalar is allowed +// because it is a string in this document's data model, which is what +// stripTimestamp says. +func requireStringScalar(node *yaml.Node, key string) error { + if node.Kind != yaml.ScalarNode { + return nil + } + switch node.Tag { + case "", strTag, nullTag, timestampTag: + return nil + } + return fmt.Errorf("yaml: line %d: cannot unmarshal %s into string field %q", node.Line, node.Tag, key) +} + +// prepareScalars walks the tree once, which is the one place every scalar is +// seen before the decode reads it. +func prepareScalars(n *yaml.Node) error { + if n == nil { + return nil + } + if n.Kind == yaml.ScalarNode { + stripTimestamp(n) + if err := checkFinite(n); err != nil { + return err + } + } + for _, c := range n.Content { + if err := prepareScalars(c); err != nil { + return err + } + } + return nil +} + +// stripTimestamp retags a date-shaped scalar as a string. +// +// YAML 1.1 resolves an untagged scalar such as 2020-06-11T16:32:50-03:00 to a +// timestamp, which would make an OpenAPI `example` of that shape decode to a +// time.Time: not a type the document's own data model has, and one that +// marshals to text that reads back as a string, so the document would not +// survive a round trip. A tag written out asks for the same type and cannot +// have it either, so it is retagged too, and the scalar keeps the text the +// document gave it rather than the time it names. +// +// Interim: https://github.com/yaml/go-yaml/issues/452 asks for an option to +// leave such a scalar a string, which removes this. +func stripTimestamp(n *yaml.Node) { + if n.Tag == timestampTag { + n.Tag = strTag + } +} + +// checkFinite rejects infinity and NaN, which YAML has and JSON does not. +// Such a document decodes, and a float field or an extension then holds a +// value that cannot be written back: marshaling fails wherever the value sits, +// naming neither the document nor the line. Refusing it here names both. +func checkFinite(n *yaml.Node) error { + if n.Tag != "!!float" { + return nil + } + switch strings.ToLower(strings.TrimLeft(n.Value, "+-")) { + case ".inf", ".nan": + return fmt.Errorf("line %d: %s has no JSON representation", n.Line, n.Value) + } + return nil +} diff --git a/openapi3/native_yaml_direct_test.go b/openapi3/native_yaml_direct_test.go new file mode 100644 index 000000000..b2c37495e --- /dev/null +++ b/openapi3/native_yaml_direct_test.go @@ -0,0 +1,32 @@ +package openapi3_test + +import ( + "encoding/json" + "testing" + + "github.com/stretchr/testify/require" + yaml "go.yaml.in/yaml/v3" + + "github.com/getkin/kin-openapi/openapi3" +) + +// Decoding these types with the yaml package keeps what the document said. +// Without UnmarshalYAML the decoder fills declared fields by struct tag, so an +// extension is dropped, since Extensions carries `yaml:"-"`, and a key that +// differs from a field only in case is dropped with it. +func TestYAMLDecodeKeepsExtensionsAndKeyCase(t *testing.T) { + t.Parallel() + + const src = "title: t\nversion: \"1\"\nx-custom: 7\nTitle: other\n" + + var info openapi3.Info + require.NoError(t, yaml.Unmarshal([]byte(src), &info)) + require.Equal(t, "t", info.Title) + require.Equal(t, "1", info.Version) + require.Equal(t, map[string]any{"x-custom": float64(7), "Title": "other"}, info.Extensions) + + // And it marshals back to what a JSON decode of the same document gives. + out, err := json.Marshal(&info) + require.NoError(t, err) + require.JSONEq(t, `{"title":"t","version":"1","x-custom":7,"Title":"other"}`, string(out)) +} diff --git a/openapi3/native_yaml_normalization_test.go b/openapi3/native_yaml_normalization_test.go new file mode 100644 index 000000000..e125299a1 --- /dev/null +++ b/openapi3/native_yaml_normalization_test.go @@ -0,0 +1,302 @@ +package openapi3 + +import ( + "context" + "encoding/json" + "fmt" + "slices" + "strings" + "testing" +) + +// Three functions decode a mapping, and each has to apply the same four +// normalizations to what it produces: +// +// struct - decodeStructWithExtensions, for objects with declared fields +// maplike - unmarshalMaplikeYAML, for keyed collections (Responses, Callback) +// ref - unmarshalRefYAML, for the $ref wrappers +// +// The normalizations: +// +// siblings - an undeclared non-x- key is recorded, so Validate can report it +// wherever the object it sits on rejects extra fields +// numbers - an integer behind an any is a float64, whatever the notation +// keys - a non-string mapping key becomes a string, so the document marshals +// merge - a << key is applied, neither ignored nor treated as content +// +// This table covers each function against each normalization. A function that +// leaves one out fails here. +var nativeDecodeTests = []struct { + path, property string + spec string + assert func(t *testing.T, doc *T) +}{ + { + path: "struct", property: "siblings", + spec: ` +openapi: 3.0.0 +info: {title: t, version: "1", bogus: true} +paths: {} +`, + assert: func(t *testing.T, doc *T) { requireValidateFails(t, doc, "bogus") }, + }, + { + path: "struct", property: "numbers", + spec: ` +openapi: 3.0.0 +info: {title: t, version: "1", x-num: 7} +paths: {} +`, + assert: func(t *testing.T, doc *T) { requireFloat(t, doc.Info.Extensions["x-num"]) }, + }, + { + path: "struct", property: "keys", + spec: ` +openapi: 3.0.0 +info: + title: t + version: "1" + x-thing: {nested: {1: one}} +paths: {} +`, + assert: requireMarshalable, + }, + { + path: "struct", property: "merge", + spec: ` +openapi: 3.0.0 +x-defaults: &d + title: t + x-num: 7 +info: + <<: *d + version: "1" +paths: {} +`, + assert: func(t *testing.T, doc *T) { + if _, ok := doc.Info.Extensions[mergeKey]; ok { + t.Errorf("merge key kept as an extension: %v", doc.Info.Extensions) + } + if doc.Info.Title != "t" { + t.Errorf("merged field lost: title = %q", doc.Info.Title) + } + if doc.Info.Extensions["x-num"] == nil { + t.Error("merged extension lost") + } + requireValidates(t, doc) + }, + }, + { + path: "maplike", property: "numbers", + spec: ` +openapi: 3.0.0 +info: {title: t, version: "1"} +paths: + /a: + get: + responses: + x-num: 7 + "200": {description: ok} +`, + assert: func(t *testing.T, doc *T) { requireFloat(t, responsesOf(doc).Extensions["x-num"]) }, + }, + { + path: "maplike", property: "keys", + spec: ` +openapi: 3.0.0 +info: {title: t, version: "1"} +paths: + /a: + get: + responses: + x-thing: {nested: {1: one}} + "200": {description: ok} +`, + assert: requireMarshalable, + }, + { + path: "maplike", property: "merge", + spec: ` +openapi: 3.0.0 +info: {title: t, version: "1"} +x-tmpl: &d + "200": {description: ok} +paths: + /a: + get: + responses: + <<: *d +`, + assert: func(t *testing.T, doc *T) { + if responsesOf(doc).Value("200") == nil { + t.Error("merged response lost") + } + requireValidates(t, doc) + }, + }, + { + path: "ref", property: "siblings", + spec: ` +openapi: 3.0.0 +info: {title: t, version: "1"} +paths: + /a: + get: + responses: + "200": {$ref: '#/components/responses/R', bogus: true} +components: + responses: + R: {description: ok} +`, + // A Reference Object ignores the siblings it does not define, so this + // document validates; the name still has to be recorded, which is what + // lets Validate report one where the object does reject it. + assert: func(t *testing.T, doc *T) { + requireRecorded(t, responsesOf(doc).Value("200").extra, "bogus") + requireValidates(t, doc) + }, + }, + { + path: "ref", property: "numbers", + spec: ` +openapi: 3.0.0 +info: {title: t, version: "1"} +paths: + /a: + get: + responses: + "200": {$ref: '#/components/responses/R', x-num: 7} +components: + responses: + R: {description: ok} +`, + assert: func(t *testing.T, doc *T) { + requireFloat(t, responsesOf(doc).Map()["200"].Extensions["x-num"]) + }, + }, + { + path: "ref", property: "keys", + spec: ` +openapi: 3.0.0 +info: {title: t, version: "1"} +paths: + /a: + get: + responses: + "200": + $ref: '#/components/responses/R' + x-meta: {1: one} +components: + responses: + R: {description: ok} +`, + assert: requireMarshalable, + }, + { + path: "ref", property: "merge", + spec: ` +openapi: 3.0.0 +info: {title: t, version: "1"} +x-tmpl: &d + $ref: '#/components/responses/R' +paths: + /a: + get: + responses: + "200": + <<: *d +components: + responses: + R: {description: ok} +`, + assert: func(t *testing.T, doc *T) { + if got := responsesOf(doc).Map()["200"].Ref; got != "#/components/responses/R" { + t.Errorf("merged $ref lost: %q", got) + } + requireValidates(t, doc) + }, + }, +} + +func TestNativeDecodePathsApplyTheSameNormalizations(t *testing.T) { + for _, c := range nativeDecodeTests { + t.Run(c.path+"/"+c.property, func(t *testing.T) { + loader := NewLoader() + doc, err := loader.LoadFromData([]byte(c.spec)) + if err != nil { + t.Fatalf("load: %v", err) + } + c.assert(t, doc) + }) + } +} + +// notApplicable records the combinations that cannot exist, with the reason. +// A combination that is neither tested nor listed here fails, so adding a decode +// function or a normalization has to come with its tests. +var notApplicable = map[string]string{ + "maplike/siblings": "every non-x- key of a keyed collection is a member of it, so there is no undeclared sibling to record", +} + +func TestNativeDecodeCoversEveryNormalization(t *testing.T) { + tested := map[string]bool{} + for _, c := range nativeDecodeTests { + tested[c.path+"/"+c.property] = true + } + for _, path := range []string{"struct", "maplike", "ref"} { + for _, property := range []string{"siblings", "numbers", "keys", "merge"} { + name := path + "/" + property + _, exempt := notApplicable[name] + if !tested[name] && !exempt { + t.Errorf("%s is untested\n add it to nativeDecodeTests, or list it in notApplicable with a reason", name) + } + if tested[name] && exempt { + t.Errorf("%s is tested but still listed in notApplicable\n remove it from notApplicable", name) + } + } + } +} + +func responsesOf(doc *T) *Responses { + return doc.Paths.Value("/a").Get.Responses +} + +func requireValidates(t *testing.T, doc *T) { + t.Helper() + if err := doc.Validate(context.Background()); err != nil { + t.Errorf("validate: %v", err) + } +} + +func requireRecorded(t *testing.T, extra []string, name string) { + t.Helper() + if !slices.Contains(extra, name) { + t.Errorf("sibling %q was not recorded, got %v", name, extra) + } +} + +func requireValidateFails(t *testing.T, doc *T, name string) { + t.Helper() + err := doc.Validate(context.Background()) + if err == nil { + t.Errorf("undeclared sibling %q was accepted", name) + return + } + if want := fmt.Sprintf("[%s]", name); !strings.Contains(err.Error(), want) { + t.Errorf("validate reported %v, want it to name %s", err, want) + } +} + +func requireFloat(t *testing.T, v any) { + t.Helper() + if _, ok := v.(float64); !ok { + t.Errorf("integer behind an any is %T(%v), want float64", v, v) + } +} + +func requireMarshalable(t *testing.T, doc *T) { + t.Helper() + if _, err := json.Marshal(doc); err != nil { + t.Errorf("document loaded but does not marshal: %v", err) + } +} diff --git a/openapi3/native_yaml_refs.go b/openapi3/native_yaml_refs.go new file mode 100644 index 000000000..1923f7aba --- /dev/null +++ b/openapi3/native_yaml_refs.go @@ -0,0 +1,77 @@ +package openapi3 + +// Shared by the generated $ref wrapper UnmarshalYAML methods in refs.go. + +import ( + "strings" + + yaml "go.yaml.in/yaml/v3" +) + +// refYAMLFields are the keys the wrapper declares itself, so they are not +// siblings. summary and description count only for wrappers that carry them: +// SchemaRef does not, and there they are siblings like any other key, which is +// what the JSON path records. + +// unmarshalRefYAML fills the reference half of a wrapper and reports whether +// the node was a reference. When false the caller decodes the value. +func unmarshalRefYAML(node *yaml.Node, ref *string, summary, description **string, extensions *map[string]any, extra *[]string, siblingExtras *map[string]any) bool { + refNode := mappingValue(node, "$ref") + if refNode != nil && refNode.Kind == yaml.AliasNode && refNode.Alias != nil { + refNode = refNode.Alias + } + // A $ref is a string. A null, a number or a collection is not a reference, + // so the object decodes as an ordinary value, which is what the json path + // does with a $ref that will not decode into a string. + if refNode == nil || refNode.Kind != yaml.ScalarNode || refNode.Tag != strTag || refNode.Value == "" { + return false + } + *ref = refNode.Value + + known := map[string]struct{}{"$ref": {}} + if summary != nil { + known["summary"] = struct{}{} + } + if description != nil { + known["description"] = struct{}{} + } + + for _, kv := range mappingPairs(node) { + switch k, v := kv[0].Value, kv[1]; { + case k == "summary" && summary != nil: + var str string + if v.Decode(&str) == nil { + *summary = &str + } + case k == "description" && description != nil: + var str string + if v.Decode(&str) == nil { + *description = &str + } + } + } + + // Every undeclared sibling is recorded, not only the x- ones: Validate reads + // these names, and a name it never sees is a name it cannot report. The x- + // ones are extensions, the rest are siblings of the $ref, which 3.1 lets a + // schema apply alongside the resolved reference. + siblings, names, err := collectExtensions(node, known) + if err != nil { + return true + } + *extra = names + for k, v := range siblings { + if !strings.HasPrefix(k, "x-") { + if *siblingExtras == nil { + *siblingExtras = make(map[string]any, len(siblings)) + } + (*siblingExtras)[k] = v + continue + } + if *extensions == nil { + *extensions = make(map[string]any) + } + (*extensions)[k] = v + } + return true +} diff --git a/openapi3/native_yaml_shadow.go b/openapi3/native_yaml_shadow.go new file mode 100644 index 000000000..4cbcd56bf --- /dev/null +++ b/openapi3/native_yaml_shadow.go @@ -0,0 +1,244 @@ +// Code generated by go generate using nativeyaml.tmpl; DO NOT EDIT native_yaml_shadow.go. +package openapi3 + +import ( + yaml "go.yaml.in/yaml/v3" +) + +// UnmarshalYAML for the types whose YAML form is a mapping of declared fields +// plus extensions. +// +// The local shadow type is what stops the decoder recursing into this method; +// converting the receiver to it decodes in place, so only the field the decoder +// skips is set afterwards. Everything else is in decodeMapping. + +// UnmarshalYAML sets Components from node. +func (components *Components) UnmarshalYAML(node *yaml.Node) error { + type bis Components + ext, err := decodeMapping[Components](node, (*bis)(components)) + if err != nil { + return err + } + components.Extensions = ext + return nil +} + +// UnmarshalYAML sets Contact from node. +func (contact *Contact) UnmarshalYAML(node *yaml.Node) error { + type bis Contact + ext, err := decodeMapping[Contact](node, (*bis)(contact)) + if err != nil { + return err + } + contact.Extensions = ext + return nil +} + +// UnmarshalYAML sets Discriminator from node. +func (discriminator *Discriminator) UnmarshalYAML(node *yaml.Node) error { + type bis Discriminator + ext, err := decodeMapping[Discriminator](node, (*bis)(discriminator)) + if err != nil { + return err + } + discriminator.Extensions = ext + return nil +} + +// UnmarshalYAML sets Encoding from node. +func (encoding *Encoding) UnmarshalYAML(node *yaml.Node) error { + type bis Encoding + ext, err := decodeMapping[Encoding](node, (*bis)(encoding)) + if err != nil { + return err + } + encoding.Extensions = ext + return nil +} + +// UnmarshalYAML sets Example from node. +func (example *Example) UnmarshalYAML(node *yaml.Node) error { + type bis Example + ext, err := decodeMapping[Example](node, (*bis)(example)) + if err != nil { + return err + } + example.Extensions = ext + return nil +} + +// UnmarshalYAML sets ExternalDocs from node. +func (e *ExternalDocs) UnmarshalYAML(node *yaml.Node) error { + type bis ExternalDocs + ext, err := decodeMapping[ExternalDocs](node, (*bis)(e)) + if err != nil { + return err + } + e.Extensions = ext + return nil +} + +// UnmarshalYAML sets Info from node. +func (info *Info) UnmarshalYAML(node *yaml.Node) error { + type bis Info + ext, err := decodeMapping[Info](node, (*bis)(info)) + if err != nil { + return err + } + info.Extensions = ext + return nil +} + +// UnmarshalYAML sets License from node. +func (license *License) UnmarshalYAML(node *yaml.Node) error { + type bis License + ext, err := decodeMapping[License](node, (*bis)(license)) + if err != nil { + return err + } + license.Extensions = ext + return nil +} + +// UnmarshalYAML sets Link from node. +func (link *Link) UnmarshalYAML(node *yaml.Node) error { + type bis Link + ext, err := decodeMapping[Link](node, (*bis)(link)) + if err != nil { + return err + } + link.Extensions = ext + return nil +} + +// UnmarshalYAML sets MediaType from node. +func (mediaType *MediaType) UnmarshalYAML(node *yaml.Node) error { + type bis MediaType + ext, err := decodeMapping[MediaType](node, (*bis)(mediaType)) + if err != nil { + return err + } + mediaType.Extensions = ext + return nil +} + +// UnmarshalYAML sets OAuthFlow from node. +func (flow *OAuthFlow) UnmarshalYAML(node *yaml.Node) error { + type bis OAuthFlow + ext, err := decodeMapping[OAuthFlow](node, (*bis)(flow)) + if err != nil { + return err + } + flow.Extensions = ext + return nil +} + +// UnmarshalYAML sets OAuthFlows from node. +func (flows *OAuthFlows) UnmarshalYAML(node *yaml.Node) error { + type bis OAuthFlows + ext, err := decodeMapping[OAuthFlows](node, (*bis)(flows)) + if err != nil { + return err + } + flows.Extensions = ext + return nil +} + +// UnmarshalYAML sets Parameter from node. +func (parameter *Parameter) UnmarshalYAML(node *yaml.Node) error { + type bis Parameter + ext, err := decodeMapping[Parameter](node, (*bis)(parameter)) + if err != nil { + return err + } + parameter.Extensions = ext + return nil +} + +// UnmarshalYAML sets PathItem from node. +func (pathItem *PathItem) UnmarshalYAML(node *yaml.Node) error { + type bis PathItem + ext, err := decodeMapping[PathItem](node, (*bis)(pathItem)) + if err != nil { + return err + } + pathItem.Extensions = ext + return nil +} + +// UnmarshalYAML sets RequestBody from node. +func (requestBody *RequestBody) UnmarshalYAML(node *yaml.Node) error { + type bis RequestBody + ext, err := decodeMapping[RequestBody](node, (*bis)(requestBody)) + if err != nil { + return err + } + requestBody.Extensions = ext + return nil +} + +// UnmarshalYAML sets Response from node. +func (response *Response) UnmarshalYAML(node *yaml.Node) error { + type bis Response + ext, err := decodeMapping[Response](node, (*bis)(response)) + if err != nil { + return err + } + response.Extensions = ext + return nil +} + +// UnmarshalYAML sets SecurityScheme from node. +func (ss *SecurityScheme) UnmarshalYAML(node *yaml.Node) error { + type bis SecurityScheme + ext, err := decodeMapping[SecurityScheme](node, (*bis)(ss)) + if err != nil { + return err + } + ss.Extensions = ext + return nil +} + +// UnmarshalYAML sets Server from node. +func (server *Server) UnmarshalYAML(node *yaml.Node) error { + type bis Server + ext, err := decodeMapping[Server](node, (*bis)(server)) + if err != nil { + return err + } + server.Extensions = ext + return nil +} + +// UnmarshalYAML sets ServerVariable from node. +func (serverVariable *ServerVariable) UnmarshalYAML(node *yaml.Node) error { + type bis ServerVariable + ext, err := decodeMapping[ServerVariable](node, (*bis)(serverVariable)) + if err != nil { + return err + } + serverVariable.Extensions = ext + return nil +} + +// UnmarshalYAML sets Tag from node. +func (t *Tag) UnmarshalYAML(node *yaml.Node) error { + type bis Tag + ext, err := decodeMapping[Tag](node, (*bis)(t)) + if err != nil { + return err + } + t.Extensions = ext + return nil +} + +// UnmarshalYAML sets XML from node. +func (xml *XML) UnmarshalYAML(node *yaml.Node) error { + type bis XML + ext, err := decodeMapping[XML](node, (*bis)(xml)) + if err != nil { + return err + } + xml.Extensions = ext + return nil +} diff --git a/openapi3/native_yaml_special.go b/openapi3/native_yaml_special.go new file mode 100644 index 000000000..df283c75f --- /dev/null +++ b/openapi3/native_yaml_special.go @@ -0,0 +1,184 @@ +package openapi3 + +// UnmarshalYAML for the maplike collections, whose entries are components +// rather than declared fields, and for the union-typed values. + +import ( + "strings" + + yaml "go.yaml.in/yaml/v3" +) + +// unmarshalMaplikeYAML decodes a mapping whose x- keys are extensions and whose +// remaining entries are components, stamping each entry's origin from the key +// that heads it. +func unmarshalMaplikeYAML[V any](node *yaml.Node, ext *map[string]any, out *map[string]*V) error { + if node.Kind != yaml.MappingNode { + return node.Decode(out) + } + *ext = make(map[string]any) + *out = make(map[string]*V, len(node.Content)/2) + for _, kv := range mappingPairs(node) { + k, v := kv[0].Value, kv[1] + if strings.HasPrefix(k, "x-") { + a, err := decodeAny(v) + if err != nil { + return err + } + (*ext)[k] = a + continue + } + var vv V + if err := v.Decode(&vv); err != nil { + return err + } + (*out)[k] = &vv + } + return nil +} + +func (responses *Responses) UnmarshalYAML(node *yaml.Node) error { + var x Responses + if err := unmarshalMaplikeYAML(node, &x.Extensions, &x.m); err != nil { + return err + } + *responses = x + return nil +} + +func (callback *Callback) UnmarshalYAML(node *yaml.Node) error { + var x Callback + if err := unmarshalMaplikeYAML(node, &x.Extensions, &x.m); err != nil { + return err + } + *callback = x + return nil +} + +func (paths *Paths) UnmarshalYAML(node *yaml.Node) error { + var x Paths + if err := unmarshalMaplikeYAML(node, &x.Extensions, &x.m); err != nil { + return err + } + *paths = x + return nil +} + +// Header embeds Parameter and carries no fields of its own. +func (header *Header) UnmarshalYAML(node *yaml.Node) error { + return header.Parameter.UnmarshalYAML(node) +} + +// BoolSchema is `true`/`false` or a schema. +func (bs *BoolSchema) UnmarshalYAML(node *yaml.Node) error { + if node.Kind == yaml.ScalarNode { + if node.Tag == nullTag { + return nil + } + var b bool + if err := node.Decode(&b); err == nil { + bs.Has = &b + return nil + } + } + var sr SchemaRef + if err := node.Decode(&sr); err != nil { + return err + } + bs.Schema = &sr + return nil +} + +// Schema is `true`/`false` or a mapping. JSON Schema 2020-12, which OpenAPI 3.1 +// adopts, allows a boolean wherever a schema is expected. +// +// The mapping branch is what the generator emits for the other declared-field +// types; only the scalar case is particular to Schema. +func (schema *Schema) UnmarshalYAML(node *yaml.Node) error { + if node.Kind == yaml.ScalarNode && node.Tag == "!!bool" { + var b bool + if err := node.Decode(&b); err != nil { + return err + } + schema.Always = &b + return nil + } + + type bis Schema + ext, err := decodeMapping[Schema](node, (*bis)(schema)) + if err != nil { + return err + } + schema.Extensions = ext + return nil +} + +// ExclusiveBound is a bool in OAS 3.0, where it modifies minimum/maximum, or a +// number in 3.1, where it is the bound itself. +func (eb *ExclusiveBound) UnmarshalYAML(node *yaml.Node) error { + if node.Kind != yaml.ScalarNode || node.Tag == nullTag { + return nil + } + var b bool + if err := node.Decode(&b); err == nil { + eb.Bool = &b + return nil + } + var f float64 + if err := node.Decode(&f); err != nil { + return err + } + eb.Value = &f + return nil +} + +// Operation distinguishes an omitted responses from an explicitly null one: +// the first is allowed in OAS 3.1 and later, the second never is. A null node +// decodes to an empty Responses, which is indistinguishable from `{}` without +// the flag. +func (operation *Operation) UnmarshalYAML(node *yaml.Node) error { + type bis Operation + ext, err := decodeMapping[Operation](node, (*bis)(operation)) + if err != nil { + return err + } + operation.Extensions = ext + if v := mappingValue(node, "responses"); v != nil && v.Tag == nullTag { + operation.Responses = &Responses{explicitlyNull: true} + } + return nil +} + +func (doc *T) UnmarshalYAML(node *yaml.Node) error { + type bis T + ext, err := decodeMapping[T](node, (*bis)(doc)) + if err != nil { + return err + } + doc.Extensions = ext + return nil +} + +// UnmarshalYAML sets SecurityRequirement from node. +// +// A scheme's scopes are a list of strings, and decoding one directly drops a +// null from it rather than keeping its place, which is what stringList is for. +func (sr *SecurityRequirement) UnmarshalYAML(node *yaml.Node) error { + type bis SecurityRequirement + if err := node.Decode((*bis)(sr)); err != nil { + return err + } + if node.Kind == yaml.AliasNode { + node = node.Alias + } + for _, kv := range mappingPairs(node) { + scopes, ok, err := stringList(kv[1], kv[0].Value) + if err != nil { + return err + } + if ok { + (*sr)[kv[0].Value] = scopes + } + } + return nil +} diff --git a/openapi3/native_yaml_test.go b/openapi3/native_yaml_test.go new file mode 100644 index 000000000..1aef1f9bd --- /dev/null +++ b/openapi3/native_yaml_test.go @@ -0,0 +1,99 @@ +package openapi3 + +import ( + "encoding/json" + "fmt" + "testing" + + "github.com/stretchr/testify/require" + goyaml "go.yaml.in/yaml/v3" +) + +const nativeSrc = `"200": + description: ok + x-tags: + - alpha + - beta + content: + application/json: + x-media: 1 +"404": + $ref: '#/components/responses/NotFound' + summary: missing +x-collection: top +` + +// A document decoded from the node must equal the same document decoded as +// JSON: the two paths are interchangeable for content. +func TestNativeStock_MatchesJSONPath(t *testing.T) { + var viaJSON Responses + jsonBytes, err := yamlToJSON(nativeSrc) + require.NoError(t, err) + require.NoError(t, json.Unmarshal(jsonBytes, &viaJSON)) + + var viaNode Responses + require.NoError(t, goyaml.Unmarshal([]byte(nativeSrc), &viaNode)) + + want, err := json.Marshal(&viaJSON) + require.NoError(t, err) + got, err := json.Marshal(&viaNode) + require.NoError(t, err) + require.JSONEq(t, string(want), string(got)) +} + +// Origins must reach nested collections, not only the top level. +func TestNativeStock_OriginsAtDepth(t *testing.T) { + var r Responses + // Through unmarshal rather than the yaml package: origins are stamped only + // for the tree a decode indexed. + _, err := unmarshal([]byte(nativeSrc), &r, true, nil) + require.NoError(t, err) + mt := r.Value("200").Value.Content["application/json"] + require.NotNil(t, mt) + require.NotNil(t, mt.Origin, "nested media type should carry an origin") + require.NotNil(t, mt.Origin.Key) + require.Equal(t, "application/json", mt.Origin.Key.Name) + require.Equal(t, 7, mt.Origin.Key.Line) +} + +func yamlToJSON(src string) ([]byte, error) { + var v any + if err := goyaml.Unmarshal([]byte(src), &v); err != nil { + return nil, err + } + return json.Marshal(v) +} + +// A type error names the OpenAPI type the document was read into, not the +// shadow type that only exists to stop the decode recursing. +func TestNativeStock_TypeErrorNamesTheTarget(t *testing.T) { + for _, test := range []struct { + name string + target any + expect string + }{ + {"document", &T{}, "openapi3.T"}, + {"info", &Info{}, "openapi3.Info"}, + } { + t.Run(test.name, func(t *testing.T) { + err := goyaml.Unmarshal([]byte("GET /anything\n"), test.target) + require.ErrorContains(t, err, test.expect) + require.NotContains(t, fmt.Sprint(err), "bis", "the shadow type is an implementation detail") + }) + } +} + +// A key YAML 1.1 reads as an int, such as an age bucket written 18_24, stays +// the string it was written as, so a $ref naming it still points at it. +func TestNativeStock_UnderscoredKeyStaysAString(t *testing.T) { + const src = `schemas: + 18_24: + type: object + 25_34: + type: object +` + var components Components + require.NoError(t, goyaml.Unmarshal([]byte(src), &components)) + require.Contains(t, components.Schemas, "18_24") + require.Contains(t, components.Schemas, "25_34") +} diff --git a/openapi3/nativeyaml.tmpl b/openapi3/nativeyaml.tmpl new file mode 100644 index 000000000..645defa5a --- /dev/null +++ b/openapi3/nativeyaml.tmpl @@ -0,0 +1,25 @@ +// Code generated by go generate using nativeyaml.tmpl; DO NOT EDIT native_yaml_shadow.go. +package {{ .Package }} + +import ( + yaml "go.yaml.in/yaml/v3" +) + +// UnmarshalYAML for the types whose YAML form is a mapping of declared fields +// plus extensions. +// +// The local shadow type is what stops the decoder recursing into this method; +// converting the receiver to it decodes in place, so only the field the decoder +// skips is set afterwards. Everything else is in decodeMapping. +{{ range $type := .Types }} +// UnmarshalYAML sets {{ $type.Name }} from node. +func ({{ $type.Recv }} *{{ $type.Name }}) UnmarshalYAML(node *yaml.Node) error { + type bis {{ $type.Name }} + ext, err := decodeMapping[{{ $type.Name }}](node, (*bis)({{ $type.Recv }})) + if err != nil { + return err + } + {{ $type.Recv }}.Extensions = ext + return nil +} +{{ end -}} diff --git a/openapi3/nativeyamlgenerator.go b/openapi3/nativeyamlgenerator.go new file mode 100644 index 000000000..b40ec5fe3 --- /dev/null +++ b/openapi3/nativeyamlgenerator.go @@ -0,0 +1,72 @@ +//go:build ignore + +// The program generates native_yaml_shadow.go, invoke `go generate ./...` to run. +package main + +import ( + "bytes" + _ "embed" + "go/format" + "os" + "text/template" +) + +//go:embed nativeyaml.tmpl +var tmplData string + +type shadowType struct { + Name string + Recv string +} + +func main() { + // The types whose YAML form is a mapping of declared fields plus + // extensions. The $ref wrappers are generated from refs.tmpl instead. + // Hand-written in native_yaml_special.go: the maplike collections, the + // union-typed values, Schema, which may be written as a boolean, Operation, + // which has to tell an omitted responses + // from an explicitly null one, and T, which has no parent to take its + // Key from. + types := []shadowType{ + {"Components", "components"}, + {"Contact", "contact"}, + {"Discriminator", "discriminator"}, + {"Encoding", "encoding"}, + {"Example", "example"}, + {"ExternalDocs", "e"}, + {"Info", "info"}, + {"License", "license"}, + {"Link", "link"}, + {"MediaType", "mediaType"}, + {"OAuthFlow", "flow"}, + {"OAuthFlows", "flows"}, + {"Parameter", "parameter"}, + {"PathItem", "pathItem"}, + {"RequestBody", "requestBody"}, + {"Response", "response"}, + {"SecurityScheme", "ss"}, + {"Server", "server"}, + {"ServerVariable", "serverVariable"}, + {"Tag", "t"}, + {"XML", "xml"}, + } + + tmpl := template.Must(template.New("nativeyaml").Parse(tmplData)) + buf := new(bytes.Buffer) + if err := tmpl.Execute(buf, struct { + Package string + Types []shadowType + }{ + Package: os.Getenv("GOPACKAGE"), // set by the go:generate directive + Types: types, + }); err != nil { + panic(err) + } + src, err := format.Source(buf.Bytes()) + if err != nil { + panic(err) + } + if err := os.WriteFile("native_yaml_shadow.go", src, 0o644); err != nil { + panic(err) + } +} diff --git a/openapi3/refs.go b/openapi3/refs.go index 085f85c1f..5f7c817b6 100644 --- a/openapi3/refs.go +++ b/openapi3/refs.go @@ -9,6 +9,7 @@ import ( "strings" "github.com/go-openapi/jsonpointer" + yaml "go.yaml.in/yaml/v3" ) // CallbackRef represents either a Callback or a $ref to a Callback. @@ -88,6 +89,14 @@ func (x CallbackRef) MarshalJSON() ([]byte, error) { return json.Marshal(y) } +// UnmarshalYAML sets CallbackRef from node. +func (x *CallbackRef) UnmarshalYAML(node *yaml.Node) error { + if !unmarshalRefYAML(node, &x.Ref, &x.Summary, &x.Description, &x.Extensions, &x.extra, &x.siblingExtras) { + return node.Decode(&x.Value) + } + return nil +} + // UnmarshalJSON sets CallbackRef to a copy of data. func (x *CallbackRef) UnmarshalJSON(data []byte) error { var refOnly Ref @@ -253,6 +262,14 @@ func (x ExampleRef) MarshalJSON() ([]byte, error) { return json.Marshal(y) } +// UnmarshalYAML sets ExampleRef from node. +func (x *ExampleRef) UnmarshalYAML(node *yaml.Node) error { + if !unmarshalRefYAML(node, &x.Ref, &x.Summary, &x.Description, &x.Extensions, &x.extra, &x.siblingExtras) { + return node.Decode(&x.Value) + } + return nil +} + // UnmarshalJSON sets ExampleRef to a copy of data. func (x *ExampleRef) UnmarshalJSON(data []byte) error { var refOnly Ref @@ -418,6 +435,14 @@ func (x HeaderRef) MarshalJSON() ([]byte, error) { return json.Marshal(y) } +// UnmarshalYAML sets HeaderRef from node. +func (x *HeaderRef) UnmarshalYAML(node *yaml.Node) error { + if !unmarshalRefYAML(node, &x.Ref, &x.Summary, &x.Description, &x.Extensions, &x.extra, &x.siblingExtras) { + return node.Decode(&x.Value) + } + return nil +} + // UnmarshalJSON sets HeaderRef to a copy of data. func (x *HeaderRef) UnmarshalJSON(data []byte) error { var refOnly Ref @@ -583,6 +608,14 @@ func (x LinkRef) MarshalJSON() ([]byte, error) { return json.Marshal(y) } +// UnmarshalYAML sets LinkRef from node. +func (x *LinkRef) UnmarshalYAML(node *yaml.Node) error { + if !unmarshalRefYAML(node, &x.Ref, &x.Summary, &x.Description, &x.Extensions, &x.extra, &x.siblingExtras) { + return node.Decode(&x.Value) + } + return nil +} + // UnmarshalJSON sets LinkRef to a copy of data. func (x *LinkRef) UnmarshalJSON(data []byte) error { var refOnly Ref @@ -748,6 +781,14 @@ func (x ParameterRef) MarshalJSON() ([]byte, error) { return json.Marshal(y) } +// UnmarshalYAML sets ParameterRef from node. +func (x *ParameterRef) UnmarshalYAML(node *yaml.Node) error { + if !unmarshalRefYAML(node, &x.Ref, &x.Summary, &x.Description, &x.Extensions, &x.extra, &x.siblingExtras) { + return node.Decode(&x.Value) + } + return nil +} + // UnmarshalJSON sets ParameterRef to a copy of data. func (x *ParameterRef) UnmarshalJSON(data []byte) error { var refOnly Ref @@ -913,6 +954,14 @@ func (x RequestBodyRef) MarshalJSON() ([]byte, error) { return json.Marshal(y) } +// UnmarshalYAML sets RequestBodyRef from node. +func (x *RequestBodyRef) UnmarshalYAML(node *yaml.Node) error { + if !unmarshalRefYAML(node, &x.Ref, &x.Summary, &x.Description, &x.Extensions, &x.extra, &x.siblingExtras) { + return node.Decode(&x.Value) + } + return nil +} + // UnmarshalJSON sets RequestBodyRef to a copy of data. func (x *RequestBodyRef) UnmarshalJSON(data []byte) error { var refOnly Ref @@ -1078,6 +1127,14 @@ func (x ResponseRef) MarshalJSON() ([]byte, error) { return json.Marshal(y) } +// UnmarshalYAML sets ResponseRef from node. +func (x *ResponseRef) UnmarshalYAML(node *yaml.Node) error { + if !unmarshalRefYAML(node, &x.Ref, &x.Summary, &x.Description, &x.Extensions, &x.extra, &x.siblingExtras) { + return node.Decode(&x.Value) + } + return nil +} + // UnmarshalJSON sets ResponseRef to a copy of data. func (x *ResponseRef) UnmarshalJSON(data []byte) error { var refOnly Ref @@ -1264,6 +1321,32 @@ func (x SchemaRef) MarshalJSON() ([]byte, error) { return json.Marshal(y) } +// UnmarshalYAML sets SchemaRef from node. +func (x *SchemaRef) UnmarshalYAML(node *yaml.Node) error { + if !unmarshalRefYAML(node, &x.Ref, nil, nil, &x.Extensions, &x.extra, &x.siblingExtras) { + return node.Decode(&x.Value) + } + // OAS 3.1 / JSON Schema 2020-12: schema keywords alongside a $ref are valid + // and are merged with the resolved reference, so they are held on sibling + // until resolveSchemaRef can apply them. + var hasSiblings bool + for _, k := range x.extra { + if !strings.HasPrefix(k, "x-") { + hasSiblings = true + break + } + } + if hasSiblings { + var sibling Schema + if err := node.Decode(&sibling); err == nil { + x.sibling = &sibling + } else { + x.siblingErr = err + } + } + return nil +} + // UnmarshalJSON sets SchemaRef to a copy of data. func (x *SchemaRef) UnmarshalJSON(data []byte) error { var refOnly Ref @@ -1443,6 +1526,14 @@ func (x SecuritySchemeRef) MarshalJSON() ([]byte, error) { return json.Marshal(y) } +// UnmarshalYAML sets SecuritySchemeRef from node. +func (x *SecuritySchemeRef) UnmarshalYAML(node *yaml.Node) error { + if !unmarshalRefYAML(node, &x.Ref, &x.Summary, &x.Description, &x.Extensions, &x.extra, &x.siblingExtras) { + return node.Decode(&x.Value) + } + return nil +} + // UnmarshalJSON sets SecuritySchemeRef to a copy of data. func (x *SecuritySchemeRef) UnmarshalJSON(data []byte) error { var refOnly Ref diff --git a/openapi3/refs.tmpl b/openapi3/refs.tmpl index 84076b991..62e2af6df 100644 --- a/openapi3/refs.tmpl +++ b/openapi3/refs.tmpl @@ -9,6 +9,7 @@ import ( "strings" "github.com/go-openapi/jsonpointer" + yaml "go.yaml.in/yaml/v3" ) {{ range $type := .Types }} // {{ $type.Name }}Ref represents either a {{ $type.Name }} or a $ref to a {{ $type.Name }}. @@ -123,6 +124,34 @@ func (x {{ $type.Name }}Ref) MarshalJSON() ([]byte, error) { return json.Marshal(y) } +// UnmarshalYAML sets {{ $type.Name }}Ref from node. +func (x *{{ $type.Name }}Ref) UnmarshalYAML(node *yaml.Node) error { + if !unmarshalRefYAML(node, &x.Ref{{ if ne $type.Name "Schema" }}, &x.Summary, &x.Description{{ else }}, nil, nil{{ end }}, &x.Extensions, &x.extra, &x.siblingExtras) { + return node.Decode(&x.Value) + } +{{- if eq $type.Name "Schema" }} + // OAS 3.1 / JSON Schema 2020-12: schema keywords alongside a $ref are valid + // and are merged with the resolved reference, so they are held on sibling + // until resolveSchemaRef can apply them. + var hasSiblings bool + for _, k := range x.extra { + if !strings.HasPrefix(k, "x-") { + hasSiblings = true + break + } + } + if hasSiblings { + var sibling Schema + if err := node.Decode(&sibling); err == nil { + x.sibling = &sibling + } else { + x.siblingErr = err + } + } +{{- end }} + return nil +} + // UnmarshalJSON sets {{ $type.Name }}Ref to a copy of data. func (x *{{ $type.Name }}Ref) UnmarshalJSON(data []byte) error { var refOnly Ref diff --git a/openapi3/testdata/fuzz/FuzzYAMLMatchesJSON/dd86b380d656a764 b/openapi3/testdata/fuzz/FuzzYAMLMatchesJSON/dd86b380d656a764 new file mode 100644 index 000000000..6288c0732 --- /dev/null +++ b/openapi3/testdata/fuzz/FuzzYAMLMatchesJSON/dd86b380d656a764 @@ -0,0 +1,2 @@ +go test fuzz v1 +[]byte("{\"<<\":{}}") diff --git a/openapi3/testdata/fuzz/FuzzYAMLMatchesJSON/null-in-string-sequence b/openapi3/testdata/fuzz/FuzzYAMLMatchesJSON/null-in-string-sequence new file mode 100644 index 000000000..1341be8f1 --- /dev/null +++ b/openapi3/testdata/fuzz/FuzzYAMLMatchesJSON/null-in-string-sequence @@ -0,0 +1,2 @@ +go test fuzz v1 +[]byte("{\"components\":{\"schemas\":{\"S\":{\"required\":[null]}}}}") diff --git a/openapi3/yaml_fuzz_test.go b/openapi3/yaml_fuzz_test.go index d3c5f5a2f..598c80e21 100644 --- a/openapi3/yaml_fuzz_test.go +++ b/openapi3/yaml_fuzz_test.go @@ -4,8 +4,8 @@ import ( "encoding/json" "testing" - "github.com/oasdiff/yaml" "github.com/stretchr/testify/require" + yaml "go.yaml.in/yaml/v3" "github.com/getkin/kin-openapi/internal/fuzzing" ) @@ -149,10 +149,17 @@ components: `, } -// decodeYAML decodes data the way unmarshal does once JSON has refused it. +// decodeYAML decodes YAML (or JSON, which parses as YAML) straight into v, +// the way unmarshal does before falling back to JSON. func decodeYAML(data []byte, v any) error { - _, err := yaml.Unmarshal(data, v, yaml.DecodeOpts{DisableTimestamps: true}) - return err + var root yaml.Node + if err := yaml.Unmarshal(data, &root); err != nil { + return err + } + if err := prepareScalars(&root); err != nil { + return err + } + return root.Decode(v) } func requireSameDoc(t *testing.T, expected, actual *T, msgAndArgs ...any) { @@ -205,7 +212,7 @@ func FuzzYAMLMatchesJSON(f *testing.F) { if fuzzing.LosesInYAML(generic) { return } - y, err := yaml.JSONToYAML(j) + y, err := yaml.Marshal(generic) require.NoError(t, err) var back T From 1a0fab2549732e56894f629bbc9a949a40f79bbf Mon Sep 17 00:00:00 2001 From: Asuka Date: Sat, 31 Oct 2026 02:28:08 +0900 Subject: [PATCH 33/78] openapi3: keep component content when internalizing a ref to a file (#1409) --- openapi3/internalize_refs.go | 25 +++++++++- openapi3/issue1393_test.go | 88 ++++++++++++++++++++++++++++++++++++ 2 files changed, 112 insertions(+), 1 deletion(-) create mode 100644 openapi3/issue1393_test.go diff --git a/openapi3/internalize_refs.go b/openapi3/internalize_refs.go index fd8c18fbc..08f697539 100644 --- a/openapi3/internalize_refs.go +++ b/openapi3/internalize_refs.go @@ -69,7 +69,7 @@ func DefaultRefNameResolver(doc *T, ref ComponentRef) string { } // Trim the common prefix with the root doc path. - if doc.url != nil { + if doc.url != nil && filePath != "" { for commonDir := path.Dir(doc.url.Path); /*no common prefix*/ commonDir != "."; commonDir = path.Dir(commonDir) { if p, found := cutDirectories(filePath, commonDir); found { filePath = p @@ -533,6 +533,11 @@ func (doc *T) InternalizeRefs(ctx context.Context, refNameResolver func(*T, Comp } } doc.derefHeaders(components.Headers, refNameResolver, false) + for _, name := range componentNames(components.Headers) { + if h := components.Headers[name]; h != nil { + h.Ref = "" // always dereference the top level + } + } for _, name := range componentNames(components.RequestBodies) { req := components.RequestBodies[name] isExternal := doc.addRequestBodyToSpec(req, refNameResolver, false) @@ -542,12 +547,30 @@ func (doc *T) InternalizeRefs(ctx context.Context, refNameResolver func(*T, Comp } } doc.derefResponseBodies(components.Responses, refNameResolver, false) + for _, name := range componentNames(components.Responses) { + if r := components.Responses[name]; r != nil { + r.Ref = "" // always dereference the top level + } + } for _, name := range componentNames(components.SecuritySchemes) { ss := components.SecuritySchemes[name] doc.addSecuritySchemeToSpec(ss, refNameResolver, false) + if ss != nil { + ss.Ref = "" // always dereference the top level + } } doc.derefExamples(components.Examples, refNameResolver, false) + for _, name := range componentNames(components.Examples) { + if e := components.Examples[name]; e != nil { + e.Ref = "" // always dereference the top level + } + } doc.derefLinks(components.Links, refNameResolver, false) + for _, name := range componentNames(components.Links) { + if l := components.Links[name]; l != nil { + l.Ref = "" // always dereference the top level + } + } for _, name := range componentNames(components.Callbacks) { cb := components.Callbacks[name] diff --git a/openapi3/issue1393_test.go b/openapi3/issue1393_test.go new file mode 100644 index 000000000..8b30960d0 --- /dev/null +++ b/openapi3/issue1393_test.go @@ -0,0 +1,88 @@ +package openapi3_test + +import ( + "os" + "path/filepath" + "testing" + + "github.com/stretchr/testify/require" + + "github.com/getkin/kin-openapi/openapi3" +) + +func TestInternalizeRefsDereferencesComponentRefsToFiles(t *testing.T) { + t.Parallel() + + dir := t.TempDir() + for name, content := range map[string]string{ + "root.yaml": `openapi: 3.0.3 +info: {title: t, version: '1'} +security: [{bearerAuth: []}] +paths: + /a: + get: + operationId: getA + responses: + '200': + description: OK + headers: + X-Header: {$ref: '#/components/headers/X-Header'} + content: + application/json: + schema: {type: integer} + examples: + example: {$ref: '#/components/examples/Example'} + links: + link: {$ref: '#/components/links/Link'} + '404': {$ref: '#/components/responses/NotFound'} +components: + headers: + X-Header: {$ref: ./header.yaml} + responses: + NotFound: {$ref: ./response.yaml} + securitySchemes: + bearerAuth: {$ref: ./securityScheme.yaml} + examples: + Example: {$ref: ./example.yaml} + links: + Link: {$ref: ./link.yaml} +`, + "header.yaml": "schema: {type: string}\n", + "response.yaml": "description: Not found\n", + "securityScheme.yaml": "type: http\nscheme: bearer\n", + "example.yaml": "value: 42\n", + "link.yaml": "operationId: getA\n", + } { + require.NoError(t, os.WriteFile(filepath.Join(dir, name), []byte(content), 0o600)) + } + + loader := openapi3.NewLoader() + loader.IsExternalRefsAllowed = true + doc, err := loader.LoadFromFile(filepath.Join(dir, "root.yaml")) + require.NoError(t, err) + require.NoError(t, doc.Validate(t.Context())) + + doc.InternalizeRefs(t.Context(), nil) + require.NoError(t, doc.Validate(t.Context())) + + components := doc.Components + require.Empty(t, components.Headers["X-Header"].Ref) + require.Empty(t, components.Responses["NotFound"].Ref) + require.Empty(t, components.SecuritySchemes["bearerAuth"].Ref) + require.Empty(t, components.Examples["Example"].Ref) + require.Empty(t, components.Links["Link"].Ref) + require.Equal(t, "Not found", *components.Responses["NotFound"].Value.Description) + + operation := doc.Paths.Value("/a").Get + require.Equal(t, "#/components/headers/X-Header", operation.Responses.Value("200").Value.Headers["X-Header"].Ref) + require.Equal(t, "#/components/examples/Example", operation.Responses.Value("200").Value.Content["application/json"].Examples["example"].Ref) + require.Equal(t, "#/components/links/Link", operation.Responses.Value("200").Value.Links["link"].Ref) + require.Equal(t, "#/components/responses/NotFound", operation.Responses.Value("404").Ref) + + data, err := doc.MarshalJSON() + require.NoError(t, err) + loader = openapi3.NewLoader() + reloaded, err := loader.LoadFromData(data) + require.NoError(t, err) + require.NoError(t, reloaded.Validate(t.Context())) +} From 3d94c22c673b70d2859d91c666da3d313b362285 Mon Sep 17 00:00:00 2001 From: Pierre Fenoll Date: Sat, 31 Oct 2026 21:06:52 +0100 Subject: [PATCH 34/78] openapi3: skip nil map entries when internalizing refs A content entry written as null, such as `application/json: null`, and likewise a null header, encoding, response or path item, made InternalizeRefs dereference a nil pointer. Signed-off-by: Pierre Fenoll Co-Authored-By: Claude Opus 5.5 --- openapi3/internalize_refs.go | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/openapi3/internalize_refs.go b/openapi3/internalize_refs.go index 08f697539..d42b53078 100644 --- a/openapi3/internalize_refs.go +++ b/openapi3/internalize_refs.go @@ -389,7 +389,7 @@ func (doc *T) derefHeaders(hs Headers, refNameResolver RefNameResolver, parentIs for _, name := range componentNames(hs) { h := hs[name] isExternal := doc.addHeaderToSpec(h, refNameResolver, parentIsExternal) - if doc.isVisitedHeader(h.Value) { + if h == nil || h.Value == nil || doc.isVisitedHeader(h.Value) { continue } doc.derefParameter(h.Value.Parameter, refNameResolver, parentIsExternal || isExternal) @@ -406,6 +406,9 @@ func (doc *T) derefExamples(es Examples, refNameResolver RefNameResolver, parent func (doc *T) derefContent(c Content, refNameResolver RefNameResolver, parentIsExternal bool) { for _, name := range componentNames(c) { mediatype := c[name] + if mediatype == nil { + continue + } isExternal := doc.addSchemaToSpec(mediatype.Schema, refNameResolver, parentIsExternal) if mediatype.Schema != nil { doc.derefSchema(mediatype.Schema.Value, refNameResolver, isExternal || parentIsExternal) @@ -413,6 +416,9 @@ func (doc *T) derefContent(c Content, refNameResolver RefNameResolver, parentIsE doc.derefExamples(mediatype.Examples, refNameResolver, parentIsExternal) for _, name := range componentNames(mediatype.Encoding) { e := mediatype.Encoding[name] + if e == nil { + continue + } doc.derefHeaders(e.Headers, refNameResolver, parentIsExternal) } } @@ -426,6 +432,9 @@ func (doc *T) derefLinks(ls Links, refNameResolver RefNameResolver, parentIsExte } func (doc *T) derefResponse(r *ResponseRef, refNameResolver RefNameResolver, parentIsExternal bool) { + if r == nil { + return + } isExternal := doc.addResponseToSpec(r, refNameResolver, parentIsExternal) if v := r.Value; v != nil { doc.derefHeaders(v.Headers, refNameResolver, isExternal || parentIsExternal) @@ -460,6 +469,9 @@ func (doc *T) derefRequestBody(r RequestBody, refNameResolver RefNameResolver, p func (doc *T) derefPaths(paths map[string]*PathItem, refNameResolver RefNameResolver, parentIsExternal bool) { for _, name := range componentNames(paths) { ops := paths[name] + if ops == nil { + continue + } pathIsExternal := isExternalRef(ops.Ref, parentIsExternal) // inline full operations ops.Ref = "" From 17aed50c1a7bbf0f34626a5e5d655e345d61661c Mon Sep 17 00:00:00 2001 From: Pierre Fenoll Date: Sat, 31 Oct 2026 21:06:52 +0100 Subject: [PATCH 35/78] openapi3: never name an internalized component "" DefaultRefNameResolver strips a ref down to nothing when it points at a directory, such as "/" or "./", and "" is not a valid component name, so the internalized document failed to load. Fall back to the collection name. Signed-off-by: Pierre Fenoll Co-Authored-By: Claude Opus 5.5 --- openapi3/internalize_refs.go | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/openapi3/internalize_refs.go b/openapi3/internalize_refs.go index d42b53078..4fa0febdc 100644 --- a/openapi3/internalize_refs.go +++ b/openapi3/internalize_refs.go @@ -97,6 +97,11 @@ func DefaultRefNameResolver(doc *T, ref ComponentRef) string { // Replace invalid characters in component fixed field names. internalizedName = InvalidIdentifierCharRegExp.ReplaceAllString(internalizedName, "_") + // Nothing is left of a ref to the directory itself, such as "/" or "./". + if internalizedName == "" { + internalizedName = ref.CollectionName() + } + return internalizedName } From 81a32c0832a695ee4ae0008dde9f30232a9ebd0b Mon Sep 17 00:00:00 2001 From: Pierre Fenoll Date: Sat, 31 Oct 2026 21:06:52 +0100 Subject: [PATCH 36/78] openapi3: leave unfollowed refs alone when internalizing The loader does not follow a ref whose target is empty, such as `$ref: 0#`, and leaves it without a value or a path. InternalizeRefs handed such a ref to the resolver, and DefaultRefNameResolver panicked with "unable to resolve reference to name". Leave it as written instead, and keep the $ref of a top-level component that has no value to inline in its place, rather than writing it out as null. Signed-off-by: Pierre Fenoll Co-Authored-By: Claude Opus 5.5 --- openapi3/internalize_refs.go | 34 +++++++++++++++++++--------------- 1 file changed, 19 insertions(+), 15 deletions(-) diff --git a/openapi3/internalize_refs.go b/openapi3/internalize_refs.go index 4fa0febdc..82548f1b9 100644 --- a/openapi3/internalize_refs.go +++ b/openapi3/internalize_refs.go @@ -130,12 +130,16 @@ func cutDirectories(p, dirs string) (string, bool) { return p, false } +// isExternalRef reports whether ref has to be moved into the root document. +// The add*ToSpec functions also leave alone any ref without a RefPath: the +// loader did not follow it (its target was empty), so there is nothing to +// move and the resolver could not name it. func isExternalRef(ref string, parentIsExternal bool) bool { return ref != "" && (!strings.HasPrefix(ref, "#/components/") || parentIsExternal) } func (doc *T) addSchemaToSpec(s *SchemaRef, refNameResolver RefNameResolver, parentIsExternal bool) bool { - if s == nil || !isExternalRef(s.Ref, parentIsExternal) { + if s == nil || !isExternalRef(s.Ref, parentIsExternal) || s.RefPath() == nil { return false } @@ -165,7 +169,7 @@ func (doc *T) addSchemaToSpec(s *SchemaRef, refNameResolver RefNameResolver, par } func (doc *T) addParameterToSpec(p *ParameterRef, refNameResolver RefNameResolver, parentIsExternal bool) bool { - if p == nil || !isExternalRef(p.Ref, parentIsExternal) { + if p == nil || !isExternalRef(p.Ref, parentIsExternal) || p.RefPath() == nil { return false } name := refNameResolver(doc, p) @@ -188,7 +192,7 @@ func (doc *T) addParameterToSpec(p *ParameterRef, refNameResolver RefNameResolve } func (doc *T) addHeaderToSpec(h *HeaderRef, refNameResolver RefNameResolver, parentIsExternal bool) bool { - if h == nil || !isExternalRef(h.Ref, parentIsExternal) { + if h == nil || !isExternalRef(h.Ref, parentIsExternal) || h.RefPath() == nil { return false } name := refNameResolver(doc, h) @@ -211,7 +215,7 @@ func (doc *T) addHeaderToSpec(h *HeaderRef, refNameResolver RefNameResolver, par } func (doc *T) addRequestBodyToSpec(r *RequestBodyRef, refNameResolver RefNameResolver, parentIsExternal bool) bool { - if r == nil || !isExternalRef(r.Ref, parentIsExternal) { + if r == nil || !isExternalRef(r.Ref, parentIsExternal) || r.RefPath() == nil { return false } name := refNameResolver(doc, r) @@ -234,7 +238,7 @@ func (doc *T) addRequestBodyToSpec(r *RequestBodyRef, refNameResolver RefNameRes } func (doc *T) addResponseToSpec(r *ResponseRef, refNameResolver RefNameResolver, parentIsExternal bool) bool { - if r == nil || !isExternalRef(r.Ref, parentIsExternal) { + if r == nil || !isExternalRef(r.Ref, parentIsExternal) || r.RefPath() == nil { return false } name := refNameResolver(doc, r) @@ -257,7 +261,7 @@ func (doc *T) addResponseToSpec(r *ResponseRef, refNameResolver RefNameResolver, } func (doc *T) addSecuritySchemeToSpec(ss *SecuritySchemeRef, refNameResolver RefNameResolver, parentIsExternal bool) { - if ss == nil || !isExternalRef(ss.Ref, parentIsExternal) { + if ss == nil || !isExternalRef(ss.Ref, parentIsExternal) || ss.RefPath() == nil { return } name := refNameResolver(doc, ss) @@ -280,7 +284,7 @@ func (doc *T) addSecuritySchemeToSpec(ss *SecuritySchemeRef, refNameResolver Ref } func (doc *T) addExampleToSpec(e *ExampleRef, refNameResolver RefNameResolver, parentIsExternal bool) { - if e == nil || !isExternalRef(e.Ref, parentIsExternal) { + if e == nil || !isExternalRef(e.Ref, parentIsExternal) || e.RefPath() == nil { return } name := refNameResolver(doc, e) @@ -303,7 +307,7 @@ func (doc *T) addExampleToSpec(e *ExampleRef, refNameResolver RefNameResolver, p } func (doc *T) addLinkToSpec(l *LinkRef, refNameResolver RefNameResolver, parentIsExternal bool) { - if l == nil || !isExternalRef(l.Ref, parentIsExternal) { + if l == nil || !isExternalRef(l.Ref, parentIsExternal) || l.RefPath() == nil { return } name := refNameResolver(doc, l) @@ -326,7 +330,7 @@ func (doc *T) addLinkToSpec(l *LinkRef, refNameResolver RefNameResolver, parentI } func (doc *T) addCallbackToSpec(c *CallbackRef, refNameResolver RefNameResolver, parentIsExternal bool) bool { - if c == nil || !isExternalRef(c.Ref, parentIsExternal) { + if c == nil || !isExternalRef(c.Ref, parentIsExternal) || c.RefPath() == nil { return false } name := refNameResolver(doc, c) @@ -536,7 +540,7 @@ func (doc *T) InternalizeRefs(ctx context.Context, refNameResolver func(*T, Comp for _, name := range componentNames(components.Schemas) { schema := components.Schemas[name] isExternal := doc.addSchemaToSpec(schema, refNameResolver, false) - if schema != nil { + if schema != nil && schema.Value != nil { schema.Ref = "" // always dereference the top level doc.derefSchema(schema.Value, refNameResolver, isExternal) } @@ -551,7 +555,7 @@ func (doc *T) InternalizeRefs(ctx context.Context, refNameResolver func(*T, Comp } doc.derefHeaders(components.Headers, refNameResolver, false) for _, name := range componentNames(components.Headers) { - if h := components.Headers[name]; h != nil { + if h := components.Headers[name]; h != nil && h.Value != nil { h.Ref = "" // always dereference the top level } } @@ -565,26 +569,26 @@ func (doc *T) InternalizeRefs(ctx context.Context, refNameResolver func(*T, Comp } doc.derefResponseBodies(components.Responses, refNameResolver, false) for _, name := range componentNames(components.Responses) { - if r := components.Responses[name]; r != nil { + if r := components.Responses[name]; r != nil && r.Value != nil { r.Ref = "" // always dereference the top level } } for _, name := range componentNames(components.SecuritySchemes) { ss := components.SecuritySchemes[name] doc.addSecuritySchemeToSpec(ss, refNameResolver, false) - if ss != nil { + if ss != nil && ss.Value != nil { ss.Ref = "" // always dereference the top level } } doc.derefExamples(components.Examples, refNameResolver, false) for _, name := range componentNames(components.Examples) { - if e := components.Examples[name]; e != nil { + if e := components.Examples[name]; e != nil && e.Value != nil { e.Ref = "" // always dereference the top level } } doc.derefLinks(components.Links, refNameResolver, false) for _, name := range componentNames(components.Links) { - if l := components.Links[name]; l != nil { + if l := components.Links[name]; l != nil && l.Value != nil { l.Ref = "" // always dereference the top level } } From 0d11ec9208fbb7740e9d2bbe930711583b3c4362 Mon Sep 17 00:00:00 2001 From: Pierre Fenoll Date: Sat, 31 Oct 2026 21:06:52 +0100 Subject: [PATCH 37/78] openapi3: report a ref into a missing part of its own document The drill closure of resolveComponent assigned the function's named err, so the fallback that re-reads the document and drills again cleared the error of the first drill when the second failed too. A ref such as `#/components/x` in a document whose components are null then loaded without error, whenever the document had a path. The error also lost its "failed to resolve ... in fragment" prefix, which the golden shows again. Signed-off-by: Pierre Fenoll Co-Authored-By: Claude Opus 5.5 --- openapi3/loader.go | 1 + .../statsocial_com_1_0_0_openapi_yaml__load | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/openapi3/loader.go b/openapi3/loader.go index d62b68059..0695163d7 100644 --- a/openapi3/loader.go +++ b/openapi3/loader.go @@ -488,6 +488,7 @@ func (loader *Loader) resolveComponent(doc *T, ref string, path *url.URL, resolv } drill := func(cursor any) (any, error) { + var err error // not the named result, which a failed drill must not clear for pathPart := range strings.SplitSeq(fragment[1:], "/") { pathPart = unescapeRefString(pathPart) attempted := false diff --git a/openapi3/testdata/apis_guru_openapi_directory/statsocial_com_1_0_0_openapi_yaml__load b/openapi3/testdata/apis_guru_openapi_directory/statsocial_com_1_0_0_openapi_yaml__load index 099ffe7fb..89cfda0c5 100644 --- a/openapi3/testdata/apis_guru_openapi_directory/statsocial_com_1_0_0_openapi_yaml__load +++ b/openapi3/testdata/apis_guru_openapi_directory/statsocial_com_1_0_0_openapi_yaml__load @@ -1 +1 @@ -map key "18_24" not found +failed to resolve "18_24" in fragment in URI: "#/components/schemas/18_24": map key "18_24" not found From edb3ecd04e0724883f13334e7db09b979e3ed59d Mon Sep 17 00:00:00 2001 From: Pierre Fenoll Date: Sat, 31 Oct 2026 21:06:52 +0100 Subject: [PATCH 38/78] openapi3: record no path for a ref that resolves to nothing A ref whose target is empty got a value of nil but a path all the same, both when resolving it and, through a typed nil passed as `any`, when a cycle through it unwound. Its path is what tells InternalizeRefs a ref was followed, so such a ref got internalized into a null component. Signed-off-by: Pierre Fenoll Co-Authored-By: Claude Opus 5.5 --- openapi3/loader.go | 48 ++++++++++++++++++++++++++++------------------ 1 file changed, 29 insertions(+), 19 deletions(-) diff --git a/openapi3/loader.go b/openapi3/loader.go index 0695163d7..e920c815a 100644 --- a/openapi3/loader.go +++ b/openapi3/loader.go @@ -447,7 +447,8 @@ func (loader *Loader) visitRef(kind, ref string) { func (loader *Loader) unvisitRef(kind, ref string, value any) { key := visitedRefKey(kind, ref) - if value != nil { + // value is a typed pointer, nil when the cycle resolved to nothing. + if v := reflect.ValueOf(value); v.IsValid() && !(v.Kind() == reflect.Pointer && v.IsNil()) { for _, fn := range loader.backtrack[key] { fn(value) } @@ -810,8 +811,9 @@ func (loader *Loader) resolveHeaderRef(doc *T, component *HeaderRef, documentPat } return err } - component.Value = resolved.Value - component.setRefPath(resolved.RefPath()) + if component.Value = resolved.Value; component.Value != nil { + component.setRefPath(resolved.RefPath()) + } } defer loader.unvisitRef("Header", ref, component.Value) applyHeaderRefMetadata(component.Value, component, isOpenAPI31OrLater) @@ -881,8 +883,9 @@ func (loader *Loader) resolveParameterRef(doc *T, component *ParameterRef, docum } return err } - component.Value = resolved.Value - component.setRefPath(resolved.RefPath()) + if component.Value = resolved.Value; component.Value != nil { + component.setRefPath(resolved.RefPath()) + } } defer loader.unvisitRef("Parameter", ref, component.Value) applyParameterRefMetadata(component.Value, component, isOpenAPI31OrLater) @@ -960,8 +963,9 @@ func (loader *Loader) resolveRequestBodyRef(doc *T, component *RequestBodyRef, d } return err } - component.Value = resolved.Value - component.setRefPath(resolved.RefPath()) + if component.Value = resolved.Value; component.Value != nil { + component.setRefPath(resolved.RefPath()) + } } defer loader.unvisitRef("RequestBody", ref, component.Value) applyRequestBodyRefMetadata(component.Value, component, isOpenAPI31OrLater) @@ -1026,8 +1030,9 @@ func (loader *Loader) resolveResponseRef(doc *T, component *ResponseRef, documen } return err } - component.Value = resolved.Value - component.setRefPath(resolved.RefPath()) + if component.Value = resolved.Value; component.Value != nil { + component.setRefPath(resolved.RefPath()) + } } defer loader.unvisitRef("Response", ref, component.Value) applyResponseRefMetadata(component.Value, component, isOpenAPI31OrLater) @@ -1132,8 +1137,9 @@ func (loader *Loader) resolveSchemaRef(doc *T, component *SchemaRef, documentPat } return err } - component.Value = resolved.Value - component.setRefPath(resolved.RefPath()) + if component.Value = resolved.Value; component.Value != nil { + component.setRefPath(resolved.RefPath()) + } } defer loader.unvisitRef("Schema", ref, component.Value) @@ -1325,8 +1331,9 @@ func (loader *Loader) resolveSecuritySchemeRef(doc *T, component *SecurityScheme } return err } - component.Value = resolved.Value - component.setRefPath(resolved.RefPath()) + if component.Value = resolved.Value; component.Value != nil { + component.setRefPath(resolved.RefPath()) + } } defer loader.unvisitRef("SecurityScheme", ref, component.Value) applySecuritySchemeRefMetadata(component.Value, component, isOpenAPI31OrLater) @@ -1386,8 +1393,9 @@ func (loader *Loader) resolveExampleRef(doc *T, component *ExampleRef, documentP } return err } - component.Value = resolved.Value - component.setRefPath(resolved.RefPath()) + if component.Value = resolved.Value; component.Value != nil { + component.setRefPath(resolved.RefPath()) + } } defer loader.unvisitRef("Example", ref, component.Value) applyExampleRefMetadata(component.Value, component, isOpenAPI31OrLater) @@ -1431,8 +1439,9 @@ func (loader *Loader) resolveCallbackRef(doc *T, component *CallbackRef, documen } return err } - component.Value = resolved.Value - component.setRefPath(resolved.RefPath()) + if component.Value = resolved.Value; component.Value != nil { + component.setRefPath(resolved.RefPath()) + } } defer loader.unvisitRef("Callback", ref, component.Value) } @@ -1498,8 +1507,9 @@ func (loader *Loader) resolveLinkRef(doc *T, component *LinkRef, documentPath *u } return err } - component.Value = resolved.Value - component.setRefPath(resolved.RefPath()) + if component.Value = resolved.Value; component.Value != nil { + component.setRefPath(resolved.RefPath()) + } } defer loader.unvisitRef("Link", ref, component.Value) applyLinkRefMetadata(component.Value, component, isOpenAPI31OrLater) From c26b4a285ffb8f82937579d2626ba87b9ab2327b Mon Sep 17 00:00:00 2001 From: Pierre Fenoll Date: Sat, 31 Oct 2026 21:06:52 +0100 Subject: [PATCH 39/78] openapi3: follow the $ref of a file a ref points to as a whole A ref to a whole file, with no fragment, decoded the file as the object itself, so a file holding only `$ref: ...` became an object whose sole content was a "$ref" extension. Decode it as a ref and resolve it from the file's location. Security schemes, examples and links also recorded the path of the referring document instead of the file's. recursiveRef's golden no longer holds a copy of Cat: Cat.yml refers back to the root's own Cat, which is now recognized as such. Signed-off-by: Pierre Fenoll Co-Authored-By: Claude Opus 5.5 --- .github/workflows/go.yml | 4 +- openapi3/loader.go | 147 +++++++++++++----- .../recursiveRef/openapi.yml.internalized.yml | 10 +- 3 files changed, 113 insertions(+), 48 deletions(-) diff --git a/.github/workflows/go.yml b/.github/workflows/go.yml index 46cd71a89..4ffba3e7a 100644 --- a/.github/workflows/go.yml +++ b/.github/workflows/go.yml @@ -201,9 +201,9 @@ jobs: - if: runner.os == 'Linux' name: Ensure readableType() covers all possible values of resolved var run: | - [[ "$(git grep -F 'var resolved ' -- openapi3/loader.go | awk '{print $4}' | sort | tr '\n' ' ')" = "$RESOLVEDS" ]] + [[ "$(git grep -F 'var resolved ' -- openapi3/loader.go | awk '{print $4}' | sort | uniq | tr '\n' ' ')" = "$RESOLVEDS" ]] env: - RESOLVEDS: 'Callback CallbackRef ExampleRef HeaderRef LinkRef ParameterRef PathItem RequestBodyRef ResponseRef SchemaRef SecuritySchemeRef ' + RESOLVEDS: 'CallbackRef ExampleRef HeaderRef LinkRef ParameterRef PathItem RequestBodyRef ResponseRef SchemaRef SecuritySchemeRef ' check-goimports: runs-on: ubuntu-latest diff --git a/openapi3/loader.go b/openapi3/loader.go index e920c815a..c705e83e5 100644 --- a/openapi3/loader.go +++ b/openapi3/loader.go @@ -1,6 +1,7 @@ package openapi3 import ( + "cmp" "context" "encoding/json" "errors" @@ -793,12 +794,20 @@ func (loader *Loader) resolveHeaderRef(doc *T, component *HeaderRef, documentPat } loader.visitRef("Header", ref) if isSingleRefElement(ref) { - var header Header - if documentPath, err = loader.loadSingleElementFromURI(ref, documentPath, &header); err != nil { + var resolved HeaderRef + if documentPath, err = loader.loadSingleElementFromURI(ref, documentPath, &resolved); err != nil { + return err + } + // The file holds the Header itself or a $ref to it, to follow from there. + if err := loader.resolveHeaderRef(doc, &resolved, documentPath); err != nil { + if err == errMUSTHeader { + return nil + } return err } - component.Value = &header - component.setRefPath(documentPath) + if component.Value = resolved.Value; component.Value != nil { + component.setRefPath(cmp.Or(resolved.RefPath(), documentPath)) + } } else { var resolved HeaderRef doc, componentPath, err := loader.resolveComponent(doc, ref, documentPath, &resolved) @@ -865,12 +874,20 @@ func (loader *Loader) resolveParameterRef(doc *T, component *ParameterRef, docum } loader.visitRef("Parameter", ref) if isSingleRefElement(ref) { - var param Parameter - if documentPath, err = loader.loadSingleElementFromURI(ref, documentPath, ¶m); err != nil { + var resolved ParameterRef + if documentPath, err = loader.loadSingleElementFromURI(ref, documentPath, &resolved); err != nil { + return err + } + // The file holds the Parameter itself or a $ref to it, to follow from there. + if err := loader.resolveParameterRef(doc, &resolved, documentPath); err != nil { + if err == errMUSTParameter { + return nil + } return err } - component.Value = ¶m - component.setRefPath(documentPath) + if component.Value = resolved.Value; component.Value != nil { + component.setRefPath(cmp.Or(resolved.RefPath(), documentPath)) + } } else { var resolved ParameterRef doc, componentPath, err := loader.resolveComponent(doc, ref, documentPath, &resolved) @@ -945,19 +962,27 @@ func (loader *Loader) resolveRequestBodyRef(doc *T, component *RequestBodyRef, d } loader.visitRef("RequestBody", ref) if isSingleRefElement(ref) { - var requestBody RequestBody - if documentPath, err = loader.loadSingleElementFromURI(ref, documentPath, &requestBody); err != nil { + var resolved RequestBodyRef + if documentPath, err = loader.loadSingleElementFromURI(ref, documentPath, &resolved); err != nil { return err } - component.Value = &requestBody - component.setRefPath(documentPath) + // The file holds the RequestBody itself or a $ref to it, to follow from there. + if err := loader.resolveRequestBodyRef(doc, &resolved, documentPath); err != nil { + if err == errMUSTRequestBody { + return nil + } + return err + } + if component.Value = resolved.Value; component.Value != nil { + component.setRefPath(cmp.Or(resolved.RefPath(), documentPath)) + } } else { var resolved RequestBodyRef doc, componentPath, err := loader.resolveComponent(doc, ref, documentPath, &resolved) if err != nil { return err } - if err = loader.resolveRequestBodyRef(doc, &resolved, componentPath); err != nil { + if err := loader.resolveRequestBodyRef(doc, &resolved, componentPath); err != nil { if err == errMUSTRequestBody { return nil } @@ -1012,12 +1037,20 @@ func (loader *Loader) resolveResponseRef(doc *T, component *ResponseRef, documen } loader.visitRef("Response", ref) if isSingleRefElement(ref) { - var resp Response - if documentPath, err = loader.loadSingleElementFromURI(ref, documentPath, &resp); err != nil { + var resolved ResponseRef + if documentPath, err = loader.loadSingleElementFromURI(ref, documentPath, &resolved); err != nil { + return err + } + // The file holds the Response itself or a $ref to it, to follow from there. + if err := loader.resolveResponseRef(doc, &resolved, documentPath); err != nil { + if err == errMUSTResponse { + return nil + } return err } - component.Value = &resp - component.setRefPath(documentPath) + if component.Value = resolved.Value; component.Value != nil { + component.setRefPath(cmp.Or(resolved.RefPath(), documentPath)) + } } else { var resolved ResponseRef doc, componentPath, err := loader.resolveComponent(doc, ref, documentPath, &resolved) @@ -1119,12 +1152,20 @@ func (loader *Loader) resolveSchemaRef(doc *T, component *SchemaRef, documentPat } loader.visitRef("Schema", ref) if isSingleRefElement(ref) { - var schema Schema - if documentPath, err = loader.loadSingleElementFromURI(ref, documentPath, &schema); err != nil { + var resolved SchemaRef + if documentPath, err = loader.loadSingleElementFromURI(ref, documentPath, &resolved); err != nil { + return err + } + // The file holds the Schema itself or a $ref to it, to follow from there. + if err := loader.resolveSchemaRef(doc, &resolved, documentPath, visited); err != nil { + if err == errMUSTSchema { + return nil + } return err } - component.Value = &schema - component.setRefPath(documentPath) + if component.Value = resolved.Value; component.Value != nil { + component.setRefPath(cmp.Or(resolved.RefPath(), documentPath)) + } } else { var resolved SchemaRef doc, componentPath, err := loader.resolveComponent(doc, ref, documentPath, &resolved) @@ -1313,12 +1354,20 @@ func (loader *Loader) resolveSecuritySchemeRef(doc *T, component *SecurityScheme } loader.visitRef("SecurityScheme", ref) if isSingleRefElement(ref) { - var scheme SecurityScheme - if _, err = loader.loadSingleElementFromURI(ref, documentPath, &scheme); err != nil { + var resolved SecuritySchemeRef + if documentPath, err = loader.loadSingleElementFromURI(ref, documentPath, &resolved); err != nil { + return err + } + // The file holds the SecurityScheme itself or a $ref to it, to follow from there. + if err := loader.resolveSecuritySchemeRef(doc, &resolved, documentPath); err != nil { + if err == errMUSTSecurityScheme { + return nil + } return err } - component.Value = &scheme - component.setRefPath(documentPath) + if component.Value = resolved.Value; component.Value != nil { + component.setRefPath(cmp.Or(resolved.RefPath(), documentPath)) + } } else { var resolved SecuritySchemeRef doc, componentPath, err := loader.resolveComponent(doc, ref, documentPath, &resolved) @@ -1375,12 +1424,20 @@ func (loader *Loader) resolveExampleRef(doc *T, component *ExampleRef, documentP } loader.visitRef("Example", ref) if isSingleRefElement(ref) { - var example Example - if _, err = loader.loadSingleElementFromURI(ref, documentPath, &example); err != nil { + var resolved ExampleRef + if documentPath, err = loader.loadSingleElementFromURI(ref, documentPath, &resolved); err != nil { + return err + } + // The file holds the Example itself or a $ref to it, to follow from there. + if err := loader.resolveExampleRef(doc, &resolved, documentPath); err != nil { + if err == errMUSTExample { + return nil + } return err } - component.Value = &example - component.setRefPath(documentPath) + if component.Value = resolved.Value; component.Value != nil { + component.setRefPath(cmp.Or(resolved.RefPath(), documentPath)) + } } else { var resolved ExampleRef doc, componentPath, err := loader.resolveComponent(doc, ref, documentPath, &resolved) @@ -1421,19 +1478,27 @@ func (loader *Loader) resolveCallbackRef(doc *T, component *CallbackRef, documen } loader.visitRef("Callback", ref) if isSingleRefElement(ref) { - var resolved Callback + var resolved CallbackRef if documentPath, err = loader.loadSingleElementFromURI(ref, documentPath, &resolved); err != nil { return err } - component.Value = &resolved - component.setRefPath(documentPath) + // The file holds the Callback itself or a $ref to it, to follow from there. + if err := loader.resolveCallbackRef(doc, &resolved, documentPath); err != nil { + if err == errMUSTCallback { + return nil + } + return err + } + if component.Value = resolved.Value; component.Value != nil { + component.setRefPath(cmp.Or(resolved.RefPath(), documentPath)) + } } else { var resolved CallbackRef doc, componentPath, err := loader.resolveComponent(doc, ref, documentPath, &resolved) if err != nil { return err } - if err = loader.resolveCallbackRef(doc, &resolved, componentPath); err != nil { + if err := loader.resolveCallbackRef(doc, &resolved, componentPath); err != nil { if err == errMUSTCallback { return nil } @@ -1489,12 +1554,20 @@ func (loader *Loader) resolveLinkRef(doc *T, component *LinkRef, documentPath *u } loader.visitRef("Link", ref) if isSingleRefElement(ref) { - var link Link - if _, err = loader.loadSingleElementFromURI(ref, documentPath, &link); err != nil { + var resolved LinkRef + if documentPath, err = loader.loadSingleElementFromURI(ref, documentPath, &resolved); err != nil { + return err + } + // The file holds the Link itself or a $ref to it, to follow from there. + if err := loader.resolveLinkRef(doc, &resolved, documentPath); err != nil { + if err == errMUSTLink { + return nil + } return err } - component.Value = &link - component.setRefPath(documentPath) + if component.Value = resolved.Value; component.Value != nil { + component.setRefPath(cmp.Or(resolved.RefPath(), documentPath)) + } } else { var resolved LinkRef doc, componentPath, err := loader.resolveComponent(doc, ref, documentPath, &resolved) diff --git a/openapi3/testdata/recursiveRef/openapi.yml.internalized.yml b/openapi3/testdata/recursiveRef/openapi.yml.internalized.yml index 33387fdf0..a987ab095 100644 --- a/openapi3/testdata/recursiveRef/openapi.yml.internalized.yml +++ b/openapi3/testdata/recursiveRef/openapi.yml.internalized.yml @@ -26,14 +26,6 @@ "example": "bar", "type": "string" }, - "components_Cat": { - "properties": { - "cat": { - "$ref": "#/components/schemas/components_Cat" - } - }, - "type": "object" - }, "components_Foo": { "properties": { "bar": { @@ -77,7 +69,7 @@ "Cat": { "properties": { "cat": { - "$ref": "#/components/schemas/components_Cat" + "$ref": "#/components/schemas/Cat" } }, "type": "object" From 80b604884336d918b653ec1ec56630d4c0d5ca45 Mon Sep 17 00:00:00 2001 From: Pierre Fenoll Date: Sat, 31 Oct 2026 21:06:53 +0100 Subject: [PATCH 40/78] openapi2, openapi3: do not discard errors decoding extensions UnmarshalJSON decodes a type twice: into its struct, and into a map from which the extensions are kept. Only the map holds the values of unknown fields, and the error decoding it was dropped, leaving a partial map: encoding/json then stored a number out of range for a float64, such as 1e700, as 0, where the YAML path kept it as text. Return the error, here and for the fields next to a $ref. Found by FuzzYAMLMatchesJSON in CI. Signed-off-by: Pierre Fenoll Co-Authored-By: Claude Opus 5.5 --- openapi2/openapi2.go | 4 ++- openapi2/operation.go | 4 ++- openapi2/parameter.go | 4 ++- openapi2/path_item.go | 4 ++- openapi2/refs.go | 4 ++- openapi2/response.go | 4 ++- openapi2/schema.go | 4 ++- openapi2/security_scheme.go | 4 ++- openapi3/components.go | 4 ++- openapi3/contact.go | 4 ++- openapi3/discriminator.go | 4 ++- openapi3/encoding.go | 4 ++- openapi3/example.go | 4 ++- openapi3/external_docs.go | 4 ++- openapi3/info.go | 4 ++- openapi3/license.go | 4 ++- openapi3/link.go | 4 ++- openapi3/media_type.go | 4 ++- openapi3/openapi3.go | 4 ++- openapi3/operation.go | 6 +++- openapi3/parameter.go | 4 ++- openapi3/path_item.go | 4 ++- openapi3/refs.go | 36 ++++++++++++++----- openapi3/refs.tmpl | 4 ++- openapi3/request_body.go | 4 ++- openapi3/response.go | 4 ++- openapi3/schema.go | 4 ++- openapi3/security_scheme.go | 12 +++++-- openapi3/server.go | 8 +++-- openapi3/tag.go | 4 ++- .../fuzz/FuzzYAMLMatchesJSON/886c20bb0385de8e | 2 ++ openapi3/xml.go | 4 ++- 32 files changed, 130 insertions(+), 42 deletions(-) create mode 100644 openapi3/testdata/fuzz/FuzzYAMLMatchesJSON/886c20bb0385de8e diff --git a/openapi2/openapi2.go b/openapi2/openapi2.go index f46c9332e..e46245ddf 100644 --- a/openapi2/openapi2.go +++ b/openapi2/openapi2.go @@ -83,7 +83,9 @@ func (doc *T) UnmarshalJSON(data []byte) error { if err := unmarshalJSON(data, &x); err != nil { return unmarshalError(err) } - _ = unmarshalJSON(data, &x.Extensions) + if err := unmarshalJSON(data, &x.Extensions); err != nil { + return unmarshalError(err) + } delete(x.Extensions, "swagger") delete(x.Extensions, "info") delete(x.Extensions, "externalDocs") diff --git a/openapi2/operation.go b/openapi2/operation.go index 55740a04b..9f8e9dd12 100644 --- a/openapi2/operation.go +++ b/openapi2/operation.go @@ -72,7 +72,9 @@ func (operation *Operation) UnmarshalJSON(data []byte) error { if err := unmarshalJSON(data, &x); err != nil { return unmarshalError(err) } - _ = unmarshalJSON(data, &x.Extensions) + if err := unmarshalJSON(data, &x.Extensions); err != nil { + return unmarshalError(err) + } delete(x.Extensions, "summary") delete(x.Extensions, "description") delete(x.Extensions, "deprecated") diff --git a/openapi2/parameter.go b/openapi2/parameter.go index eaeed8601..3b0e1e85d 100644 --- a/openapi2/parameter.go +++ b/openapi2/parameter.go @@ -128,7 +128,9 @@ func (parameter *Parameter) UnmarshalJSON(data []byte) error { if err := unmarshalJSON(data, &x); err != nil { return unmarshalError(err) } - _ = unmarshalJSON(data, &x.Extensions) + if err := unmarshalJSON(data, &x.Extensions); err != nil { + return unmarshalError(err) + } delete(x.Extensions, "$ref") delete(x.Extensions, "in") diff --git a/openapi2/path_item.go b/openapi2/path_item.go index 79596b455..f141403de 100644 --- a/openapi2/path_item.go +++ b/openapi2/path_item.go @@ -66,7 +66,9 @@ func (pathItem *PathItem) UnmarshalJSON(data []byte) error { if err := unmarshalJSON(data, &x); err != nil { return unmarshalError(err) } - _ = unmarshalJSON(data, &x.Extensions) + if err := unmarshalJSON(data, &x.Extensions); err != nil { + return unmarshalError(err) + } delete(x.Extensions, "$ref") delete(x.Extensions, "delete") delete(x.Extensions, "get") diff --git a/openapi2/refs.go b/openapi2/refs.go index c7402faaf..b9f8a7189 100644 --- a/openapi2/refs.go +++ b/openapi2/refs.go @@ -56,7 +56,9 @@ func (x *SchemaRef) UnmarshalJSON(data []byte) error { var refOnly Ref if err := unmarshalJSON(data, &refOnly); err == nil && refOnly.Ref != "" { extra := map[string]any{} - _ = unmarshalJSON(data, &extra) + if err := unmarshalJSON(data, &extra); err != nil { + return unmarshalError(err) + } delete(extra, "$ref") x.Ref = refOnly.Ref if len(extra) != 0 { diff --git a/openapi2/response.go b/openapi2/response.go index 40276de0f..e28d03fbb 100644 --- a/openapi2/response.go +++ b/openapi2/response.go @@ -50,7 +50,9 @@ func (response *Response) UnmarshalJSON(data []byte) error { if err := unmarshalJSON(data, &x); err != nil { return unmarshalError(err) } - _ = unmarshalJSON(data, &x.Extensions) + if err := unmarshalJSON(data, &x.Extensions); err != nil { + return unmarshalError(err) + } delete(x.Extensions, "$ref") delete(x.Extensions, "description") delete(x.Extensions, "schema") diff --git a/openapi2/schema.go b/openapi2/schema.go index e24435016..88ac9c570 100644 --- a/openapi2/schema.go +++ b/openapi2/schema.go @@ -198,7 +198,9 @@ func (schema *Schema) UnmarshalJSON(data []byte) error { if err := unmarshalJSON(data, &x); err != nil { return unmarshalError(err) } - _ = unmarshalJSON(data, &x.Extensions) + if err := unmarshalJSON(data, &x.Extensions); err != nil { + return unmarshalError(err) + } delete(x.Extensions, "oneOf") delete(x.Extensions, "anyOf") diff --git a/openapi2/security_scheme.go b/openapi2/security_scheme.go index 6a0e9ae8b..6eb7235c0 100644 --- a/openapi2/security_scheme.go +++ b/openapi2/security_scheme.go @@ -70,7 +70,9 @@ func (securityScheme *SecurityScheme) UnmarshalJSON(data []byte) error { if err := unmarshalJSON(data, &x); err != nil { return unmarshalError(err) } - _ = unmarshalJSON(data, &x.Extensions) + if err := unmarshalJSON(data, &x.Extensions); err != nil { + return unmarshalError(err) + } delete(x.Extensions, "$ref") delete(x.Extensions, "description") delete(x.Extensions, "type") diff --git a/openapi3/components.go b/openapi3/components.go index 30bcef45c..2d9b1735f 100644 --- a/openapi3/components.go +++ b/openapi3/components.go @@ -90,7 +90,9 @@ func (components *Components) UnmarshalJSON(data []byte) error { if err := unmarshalJSON(data, &x); err != nil { return unmarshalError(err) } - _ = unmarshalJSON(data, &x.Extensions) + if err := unmarshalJSON(data, &x.Extensions); err != nil { + return unmarshalError(err) + } delete(x.Extensions, "schemas") delete(x.Extensions, "parameters") delete(x.Extensions, "headers") diff --git a/openapi3/contact.go b/openapi3/contact.go index 07f55eccc..7af350632 100644 --- a/openapi3/contact.go +++ b/openapi3/contact.go @@ -49,7 +49,9 @@ func (contact *Contact) UnmarshalJSON(data []byte) error { if err := unmarshalJSON(data, &x); err != nil { return unmarshalError(err) } - _ = unmarshalJSON(data, &x.Extensions) + if err := unmarshalJSON(data, &x.Extensions); err != nil { + return unmarshalError(err) + } delete(x.Extensions, "name") delete(x.Extensions, "url") diff --git a/openapi3/discriminator.go b/openapi3/discriminator.go index c1853480f..4b425bef8 100644 --- a/openapi3/discriminator.go +++ b/openapi3/discriminator.go @@ -57,7 +57,9 @@ func (discriminator *Discriminator) UnmarshalJSON(data []byte) error { if err := unmarshalJSON(data, &x); err != nil { return unmarshalError(err) } - _ = unmarshalJSON(data, &x.Extensions) + if err := unmarshalJSON(data, &x.Extensions); err != nil { + return unmarshalError(err) + } delete(x.Extensions, "propertyName") delete(x.Extensions, "mapping") diff --git a/openapi3/encoding.go b/openapi3/encoding.go index 954aab9fd..afb2bba8f 100644 --- a/openapi3/encoding.go +++ b/openapi3/encoding.go @@ -82,7 +82,9 @@ func (encoding *Encoding) UnmarshalJSON(data []byte) error { if err := unmarshalJSON(data, &x); err != nil { return unmarshalError(err) } - _ = unmarshalJSON(data, &x.Extensions) + if err := unmarshalJSON(data, &x.Extensions); err != nil { + return unmarshalError(err) + } delete(x.Extensions, "contentType") delete(x.Extensions, "headers") diff --git a/openapi3/example.go b/openapi3/example.go index f568e8841..42b10c621 100644 --- a/openapi3/example.go +++ b/openapi3/example.go @@ -57,7 +57,9 @@ func (example *Example) UnmarshalJSON(data []byte) error { if err := unmarshalJSON(data, &x); err != nil { return unmarshalError(err) } - _ = unmarshalJSON(data, &x.Extensions) + if err := unmarshalJSON(data, &x.Extensions); err != nil { + return unmarshalError(err) + } delete(x.Extensions, "summary") delete(x.Extensions, "description") delete(x.Extensions, "value") diff --git a/openapi3/external_docs.go b/openapi3/external_docs.go index 862cd7e4b..d6893e44c 100644 --- a/openapi3/external_docs.go +++ b/openapi3/external_docs.go @@ -46,7 +46,9 @@ func (e *ExternalDocs) UnmarshalJSON(data []byte) error { if err := unmarshalJSON(data, &x); err != nil { return unmarshalError(err) } - _ = unmarshalJSON(data, &x.Extensions) + if err := unmarshalJSON(data, &x.Extensions); err != nil { + return unmarshalError(err) + } delete(x.Extensions, "description") delete(x.Extensions, "url") if len(x.Extensions) == 0 { diff --git a/openapi3/info.go b/openapi3/info.go index 9230d348d..5c79a8d7b 100644 --- a/openapi3/info.go +++ b/openapi3/info.go @@ -65,7 +65,9 @@ func (info *Info) UnmarshalJSON(data []byte) error { if err := unmarshalJSON(data, &x); err != nil { return unmarshalError(err) } - _ = unmarshalJSON(data, &x.Extensions) + if err := unmarshalJSON(data, &x.Extensions); err != nil { + return unmarshalError(err) + } delete(x.Extensions, "title") delete(x.Extensions, "summary") delete(x.Extensions, "description") diff --git a/openapi3/license.go b/openapi3/license.go index 014bbb880..e54ccd4a6 100644 --- a/openapi3/license.go +++ b/openapi3/license.go @@ -51,7 +51,9 @@ func (license *License) UnmarshalJSON(data []byte) error { if err := unmarshalJSON(data, &x); err != nil { return unmarshalError(err) } - _ = unmarshalJSON(data, &x.Extensions) + if err := unmarshalJSON(data, &x.Extensions); err != nil { + return unmarshalError(err) + } delete(x.Extensions, "name") delete(x.Extensions, "url") delete(x.Extensions, "identifier") diff --git a/openapi3/link.go b/openapi3/link.go index af9e792c1..4356e038e 100644 --- a/openapi3/link.go +++ b/openapi3/link.go @@ -63,7 +63,9 @@ func (link *Link) UnmarshalJSON(data []byte) error { if err := unmarshalJSON(data, &x); err != nil { return unmarshalError(err) } - _ = unmarshalJSON(data, &x.Extensions) + if err := unmarshalJSON(data, &x.Extensions); err != nil { + return unmarshalError(err) + } delete(x.Extensions, "operationRef") delete(x.Extensions, "operationId") diff --git a/openapi3/media_type.go b/openapi3/media_type.go index a8f62df71..55de39dea 100644 --- a/openapi3/media_type.go +++ b/openapi3/media_type.go @@ -101,7 +101,9 @@ func (mediaType *MediaType) UnmarshalJSON(data []byte) error { if err := unmarshalJSON(data, &x); err != nil { return unmarshalError(err) } - _ = unmarshalJSON(data, &x.Extensions) + if err := unmarshalJSON(data, &x.Extensions); err != nil { + return unmarshalError(err) + } delete(x.Extensions, "schema") delete(x.Extensions, "itemSchema") delete(x.Extensions, "example") diff --git a/openapi3/openapi3.go b/openapi3/openapi3.go index 4463f7d13..ee2ed4fe8 100644 --- a/openapi3/openapi3.go +++ b/openapi3/openapi3.go @@ -163,7 +163,9 @@ func (doc *T) UnmarshalJSON(data []byte) error { if err := unmarshalJSON(data, &x); err != nil { return unmarshalError(err) } - _ = unmarshalJSON(data, &x.Extensions) + if err := unmarshalJSON(data, &x.Extensions); err != nil { + return unmarshalError(err) + } delete(x.Extensions, "openapi") delete(x.Extensions, "components") delete(x.Extensions, "info") diff --git a/openapi3/operation.go b/openapi3/operation.go index c734e6962..06ce48408 100644 --- a/openapi3/operation.go +++ b/openapi3/operation.go @@ -116,7 +116,11 @@ func (operation *Operation) UnmarshalJSON(data []byte) error { return unmarshalError(err) } - _ = unmarshalJSON(data, &x.Extensions) + if err := unmarshalJSON(data, &x.Extensions); err != nil { + + return unmarshalError(err) + + } if value, present := x.Extensions["responses"]; present && value == nil { x.Responses = &Responses{explicitlyNull: true} } diff --git a/openapi3/parameter.go b/openapi3/parameter.go index abfa90154..15f026b56 100644 --- a/openapi3/parameter.go +++ b/openapi3/parameter.go @@ -212,7 +212,9 @@ func (parameter *Parameter) UnmarshalJSON(data []byte) error { if err := unmarshalJSON(data, &x); err != nil { return unmarshalError(err) } - _ = unmarshalJSON(data, &x.Extensions) + if err := unmarshalJSON(data, &x.Extensions); err != nil { + return unmarshalError(err) + } delete(x.Extensions, "name") delete(x.Extensions, "in") diff --git a/openapi3/path_item.go b/openapi3/path_item.go index 2f1c6edcf..9a7129cd3 100644 --- a/openapi3/path_item.go +++ b/openapi3/path_item.go @@ -160,7 +160,9 @@ func (pathItem *PathItem) UnmarshalJSON(data []byte) error { if err := unmarshalJSON(data, &x); err != nil { return unmarshalError(err) } - _ = unmarshalJSON(data, &x.Extensions) + if err := unmarshalJSON(data, &x.Extensions); err != nil { + return unmarshalError(err) + } delete(x.Extensions, "$ref") delete(x.Extensions, "summary") delete(x.Extensions, "description") diff --git a/openapi3/refs.go b/openapi3/refs.go index 5f7c817b6..afab87acd 100644 --- a/openapi3/refs.go +++ b/openapi3/refs.go @@ -102,7 +102,9 @@ func (x *CallbackRef) UnmarshalJSON(data []byte) error { var refOnly Ref if err := unmarshalJSON(data, &refOnly); err == nil && refOnly.Ref != "" { extra := map[string]any{} - _ = unmarshalJSON(data, &extra) + if err := unmarshalJSON(data, &extra); err != nil { + return unmarshalError(err) + } delete(extra, "$ref") x.Ref = refOnly.Ref x.Origin = refOnly.Origin @@ -275,7 +277,9 @@ func (x *ExampleRef) UnmarshalJSON(data []byte) error { var refOnly Ref if err := unmarshalJSON(data, &refOnly); err == nil && refOnly.Ref != "" { extra := map[string]any{} - _ = unmarshalJSON(data, &extra) + if err := unmarshalJSON(data, &extra); err != nil { + return unmarshalError(err) + } delete(extra, "$ref") x.Ref = refOnly.Ref x.Origin = refOnly.Origin @@ -448,7 +452,9 @@ func (x *HeaderRef) UnmarshalJSON(data []byte) error { var refOnly Ref if err := unmarshalJSON(data, &refOnly); err == nil && refOnly.Ref != "" { extra := map[string]any{} - _ = unmarshalJSON(data, &extra) + if err := unmarshalJSON(data, &extra); err != nil { + return unmarshalError(err) + } delete(extra, "$ref") x.Ref = refOnly.Ref x.Origin = refOnly.Origin @@ -621,7 +627,9 @@ func (x *LinkRef) UnmarshalJSON(data []byte) error { var refOnly Ref if err := unmarshalJSON(data, &refOnly); err == nil && refOnly.Ref != "" { extra := map[string]any{} - _ = unmarshalJSON(data, &extra) + if err := unmarshalJSON(data, &extra); err != nil { + return unmarshalError(err) + } delete(extra, "$ref") x.Ref = refOnly.Ref x.Origin = refOnly.Origin @@ -794,7 +802,9 @@ func (x *ParameterRef) UnmarshalJSON(data []byte) error { var refOnly Ref if err := unmarshalJSON(data, &refOnly); err == nil && refOnly.Ref != "" { extra := map[string]any{} - _ = unmarshalJSON(data, &extra) + if err := unmarshalJSON(data, &extra); err != nil { + return unmarshalError(err) + } delete(extra, "$ref") x.Ref = refOnly.Ref x.Origin = refOnly.Origin @@ -967,7 +977,9 @@ func (x *RequestBodyRef) UnmarshalJSON(data []byte) error { var refOnly Ref if err := unmarshalJSON(data, &refOnly); err == nil && refOnly.Ref != "" { extra := map[string]any{} - _ = unmarshalJSON(data, &extra) + if err := unmarshalJSON(data, &extra); err != nil { + return unmarshalError(err) + } delete(extra, "$ref") x.Ref = refOnly.Ref x.Origin = refOnly.Origin @@ -1140,7 +1152,9 @@ func (x *ResponseRef) UnmarshalJSON(data []byte) error { var refOnly Ref if err := unmarshalJSON(data, &refOnly); err == nil && refOnly.Ref != "" { extra := map[string]any{} - _ = unmarshalJSON(data, &extra) + if err := unmarshalJSON(data, &extra); err != nil { + return unmarshalError(err) + } delete(extra, "$ref") x.Ref = refOnly.Ref x.Origin = refOnly.Origin @@ -1352,7 +1366,9 @@ func (x *SchemaRef) UnmarshalJSON(data []byte) error { var refOnly Ref if err := unmarshalJSON(data, &refOnly); err == nil && refOnly.Ref != "" { extra := map[string]any{} - _ = unmarshalJSON(data, &extra) + if err := unmarshalJSON(data, &extra); err != nil { + return unmarshalError(err) + } delete(extra, "$ref") x.Ref = refOnly.Ref x.Origin = refOnly.Origin @@ -1539,7 +1555,9 @@ func (x *SecuritySchemeRef) UnmarshalJSON(data []byte) error { var refOnly Ref if err := unmarshalJSON(data, &refOnly); err == nil && refOnly.Ref != "" { extra := map[string]any{} - _ = unmarshalJSON(data, &extra) + if err := unmarshalJSON(data, &extra); err != nil { + return unmarshalError(err) + } delete(extra, "$ref") x.Ref = refOnly.Ref x.Origin = refOnly.Origin diff --git a/openapi3/refs.tmpl b/openapi3/refs.tmpl index 62e2af6df..3b2669ad3 100644 --- a/openapi3/refs.tmpl +++ b/openapi3/refs.tmpl @@ -157,7 +157,9 @@ func (x *{{ $type.Name }}Ref) UnmarshalJSON(data []byte) error { var refOnly Ref if err := unmarshalJSON(data, &refOnly); err == nil && refOnly.Ref != "" { extra := map[string]any{} - _ = unmarshalJSON(data, &extra) + if err := unmarshalJSON(data, &extra); err != nil { + return unmarshalError(err) + } delete(extra, "$ref") x.Ref = refOnly.Ref x.Origin = refOnly.Origin diff --git a/openapi3/request_body.go b/openapi3/request_body.go index 965d5b2e8..4f02603ea 100644 --- a/openapi3/request_body.go +++ b/openapi3/request_body.go @@ -106,7 +106,9 @@ func (requestBody *RequestBody) UnmarshalJSON(data []byte) error { if err := unmarshalJSON(data, &x); err != nil { return unmarshalError(err) } - _ = unmarshalJSON(data, &x.Extensions) + if err := unmarshalJSON(data, &x.Extensions); err != nil { + return unmarshalError(err) + } delete(x.Extensions, "description") delete(x.Extensions, "required") delete(x.Extensions, "content") diff --git a/openapi3/response.go b/openapi3/response.go index ba0f9c0c7..70c3cf429 100644 --- a/openapi3/response.go +++ b/openapi3/response.go @@ -172,7 +172,9 @@ func (response *Response) UnmarshalJSON(data []byte) error { if err := unmarshalJSON(data, &x); err != nil { return unmarshalError(err) } - _ = unmarshalJSON(data, &x.Extensions) + if err := unmarshalJSON(data, &x.Extensions); err != nil { + return unmarshalError(err) + } delete(x.Extensions, "description") delete(x.Extensions, "headers") delete(x.Extensions, "content") diff --git a/openapi3/schema.go b/openapi3/schema.go index e01f5d7ba..10aeb9386 100644 --- a/openapi3/schema.go +++ b/openapi3/schema.go @@ -792,7 +792,9 @@ func (schema *Schema) UnmarshalJSON(data []byte) error { if err := unmarshalJSON(data, &x); err != nil { return unmarshalError(err) } - _ = unmarshalJSON(data, &x.Extensions) + if err := unmarshalJSON(data, &x.Extensions); err != nil { + return unmarshalError(err) + } delete(x.Extensions, "oneOf") delete(x.Extensions, "anyOf") diff --git a/openapi3/security_scheme.go b/openapi3/security_scheme.go index 2f03a95ea..353b0c4ba 100644 --- a/openapi3/security_scheme.go +++ b/openapi3/security_scheme.go @@ -101,7 +101,9 @@ func (ss *SecurityScheme) UnmarshalJSON(data []byte) error { if err := unmarshalJSON(data, &x); err != nil { return unmarshalError(err) } - _ = unmarshalJSON(data, &x.Extensions) + if err := unmarshalJSON(data, &x.Extensions); err != nil { + return unmarshalError(err) + } delete(x.Extensions, "type") delete(x.Extensions, "description") delete(x.Extensions, "name") @@ -290,7 +292,9 @@ func (flows *OAuthFlows) UnmarshalJSON(data []byte) error { if err := unmarshalJSON(data, &x); err != nil { return unmarshalError(err) } - _ = unmarshalJSON(data, &x.Extensions) + if err := unmarshalJSON(data, &x.Extensions); err != nil { + return unmarshalError(err) + } delete(x.Extensions, "implicit") delete(x.Extensions, "password") delete(x.Extensions, "clientCredentials") @@ -378,7 +382,9 @@ func (flow *OAuthFlow) UnmarshalJSON(data []byte) error { if err := unmarshalJSON(data, &x); err != nil { return unmarshalError(err) } - _ = unmarshalJSON(data, &x.Extensions) + if err := unmarshalJSON(data, &x.Extensions); err != nil { + return unmarshalError(err) + } delete(x.Extensions, "authorizationUrl") delete(x.Extensions, "tokenUrl") diff --git a/openapi3/server.go b/openapi3/server.go index 4fed3fc5c..3a53a91a7 100644 --- a/openapi3/server.go +++ b/openapi3/server.go @@ -112,7 +112,9 @@ func (server *Server) UnmarshalJSON(data []byte) error { if err := unmarshalJSON(data, &x); err != nil { return unmarshalError(err) } - _ = unmarshalJSON(data, &x.Extensions) + if err := unmarshalJSON(data, &x.Extensions); err != nil { + return unmarshalError(err) + } delete(x.Extensions, "url") delete(x.Extensions, "description") delete(x.Extensions, "variables") @@ -320,7 +322,9 @@ func (serverVariable *ServerVariable) UnmarshalJSON(data []byte) error { if err := unmarshalJSON(data, &x); err != nil { return unmarshalError(err) } - _ = unmarshalJSON(data, &x.Extensions) + if err := unmarshalJSON(data, &x.Extensions); err != nil { + return unmarshalError(err) + } delete(x.Extensions, "enum") delete(x.Extensions, "default") delete(x.Extensions, "description") diff --git a/openapi3/tag.go b/openapi3/tag.go index 1d6b22606..94266d1d5 100644 --- a/openapi3/tag.go +++ b/openapi3/tag.go @@ -90,7 +90,9 @@ func (t *Tag) UnmarshalJSON(data []byte) error { if err := unmarshalJSON(data, &x); err != nil { return unmarshalError(err) } - _ = unmarshalJSON(data, &x.Extensions) + if err := unmarshalJSON(data, &x.Extensions); err != nil { + return unmarshalError(err) + } delete(x.Extensions, "name") delete(x.Extensions, "description") delete(x.Extensions, "externalDocs") diff --git a/openapi3/testdata/fuzz/FuzzYAMLMatchesJSON/886c20bb0385de8e b/openapi3/testdata/fuzz/FuzzYAMLMatchesJSON/886c20bb0385de8e new file mode 100644 index 000000000..c36c0354b --- /dev/null +++ b/openapi3/testdata/fuzz/FuzzYAMLMatchesJSON/886c20bb0385de8e @@ -0,0 +1,2 @@ +go test fuzz v1 +[]byte("{\"0\":{\"\":{\"\":{\"0\":1e700}}}}") diff --git a/openapi3/xml.go b/openapi3/xml.go index b0b98a766..09ff60302 100644 --- a/openapi3/xml.go +++ b/openapi3/xml.go @@ -57,7 +57,9 @@ func (xml *XML) UnmarshalJSON(data []byte) error { if err := unmarshalJSON(data, &x); err != nil { return unmarshalError(err) } - _ = unmarshalJSON(data, &x.Extensions) + if err := unmarshalJSON(data, &x.Extensions); err != nil { + return unmarshalError(err) + } delete(x.Extensions, "name") delete(x.Extensions, "namespace") delete(x.Extensions, "prefix") From 247149578c59cb52bf0601ed9570a8ed7cf6c2e0 Mon Sep 17 00:00:00 2001 From: Pierre Fenoll Date: Sat, 31 Oct 2026 21:06:53 +0100 Subject: [PATCH 41/78] openapi3: terminate Schema.IsEmpty on cyclic schemas A schema whose only content is a cycle back to itself, as through oneOf, recursed until the stack overflowed. A schema met again on the way down adds no constraint of its own there, so count it as empty. Signed-off-by: Pierre Fenoll Co-Authored-By: Claude Opus 5.5 --- openapi3/schema.go | 49 ++++++++++++++++++++++++++--------------- openapi3/schema_test.go | 12 ++++++++++ 2 files changed, 43 insertions(+), 18 deletions(-) diff --git a/openapi3/schema.go b/openapi3/schema.go index 10aeb9386..e4819afc9 100644 --- a/openapi3/schema.go +++ b/openapi3/schema.go @@ -1399,6 +1399,19 @@ func (schema *Schema) permitsNull(settings *schemaValidationSettings) bool { // IsEmpty tells whether schema is equivalent to the empty schema `{}`. func (schema *Schema) IsEmpty() bool { + return schema.isEmpty(make(map[*Schema]struct{})) +} + +// isEmpty is IsEmpty over a schema graph, which may be cyclic. A schema met +// again on the way down is already being judged: it adds no constraint of its +// own there, so it counts as empty and the others decide. +func (schema *Schema) isEmpty(visiting map[*Schema]struct{}) bool { + if _, ok := visiting[schema]; ok { + return true + } + visiting[schema] = struct{}{} + defer delete(visiting, schema) + if schema.Type != nil || schema.Format != "" || len(schema.Enum) != 0 || schema.UniqueItems || schema.ExclusiveMin.IsSet() || schema.ExclusiveMax.IsSet() || schema.Nullable || schema.ReadOnly || schema.WriteOnly || schema.AllowEmptyValue || @@ -1410,54 +1423,54 @@ func (schema *Schema) IsEmpty() bool { schema.Const != nil { return false } - if n := schema.Not; n != nil && n.Value != nil && !n.Value.IsEmpty() { + if n := schema.Not; n != nil && n.Value != nil && !n.Value.isEmpty(visiting) { return false } - if ap := schema.AdditionalProperties.Schema; ap != nil && ap.Value != nil && !ap.Value.IsEmpty() { + if ap := schema.AdditionalProperties.Schema; ap != nil && ap.Value != nil && !ap.Value.isEmpty(visiting) { return false } if apa := schema.AdditionalProperties.Has; apa != nil && !*apa { return false } - if items := schema.Items; items != nil && items.Value != nil && !items.Value.IsEmpty() { + if items := schema.Items; items != nil && items.Value != nil && !items.Value.isEmpty(visiting) { return false } for _, s := range schema.PrefixItems { - if ss := s.Value; ss != nil && !ss.IsEmpty() { + if ss := s.Value; ss != nil && !ss.isEmpty(visiting) { return false } } - if c := schema.Contains; c != nil && c.Value != nil && !c.Value.IsEmpty() { + if c := schema.Contains; c != nil && c.Value != nil && !c.Value.isEmpty(visiting) { return false } if schema.MinContains != nil || schema.MaxContains != nil { return false } for _, s := range schema.Properties { - if ss := s.Value; ss != nil && !ss.IsEmpty() { + if ss := s.Value; ss != nil && !ss.isEmpty(visiting) { return false } } for _, s := range schema.PatternProperties { - if ss := s.Value; ss != nil && !ss.IsEmpty() { + if ss := s.Value; ss != nil && !ss.isEmpty(visiting) { return false } } for _, s := range schema.DependentSchemas { - if ss := s.Value; ss != nil && !ss.IsEmpty() { + if ss := s.Value; ss != nil && !ss.isEmpty(visiting) { return false } } - if pn := schema.PropertyNames; pn != nil && pn.Value != nil && !pn.Value.IsEmpty() { + if pn := schema.PropertyNames; pn != nil && pn.Value != nil && !pn.Value.isEmpty(visiting) { return false } - if ui := schema.UnevaluatedItems.Schema; ui != nil && ui.Value != nil && !ui.Value.IsEmpty() { + if ui := schema.UnevaluatedItems.Schema; ui != nil && ui.Value != nil && !ui.Value.isEmpty(visiting) { return false } if uih := schema.UnevaluatedItems.Has; uih != nil && !*uih { return false } - if up := schema.UnevaluatedProperties.Schema; up != nil && up.Value != nil && !up.Value.IsEmpty() { + if up := schema.UnevaluatedProperties.Schema; up != nil && up.Value != nil && !up.Value.isEmpty(visiting) { return false } if uph := schema.UnevaluatedProperties.Has; uph != nil && !*uph { @@ -1467,27 +1480,27 @@ func (schema *Schema) IsEmpty() bool { return false } for _, s := range schema.OneOf { - if ss := s.Value; ss != nil && !ss.IsEmpty() { + if ss := s.Value; ss != nil && !ss.isEmpty(visiting) { return false } } for _, s := range schema.AnyOf { - if ss := s.Value; ss != nil && !ss.IsEmpty() { + if ss := s.Value; ss != nil && !ss.isEmpty(visiting) { return false } } for _, s := range schema.AllOf { - if ss := s.Value; ss != nil && !ss.IsEmpty() { + if ss := s.Value; ss != nil && !ss.isEmpty(visiting) { return false } } - if f := schema.If; f != nil && f.Value != nil && !f.Value.IsEmpty() { + if f := schema.If; f != nil && f.Value != nil && !f.Value.isEmpty(visiting) { return false } - if t := schema.Then; t != nil && t.Value != nil && !t.Value.IsEmpty() { + if t := schema.Then; t != nil && t.Value != nil && !t.Value.isEmpty(visiting) { return false } - if e := schema.Else; e != nil && e.Value != nil && !e.Value.IsEmpty() { + if e := schema.Else; e != nil && e.Value != nil && !e.Value.isEmpty(visiting) { return false } if len(schema.DependentRequired) != 0 { @@ -1505,7 +1518,7 @@ func (schema *Schema) IsEmpty() bool { if schema.ContentMediaType != "" || schema.ContentEncoding != "" { return false } - if cs := schema.ContentSchema; cs != nil && cs.Value != nil && !cs.Value.IsEmpty() { + if cs := schema.ContentSchema; cs != nil && cs.Value != nil && !cs.Value.isEmpty(visiting) { return false } // Last, so a schema carrying both a boolean and other keywords is judged by diff --git a/openapi3/schema_test.go b/openapi3/schema_test.go index 014716b33..8b5761ad5 100644 --- a/openapi3/schema_test.go +++ b/openapi3/schema_test.go @@ -1689,3 +1689,15 @@ func TestSchemaLengthDecodedBase64(t *testing.T) { require.Equal(t, uint64(4), *schema.MaxLength) }) } + +func TestSchemaIsEmptyCyclic(t *testing.T) { + // a: {oneOf: [b]}, b: {oneOf: [a]} constrains nothing, and must not + // recurse forever finding that out. + a, b := &Schema{}, &Schema{} + a.OneOf = SchemaRefs{{Value: b}} + b.OneOf = SchemaRefs{{Value: a}} + require.True(t, a.IsEmpty()) + + b.OneOf = append(b.OneOf, &SchemaRef{Value: &Schema{Type: &Types{TypeString}}}) + require.False(t, a.IsEmpty()) +} From b484990162e389e65746332717a53cb5c6e53b86 Mon Sep 17 00:00:00 2001 From: Pierre Fenoll Date: Sat, 31 Oct 2026 21:06:53 +0100 Subject: [PATCH 42/78] openapi2, openapi3: write missing required maps as null in YAML too A required field holding a nil map or slice, such as the content of a request body, the scopes of an OAuth flow or of a security requirement, or the responses of an operation, was written null as JSON and as {} or [] as YAML, so a document read back differently from its YAML. Signed-off-by: Pierre Fenoll Co-Authored-By: Claude Opus 5.5 --- .github/docs/openapi3.txt | 5 +++++ openapi2/operation.go | 8 +++++++- openapi3/request_body.go | 6 +++++- openapi3/security_requirements.go | 18 ++++++++++++++++++ openapi3/security_scheme.go | 8 +++++++- 5 files changed, 42 insertions(+), 3 deletions(-) diff --git a/.github/docs/openapi3.txt b/.github/docs/openapi3.txt index 133814dfd..119a72871 100644 --- a/.github/docs/openapi3.txt +++ b/.github/docs/openapi3.txt @@ -3572,6 +3572,11 @@ func NewSecurityRequirement() SecurityRequirement func (security SecurityRequirement) Authenticate(provider string, scopes ...string) SecurityRequirement +func (security SecurityRequirement) MarshalYAML() (any, error) + MarshalYAML returns the YAML encoding of SecurityRequirement. A nil + SecurityRequirement or list of scopes is written null, as JSON writes it, + rather than the "{}" or "[]" YAML would make of it. + func (sr *SecurityRequirement) UnmarshalYAML(node *yaml.Node) error UnmarshalYAML sets SecurityRequirement from node. diff --git a/openapi2/operation.go b/openapi2/operation.go index 9f8e9dd12..b8420140f 100644 --- a/openapi2/operation.go +++ b/openapi2/operation.go @@ -49,7 +49,13 @@ func (operation Operation) MarshalJSON() ([]byte, error) { if x := operation.Parameters; len(x) != 0 { m["parameters"] = x } - m["responses"] = operation.Responses + // Required, so written even when missing: as null, not as the "{}" YAML + // would make of a nil map. + if x := operation.Responses; x != nil { + m["responses"] = x + } else { + m["responses"] = nil + } if x := operation.Consumes; len(x) != 0 { m["consumes"] = x } diff --git a/openapi3/request_body.go b/openapi3/request_body.go index 4f02603ea..91d7b5997 100644 --- a/openapi3/request_body.go +++ b/openapi3/request_body.go @@ -93,8 +93,12 @@ func (requestBody RequestBody) MarshalYAML() (any, error) { if x := requestBody.Required; x { m["required"] = x } - if x := requestBody.Content; true { + // Required, so written even when missing. A nil map would be written + // "null" as JSON and "{}" as YAML: write null both ways. + if x := requestBody.Content; x != nil { m["content"] = x + } else { + m["content"] = nil } return m, nil } diff --git a/openapi3/security_requirements.go b/openapi3/security_requirements.go index 3f5bd9510..90a5de5b6 100644 --- a/openapi3/security_requirements.go +++ b/openapi3/security_requirements.go @@ -43,6 +43,24 @@ func (security SecurityRequirement) Authenticate(provider string, scopes ...stri return security } +// MarshalYAML returns the YAML encoding of SecurityRequirement. A nil +// SecurityRequirement or list of scopes is written null, as JSON writes it, +// rather than the "{}" or "[]" YAML would make of it. +func (security SecurityRequirement) MarshalYAML() (any, error) { + if security == nil { + return nil, nil + } + m := make(map[string]any, len(security)) + for name, scopes := range security { + if scopes == nil { + m[name] = nil + } else { + m[name] = scopes + } + } + return m, nil +} + // Validate returns an error if SecurityRequirement does not comply with the OpenAPI spec. func (security *SecurityRequirement) Validate(ctx context.Context, opts ...ValidationOption) error { // ctx = WithValidationOptions(ctx, opts...) diff --git a/openapi3/security_scheme.go b/openapi3/security_scheme.go index 353b0c4ba..9b9ccbc43 100644 --- a/openapi3/security_scheme.go +++ b/openapi3/security_scheme.go @@ -371,7 +371,13 @@ func (flow OAuthFlow) MarshalYAML() (any, error) { if x := flow.RefreshURL; x != "" { m["refreshUrl"] = x } - m["scopes"] = flow.Scopes + // Required, so written even when missing: as null, not as the "{}" YAML + // would make of a nil map. + if x := flow.Scopes; x != nil { + m["scopes"] = x + } else { + m["scopes"] = nil + } return m, nil } From e3e3b24dda723e1e23580a400cddb022877ba71f Mon Sep 17 00:00:00 2001 From: Pierre Fenoll Date: Sat, 31 Oct 2026 21:06:53 +0100 Subject: [PATCH 43/78] openapi3filter: no panic decoding a form body without a schema UrlencodedBodyDecoder and MultipartBodyDecoder are exported, and given a nil schema they dereferenced it. Signed-off-by: Pierre Fenoll Co-Authored-By: Claude Opus 5.5 --- openapi3filter/req_resp_decoder.go | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/openapi3filter/req_resp_decoder.go b/openapi3filter/req_resp_decoder.go index 0cbb99b4b..92f714e93 100644 --- a/openapi3filter/req_resp_decoder.go +++ b/openapi3filter/req_resp_decoder.go @@ -1535,7 +1535,7 @@ func UrlencodedBodyDecoder(body io.Reader, header http.Header, schema *openapi3. // Validate schema of request body. // By the OpenAPI 3 specification request body's schema must have type "object". // Properties of the schema describes individual parts of request body. - if !schema.Value.Type.Is("object") { + if schema == nil || schema.Value == nil || !schema.Value.Type.Is("object") { return nil, errors.New("unsupported schema of request body") } propNames := make([]string, 0, len(schema.Value.Properties)) @@ -1649,7 +1649,7 @@ func decodeProperty(dec valueDecoder, name string, prop *openapi3.SchemaRef, enc } func MultipartBodyDecoder(body io.Reader, header http.Header, schema *openapi3.SchemaRef, encFn EncodingFn) (any, error) { - if !schema.Value.Type.Is("object") { + if schema == nil || schema.Value == nil || !schema.Value.Type.Is("object") { return nil, errors.New("unsupported schema of request body") } From 1cdf081a66c56e546899410efcbba78d0aad2873 Mon Sep 17 00:00:00 2001 From: Pierre Fenoll Date: Sat, 31 Oct 2026 21:06:53 +0100 Subject: [PATCH 44/78] openapi3filter: decode YAML bodies with non-string keys to map[string]any A YAML body with a key other than a string, such as `1: a` or `? : a`, decoded to a map[any]any, which the BodyDecoder contract does not allow and schema validation does not handle. Write scalar keys as JSON would, and refuse mappings or sequences used as keys. Signed-off-by: Pierre Fenoll Co-Authored-By: Claude Opus 5.5 --- openapi3filter/req_resp_decoder.go | 54 ++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) diff --git a/openapi3filter/req_resp_decoder.go b/openapi3filter/req_resp_decoder.go index 92f714e93..dddb1d902 100644 --- a/openapi3filter/req_resp_decoder.go +++ b/openapi3filter/req_resp_decoder.go @@ -1515,6 +1515,60 @@ func YamlBodyDecoder(body io.Reader, header http.Header, schema *openapi3.Schema if err := yaml.NewDecoder(body).Decode(&value); err != nil { return nil, &ParseError{Kind: KindInvalidFormat, Cause: err} } + value, err := yamlToJSONValue(value) + if err != nil { + return nil, &ParseError{Kind: KindInvalidFormat, Cause: err} + } + return value, nil +} + +// yamlToJSONValue turns the mappings YAML decodes with keys other than +// strings, such as "1: a" or "? : a", into the map[string]any a BodyDecoder +// returns. A scalar key is written the way JSON would write it, and a mapping +// or sequence as a key is refused: no JSON object can hold it. +func yamlToJSONValue(value any) (any, error) { + switch v := value.(type) { + case map[string]any: + for k, e := range v { + e, err := yamlToJSONValue(e) + if err != nil { + return nil, err + } + v[k] = e + } + case map[any]any: + m := make(map[string]any, len(v)) + for k, e := range v { + var key string + switch k := k.(type) { + case nil: + key = "null" + case string: + key = k + case bool, int, int64, uint64, float64: + key = fmt.Sprint(k) + default: + return nil, fmt.Errorf("unsupported mapping key of type %T", k) + } + if _, ok := m[key]; ok { + return nil, fmt.Errorf("duplicate mapping key %q", key) + } + e, err := yamlToJSONValue(e) + if err != nil { + return nil, err + } + m[key] = e + } + return m, nil + case []any: + for i, e := range v { + e, err := yamlToJSONValue(e) + if err != nil { + return nil, err + } + v[i] = e + } + } return value, nil } From 6c870befbc7b21b76f475eb132d0df4392df7f38 Mon Sep 17 00:00:00 2001 From: Pierre Fenoll Date: Sat, 31 Oct 2026 21:06:53 +0100 Subject: [PATCH 45/78] openapi2: emit YAML from the generic form in FuzzUnmarshalFromData oasdiff/yaml's Marshal goes through JSON and back, and fails on keys longer than YAML allows an implicit key to be. yaml/v3 writes those as explicit "? " keys. Found by FuzzUnmarshalFromData in CI. Signed-off-by: Pierre Fenoll Co-Authored-By: Claude Opus 5.5 --- openapi2/fuzz_test.go | 7 +++++-- .../testdata/fuzz/FuzzUnmarshalFromData/ed99ca47ae7577b2 | 2 ++ 2 files changed, 7 insertions(+), 2 deletions(-) create mode 100644 openapi2/testdata/fuzz/FuzzUnmarshalFromData/ed99ca47ae7577b2 diff --git a/openapi2/fuzz_test.go b/openapi2/fuzz_test.go index 764a961ce..d87c5674d 100644 --- a/openapi2/fuzz_test.go +++ b/openapi2/fuzz_test.go @@ -4,8 +4,8 @@ import ( "encoding/json" "testing" - "github.com/oasdiff/yaml" "github.com/stretchr/testify/require" + yaml "go.yaml.in/yaml/v3" "github.com/getkin/kin-openapi/internal/fuzzing" ) @@ -67,7 +67,10 @@ definitions: if fuzzing.LosesInYAML(generic) { return } - y, err := yaml.Marshal(&doc) + // Emitted from the generic form: going through JSON and back, as + // oasdiff/yaml's Marshal does, refuses keys longer than YAML allows + // implicit keys to be, which the emitter writes as explicit "? " keys. + y, err := yaml.Marshal(generic) require.NoError(t, err) var fromYAML T require.NoError(t, unmarshal(y, &fromYAML), "yaml:\n%s", y) diff --git a/openapi2/testdata/fuzz/FuzzUnmarshalFromData/ed99ca47ae7577b2 b/openapi2/testdata/fuzz/FuzzUnmarshalFromData/ed99ca47ae7577b2 new file mode 100644 index 000000000..de3288486 --- /dev/null +++ b/openapi2/testdata/fuzz/FuzzUnmarshalFromData/ed99ca47ae7577b2 @@ -0,0 +1,2 @@ +go test fuzz v1 +[]byte("{aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"Ό\":\"0}") From e57ca64e41623561bfd8e09aa450836cd14ad40a Mon Sep 17 00:00:00 2001 From: Pierre Fenoll Date: Sun, 1 Nov 2026 01:30:31 +0100 Subject: [PATCH 46/78] openapi3: validate discriminators and the schemas their mapping loads Discriminator.Validate was never called, and a schema reachable only through a discriminator mapping was never validated. InternalizeRefs then gives such a schema a component, where Validate does check it: a document that validated stopped validating once internalized. Schema validation now validates its discriminator and each schema the mapping loaded. Mapping values without one (plain schema names, refs into the root document's components, refs left unfollowed) are skipped. Found by FuzzInternalizeRefs. Signed-off-by: Pierre Fenoll Co-Authored-By: Claude Opus 5.5 --- openapi3/schema.go | 14 ++++++++++++++ .../fuzz/FuzzInternalizeRefs/e5b6d28717abfbc3 | 3 +++ 2 files changed, 17 insertions(+) create mode 100644 openapi3/testdata/fuzz/FuzzInternalizeRefs/e5b6d28717abfbc3 diff --git a/openapi3/schema.go b/openapi3/schema.go index e4819afc9..bc12c53b7 100644 --- a/openapi3/schema.go +++ b/openapi3/schema.go @@ -1790,6 +1790,20 @@ func (schema *Schema) validate(ctx context.Context, visited map[*Schema]struct{} } } + if d := schema.Discriminator; d != nil { + if err := d.Validate(ctx); err != nil { + return visited, err + } + for _, k := range componentNames(d.Mapping) { + if v := d.Mapping[k].Value; v != nil { + var err error + if visited, err = v.validate(ctx, visited); err != nil { + return visited, err + } + } + } + } + if ref := schema.Not; ref != nil { v := ref.Value if v == nil { diff --git a/openapi3/testdata/fuzz/FuzzInternalizeRefs/e5b6d28717abfbc3 b/openapi3/testdata/fuzz/FuzzInternalizeRefs/e5b6d28717abfbc3 new file mode 100644 index 000000000..6b4fe629b --- /dev/null +++ b/openapi3/testdata/fuzz/FuzzInternalizeRefs/e5b6d28717abfbc3 @@ -0,0 +1,3 @@ +go test fuzz v1 +[]byte("{\"components\":{\"schemas\":{\"0\":{\"discriminator\":{\"mapping\":{0: /}}}}},\"info\":{\"title\":A,\"version\":A},\"openapi\":A}") +[]byte("{0}") From 84645cdb6e6bc33248af77459487dfe3d6d9aa44 Mon Sep 17 00:00:00 2001 From: Pierre Fenoll Date: Sat, 31 Oct 2026 21:06:53 +0100 Subject: [PATCH 47/78] openapi3: add FuzzInternalizeRefs Loads a root document whose external refs read a second input, then checks that internalizing leaves only local refs, that the result loads with external refs disallowed, stays valid when it was, and does not change when internalized again. Signed-off-by: Pierre Fenoll Co-Authored-By: Claude Opus 5.5 --- .github/workflows/fuzz.yml | 1 + openapi3/internalize_refs_fuzz_test.go | 166 ++++++++++++++++++ .../fuzz/FuzzInternalizeRefs/294f1ea5661836e3 | 3 + .../fuzz/FuzzInternalizeRefs/2d1608a3eaf3c0a4 | 3 + .../fuzz/FuzzInternalizeRefs/b711821bf5eb26eb | 3 + .../fuzz/FuzzInternalizeRefs/e2a9b4711a836c5c | 3 + 6 files changed, 179 insertions(+) create mode 100644 openapi3/internalize_refs_fuzz_test.go create mode 100644 openapi3/testdata/fuzz/FuzzInternalizeRefs/294f1ea5661836e3 create mode 100644 openapi3/testdata/fuzz/FuzzInternalizeRefs/2d1608a3eaf3c0a4 create mode 100644 openapi3/testdata/fuzz/FuzzInternalizeRefs/b711821bf5eb26eb create mode 100644 openapi3/testdata/fuzz/FuzzInternalizeRefs/e2a9b4711a836c5c diff --git a/.github/workflows/fuzz.yml b/.github/workflows/fuzz.yml index 68ba5f3b4..e0334d581 100644 --- a/.github/workflows/fuzz.yml +++ b/.github/workflows/fuzz.yml @@ -38,6 +38,7 @@ jobs: - {package: ./openapi3, target: FuzzLoadWithOrigins} - {package: ./openapi3, target: FuzzYAMLMatchesJSON} - {package: ./openapi3, target: FuzzSchemaVisitJSON} + - {package: ./openapi3, target: FuzzInternalizeRefs} - {package: ./openapi2, target: FuzzUnmarshalFromData} - {package: ./internal/nodeindex, target: FuzzNew} - {package: ./openapi2conv, target: FuzzToV3} diff --git a/openapi3/internalize_refs_fuzz_test.go b/openapi3/internalize_refs_fuzz_test.go new file mode 100644 index 000000000..bd4c7fd7a --- /dev/null +++ b/openapi3/internalize_refs_fuzz_test.go @@ -0,0 +1,166 @@ +package openapi3_test + +import ( + "net/url" + "os" + "path" + "reflect" + "strings" + "testing" + + "github.com/stretchr/testify/require" + + "github.com/getkin/kin-openapi/internal/fuzzing" + "github.com/getkin/kin-openapi/openapi3" +) + +// fuzzRootURL is where the root document of FuzzInternalizeRefs lives. A ref +// naming its file reads the root again, any other file reads the second input. +var fuzzRootURL = &url.URL{Path: "/spec/root.yaml"} + +func newTwoDocLoader(root, other []byte) *openapi3.Loader { + loader := openapi3.NewLoader() + loader.IsExternalRefsAllowed = true + loader.ReadFromURIFunc = func(_ *openapi3.Loader, location *url.URL) ([]byte, error) { + if path.Base(location.Path) == path.Base(fuzzRootURL.Path) { + return root, nil + } + return other, nil + } + return loader +} + +// internalizeSeeds pairs each root of TestInternalizeRefs with a document its +// external refs point to. +var internalizeSeeds = [][2]string{ + {"testdata/testref.openapi.yml", "testdata/components.openapi.yml"}, + {"testdata/recursiveRef/openapi.yml", "testdata/recursiveRef/components/Foo.yml"}, + {"testdata/interalizationNameCollision/api.yml", "testdata/interalizationNameCollision/schemas/book/record.yml"}, + {"testdata/issue1205/openapi.yml", "testdata/issue1205/ext.yml"}, + {"testdata/issue1205/mutual.yml", "testdata/issue1205/mutual-a.yml"}, + {"testdata/issue1205/mutual.yml", "testdata/issue1205/mutual-b.yml"}, +} + +// Once internalized, a document refers to nothing outside itself, loads +// without external refs allowed, and internalizing it again changes nothing. +// A valid document stays valid. +func FuzzInternalizeRefs(f *testing.F) { + for _, pair := range internalizeSeeds { + root, err := os.ReadFile(pair[0]) + require.NoError(f, err) + other, err := os.ReadFile(pair[1]) + require.NoError(f, err) + f.Add(root, other) + } + // Any document whose refs, whatever file they name, read itself back. + for _, seed := range fuzzing.Testdata(f, "testdata") { + f.Add(seed, seed) + } + f.Add( + []byte(`{"openapi":"3.0.0","info":{"title":"t","version":"1"},"paths":{"/a":{"$ref":"other.yaml#/paths/~1b"}}}`), + []byte(`{"paths":{"/b":{"get":{"responses":{"200":{"$ref":"#/components/responses/R"}}}}},"components":{"responses":{"R":{"description":"d","content":{"application/json":{"schema":{"$ref":"#/components/schemas/S"}}}}},"schemas":{"S":{"type":"string"}}}}`), + ) + f.Add( + []byte(`{"openapi":"3.0.0","info":{"title":"t","version":"1"},"paths":{},"components":{"schemas":{"A":{"$ref":"x.json#/components/schemas/A"},"x_A":{"type":"integer"}}}}`), + []byte(`{"components":{"schemas":{"A":{"type":"object","properties":{"self":{"$ref":"#/components/schemas/A"},"root":{"$ref":"root.yaml#/components/schemas/x_A"}}}}}}`), + ) + + f.Fuzz(func(t *testing.T, root, other []byte) { + if len(root)+len(other) > maxFuzzInput { + t.Skip() + } + + doc, err := newTwoDocLoader(root, other).LoadFromDataWithPath(root, fuzzRootURL) + if err != nil { + return + } + valid := doc.Validate(t.Context()) + + doc.InternalizeRefs(t.Context(), nil) + + unfollowed := false + forEachRef(doc, func(site refSite) { + if site.Mapping && !strings.Contains(site.Ref, "/") { + return // a plain schema name, not a reference + } + if site.Ref == "" || strings.HasPrefix(site.Ref, "#") { + return + } + // The loader did not follow it, so there is nothing to internalize. + require.True(t, site.Unfollowed, "external ref left: %q", site.Ref) + unfollowed = true + }) + + once, err := doc.MarshalJSON() + require.NoError(t, err) + + strict := openapi3.NewLoader() + reloaded, err := strict.LoadFromData(once) + if unfollowed { + return // still refers elsewhere, which strict refuses + } + require.NoError(t, err, "\nonce: %s\nroot:\n%s\nother:\n%s", once, root, other) + + if valid == nil { + require.NoError(t, reloaded.Validate(t.Context()), "\nonce: %s", once) + } + + reloaded.InternalizeRefs(t.Context(), nil) + twice, err := reloaded.MarshalJSON() + require.NoError(t, err) + require.JSONEq(t, string(once), string(twice)) + }) +} + +var mappingRefType = reflect.TypeFor[openapi3.MappingRef]() + +// refSite is the Ref field of a reference object, path item or discriminator +// mapping. +type refSite struct { + Ref string + // Mapping tells a discriminator mapping value, which may be a plain name. + Mapping bool + // Unfollowed tells a ref the loader left without a target. + Unfollowed bool +} + +// forEachRef calls fn on every refSite reachable from v. A resolved document +// is a graph, so each pointer is visited once. Values typed any, such as +// examples and extensions, are not entered: a "$ref" key there is data. +func forEachRef(v any, fn func(refSite)) { + seen := make(map[uintptr]struct{}) + var walk func(reflect.Value) + walk = func(v reflect.Value) { + switch v.Kind() { + case reflect.Pointer: + if v.IsNil() { + return + } + if _, ok := seen[v.Pointer()]; ok { + return + } + seen[v.Pointer()] = struct{}{} + walk(v.Elem()) + case reflect.Struct: + if f, ok := v.Type().FieldByName("Ref"); ok && f.Type.Kind() == reflect.String && len(f.Index) == 1 { + site := refSite{Ref: v.FieldByIndex(f.Index).String(), Mapping: v.Type() == mappingRefType} + if p := v.FieldByName("refPath"); p.IsValid() { + site.Unfollowed = site.Ref != "" && p.IsNil() + } + fn(site) + } + for i := range v.NumField() { + walk(v.Field(i)) + } + case reflect.Slice, reflect.Array: + for i := range v.Len() { + walk(v.Index(i)) + } + case reflect.Map: + for it := v.MapRange(); it.Next(); { + walk(it.Value()) + } + } + } + walk(reflect.ValueOf(v)) +} diff --git a/openapi3/testdata/fuzz/FuzzInternalizeRefs/294f1ea5661836e3 b/openapi3/testdata/fuzz/FuzzInternalizeRefs/294f1ea5661836e3 new file mode 100644 index 000000000..b3cc8255b --- /dev/null +++ b/openapi3/testdata/fuzz/FuzzInternalizeRefs/294f1ea5661836e3 @@ -0,0 +1,3 @@ +go test fuzz v1 +[]byte("paths:\n 0:\n get:\n responses:\n 0:\n $ref: '#/components/0000000000'\ncomponents:") +[]byte("0") diff --git a/openapi3/testdata/fuzz/FuzzInternalizeRefs/2d1608a3eaf3c0a4 b/openapi3/testdata/fuzz/FuzzInternalizeRefs/2d1608a3eaf3c0a4 new file mode 100644 index 000000000..67c6a450e --- /dev/null +++ b/openapi3/testdata/fuzz/FuzzInternalizeRefs/2d1608a3eaf3c0a4 @@ -0,0 +1,3 @@ +go test fuzz v1 +[]byte("components:\n schemas:\n 0:\n $ref: 0#") +[]byte("") diff --git a/openapi3/testdata/fuzz/FuzzInternalizeRefs/b711821bf5eb26eb b/openapi3/testdata/fuzz/FuzzInternalizeRefs/b711821bf5eb26eb new file mode 100644 index 000000000..341f8a4a9 --- /dev/null +++ b/openapi3/testdata/fuzz/FuzzInternalizeRefs/b711821bf5eb26eb @@ -0,0 +1,3 @@ +go test fuzz v1 +[]byte("components:\n schemas:\n 0:\n $ref: A0000#") +[]byte("$ref: A") diff --git a/openapi3/testdata/fuzz/FuzzInternalizeRefs/e2a9b4711a836c5c b/openapi3/testdata/fuzz/FuzzInternalizeRefs/e2a9b4711a836c5c new file mode 100644 index 000000000..0573fb943 --- /dev/null +++ b/openapi3/testdata/fuzz/FuzzInternalizeRefs/e2a9b4711a836c5c @@ -0,0 +1,3 @@ +go test fuzz v1 +[]byte("{\"components\":{\"schemas\":{\"00000000\":{\"discriminator\":{\"mapping\":{0: /}}}}},\"info\":{\"title\":A,\"version\":0A},\"openapi\":A}") +[]byte("{}") From 767eb7d3fadd510af9c00d6d554534aaf5c3d04a Mon Sep 17 00:00:00 2001 From: Pierre Fenoll Date: Sat, 31 Oct 2026 21:06:53 +0100 Subject: [PATCH 48/78] openapi3: add FuzzInternalizeRefsKeepsMeaning Each schema of the root's components accepts the same value before and after internalizing. Signed-off-by: Pierre Fenoll Co-Authored-By: Claude Opus 5.5 --- .github/workflows/fuzz.yml | 1 + openapi3/internalize_refs_fuzz_test.go | 59 +++++++++++++++++++ .../81a933eb969de984 | 4 ++ 3 files changed, 64 insertions(+) create mode 100644 openapi3/testdata/fuzz/FuzzInternalizeRefsKeepsMeaning/81a933eb969de984 diff --git a/.github/workflows/fuzz.yml b/.github/workflows/fuzz.yml index e0334d581..95cca421f 100644 --- a/.github/workflows/fuzz.yml +++ b/.github/workflows/fuzz.yml @@ -39,6 +39,7 @@ jobs: - {package: ./openapi3, target: FuzzYAMLMatchesJSON} - {package: ./openapi3, target: FuzzSchemaVisitJSON} - {package: ./openapi3, target: FuzzInternalizeRefs} + - {package: ./openapi3, target: FuzzInternalizeRefsKeepsMeaning} - {package: ./openapi2, target: FuzzUnmarshalFromData} - {package: ./internal/nodeindex, target: FuzzNew} - {package: ./openapi2conv, target: FuzzToV3} diff --git a/openapi3/internalize_refs_fuzz_test.go b/openapi3/internalize_refs_fuzz_test.go index bd4c7fd7a..4e09799c8 100644 --- a/openapi3/internalize_refs_fuzz_test.go +++ b/openapi3/internalize_refs_fuzz_test.go @@ -1,6 +1,7 @@ package openapi3_test import ( + "encoding/json" "net/url" "os" "path" @@ -164,3 +165,61 @@ func forEachRef(v any, fn func(refSite)) { } walk(reflect.ValueOf(v)) } + +// Internalizing changes where schemas live, not what they mean: each schema +// of the root's components accepts the same values before and after. +func FuzzInternalizeRefsKeepsMeaning(f *testing.F) { + for _, pair := range internalizeSeeds { + root, err := os.ReadFile(pair[0]) + require.NoError(f, err) + other, err := os.ReadFile(pair[1]) + require.NoError(f, err) + for _, value := range []string{`{}`, `null`, `"s"`, `1`, `[{"cat":{}}]`, `{"foo":{"bar":"x"},"cat":{"cat":1}}`} { + f.Add(root, other, []byte(value)) + } + } + f.Add( + []byte(`{"openapi":"3.0.0","info":{"title":"t","version":"1"},"paths":{},"components":{"schemas":{"A":{"type":"object","properties":{"b":{"$ref":"other.yaml#/components/schemas/B"}}}}}}`), + []byte(`{"components":{"schemas":{"B":{"type":"array","items":{"$ref":"#/components/schemas/C"}},"C":{"type":"integer","maximum":3}}}}`), + []byte(`{"b":[1,2,4]}`), + ) + + f.Fuzz(func(t *testing.T, root, other, value []byte) { + if len(root)+len(other)+len(value) > maxFuzzInput { + t.Skip() + } + var v any + if json.Unmarshal(value, &v) != nil { + t.Skip() + } + + doc, err := newTwoDocLoader(root, other).LoadFromDataWithPath(root, fuzzRootURL) + if err != nil || doc.Components == nil { + return + } + if doc.Validate(t.Context()) != nil { + return + } + before := make(map[string]bool, len(doc.Components.Schemas)) + for name, schema := range doc.Components.Schemas { + if schema != nil && schema.Value != nil { + before[name] = schema.Value.VisitJSON(v) == nil + } + } + + doc.InternalizeRefs(t.Context(), nil) + once, err := doc.MarshalJSON() + require.NoError(t, err) + loader := openapi3.NewLoader() + reloaded, err := loader.LoadFromData(once) + if err != nil { + return // FuzzInternalizeRefs covers this + } + for name, accepted := range before { + schema := reloaded.Components.Schemas[name] + require.NotNil(t, schema, name) + require.NotNil(t, schema.Value, name) + require.Equal(t, accepted, schema.Value.VisitJSON(v) == nil, "schema %q, value %s\nonce: %s", name, value, once) + } + }) +} diff --git a/openapi3/testdata/fuzz/FuzzInternalizeRefsKeepsMeaning/81a933eb969de984 b/openapi3/testdata/fuzz/FuzzInternalizeRefsKeepsMeaning/81a933eb969de984 new file mode 100644 index 000000000..321565735 --- /dev/null +++ b/openapi3/testdata/fuzz/FuzzInternalizeRefsKeepsMeaning/81a933eb969de984 @@ -0,0 +1,4 @@ +go test fuzz v1 +[]byte("openapi: 3.1.0\ninfo:\n title: external recursive discminated union\n version: 1.0.0\npaths: {}\ncomponents:\n schemas:\n irobe:\n type: object\n properties: \n deep:\n $ref: './ext.yml#/components/schemas/Comp'") +[]byte("openapi: 3.1.0\ninfo:\n title: recursive discriminated union\n version: 1.0.0\npaths: {}\ncomponents:\n schemas:\n Comp:\n oneOf:\n - $ref: '#/components/schemas/Container'\n discriminator:\n propertyName: type\n mapping:\n container: '#/components/schemas/Container'\n Container:\n type: object\n required: [type]\n properties:\n type:\n type: string\n children:\n type: array\n items : \n $ref: '#/components/schemas/Comp'") +[]byte("[{\"\x81a\xea7ޫ\x86\xb0G;t\":{}}]") From 3d3b367c23c7e03328a8b22d1ab497b540ddd478 Mon Sep 17 00:00:00 2001 From: Pierre Fenoll Date: Sat, 31 Oct 2026 21:06:53 +0100 Subject: [PATCH 49/78] openapi3: add FuzzValidateOptions Turning a check off never rejects a document the default checks accept, and EnableMultiError does not change whether there is an error. Signed-off-by: Pierre Fenoll Co-Authored-By: Claude Opus 5.5 --- .github/workflows/fuzz.yml | 1 + openapi3/validate_options_fuzz_test.go | 47 ++++++++++++++++++++++++++ 2 files changed, 48 insertions(+) create mode 100644 openapi3/validate_options_fuzz_test.go diff --git a/.github/workflows/fuzz.yml b/.github/workflows/fuzz.yml index 95cca421f..fc3991a8a 100644 --- a/.github/workflows/fuzz.yml +++ b/.github/workflows/fuzz.yml @@ -40,6 +40,7 @@ jobs: - {package: ./openapi3, target: FuzzSchemaVisitJSON} - {package: ./openapi3, target: FuzzInternalizeRefs} - {package: ./openapi3, target: FuzzInternalizeRefsKeepsMeaning} + - {package: ./openapi3, target: FuzzValidateOptions} - {package: ./openapi2, target: FuzzUnmarshalFromData} - {package: ./internal/nodeindex, target: FuzzNew} - {package: ./openapi2conv, target: FuzzToV3} diff --git a/openapi3/validate_options_fuzz_test.go b/openapi3/validate_options_fuzz_test.go new file mode 100644 index 000000000..47285af55 --- /dev/null +++ b/openapi3/validate_options_fuzz_test.go @@ -0,0 +1,47 @@ +package openapi3_test + +import ( + "testing" + + "github.com/stretchr/testify/require" + + "github.com/getkin/kin-openapi/openapi3" +) + +// Turning a check off never rejects a document the default checks accept, +// and collecting every error instead of the first changes nothing about +// whether there is one. +func FuzzValidateOptions(f *testing.F) { + seedFromTestdata(f) + f.Add([]byte(`{"openapi":"3.0.0","info":{"title":"t","version":"1"},"paths":{},"components":{"schemas":{"a":{"type":"string","format":"email","pattern":"^a","default":"b","example":"c"}}}}`)) + f.Add([]byte(`{"openapi":"3.0.0","info":{"title":"t","version":"1"},"paths":{},"components":{"schemas":{"a":{"$ref":"#/components/schemas/b","x-a":1,"description":"d"},"b":{}}}}`)) + + relaxed := map[string]openapi3.ValidationOption{ + "DisableSchemaFormatValidation": openapi3.DisableSchemaFormatValidation(), + "DisableSchemaPatternValidation": openapi3.DisableSchemaPatternValidation(), + "DisableSchemaDefaultsValidation": openapi3.DisableSchemaDefaultsValidation(), + "DisableExamplesValidation": openapi3.DisableExamplesValidation(), + "AllowExtensionsWithRef": openapi3.AllowExtensionsWithRef(), + "AllowExtraSiblingFields": openapi3.AllowExtraSiblingFields("description", "summary", "type"), + } + + f.Fuzz(func(t *testing.T, data []byte) { + if len(data) > maxFuzzInput { + t.Skip() + } + doc, err := newFuzzLoader().LoadFromData(data) + if err != nil { + return + } + + strict := doc.Validate(t.Context()) + multi := doc.Validate(t.Context(), openapi3.EnableMultiError()) + require.Equal(t, strict == nil, multi == nil, "first: %v\nall: %v", strict, multi) + if strict != nil { + return + } + for name, option := range relaxed { + require.NoError(t, doc.Validate(t.Context(), option), name) + } + }) +} From fafe475fa9ecabad5d599a95108f9b9fc28259b9 Mon Sep 17 00:00:00 2001 From: Pierre Fenoll Date: Sat, 31 Oct 2026 21:06:53 +0100 Subject: [PATCH 50/78] openapi3: add FuzzInternalizeRefsCustomResolver Whatever names a resolver returns, colliding, empty or invalid ones included, InternalizeRefs does not panic and leaves only local refs. Signed-off-by: Pierre Fenoll Co-Authored-By: Claude Opus 5.5 --- .github/workflows/fuzz.yml | 1 + openapi3/internalize_refs_fuzz_test.go | 37 ++++++++++++++++++++++++++ 2 files changed, 38 insertions(+) diff --git a/.github/workflows/fuzz.yml b/.github/workflows/fuzz.yml index fc3991a8a..0dffb3c76 100644 --- a/.github/workflows/fuzz.yml +++ b/.github/workflows/fuzz.yml @@ -41,6 +41,7 @@ jobs: - {package: ./openapi3, target: FuzzInternalizeRefs} - {package: ./openapi3, target: FuzzInternalizeRefsKeepsMeaning} - {package: ./openapi3, target: FuzzValidateOptions} + - {package: ./openapi3, target: FuzzInternalizeRefsCustomResolver} - {package: ./openapi2, target: FuzzUnmarshalFromData} - {package: ./internal/nodeindex, target: FuzzNew} - {package: ./openapi2conv, target: FuzzToV3} diff --git a/openapi3/internalize_refs_fuzz_test.go b/openapi3/internalize_refs_fuzz_test.go index 4e09799c8..a73626327 100644 --- a/openapi3/internalize_refs_fuzz_test.go +++ b/openapi3/internalize_refs_fuzz_test.go @@ -223,3 +223,40 @@ func FuzzInternalizeRefsKeepsMeaning(f *testing.F) { } }) } + +// Whatever names a resolver hands out, colliding, empty or invalid ones +// included, internalizing does not panic and leaves only local refs behind. +func FuzzInternalizeRefsCustomResolver(f *testing.F) { + for _, pair := range internalizeSeeds { + root, err := os.ReadFile(pair[0]) + require.NoError(f, err) + other, err := os.ReadFile(pair[1]) + require.NoError(f, err) + f.Add(root, other, "a,a,b,,#/x,~1") + } + + f.Fuzz(func(t *testing.T, root, other []byte, names string) { + if len(root)+len(other)+len(names) > maxFuzzInput { + t.Skip() + } + doc, err := newTwoDocLoader(root, other).LoadFromDataWithPath(root, fuzzRootURL) + if err != nil { + return + } + given := strings.Split(names, ",") + calls := 0 + doc.InternalizeRefs(t.Context(), func(*openapi3.T, openapi3.ComponentRef) string { + name := given[calls%len(given)] + calls++ + return name + }) + forEachRef(doc, func(site refSite) { + if site.Mapping && !strings.Contains(site.Ref, "/") || site.Unfollowed { + return + } + require.True(t, site.Ref == "" || strings.HasPrefix(site.Ref, "#"), "external ref left: %q", site.Ref) + }) + _, err = doc.MarshalJSON() + require.NoError(t, err) + }) +} From 48e3ec408325a101b057d4fa79fd5330171a9416 Mon Sep 17 00:00:00 2001 From: Pierre Fenoll Date: Sun, 1 Nov 2026 00:23:12 +0100 Subject: [PATCH 51/78] openapi3: write a nil dependentRequired list as null in YAML too A dependentRequired entry with no list of names is written null as JSON but "[]" as YAML, so a document does not load back the same from its YAML. Write null both ways, as SecurityRequirement now does. Found by FuzzMarshalYAML. Signed-off-by: Pierre Fenoll Co-Authored-By: Claude Opus 5.5 --- openapi3/schema.go | 12 +++++++++++- .../testdata/fuzz/FuzzMarshalYAML/44d4c659af5084cf | 2 ++ .../fuzz/FuzzMarshalYAML/null-security-requirement | 2 ++ 3 files changed, 15 insertions(+), 1 deletion(-) create mode 100644 openapi3/testdata/fuzz/FuzzMarshalYAML/44d4c659af5084cf create mode 100644 openapi3/testdata/fuzz/FuzzMarshalYAML/null-security-requirement diff --git a/openapi3/schema.go b/openapi3/schema.go index bc12c53b7..938d667cb 100644 --- a/openapi3/schema.go +++ b/openapi3/schema.go @@ -729,7 +729,17 @@ func (schema Schema) MarshalYAML() (any, error) { m["else"] = x } if x := schema.DependentRequired; len(x) != 0 { - m["dependentRequired"] = x + // A nil list of names is written null, as JSON writes it, rather + // than the "[]" YAML would make of it. + dr := make(map[string]any, len(x)) + for name, names := range x { + if names == nil { + dr[name] = nil + } else { + dr[name] = names + } + } + m["dependentRequired"] = dr } if x := schema.Defs; len(x) != 0 { m["$defs"] = x diff --git a/openapi3/testdata/fuzz/FuzzMarshalYAML/44d4c659af5084cf b/openapi3/testdata/fuzz/FuzzMarshalYAML/44d4c659af5084cf new file mode 100644 index 000000000..72ee018c4 --- /dev/null +++ b/openapi3/testdata/fuzz/FuzzMarshalYAML/44d4c659af5084cf @@ -0,0 +1,2 @@ +go test fuzz v1 +[]byte("components:\n schemas:\n 0: \n dependentRequired:\n 0:") diff --git a/openapi3/testdata/fuzz/FuzzMarshalYAML/null-security-requirement b/openapi3/testdata/fuzz/FuzzMarshalYAML/null-security-requirement new file mode 100644 index 000000000..0e489d8fd --- /dev/null +++ b/openapi3/testdata/fuzz/FuzzMarshalYAML/null-security-requirement @@ -0,0 +1,2 @@ +go test fuzz v1 +[]byte("openapi: 3.0.0\ninfo: {title: t, version: \"1\"}\npaths:\n /:\n get:\n responses: {\"200\": {description: d}}\n security: [null]\nsecurity: [null]\n") From 5a0cd1e4e73e2ceec0aafba5529197517d423563 Mon Sep 17 00:00:00 2001 From: Pierre Fenoll Date: Sat, 31 Oct 2026 21:06:53 +0100 Subject: [PATCH 52/78] openapi3: add FuzzMarshalYAML A document written as YAML by its own MarshalYAML loads back to itself. Signed-off-by: Pierre Fenoll Co-Authored-By: Claude Opus 5.5 --- .github/workflows/fuzz.yml | 1 + openapi3/fuzz_test.go | 31 +++++++++++++++++++ .../fuzz/FuzzMarshalYAML/025f382fc8664983 | 2 ++ .../fuzz/FuzzMarshalYAML/726e0d247bb78c19 | 2 ++ .../fuzz/FuzzMarshalYAML/ad3fea4f960da6cb | 2 ++ 5 files changed, 38 insertions(+) create mode 100644 openapi3/testdata/fuzz/FuzzMarshalYAML/025f382fc8664983 create mode 100644 openapi3/testdata/fuzz/FuzzMarshalYAML/726e0d247bb78c19 create mode 100644 openapi3/testdata/fuzz/FuzzMarshalYAML/ad3fea4f960da6cb diff --git a/.github/workflows/fuzz.yml b/.github/workflows/fuzz.yml index 0dffb3c76..ab887878f 100644 --- a/.github/workflows/fuzz.yml +++ b/.github/workflows/fuzz.yml @@ -42,6 +42,7 @@ jobs: - {package: ./openapi3, target: FuzzInternalizeRefsKeepsMeaning} - {package: ./openapi3, target: FuzzValidateOptions} - {package: ./openapi3, target: FuzzInternalizeRefsCustomResolver} + - {package: ./openapi3, target: FuzzMarshalYAML} - {package: ./openapi2, target: FuzzUnmarshalFromData} - {package: ./internal/nodeindex, target: FuzzNew} - {package: ./openapi2conv, target: FuzzToV3} diff --git a/openapi3/fuzz_test.go b/openapi3/fuzz_test.go index c87c875c7..447ef3ce4 100644 --- a/openapi3/fuzz_test.go +++ b/openapi3/fuzz_test.go @@ -8,6 +8,7 @@ import ( "testing" "github.com/stretchr/testify/require" + yaml "go.yaml.in/yaml/v3" "github.com/getkin/kin-openapi/internal/fuzzing" "github.com/getkin/kin-openapi/openapi3" @@ -215,3 +216,33 @@ func FuzzSchemaVisitJSON(f *testing.F) { _ = schema.VisitJSON(value, openapi3.EnableJSONSchema2020()) }) } + +// A document written out as YAML by its own MarshalYAML loads back to itself. +func FuzzMarshalYAML(f *testing.F) { + seedFromTestdata(f) + + f.Fuzz(func(t *testing.T, data []byte) { + if len(data) > maxFuzzInput { + t.Skip() + } + doc, err := newFuzzLoader().LoadFromData(data) + if err != nil { + return + } + j, err := doc.MarshalJSON() + require.NoError(t, err) + var generic any + require.NoError(t, json.Unmarshal(j, &generic)) + if fuzzing.LosesInYAML(generic) { + return + } + + y, err := yaml.Marshal(doc) + require.NoError(t, err) + back, err := newFuzzLoader().LoadFromData(y) + require.NoError(t, err, "yaml:\n%s", y) + j2, err := back.MarshalJSON() + require.NoError(t, err) + require.JSONEq(t, string(j), string(j2), "yaml:\n%s", y) + }) +} diff --git a/openapi3/testdata/fuzz/FuzzMarshalYAML/025f382fc8664983 b/openapi3/testdata/fuzz/FuzzMarshalYAML/025f382fc8664983 new file mode 100644 index 000000000..d03b234fb --- /dev/null +++ b/openapi3/testdata/fuzz/FuzzMarshalYAML/025f382fc8664983 @@ -0,0 +1,2 @@ +go test fuzz v1 +[]byte("openapi: 3.0.0\ninfo:\n title: Security Requirement Example\n version: 1.0.0\npaths:\n /subscribe:\n post:\n requestBody:\n content:\n application/json:\n schema:\n type: object\n properties:\n inProgressUrl:\n type: string\n failedUrl:\n type: string\n successUrl:\n type: string\n responses:\n \"200\":\n description: OK\n security:\n - petstore_auth:\n - write:pets\n - read:pets\ncomponents:\n securitySchemes:\n petstore_auth:\n type: oauth2\n flows:\n implicit:\n authorizationUrl: http://example.org/api/oauth/dialog\n scope{:\n write:pets: modify pets in your account\n read:pets: read your pets") diff --git a/openapi3/testdata/fuzz/FuzzMarshalYAML/726e0d247bb78c19 b/openapi3/testdata/fuzz/FuzzMarshalYAML/726e0d247bb78c19 new file mode 100644 index 000000000..d58dbf563 --- /dev/null +++ b/openapi3/testdata/fuzz/FuzzMarshalYAML/726e0d247bb78c19 @@ -0,0 +1,2 @@ +go test fuzz v1 +[]byte("openapi: 3.0.0\ninfo:\n title: Security Requirement Example\n version: 1.0.0\npaths:\n /subscribe:\n post:\n requestBody:\n content:\n application/json:\n schema:\n type: object\n properties:\n inProgressUrl:\n type: string\n failedUrl:\n type: string\n successUrl:\n type: string\n responses:\n \"200\":\n description: OK\n security:\n - petstore_auth:\n - write:pets\n 99999999999999999999999999999999tySchemes:\n petstore_auth:\n type: oauth2\n flows:\n implicit:\n authorizationUrl: http://example.org/api/oauth/dialog\n scope{:\n write:pets: modify pets in your account\n read:pets: read your pets") diff --git a/openapi3/testdata/fuzz/FuzzMarshalYAML/ad3fea4f960da6cb b/openapi3/testdata/fuzz/FuzzMarshalYAML/ad3fea4f960da6cb new file mode 100644 index 000000000..3bd2a6901 --- /dev/null +++ b/openapi3/testdata/fuzz/FuzzMarshalYAML/ad3fea4f960da6cb @@ -0,0 +1,2 @@ +go test fuzz v1 +[]byte("openapi: 3.0.0\nservers:\n - url: https://rest-api.d7networks.com/secure\ninfo:\n contact:\n email: int@d7networks.com\n name: Emanuel\n url: https://d7networks.com/\n x-twitter: d7sms\n description: D7 SMS allows you to reach your customers via SMS over D7's own connectivity to global mobile networks. D7 provides reliable and cost-effective SMS services to businesses across all industries and aims to connect all countries and territories via direct connections.\n title: D7SMS\n version: 1.0.2\n x-apisguru-categories:\n - messaging\n x-logo:\n url: https://twitter.com/d7sms/profile_image?size=original\n x-origin:\n - format: openapi\n url: https://api.swaggerhub.com/apis/Direct7Networks/D7SMS/1.0.2\n version: \"3.0\"\n x-providerName: d7networks.com\nsecurity:\n - auth: []\ntags: []\npaths:\n /balance:\n get:\n deprecated: false\n description: Check account balance\n operationId: BalanceGet\n responses:\n \"200\":\n description: \"\"\n headers: {}\n \"500\":\n content:\n application/json:\n schema: {}\n description: Internal Server Error\n summary: Balance\n /send:\n post:\n deprecated: false\n description: Send SMS to recipients using D7 SMS Gateway\n operationId: SendPost\n parameters:\n - description: \"\"\n in: header\n name: Content-Type\n required: true\n schema:\n type: string\n - description: \"\"\n in: header\n name: Accept\n required: true\n schema:\n type: string\n requestBody:\n conte application/json:\n schema:\n $ref: \"#/components/schemas/SendSMSRequest\"\n description: Message Body\n required: true\n responses:\n \"200\":\n description: \"\"\n headers: {}\n \"500\":\n content:\n application/json:\n schema: {}\n description: Internal Server Error\n summary: SendSMS\n /sendbatch:\n post:\n deprecated: false\n description: Send Bulk SMS to multiple recipients using D7 SMS Gateway\n operationId: SendbatchPost\n parameters:\n - description: \"\"\n in: header\n name: Content-Type\n required: true\n schema:\n type: string\n - description: \"\"\n in: header\n name: Accept\n required: true\n schema:\n type: string\n requestBody:\n content:\n application/json:\n schema:\n $ref: \"#/components/schemas/BulkSMSRequest\"\n description: Message Body\n required: true\n responses:\n \"200\":\n description: \"\"\n headers: {}\n summary: Bulk SMS\ncomponents:\n schemas:\n BulkSMSRequest:\n description: Bulk SMS Request\n example:\n messages:\n - content: Same content goes to three numbers\n from: SignSMS\n to:\n - \"971562316353\"\n - \"971562316354\"\n - \"971562316355\"\n properties:\n messages:\n description: Sendbatch message body\n items:\n $ref: \"#/components/schemas/Message\"\n type: array\n required:\n - messages\n title: BulkSMSRequest\n type: object\n Message:\n description: \"\"\n example:\n content: Same content goes to three numbers\n from: SignSMS\n to:\n - \"971562316353\"\n - \"971562316354\"\n - \"971562316355\"\n properties:\n content:\n type: string\n from:\n type: string\n to:\n description: Destination Number\n items:\n type: string\n type: array\n required:\n - to\n - content\n - from\n title: Message\n type: object\n SendSMSRequest:\n description: Send SMS Request\n example:\n content: Send single SMS Testing\n from: SignSMS\n to: 971562316353\n properties:\n content:\n description: Message Content\n type: string\n from:\n description: Sender ID / Number\n type: string\n to:\n description: Destination Mobile Number\n format: int64\n type: integer\n required:\n - to\n - from\n - content\n title: SendSMSRequest\n type: object\n securitySchemes:\n auth:\n scheme: basic\n type: http\n") From d43935b25f4ade0e024299e77293987e8cae234a Mon Sep 17 00:00:00 2001 From: Pierre Fenoll Date: Sat, 31 Oct 2026 21:06:53 +0100 Subject: [PATCH 53/78] openapi3filter: add FuzzValidateResponse Validating a response never panics, reaches the same verdict every time, and turning checks off never rejects a response the full checks accept. Signed-off-by: Pierre Fenoll Co-Authored-By: Claude Opus 5.5 --- .github/workflows/fuzz.yml | 1 + openapi3filter/response_fuzz_test.go | 122 +++++++++++++++++++++++++++ 2 files changed, 123 insertions(+) create mode 100644 openapi3filter/response_fuzz_test.go diff --git a/.github/workflows/fuzz.yml b/.github/workflows/fuzz.yml index ab887878f..bb7133529 100644 --- a/.github/workflows/fuzz.yml +++ b/.github/workflows/fuzz.yml @@ -47,6 +47,7 @@ jobs: - {package: ./internal/nodeindex, target: FuzzNew} - {package: ./openapi2conv, target: FuzzToV3} - {package: ./openapi3filter, target: FuzzValidateRequest} + - {package: ./openapi3filter, target: FuzzValidateResponse} steps: - uses: actions/setup-go@v6 diff --git a/openapi3filter/response_fuzz_test.go b/openapi3filter/response_fuzz_test.go new file mode 100644 index 000000000..d3c28d051 --- /dev/null +++ b/openapi3filter/response_fuzz_test.go @@ -0,0 +1,122 @@ +package openapi3filter_test + +import ( + "bytes" + "net/http" + "testing" + + "github.com/stretchr/testify/require" + + "github.com/getkin/kin-openapi/internal/fuzzing" + "github.com/getkin/kin-openapi/openapi3filter" + "github.com/getkin/kin-openapi/routers/gorillamux" +) + +// Validating a response never panics and reaches the same verdict every +// time, and turning checks off never rejects a response the full checks +// accept. +func FuzzValidateResponse(f *testing.F) { + seeds := fuzzing.Testdata(f, "../openapi3/testdata", "testdata") + for _, seed := range seeds { + f.Add(seed, "GET", "/", 200, "application/json", []byte(`{}`)) + } + + const spec = ` +openapi: 3.0.0 +info: {title: t, version: "1"} +paths: + /items/{id}: + get: + parameters: + - {name: id, in: path, required: true, schema: {type: integer}} + responses: + "200": + description: ok + headers: + X-Rate: {required: true, schema: {type: integer, minimum: 0}} + X-Tags: {schema: {type: array, items: {type: string}}, style: simple} + content: + application/json: + schema: + type: object + required: [n] + properties: + n: {type: number, readOnly: true} + w: {type: string, writeOnly: true} + d: {type: string, format: date-time} + text/plain: {schema: {type: string, maxLength: 3}} + application/x-www-form-urlencoded: {schema: {type: object, properties: {a: {type: string}}}} + 4XX: + description: client error + content: + application/problem+json: {schema: {type: object, properties: {title: {type: string}}}} + default: + description: other +` + f.Add([]byte(spec), "GET", "/items/1", 200, "application/json", []byte(`{"n":1,"d":"2020-01-01T00:00:00Z"}`)) + f.Add([]byte(spec), "GET", "/items/1", 200, "application/json", []byte(`{"w":"x"}`)) + f.Add([]byte(spec), "GET", "/items/1", 200, "text/plain; charset=utf-8", []byte(`abcd`)) + f.Add([]byte(spec), "GET", "/items/1", 200, "application/x-www-form-urlencoded", []byte(`a=b&a=c`)) + f.Add([]byte(spec), "GET", "/items/1", 404, "application/problem+json", []byte(`{"title":1}`)) + f.Add([]byte(spec), "GET", "/items/1", 503, "", []byte(``)) + + f.Fuzz(func(t *testing.T, data []byte, method, target string, status int, contentType string, body []byte) { + if len(data) > maxFuzzInput || len(body) > maxFuzzInput { + t.Skip() + } + if len(method) > 64 || len(target) > 4<<10 || len(contentType) > 1<<10 { + t.Skip() + } + + doc, err := newFuzzLoader().LoadFromData(data) + if err != nil { + t.Skip() + } + if err = doc.Validate(t.Context()); err != nil { + t.Skip() + } + router, err := gorillamux.NewRouter(doc) + if err != nil { + return + } + req, err := http.NewRequest(method, target, nil) + if err != nil { + t.Skip() + } + route, pathParams, err := router.FindRoute(req) + if err != nil { + return + } + + validate := func(options openapi3filter.Options) error { + options.MultiError = true + options.AuthenticationFunc = openapi3filter.NoopAuthenticationFunc + input := &openapi3filter.ResponseValidationInput{ + RequestValidationInput: &openapi3filter.RequestValidationInput{ + Request: req, + PathParams: pathParams, + Route: route, + }, + Status: status, + Header: http.Header{"Content-Type": {contentType}, "X-Rate": {"1"}}, + Options: &options, + } + input.SetBodyBytes(bytes.Clone(body)) + return openapi3filter.ValidateResponse(t.Context(), input) + } + + full := validate(openapi3filter.Options{IncludeResponseStatus: true}) + again := validate(openapi3filter.Options{IncludeResponseStatus: true}) + require.Equal(t, full == nil, again == nil, "first: %v\nagain: %v", full, again) + if full != nil { + return + } + for _, lax := range []openapi3filter.Options{ + {}, + {ExcludeResponseBody: true}, + {ExcludeReadOnlyValidations: true, ExcludeWriteOnlyValidations: true}, + } { + require.NoError(t, validate(lax), "%+v", lax) + } + }) +} From 683e535786d9cc00645403b2eaf77be9c1ccbebb Mon Sep 17 00:00:00 2001 From: Pierre Fenoll Date: Sat, 31 Oct 2026 21:06:53 +0100 Subject: [PATCH 54/78] openapi3filter: add FuzzBodyDecoder The registered body decoders never panic and return only a primitive, []any or map[string]any. Signed-off-by: Pierre Fenoll Co-Authored-By: Claude Opus 5.5 --- .github/workflows/fuzz.yml | 1 + openapi3filter/body_decoder_fuzz_test.go | 83 +++++++++++++++++++ .../fuzz/FuzzBodyDecoder/998275c530f638c7 | 5 ++ .../fuzz/FuzzBodyDecoder/e5ea51e705f070e5 | 5 ++ 4 files changed, 94 insertions(+) create mode 100644 openapi3filter/body_decoder_fuzz_test.go create mode 100644 openapi3filter/testdata/fuzz/FuzzBodyDecoder/998275c530f638c7 create mode 100644 openapi3filter/testdata/fuzz/FuzzBodyDecoder/e5ea51e705f070e5 diff --git a/.github/workflows/fuzz.yml b/.github/workflows/fuzz.yml index bb7133529..8f5f9fbb1 100644 --- a/.github/workflows/fuzz.yml +++ b/.github/workflows/fuzz.yml @@ -48,6 +48,7 @@ jobs: - {package: ./openapi2conv, target: FuzzToV3} - {package: ./openapi3filter, target: FuzzValidateRequest} - {package: ./openapi3filter, target: FuzzValidateResponse} + - {package: ./openapi3filter, target: FuzzBodyDecoder} steps: - uses: actions/setup-go@v6 diff --git a/openapi3filter/body_decoder_fuzz_test.go b/openapi3filter/body_decoder_fuzz_test.go new file mode 100644 index 000000000..f55a21183 --- /dev/null +++ b/openapi3filter/body_decoder_fuzz_test.go @@ -0,0 +1,83 @@ +package openapi3filter_test + +import ( + "bytes" + "encoding/json" + "net/http" + "testing" + + "github.com/stretchr/testify/require" + + "github.com/getkin/kin-openapi/openapi3" + "github.com/getkin/kin-openapi/openapi3filter" +) + +var fuzzedBodyDecoders = []string{ + "application/json", + "application/octet-stream", + "application/x-www-form-urlencoded", + "application/yaml", + "multipart/form-data", + "text/csv", + "text/plain", +} + +// The registered body decoders never panic, and return only what the +// BodyDecoder contract allows: a primitive, []any or map[string]any. +func FuzzBodyDecoder(f *testing.F) { + const object = `{"type":"object","properties":{"a":{"type":"integer"},"b":{"type":"array","items":{"type":"string"}},"o":{"type":"object","properties":{"x":{"type":"boolean"}}},"f":{"type":"string","format":"binary"}}}` + f.Add(uint8(0), "application/json", []byte(`{"a":1,"b":["x"]}`), []byte(object)) + f.Add(uint8(1), "application/octet-stream", []byte("\x00\x01"), []byte(`{"type":"string","format":"binary"}`)) + f.Add(uint8(2), "application/x-www-form-urlencoded", []byte(`a=1&b=x&b=y&o[x]=true`), []byte(object)) + f.Add(uint8(2), "application/x-www-form-urlencoded", []byte(`a=1`), []byte(`{"type":"object","additionalProperties":{"type":"integer"}}`)) + f.Add(uint8(3), "application/yaml", []byte("a: 1\nb: [x]\n"), []byte(object)) + f.Add(uint8(4), "multipart/form-data; boundary=b", []byte("--b\r\nContent-Disposition: form-data; name=\"a\"\r\n\r\n1\r\n--b\r\nContent-Disposition: form-data; name=\"b\"\r\n\r\nx\r\n--b\r\nContent-Disposition: form-data; name=\"o\"\r\nContent-Type: application/json\r\n\r\n{\"x\":true}\r\n--b\r\nContent-Disposition: form-data; name=\"f\"; filename=\"f\"\r\n\r\nraw\r\n--b--\r\n"), []byte(object)) + f.Add(uint8(5), "text/csv", []byte("a,b\n1,2\n"), []byte(`{"type":"string"}`)) + f.Add(uint8(6), "text/plain", []byte("hi"), []byte(`{"type":"string"}`)) + + f.Fuzz(func(t *testing.T, which uint8, contentType string, body, schemaJSON []byte) { + if len(body) > maxFuzzInput || len(schemaJSON) > maxFuzzInput || len(contentType) > 1<<10 { + t.Skip() + } + decoder := openapi3filter.RegisteredBodyDecoder(fuzzedBodyDecoders[int(which)%len(fuzzedBodyDecoders)]) + + var schema *openapi3.SchemaRef + if len(schemaJSON) != 0 { + schema = &openapi3.SchemaRef{} + if err := schema.UnmarshalJSON(schemaJSON); err != nil { + t.Skip() + } + if schema.Ref != "" { + t.Skip() // unresolved + } + } + encFn := func(string) *openapi3.Encoding { return nil } + + value, err := decoder(bytes.NewReader(body), http.Header{"Content-Type": {contentType}}, schema, encFn) + if err != nil { + return + } + requireBodyDecoderValue(t, value) + + if schema != nil && schema.Value != nil { + _ = schema.Value.VisitJSON(value) // no crash + } + }) +} + +func requireBodyDecoderValue(t *testing.T, value any) { + t.Helper() + switch v := value.(type) { + case nil, bool, string, json.Number, float64, int64, int, uint64, float32, int32: + case []any: + for _, e := range v { + requireBodyDecoderValue(t, e) + } + case map[string]any: + for _, e := range v { + requireBodyDecoderValue(t, e) + } + default: + require.Failf(t, "not a primitive, []any nor map[string]any", "%T: %#v", value, value) + } +} diff --git a/openapi3filter/testdata/fuzz/FuzzBodyDecoder/998275c530f638c7 b/openapi3filter/testdata/fuzz/FuzzBodyDecoder/998275c530f638c7 new file mode 100644 index 000000000..f60d0441d --- /dev/null +++ b/openapi3filter/testdata/fuzz/FuzzBodyDecoder/998275c530f638c7 @@ -0,0 +1,5 @@ +go test fuzz v1 +byte('\x02') +string("applicatiw-formon/x-www-form-urlencoded") +[]byte("a=1") +[]byte("") diff --git a/openapi3filter/testdata/fuzz/FuzzBodyDecoder/e5ea51e705f070e5 b/openapi3filter/testdata/fuzz/FuzzBodyDecoder/e5ea51e705f070e5 new file mode 100644 index 000000000..20882a44e --- /dev/null +++ b/openapi3filter/testdata/fuzz/FuzzBodyDecoder/e5ea51e705f070e5 @@ -0,0 +1,5 @@ +go test fuzz v1 +byte('¹') +string("0") +[]byte("?") +[]byte("") From 99d5439edd6b65bc104051cfc45a171c2777db49 Mon Sep 17 00:00:00 2001 From: Pierre Fenoll Date: Sat, 31 Oct 2026 21:06:53 +0100 Subject: [PATCH 55/78] routers: add FuzzRoutersAgree Neither router panics, and when both match a request they agree on the route and on its path parameters, compared decoded: gorillamux leaves every value escaped, legacy only "%2F". Signed-off-by: Pierre Fenoll Co-Authored-By: Claude Opus 5.5 --- .github/workflows/fuzz.yml | 1 + routers/fuzz_test.go | 88 +++++++++++++++++++ .../fuzz/FuzzRoutersAgree/fa85e7cd2f151617 | 4 + 3 files changed, 93 insertions(+) create mode 100644 routers/fuzz_test.go create mode 100644 routers/testdata/fuzz/FuzzRoutersAgree/fa85e7cd2f151617 diff --git a/.github/workflows/fuzz.yml b/.github/workflows/fuzz.yml index 8f5f9fbb1..d29bb88e0 100644 --- a/.github/workflows/fuzz.yml +++ b/.github/workflows/fuzz.yml @@ -49,6 +49,7 @@ jobs: - {package: ./openapi3filter, target: FuzzValidateRequest} - {package: ./openapi3filter, target: FuzzValidateResponse} - {package: ./openapi3filter, target: FuzzBodyDecoder} + - {package: ./routers, target: FuzzRoutersAgree} steps: - uses: actions/setup-go@v6 diff --git a/routers/fuzz_test.go b/routers/fuzz_test.go new file mode 100644 index 000000000..f4762a90b --- /dev/null +++ b/routers/fuzz_test.go @@ -0,0 +1,88 @@ +package routers_test + +import ( + "net/http" + "net/url" + "testing" + + "github.com/stretchr/testify/require" + + "github.com/getkin/kin-openapi/internal/fuzzing" + "github.com/getkin/kin-openapi/openapi3" + "github.com/getkin/kin-openapi/routers/gorillamux" + "github.com/getkin/kin-openapi/routers/legacy" +) + +// maxFuzzInput bounds fuzzer inputs so the fuzzer spends its budget on +// routing rather than on allocating huge documents. +const maxFuzzInput = 32 << 10 + +// Neither router panics, and when both find a route for a request they agree +// on which one it is and on the values of its path parameters. +func FuzzRoutersAgree(f *testing.F) { + for _, seed := range fuzzing.Testdata(f, "../openapi3/testdata") { + f.Add(seed, "GET", "/") + } + const spec = ` +openapi: 3.0.0 +info: {title: t, version: "1"} +servers: +- url: http://example.com/api/{v} + variables: {v: {default: v1, enum: [v1, v2]}} +- url: / +paths: + /items: {get: {responses: {"200": {description: ok}}}} + /items/{id}: {get: {parameters: [{name: id, in: path, required: true, schema: {type: string}}], responses: {"200": {description: ok}}}} + /items/{id}/tags/{tag}: {delete: {parameters: [{name: id, in: path, required: true, schema: {type: string}}, {name: tag, in: path, required: true, schema: {type: string}}], responses: {"200": {description: ok}}}} + /files/{name}.{ext}: {get: {parameters: [{name: name, in: path, required: true, schema: {type: string}}, {name: ext, in: path, required: true, schema: {type: string}}], responses: {"200": {description: ok}}}} +` + f.Add([]byte(spec), "GET", "http://example.com/api/v1/items/42") + f.Add([]byte(spec), "GET", "http://example.com/api/v3/items") + f.Add([]byte(spec), "DELETE", "/items/a%2Fb/tags/x") + f.Add([]byte(spec), "GET", "/files/report.tar.gz") + f.Add([]byte(spec), "GET", "/items/") + + f.Fuzz(func(t *testing.T, data []byte, method, target string) { + if len(data) > maxFuzzInput || len(method) > 64 || len(target) > 4<<10 { + t.Skip() + } + + loader := openapi3.NewLoader() + loader.IsExternalRefsAllowed = true + loader.ReadFromURIFunc = func(*openapi3.Loader, *url.URL) ([]byte, error) { return []byte(`{}`), nil } + doc, err := loader.LoadFromData(data) + if err != nil { + t.Skip() + } + if err := doc.Validate(t.Context()); err != nil { + t.Skip() + } + req, err := http.NewRequest(method, target, nil) + if err != nil { + t.Skip() + } + + mux, muxErr := gorillamux.NewRouter(doc) + leg, legErr := legacy.NewRouter(doc) + if muxErr != nil || legErr != nil { + return + } + + muxRoute, muxParams, muxErr := mux.FindRoute(req) + legRoute, legParams, legErr := leg.FindRoute(req) + if muxErr != nil || legErr != nil { + return + } + require.Equal(t, muxRoute.Method, legRoute.Method) + require.Equal(t, muxRoute.Path, legRoute.Path, "target: %s", target) + for name, value := range legParams { + // gorillamux leaves every value escaped, legacy only "%2F": compare + // them decoded. + muxValue, err := url.PathUnescape(muxParams[name]) + require.NoError(t, err) + legValue, err := url.PathUnescape(value) + require.NoError(t, err) + require.Equal(t, legValue, muxValue, "parameter %q of %s for %s", name, muxRoute.Path, target) + } + }) +} diff --git a/routers/testdata/fuzz/FuzzRoutersAgree/fa85e7cd2f151617 b/routers/testdata/fuzz/FuzzRoutersAgree/fa85e7cd2f151617 new file mode 100644 index 000000000..921d5dd61 --- /dev/null +++ b/routers/testdata/fuzz/FuzzRoutersAgree/fa85e7cd2f151617 @@ -0,0 +1,4 @@ +go test fuzz v1 +[]byte("{\"info\":{\"title\":A,\"version\":0A},\"openapi\":0A,\"paths\":{\"/{external1}\":{\"get\":{\"responses\":{0: {\"description\":A}}},\"parameters\":[{\"in\":\"path\",\"name\":\"external1\",\"required\":true,\"schema\":{}}]}}}") +string("") +string("/ ") From d8955bb2614c2a50a911d2a58c5f3b33b2b62931 Mon Sep 17 00:00:00 2001 From: Pierre Fenoll Date: Sat, 31 Oct 2026 21:16:04 +0100 Subject: [PATCH 56/78] openapi3: nit Signed-off-by: Pierre Fenoll --- openapi3/native_yaml.go | 2 +- openapi3/native_yaml_normalization_test.go | 11 +++++------ 2 files changed, 6 insertions(+), 7 deletions(-) diff --git a/openapi3/native_yaml.go b/openapi3/native_yaml.go index 7a96fa82c..d7e10e0a0 100644 --- a/openapi3/native_yaml.go +++ b/openapi3/native_yaml.go @@ -485,7 +485,7 @@ func stringList(node *yaml.Node, key string) ([]string, bool, error) { return nil, false, nil } - list := make([]string, len(node.Content)) + list := make([]string /*,*/, len(node.Content)) for i, e := range node.Content { if e.Kind == yaml.AliasNode { e = e.Alias diff --git a/openapi3/native_yaml_normalization_test.go b/openapi3/native_yaml_normalization_test.go index e125299a1..2a4ad0901 100644 --- a/openapi3/native_yaml_normalization_test.go +++ b/openapi3/native_yaml_normalization_test.go @@ -277,14 +277,13 @@ func requireRecorded(t *testing.T, extra []string, name string) { func requireValidateFails(t *testing.T, doc *T, name string) { t.Helper() - err := doc.Validate(context.Background()) - if err == nil { - t.Errorf("undeclared sibling %q was accepted", name) + if err := doc.Validate(context.Background()); err != nil { + if want := fmt.Sprintf("[%s]", name); !strings.Contains(err.Error(), want) { + t.Errorf("validate reported %v, want it to name %s", err, want) + } return } - if want := fmt.Sprintf("[%s]", name); !strings.Contains(err.Error(), want) { - t.Errorf("validate reported %v, want it to name %s", err, want) - } + t.Errorf("undeclared sibling %q was accepted", name) } func requireFloat(t *testing.T, v any) { From 76af2069488aae061b03d5b0e0c42cd18ec70393 Mon Sep 17 00:00:00 2001 From: Pierre Fenoll Date: Sun, 1 Nov 2026 01:30:31 +0100 Subject: [PATCH 57/78] ci: check out before setup-go so its cache works setup-go keys its module and build cache on go.sum. Run before the checkout it found none, warned "Dependencies file is not found" and cached nothing, so every job downloaded every module again. Also move actions/cache from v3, which actionlint reports as too old to run, to v4. Signed-off-by: Pierre Fenoll Co-Authored-By: Claude Opus 5.5 --- .github/workflows/fuzz.yml | 8 +++++--- .github/workflows/go.yml | 8 +++++--- 2 files changed, 10 insertions(+), 6 deletions(-) diff --git a/.github/workflows/fuzz.yml b/.github/workflows/fuzz.yml index d29bb88e0..d26deeb21 100644 --- a/.github/workflows/fuzz.yml +++ b/.github/workflows/fuzz.yml @@ -52,12 +52,14 @@ jobs: - {package: ./routers, target: FuzzRoutersAgree} steps: + # Checked out first: setup-go keys its module and build cache on go.sum, + # and without one it caches nothing. + - uses: actions/checkout@v6 + - uses: actions/setup-go@v6 with: go-version: stable - - uses: actions/checkout@v6 - # The APIs-guru corpus seeds the fuzzers alongside testdata. The go # workflow caches it, so fetch it only when that cache is missing. - name: APIs-guru corpus cache @@ -81,7 +83,7 @@ jobs: # carries the run id so each run writes a fresh entry, and restore-keys # falls back to the most recent one for this target. - name: Fuzzing corpus cache - uses: actions/cache@v3 + uses: actions/cache@v4 with: path: ~/.cache/go-build/fuzz key: fuzz-${{ matrix.target }}-${{ github.run_id }} diff --git a/.github/workflows/go.yml b/.github/workflows/go.yml index 4ffba3e7a..bb01caff0 100644 --- a/.github/workflows/go.yml +++ b/.github/workflows/go.yml @@ -25,6 +25,10 @@ jobs: name: ${{ matrix.go }} on ${{ matrix.os }} steps: + # Checked out first: setup-go keys its module and build cache on go.sum, + # and without one it caches nothing. + - uses: actions/checkout@v6 + - uses: actions/setup-go@v6 with: go-version: ${{ matrix.go }} @@ -32,10 +36,8 @@ jobs: - if: runner.os == 'Linux' run: sudo apt install silversearcher-ag - - uses: actions/checkout@v6 - - name: Test suite fixtures cache - uses: actions/cache@v3 + uses: actions/cache@v4 with: path: | openapi2/testdata/APIs-guru-openapi-directory-* From 2fe77d6bb1fb85750855626d1b6208974776afd3 Mon Sep 17 00:00:00 2001 From: CH <340279802+connabyss@users.noreply.github.com> Date: Sun, 1 Nov 2026 03:25:47 -0500 Subject: [PATCH 58/78] openapi3filter: test deepObject array index limits (#1412) Co-authored-by: connabyss --- openapi3filter/req_resp_decoder_test.go | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/openapi3filter/req_resp_decoder_test.go b/openapi3filter/req_resp_decoder_test.go index 26eac74a9..96898a784 100644 --- a/openapi3filter/req_resp_decoder_test.go +++ b/openapi3filter/req_resp_decoder_test.go @@ -1056,6 +1056,27 @@ func TestDecodeParameter(t *testing.T) { want: map[string]any{"items": []any{int64(123), int64(456)}}, found: true, }, + { + name: "deepObject explode array - negative index", + param: &openapi3.Parameter{Name: "param", In: "query", Style: "deepObject", Explode: explode, Schema: objectOf("items", integerArraySchema)}, + query: "param[items][-1]=123", + found: true, + err: &ParseError{path: []any{"items"}, Kind: KindInvalidFormat, Reason: "could not convert value map to array: array indexes must not be negative: -1"}, + }, + { + name: "deepObject explode array - sparse index within limit", + param: &openapi3.Parameter{Name: "param", In: "query", Style: "deepObject", Explode: explode, Schema: objectOf("items", integerArraySchema)}, + query: "param[items][2]=123", + want: map[string]any{"items": []any{nil, nil, int64(123)}}, + found: true, + }, + { + name: "deepObject explode array - too sparse index", + param: &openapi3.Parameter{Name: "param", In: "query", Style: "deepObject", Explode: explode, Schema: objectOf("items", integerArraySchema)}, + query: "param[items][99999999]=123", + found: true, + err: &ParseError{path: []any{"items"}, Kind: KindInvalidFormat, Reason: "could not convert value map to array: array index 99999999 is too sparse relative to the 1 supplied items"}, + }, { name: "deepObject explode nested object additionalProperties", param: &openapi3.Parameter{ From b91a6818d29597b2ea6ef376ad6ec7b745e2f17f Mon Sep 17 00:00:00 2001 From: Aryan Gupta Date: Sun, 1 Nov 2026 14:23:17 +0530 Subject: [PATCH 59/78] openapi3: scope whole-file schema fragments to their document (#1413) Signed-off-by: Aryan --- openapi3/loader.go | 6 ++ .../loader_schema_ref_local_fragment_test.go | 80 +++++++++++++++++++ 2 files changed, 86 insertions(+) create mode 100644 openapi3/loader_schema_ref_local_fragment_test.go diff --git a/openapi3/loader.go b/openapi3/loader.go index c705e83e5..e667bfe23 100644 --- a/openapi3/loader.go +++ b/openapi3/loader.go @@ -1156,6 +1156,12 @@ func (loader *Loader) resolveSchemaRef(doc *T, component *SchemaRef, documentPat if documentPath, err = loader.loadSingleElementFromURI(ref, documentPath, &resolved); err != nil { return err } + if strings.HasPrefix(resolved.Ref, "#") { + // Local fragments belong to the referenced file, not the referring document. + if doc, err = loader.loadFromURIInternal(documentPath); err != nil { + return err + } + } // The file holds the Schema itself or a $ref to it, to follow from there. if err := loader.resolveSchemaRef(doc, &resolved, documentPath, visited); err != nil { if err == errMUSTSchema { diff --git a/openapi3/loader_schema_ref_local_fragment_test.go b/openapi3/loader_schema_ref_local_fragment_test.go new file mode 100644 index 000000000..5ed9df1ab --- /dev/null +++ b/openapi3/loader_schema_ref_local_fragment_test.go @@ -0,0 +1,80 @@ +package openapi3 + +import ( + "encoding/json" + "fmt" + "os" + "path/filepath" + "testing" + + "github.com/stretchr/testify/require" +) + +func TestLoaderWholeFileSchemaRefLocalFragment(t *testing.T) { + t.Parallel() + + for _, version := range []string{"3.0.3", "3.1.0"} { + for _, format := range []string{"yaml", "json"} { + for _, fragment := range []string{"", "#"} { + for _, missing := range []bool{false, true} { + t.Run(fmt.Sprintf("%s/%s/alias%s/missing=%t", version, format, fragment, missing), func(t *testing.T) { + t.Parallel() + dir := t.TempDir() + require.NoError(t, os.Mkdir(filepath.Join(dir, "schemas"), 0o700)) + root := fmt.Sprintf(`openapi: %s +info: {title: Local schema reference, version: '1'} +paths: {} +components: + schemas: + Alias: {$ref: './schemas/alias.%s%s'} + Target: {type: integer} +`, version, format, fragment) + name := "Target" + if missing { + name = "Other" + } + alias := fmt.Sprintf(`$ref: '#/components/schemas/Target' +components: + schemas: + %s: {type: string, minLength: 3} +`, name) + if format == "json" { + alias = fmt.Sprintf(`{"$ref":"#/components/schemas/Target","components":{"schemas":{"%s":{"type":"string","minLength":3}}}}`, name) + } + require.NoError(t, os.WriteFile(filepath.Join(dir, "openapi.yaml"), []byte(root), 0o600)) + require.NoError(t, os.WriteFile(filepath.Join(dir, "schemas", "alias."+format), []byte(alias), 0o600)) + + loader := NewLoader() + loader.IsExternalRefsAllowed = true + loader.IncludeOrigin = true + doc, err := loader.LoadFromFile(filepath.Join(dir, "openapi.yaml")) + if missing { + require.ErrorContains(t, err, "Target") + return + } + require.NoError(t, err) + require.NoError(t, doc.Validate(loader.Context)) + schema := doc.Components.Schemas["Alias"].Value + require.NotNil(t, schema) + require.NoError(t, schema.VisitJSON("abc")) + require.Error(t, schema.VisitJSON("ab")) + require.Error(t, schema.VisitJSON(42)) + + doc.InternalizeRefs(loader.Context, nil) + data, err := json.Marshal(doc) + require.NoError(t, err) + bundledLoader := NewLoader() + bundled, err := bundledLoader.LoadFromData(data) + require.NoError(t, err) + require.NoError(t, bundled.Validate(bundledLoader.Context)) + schema = bundled.Components.Schemas["Alias"].Value + require.NotNil(t, schema) + require.NoError(t, schema.VisitJSON("abc")) + require.Error(t, schema.VisitJSON("ab")) + require.Error(t, schema.VisitJSON(42)) + }) + } + } + } + } +} From 368af76e5d652c948a7ea7748695c4ae80a9d520 Mon Sep 17 00:00:00 2001 From: Pierre Fenoll Date: Sun, 1 Nov 2026 18:58:17 +0100 Subject: [PATCH 60/78] openapi3: compare FuzzLoadFromData's validation errors by message (#1417) --- openapi3/fuzz_test.go | 8 ++++++-- openapi3/testdata/fuzz/FuzzLoadFromData/736267b7053f3253 | 2 ++ 2 files changed, 8 insertions(+), 2 deletions(-) create mode 100644 openapi3/testdata/fuzz/FuzzLoadFromData/736267b7053f3253 diff --git a/openapi3/fuzz_test.go b/openapi3/fuzz_test.go index 447ef3ce4..14716a6ff 100644 --- a/openapi3/fuzz_test.go +++ b/openapi3/fuzz_test.go @@ -2,6 +2,7 @@ package openapi3_test import ( "encoding/json" + "fmt" "net/url" "reflect" "strings" @@ -73,8 +74,11 @@ func FuzzLoadFromData(f *testing.F) { require.JSONEq(t, string(once), string(twice)) - // Validation should be deterministic - require.Equal(t, valid, reloaded.Validate(t.Context())) + // Validation should be deterministic. The errors are compared by what + // they say: one can carry the schema it is about, and the round trip + // writes an empty map such as properties: {} as absent, which changes + // the value it carries but not what the error says. + require.Equal(t, fmt.Sprint(valid), fmt.Sprint(reloaded.Validate(t.Context()))) }) } diff --git a/openapi3/testdata/fuzz/FuzzLoadFromData/736267b7053f3253 b/openapi3/testdata/fuzz/FuzzLoadFromData/736267b7053f3253 new file mode 100644 index 000000000..70f87f1f9 --- /dev/null +++ b/openapi3/testdata/fuzz/FuzzLoadFromData/736267b7053f3253 @@ -0,0 +1,2 @@ +go test fuzz v1 +[]byte("openapi: 3.0.0\nservers:\n - description: via RapidAPI.com\n url: https://dynamicdocs.p.rapidapi.com\ninfo:\n contact:\n email: info@advicement.io\n name: Igor Rodionov\n url: https://advicement.io/dynamic-documents-api\n x-twitter: Rapid_API\n description: |-\n ADVICEment's [DynamicDocs API automates your document generation](https://advicement.io/dynamic-documents-api) and creates dynamic, optimized, interactive PDFs. Write your templates in LaTeX and call the API with JSON data to get your PDFs in seconds.\n\n The template files are stored in your dashboard and can be edited, tested and published online. Document templates can contain dynamic text using logic statements, include tables stretching multiple pages and show great-looking charts based on the underlying data. LaTeX creates crisp, high-quality documents where every detail is well-positioned and styled.\n\n Integrate with ADVICEment DynamicDocs API in minutes and start creating beautiful [dynamic PDF documents](https://advicement.io/dynamic-documents-api) for your needs.\n\n For more information, visit [DynamicDocs API Home page](https://advicement.io/dynamic-documents-api).\n termsOfService: https://advicement.io/terms-of-service\n title: DynamicDocs\n version: \"1.0\"\n x-apisguru-categories:\n - text\n - developer_tools\n x-logo:\n url: https://advicement.io/images/logo/Advicement_DynamicDocs_API.png\n x-origin:\n - format: openapi\n url: https://advicement.io/open_api_spec/dynamicdocs.json\n version: \"3.0\"\n x-providerName: rapidapi.com\n x-serviceName: dynamicdocs\nsecurity:\n - Adv-Security-Token: []\n - X-RapidAPI-Key: []\ntags:\n - name: PDF Generation\npaths:\n \"/templates/{template-token}/compile\":\n parameters:\n - description: The template-token is available in your template settings after publishing your template.\n in: path\n name: template-token\n required: true\n schema:\n example: 7a582350acb835ed\n type: string\n post:\n description: Compile a PDF document from a specific template\n operationId: compile\n parameters:\n - description: Should be set to \"application/json\"\n in: header\n name: Content-Type\n required: true\n schema:\n default: application/json\n example: application/json\n type: string\n - description: The doc-url-expires-in is a numerical parameter which takes integers and describes after how many seconds the provided URL is available to download the document.\n in: query\n name: doc-url-expires-in\n schema:\n example: 3600\n type: integer\n - description: \"The latex-compiler parameter can take the following values: pdflatex lualatex\"\n in: query\n name: latex-compiler\n schema:\n enum:\n - pdflatex\n - lualatex\n type: string\n - description: \"The latex-runs is a numerical parameter and can take values of 1, 2 and 3. \"\n in: query\n name: \"latex-runs \"\n schema:\n maximum: 3\n minimum: 1\n type: integer\n - description: The main-file-name is a string parameter which identifies the main file to compile.\n in: query\n name: main-file-name\n schema:\n example: inputFile.tex\n type: string\n - description: The doc-file-name is a string parameter which determines the name of the file. Note that the extension of the file is not required.\n in: query\n name: doc-file-name\n schema:\n example: brilliantDocument\n type: string\n requestBody:\n content:\n application/json:\n examples:\n Example of dynamic data for the simple report template:\n value:\n amount: ZAR 100 000\n client:\n address: xx Long Street\n company: ABC Company Pty Ltd\n firstName: John\n lastName: Smith\n location: Cape Town, South Africa\n consultant:\n address: xx Rivonia Road\n company: XYZ Company Pty Ltd\n firstName: Kobus\n lastName: van der Merwe\n location: Sandton, South Africa\n effectiveDate: 1 February 2021\n servicesDescription: perform analysis on the company's clients and identify existing market segments\n schema:\n properties: {}\n type: object\n description: Post the dynamic data for the template to compile the document PDF.\n responses:\n \"200\":\n content:\n application/json:\n examples:\n Document Status URL:\n value:\n documentStatusUrlps://advicement-prod-api-calls.s3.eu-west-1.amazonaws.com/testRapid/rapid-simple-contract/cf7cb57b-62ac-499e-afa5-2a2a4abba593/output/progress.json?AWSAccessKeyId=ASIA2LMZZZXSNUODI76L&Expires=1626094954&Signature=cTUlDBYPqJr5iiRjlBpVp%2FzIvtc%3D&x-amz-security-token=IQoJb3JpZ2luX2VjEOz%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaCWV1LXdlc3QtMSJHMEUCIQCZNyie%2B%2BOFdkfZELMvUgYaDi74N0AqRGcY7y30s7p80AIgFFa2obOH74FGOChjM9%2FT7Ggj4P2eGmJ1Ju0yz%2F0fSrgqmQII1f%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FARACGgw3MTE2NzY1MTM3NjQiDHuCNCrlHUNf2eeGtirtAb%2FPdNk%2Ba42RNnmmN8spasfJ9JeaSZ13fmtSYPqBTVJ00Nj0LzBON3IbFfq12zdnEooNk1ovxMH4CDYZq%2B20MwoxN4IhqPGpIbTqqp8zeDck5YqmvotQs%2F7NpwJ3xphfbcCZgjwzdi2ZskYC5k42SFg64skQd66UyQuP8yQr0RGw4JHTYFWkkDvjWyBUiaJHQWGrrbtnjuTnmAwqMx86ltCasdjVC25DXdLR3WSxwhV%2BFlxC%2FXViLBiv%2FbH57zU85ZkEMDwUuVct5mJ8guQrXzmaOu%2F14VMufNHpNwjB8JWi2O6jc1UTDZ3rCHBjqaAbphG9YZfZZKljRDrJIedpodFkIMa25rVmXz4vPrUMH9nkpIq%2BwR9o3z9gVZx4MkPWQul9sOhcktmx%2FLywTqlDWw7F4GHfXw4nIe4B%2BdIjlvCqpR%2BRnTfQlTofenqoRvtbLoMnl4xwKZkeQHrvjGp8eRlasdSOsCJpjUi5LNOcs59qFoiXo51IC%2Fhx%2B7QmDBCIJ3gpnZxkACw%3D\n schema:\n properties: {}\n type: object\n description: Document Status URL Created\n \"401\":\n description: Unauthorized\n summary: Compile New Document PDF\n tags:\n - PDF Generation\ncomponents:\n schemas: {}\n securitySchemes:\n Adv-Security-Token:\n description: The Adv-Security-Token header parameter is generated via the Dashboard on advicement.io website.\n in: header\n name: ADVICEment API Key\n type: apiKey\n X-RapidAPI-Key:\n description: The X-RapidAPI-Key header parameter can be found in the security section of your account on rapidapi.com\n in: header\n name: RapidAPI.com API Key\n type: apiKey\n") From 29427b001b1a9db2d5c967700eeadc686fc3620b Mon Sep 17 00:00:00 2001 From: Pierre Fenoll Date: Sun, 1 Nov 2026 19:12:22 +0100 Subject: [PATCH 61/78] openapi3: internalize refs under the 3.1 subschema keywords (#1418) Co-authored-by: Claude Opus 5.5 --- openapi3/internalize_refs.go | 20 +++++--- openapi3/internalize_refs_subschemas_test.go | 46 +++++++++++++++++++ .../fuzz/FuzzInternalizeRefs/951517de40b6a594 | 3 ++ 3 files changed, 62 insertions(+), 7 deletions(-) create mode 100644 openapi3/internalize_refs_subschemas_test.go create mode 100644 openapi3/testdata/fuzz/FuzzInternalizeRefs/951517de40b6a594 diff --git a/openapi3/internalize_refs.go b/openapi3/internalize_refs.go index 82548f1b9..09fb2873d 100644 --- a/openapi3/internalize_refs.go +++ b/openapi3/internalize_refs.go @@ -351,7 +351,7 @@ func (doc *T) derefSchema(s *Schema, refNameResolver RefNameResolver, parentIsEx return } - for _, list := range []SchemaRefs{s.AllOf, s.AnyOf, s.OneOf} { + for _, list := range []SchemaRefs{s.AllOf, s.AnyOf, s.OneOf, s.PrefixItems} { for _, s2 := range list { isExternal := doc.addSchemaToSpec(s2, refNameResolver, parentIsExternal) if s2 != nil { @@ -379,14 +379,20 @@ func (doc *T) derefSchema(s *Schema, refNameResolver RefNameResolver, parentIsEx } } - for _, name := range componentNames(s.Properties) { - s2 := s.Properties[name] - isExternal := doc.addSchemaToSpec(s2, refNameResolver, parentIsExternal) - if s2 != nil { - doc.derefSchema(s2.Value, refNameResolver, isExternal || parentIsExternal) + for _, schemas := range []Schemas{s.Properties, s.PatternProperties, s.DependentSchemas, s.Defs} { + for _, name := range componentNames(schemas) { + s2 := schemas[name] + isExternal := doc.addSchemaToSpec(s2, refNameResolver, parentIsExternal) + if s2 != nil { + doc.derefSchema(s2.Value, refNameResolver, isExternal || parentIsExternal) + } } } - for _, ref := range []*SchemaRef{s.Not, s.AdditionalProperties.Schema, s.Items} { + for _, ref := range []*SchemaRef{ + s.Not, s.AdditionalProperties.Schema, s.Items, + s.Contains, s.PropertyNames, s.If, s.Then, s.Else, s.ContentSchema, + s.UnevaluatedItems.Schema, s.UnevaluatedProperties.Schema, + } { isExternal := doc.addSchemaToSpec(ref, refNameResolver, parentIsExternal) if ref != nil { doc.derefSchema(ref.Value, refNameResolver, isExternal || parentIsExternal) diff --git a/openapi3/internalize_refs_subschemas_test.go b/openapi3/internalize_refs_subschemas_test.go new file mode 100644 index 000000000..e6ebd02d6 --- /dev/null +++ b/openapi3/internalize_refs_subschemas_test.go @@ -0,0 +1,46 @@ +package openapi3_test + +import ( + "encoding/json" + "testing" + + "github.com/stretchr/testify/require" +) + +// InternalizeRefs reaches an external ref under every keyword that holds a +// subschema, not only the ones 3.0 has. +func TestInternalizeRefsSubschemaKeywords(t *testing.T) { + other := []byte(`{"components":{"schemas":{"Ext":{"type":"string"}}}}`) + const ext = `{"$ref":"ext.json#/components/schemas/Ext"}` + + for keyword, value := range map[string]string{ + "prefixItems": `[` + ext + `]`, + "contains": ext, + "propertyNames": ext, + "if": ext, + "then": ext, + "else": ext, + "contentSchema": ext, + "unevaluatedItems": ext, + "unevaluatedProperties": ext, + "patternProperties": `{"^a":` + ext + `}`, + "dependentSchemas": `{"a":` + ext + `}`, + "$defs": `{"D":` + ext + `}`, + } { + t.Run(keyword, func(t *testing.T) { + root := []byte(`{"openapi":"3.1.0","info":{"title":"t","version":"1"},"paths":{},` + + `"components":{"schemas":{"S":{"` + keyword + `":` + value + `}}}}`) + + loader := newTwoDocLoader(root, other) + doc, err := loader.LoadFromDataWithPath(root, fuzzRootURL) + require.NoError(t, err) + + doc.InternalizeRefs(t.Context(), nil) + + data, err := json.Marshal(doc) + require.NoError(t, err) + require.NotContains(t, string(data), "ext.json") + require.Len(t, doc.Components.Schemas, 2) + }) + } +} diff --git a/openapi3/testdata/fuzz/FuzzInternalizeRefs/951517de40b6a594 b/openapi3/testdata/fuzz/FuzzInternalizeRefs/951517de40b6a594 new file mode 100644 index 000000000..97693f925 --- /dev/null +++ b/openapi3/testdata/fuzz/FuzzInternalizeRefs/951517de40b6a594 @@ -0,0 +1,3 @@ +go test fuzz v1 +[]byte("components:\n schemas:\n 000: \n propertyNames:\n $ref: 0A") +[]byte("0:") From 787f45fd3fa313dcaf5575de4f760e9cd471cc83 Mon Sep 17 00:00:00 2001 From: Reuven Harrison Date: Mon, 2 Nov 2026 10:07:51 +0200 Subject: [PATCH 62/78] openapi3: an extension next to a $ref reaches the schema it resolves to (#1400) Co-authored-by: Claude Opus 5 --- openapi3/loader.go | 27 ++++++++++++++-- openapi3/schema_ref_siblings_test.go | 46 ++++++++++++++++++++++++++++ 2 files changed, 70 insertions(+), 3 deletions(-) diff --git a/openapi3/loader.go b/openapi3/loader.go index e667bfe23..e767e60d6 100644 --- a/openapi3/loader.go +++ b/openapi3/loader.go @@ -7,6 +7,7 @@ import ( "errors" "fmt" "io" + "maps" "net/url" "os" "path" @@ -1717,12 +1718,23 @@ var refSiblingAnnotations = map[string]struct{}{ // // It works on a copy so a schema shared by other references is not mutated. func (component *SchemaRef) applyRefSiblings(isOpenAPI31OrLater bool) { - if !isOpenAPI31OrLater || component.sibling == nil || component.Value == nil { + if !isOpenAPI31OrLater || component.Value == nil { + return + } + // An extension can be the only thing written next to the $ref, in which + // case there is no sibling schema but there is still something to apply. + if component.sibling == nil && len(component.Extensions) == 0 { return } component.target = component.Value var annotations, assertions []string for _, field := range component.extra { + // An extension describes the member carrying the $ref and asserts + // nothing about the value, so it belongs on the copy rather than in + // a conjunct, and applySiblingSchemaFields has no field to set for it. + if strings.HasPrefix(field, "x-") { + continue + } if _, ok := refSiblingAnnotations[field]; ok { annotations = append(annotations, field) } else { @@ -1730,8 +1742,17 @@ func (component *SchemaRef) applyRefSiblings(isOpenAPI31OrLater bool) { } } schemaCopy := *component.Value - applySiblingSchemaFields(&schemaCopy, component.sibling, annotations) - if len(assertions) != 0 { + if component.sibling != nil { + applySiblingSchemaFields(&schemaCopy, component.sibling, annotations) + } + if len(component.Extensions) != 0 { + extensions := make(map[string]any, len(schemaCopy.Extensions)+len(component.Extensions)) + maps.Copy(extensions, schemaCopy.Extensions) + // The nearer extension wins, as the annotations above do. + maps.Copy(extensions, component.Extensions) + schemaCopy.Extensions = extensions + } + if component.sibling != nil && len(assertions) != 0 { // The siblings sit in the same object as the $ref, so they share its origin. conjunct := Schema{Origin: component.Origin} applySiblingSchemaFields(&conjunct, component.sibling, assertions) diff --git a/openapi3/schema_ref_siblings_test.go b/openapi3/schema_ref_siblings_test.go index 5cc07e2ea..e39603b2b 100644 --- a/openapi3/schema_ref_siblings_test.go +++ b/openapi3/schema_ref_siblings_test.go @@ -127,3 +127,49 @@ func TestSchemaRefSiblingsAreIgnoredIn30(t *testing.T) { require.Same(t, doc.Components.Schemas["Base"].Value, value) require.NoError(t, value.VisitJSON("abc")) } + +// An extension next to a $ref describes the member that carries it, so it +// reaches the schema the member resolves to. A tool reading x-sunset off a +// property finds it whether the property is written inline or as a $ref. +func TestSchemaRefSiblingExtensionsReachTheSchema(t *testing.T) { + t.Parallel() + doc := loadSchemaRefSiblings(t, "3.1.0", `{ + "Nickname": {"type": "string", "x-owner": "identity"}, + "User": {"type": "object", "properties": { + "nickname": {"$ref": "#/components/schemas/Nickname", "x-sunset": "2099-12-31"} + }} + }`) + + nickname := doc.Components.Schemas["User"].Value.Properties["nickname"] + require.Equal(t, "2099-12-31", nickname.Value.Extensions["x-sunset"]) + require.Equal(t, "identity", nickname.Value.Extensions["x-owner"], "the referenced schema's own extensions are kept") + require.Empty(t, doc.Components.Schemas["Nickname"].Value.Extensions["x-sunset"], "the referenced schema is not written to") +} + +// The nearer extension wins, as a sibling annotation does. +func TestSchemaRefSiblingExtensionOverridesTheReferenced(t *testing.T) { + t.Parallel() + doc := loadSchemaRefSiblings(t, "3.1.0", `{ + "Nickname": {"type": "string", "x-sunset": "2030-01-01"}, + "User": {"type": "object", "properties": { + "nickname": {"$ref": "#/components/schemas/Nickname", "x-sunset": "2099-12-31"} + }} + }`) + + require.Equal(t, "2099-12-31", doc.Components.Schemas["User"].Value.Properties["nickname"].Value.Extensions["x-sunset"]) + require.Equal(t, "2030-01-01", doc.Components.Schemas["Nickname"].Value.Extensions["x-sunset"]) +} + +// In 3.0 a $ref replaces its whole object, siblings included, so an extension +// next to it is ignored like every other sibling. +func TestSchemaRefSiblingExtensionsIgnoredIn30(t *testing.T) { + t.Parallel() + doc := loadSchemaRefSiblings(t, "3.0.3", `{ + "Nickname": {"type": "string"}, + "User": {"type": "object", "properties": { + "nickname": {"$ref": "#/components/schemas/Nickname", "x-sunset": "2099-12-31"} + }} + }`) + + require.Empty(t, doc.Components.Schemas["User"].Value.Properties["nickname"].Value.Extensions["x-sunset"]) +} From e21ab807ae16eeab14296cbe47a60f0aa834e5a2 Mon Sep 17 00:00:00 2001 From: yi111 <153097222+Yi-111-a@users.noreply.github.com> Date: Mon, 2 Nov 2026 21:46:51 +0800 Subject: [PATCH 63/78] openapi3: DefaultRefNameResolver stops stripping extensions at the last dot (#1419) --- openapi3/internalize_refs.go | 8 +++- openapi3/internalize_refs_test.go | 1 + .../testdata/issue1395/Lib.AccountId.yaml | 4 ++ openapi3/testdata/issue1395/Lib.PageSize.yaml | 4 ++ openapi3/testdata/issue1395/openapi.yaml | 13 ++++++ .../issue1395/openapi.yaml.internalized.yml | 44 +++++++++++++++++++ .../testref.openapi.yml.internalized.yml | 2 +- 7 files changed, 73 insertions(+), 3 deletions(-) create mode 100644 openapi3/testdata/issue1395/Lib.AccountId.yaml create mode 100644 openapi3/testdata/issue1395/Lib.PageSize.yaml create mode 100644 openapi3/testdata/issue1395/openapi.yaml create mode 100644 openapi3/testdata/issue1395/openapi.yaml.internalized.yml diff --git a/openapi3/internalize_refs.go b/openapi3/internalize_refs.go index 09fb2873d..a908823f9 100644 --- a/openapi3/internalize_refs.go +++ b/openapi3/internalize_refs.go @@ -63,8 +63,12 @@ func DefaultRefNameResolver(doc *T, ref ComponentRef) string { filePath = "" } - // Remove the path extensions to make this JSON/YAML agnostic. - for ext := path.Ext(filePath); len(ext) > 0; ext = path.Ext(filePath) { + // Remove the path extension to make this JSON/YAML agnostic. Only + // the last one is stripped: earlier dots belong to the file name + // itself (e.g. "Lib.AccountId.yaml" must stay "Lib.AccountId"), + // otherwise two files like "Lib.AccountId.yaml" and + // "Lib.PageSize.yaml" would collapse to the same name. + if ext := path.Ext(filePath); len(ext) > 0 { filePath = strings.TrimSuffix(filePath, ext) } diff --git a/openapi3/internalize_refs_test.go b/openapi3/internalize_refs_test.go index cc48f571c..402466440 100644 --- a/openapi3/internalize_refs_test.go +++ b/openapi3/internalize_refs_test.go @@ -32,6 +32,7 @@ func TestInternalizeRefs(t *testing.T) { {"testdata/discriminatorLocalMapping.yml"}, {"testdata/issue1205/openapi.yml"}, {"testdata/issue1205/mutual.yml"}, + {"testdata/issue1395/openapi.yaml"}, } for _, test := range tests { diff --git a/openapi3/testdata/issue1395/Lib.AccountId.yaml b/openapi3/testdata/issue1395/Lib.AccountId.yaml new file mode 100644 index 000000000..8aa08eb1c --- /dev/null +++ b/openapi3/testdata/issue1395/Lib.AccountId.yaml @@ -0,0 +1,4 @@ +name: account_id +in: query +schema: + type: string diff --git a/openapi3/testdata/issue1395/Lib.PageSize.yaml b/openapi3/testdata/issue1395/Lib.PageSize.yaml new file mode 100644 index 000000000..3e91ab14d --- /dev/null +++ b/openapi3/testdata/issue1395/Lib.PageSize.yaml @@ -0,0 +1,4 @@ +name: page_size +in: query +schema: + type: integer diff --git a/openapi3/testdata/issue1395/openapi.yaml b/openapi3/testdata/issue1395/openapi.yaml new file mode 100644 index 000000000..29f35b254 --- /dev/null +++ b/openapi3/testdata/issue1395/openapi.yaml @@ -0,0 +1,13 @@ +openapi: "3.1.0" +info: + title: Parameters from files that carry dots in their name. + version: "1.0.0" +paths: + /p: + get: + parameters: + - $ref: './Lib.AccountId.yaml' + - $ref: './Lib.PageSize.yaml' + responses: + 200: + description: OK diff --git a/openapi3/testdata/issue1395/openapi.yaml.internalized.yml b/openapi3/testdata/issue1395/openapi.yaml.internalized.yml new file mode 100644 index 000000000..0c68bb986 --- /dev/null +++ b/openapi3/testdata/issue1395/openapi.yaml.internalized.yml @@ -0,0 +1,44 @@ +{ + "components": { + "parameters": { + "Lib.AccountId": { + "in": "query", + "name": "account_id", + "schema": { + "type": "string" + } + }, + "Lib.PageSize": { + "in": "query", + "name": "page_size", + "schema": { + "type": "integer" + } + } + } + }, + "info": { + "title": "Parameters from files that carry dots in their name.", + "version": "1.0.0" + }, + "openapi": "3.1.0", + "paths": { + "/p": { + "get": { + "parameters": [ + { + "$ref": "#/components/parameters/Lib.AccountId" + }, + { + "$ref": "#/components/parameters/Lib.PageSize" + } + ], + "responses": { + "200": { + "description": "OK" + } + } + } + } + } +} diff --git a/openapi3/testdata/testref.openapi.yml.internalized.yml b/openapi3/testdata/testref.openapi.yml.internalized.yml index f270941d8..cf4856d8a 100644 --- a/openapi3/testdata/testref.openapi.yml.internalized.yml +++ b/openapi3/testdata/testref.openapi.yml.internalized.yml @@ -4,7 +4,7 @@ "AnotherTestSchema": { "type": "string" }, - "components_Name": { + "components.openapi_Name": { "type": "string" } } From 2fe145b861f765b92aff84051bbaca227b247620 Mon Sep 17 00:00:00 2001 From: subotac <73706465+subotac@users.noreply.github.com> Date: Wed, 4 Nov 2026 11:47:15 +0200 Subject: [PATCH 64/78] openapi3: isolate reference sibling constraints (#1406) --- openapi3/issue1381_test.go | 42 +++++++++++++++++++++++++ openapi3/schema_jsonschema_validator.go | 8 +++-- 2 files changed, 48 insertions(+), 2 deletions(-) create mode 100644 openapi3/issue1381_test.go diff --git a/openapi3/issue1381_test.go b/openapi3/issue1381_test.go new file mode 100644 index 000000000..2138484f2 --- /dev/null +++ b/openapi3/issue1381_test.go @@ -0,0 +1,42 @@ +package openapi3_test + +import ( + "testing" + + "github.com/stretchr/testify/require" + + "github.com/getkin/kin-openapi/openapi3" +) + +func TestSchemaRefSiblingConstraintsStayAtTheirUseSites(t *testing.T) { + t.Parallel() + loader := openapi3.NewLoader() + doc, err := loader.LoadFromData([]byte(` +openapi: 3.1.0 +info: {title: independent reference constraints, version: "1"} +paths: {} +components: + schemas: + Kind: + type: string + enum: [a, b] + TwoProps: + type: object + properties: + x: {$ref: '#/components/schemas/Kind', const: a} + y: {$ref: '#/components/schemas/Kind', const: b} + required: [x, y] +`)) + require.NoError(t, err) + require.NoError(t, doc.Validate(loader.Context)) + + schema := doc.Components.Schemas["TwoProps"].Value + require.NoError(t, schema.VisitJSON(map[string]any{"x": "a", "y": "b"}, openapi3.EnableJSONSchema2020())) + require.Error(t, schema.VisitJSON(map[string]any{"x": "b", "y": "b"}, openapi3.EnableJSONSchema2020())) + require.Error(t, schema.VisitJSON(map[string]any{"x": "a", "y": "a"}, openapi3.EnableJSONSchema2020())) + + base := doc.Components.Schemas["Kind"].Value + for _, value := range []string{"a", "b"} { + require.NoError(t, base.VisitJSON(value, openapi3.EnableJSONSchema2020())) + } +} diff --git a/openapi3/schema_jsonschema_validator.go b/openapi3/schema_jsonschema_validator.go index c52480d0d..72723e7ac 100644 --- a/openapi3/schema_jsonschema_validator.go +++ b/openapi3/schema_jsonschema_validator.go @@ -109,8 +109,12 @@ func addInternalSchemaRefs(schemaMap map[string]any, schema *Schema) (map[string if _, ok := refs[ref.Ref]; ok { return nil } + resolved := ref.Value + if ref.target != nil { + resolved = ref.target + } var target any - bytes, err := json.Marshal(ref.Value) + bytes, err := json.Marshal(resolved) if err != nil { return err } @@ -118,7 +122,7 @@ func addInternalSchemaRefs(schemaMap map[string]any, schema *Schema) (map[string return err } refs[ref.Ref] = target - values[ref.Ref] = ref.Value + values[ref.Ref] = resolved return nil }) if err != nil { From de92908414b8849967fa7a531d96d5dc0ead1cc2 Mon Sep 17 00:00:00 2001 From: Luis Figueroa <62305361+LuisFigueroaG@users.noreply.github.com> Date: Wed, 4 Nov 2026 06:48:04 -0300 Subject: [PATCH 65/78] openapi3: reject impossible days and offsets in the date and date-time formats (#1407) --- .github/docs/openapi3.txt | 2 +- README.md | 1 + openapi3/datetime_schema_test.go | 109 ++++++++++++++++++ openapi3/schema_formats.go | 20 +++- ...vicefarm_2015_06_23_openapi_yaml__validate | 2 +- ...nspector_2016_02_16_openapi_yaml__validate | 2 +- ...izations_2016_11_28_openapi_yaml__validate | 2 +- ...smanager_2017_10_17_openapi_yaml__validate | 2 +- ...urityhub_2018_10_26_openapi_yaml__validate | 2 +- ...dynamodb_2012_08_10_openapi_yaml__validate | 2 +- ..._com_waf_2015_08_24_openapi_yaml__validate | 2 +- ...regional_2016_11_28_openapi_yaml__validate | 2 +- .../ato_gov_au_0_0_6_openapi_yaml__validate | 2 +- .../bigredcloud_com_v1_openapi_yaml__validate | 2 +- .../extpose_com_1_0_0_openapi_yaml__validate | 2 +- .../giphy_com_1_0_openapi_yaml__validate | 2 +- ...thub_com_ghec_1_1_4_openapi_yaml__validate | 2 +- ...ec_2022_11_28_1_1_4_openapi_yaml__validate | 2 +- ..._com_ghes_3_0_1_1_4_openapi_yaml__validate | 2 +- ..._com_ghes_3_1_1_1_4_openapi_yaml__validate | 2 +- ..._com_ghes_3_2_1_1_4_openapi_yaml__validate | 2 +- ..._com_ghes_3_3_1_1_4_openapi_yaml__validate | 2 +- ..._com_ghes_3_4_1_1_4_openapi_yaml__validate | 2 +- ..._com_ghes_3_5_1_1_4_openapi_yaml__validate | 2 +- ..._com_ghes_3_6_1_1_4_openapi_yaml__validate | 2 +- ..._com_ghes_3_7_1_1_4_openapi_yaml__validate | 2 +- ..._com_ghes_3_8_1_1_4_openapi_yaml__validate | 2 +- ...com_github_ae_1_1_4_openapi_yaml__validate | 2 +- .../linode_com_4_151_1_openapi_yaml__validate | 2 +- .../meteosource_com_v1_openapi_yaml__validate | 2 +- .../sinao_app_1_1_0_openapi_yaml__validate | 2 +- ...spinitron_com_1_0_0_openapi_yaml__validate | 2 +- .../svix_com_1_4_openapi_yaml__validate | 2 +- ...rashnothing_com_1_3_openapi_yaml__validate | 2 +- ...er_com_current_2_62_openapi_yaml__validate | 2 +- ...nse_Manager_API_1_0_openapi_yaml__validate | 2 +- .../zoom_us_2_0_0_openapi_yaml__validate | 4 +- 37 files changed, 162 insertions(+), 38 deletions(-) diff --git a/.github/docs/openapi3.txt b/.github/docs/openapi3.txt index 119a72871..49ccc2c04 100644 --- a/.github/docs/openapi3.txt +++ b/.github/docs/openapi3.txt @@ -78,7 +78,7 @@ const ( FormatOfStringDate = `^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])$` // FormatOfStringDateTime is a RFC3339 date-time format regexp, for example "2017-07-21T17:32:28Z". - FormatOfStringDateTime = `^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)[0-9]{2}:[0-9]{2})$` + FormatOfStringDateTime = `^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)([0-1][0-9]|2[0-3]):[0-5][0-9])$` ) const ( SerializationSimple = "simple" diff --git a/README.md b/README.md index 610de68e5..99b8feccf 100644 --- a/README.md +++ b/README.md @@ -334,6 +334,7 @@ for _, path := range doc.Paths.InMatchingOrder() { * `(*openapi3.Schema).Validate(..)` (hence `(*openapi3.T).Validate(..)`) now rejects a `multipleOf` of zero or less (`openapi3.SchemaMultipleOfNotPositiveError`), as JSON Schema requires it to be strictly greater than 0. Such a schema used to pass validation and then reject every value with `multipleOf must be greater than zero`. * `(*openapi3.Schema).Validate(..)` now also compiles the `pattern` of a schema without `type`, as it does for `type: string`, and rejects one that does not compile with `openapi3.SchemaPatternRegexError`. Such a schema used to pass validation and then fail on every string value it was given. * `(*openapi3.Schema).WithMaxLengthDecodedBase64(..)` now sets `maxLength`. It used to set `minLength` instead, overwriting any minimum and leaving the length unbounded. +* The `date` and `date-time` string formats now reject a day that its month does not have, such as `2023-02-29` or `2023-04-31`, and `openapi3.FormatOfStringDateTime` now only matches a time offset with hours `00` to `23` and minutes `00` to `59`, so `+99:99` is rejected. Such values used to pass, and so did schema examples and defaults made of them in `(*openapi3.T).Validate(..)`. ### v0.152.0 * JSON keys of OpenAPI documents only fill the field of the same case (`json:",case:strict"`) when `encoding/json` is implemented with `encoding/json/v2` (by default from Go 1.27, and on Go 1.25 and 1.26 with `GOEXPERIMENT=jsonv2`): a key such as `"Components"` (not `"components"`) is kept as an extension instead of filling `openapi3.T.Components`. Other builds still match keys case-insensitively, as `encoding/json` v1 does. diff --git a/openapi3/datetime_schema_test.go b/openapi3/datetime_schema_test.go index 1a1f8c633..2ea2ddb8b 100644 --- a/openapi3/datetime_schema_test.go +++ b/openapi3/datetime_schema_test.go @@ -169,3 +169,112 @@ func TestDateTimeSecondOutOfBounds(t *testing.T) { }) require.EqualError(t, err, `Error at "/datetime": string doesn't match the format "date-time": string doesn't match pattern "`+openapi3.FormatOfStringDateTime+`"`) } + +func TestDateDayOutOfMonth(t *testing.T) { + t.Parallel() + + loader := openapi3.NewLoader() + doc, err := loader.LoadFromData(DateSpec) + require.NoError(t, err) + + err = doc.Validate(loader.Context) + require.NoError(t, err) + + for _, date := range []string{"2023-01-31", "2023-02-28", "2024-02-29", "2000-02-29", "2023-04-30", "2023-12-31"} { + err = doc.Components.Schemas["Server"].Value.VisitJSON(map[string]any{ + "name": "kin-openapi", + "date": date, + }) + require.NoError(t, err, date) + } + + for _, date := range []string{"2023-02-29", "2100-02-29", "2024-02-30", "2024-02-31", "2023-04-31", "2023-06-31", "2023-09-31", "2023-11-31"} { + err = doc.Components.Schemas["Server"].Value.VisitJSON(map[string]any{ + "name": "kin-openapi", + "date": date, + }) + require.EqualError(t, err, `Error at "/date": string doesn't match the format "date": parsing time "`+date+`": day out of range`) + } +} + +func TestDateTimeDayOutOfMonth(t *testing.T) { + t.Parallel() + + loader := openapi3.NewLoader() + doc, err := loader.LoadFromData(DateTimeSpec) + require.NoError(t, err) + + err = doc.Validate(loader.Context) + require.NoError(t, err) + + err = doc.Components.Schemas["Server"].Value.VisitJSON(map[string]any{ + "name": "kin-openapi", + "datetime": "2024-02-29T04:05:06.789Z", + }) + require.NoError(t, err) + + err = doc.Components.Schemas["Server"].Value.VisitJSON(map[string]any{ + "name": "kin-openapi", + "datetime": "2023-02-29T04:05:06.789Z", + }) + require.EqualError(t, err, `Error at "/datetime": string doesn't match the format "date-time": parsing time "2023-02-29": day out of range`) + + err = doc.Components.Schemas["Server"].Value.VisitJSON(map[string]any{ + "name": "kin-openapi", + "datetime": "2023-04-31T04:05:06+02:00", + }) + require.EqualError(t, err, `Error at "/datetime": string doesn't match the format "date-time": parsing time "2023-04-31": day out of range`) +} + +func TestDateTimeOffsetOutOfBounds(t *testing.T) { + t.Parallel() + + loader := openapi3.NewLoader() + doc, err := loader.LoadFromData(DateTimeSpec) + require.NoError(t, err) + + err = doc.Validate(loader.Context) + require.NoError(t, err) + + for _, datetime := range []string{"2016-12-31T23:59:59+00:00", "2016-12-31T23:59:59-23:59", "2016-12-31T23:59:59+14:00"} { + err = doc.Components.Schemas["Server"].Value.VisitJSON(map[string]any{ + "name": "kin-openapi", + "datetime": datetime, + }) + require.NoError(t, err, datetime) + } + + for _, datetime := range []string{"2016-12-31T23:59:59+24:00", "2016-12-31T23:59:59-99:00", "2016-12-31T23:59:59+01:60", "2016-12-31T23:59:59+99:99"} { + err = doc.Components.Schemas["Server"].Value.VisitJSON(map[string]any{ + "name": "kin-openapi", + "datetime": datetime, + }) + require.EqualError(t, err, `Error at "/datetime": string doesn't match the format "date-time": string doesn't match pattern "`+openapi3.FormatOfStringDateTime+`"`) + } +} + +func TestDateDayOutOfMonthInExample(t *testing.T) { + t.Parallel() + + for _, version := range []string{"3.0.3", "3.1.0"} { + t.Run(version, func(t *testing.T) { + loader := openapi3.NewLoader() + doc, err := loader.LoadFromData([]byte(` +openapi: ` + version + ` +info: { title: t, version: "1" } +paths: {} +components: + schemas: + Day: + type: string + format: date + example: "2023-02-29" +`)) + require.NoError(t, err) + + err = doc.Validate(loader.Context) + require.ErrorContains(t, err, `schema "Day": invalid example`) + require.ErrorContains(t, err, `parsing time "2023-02-29": day out of range`) + }) + } +} diff --git a/openapi3/schema_formats.go b/openapi3/schema_formats.go index 57594e76e..d18e7128e 100644 --- a/openapi3/schema_formats.go +++ b/openapi3/schema_formats.go @@ -5,6 +5,7 @@ import ( "math" "net/netip" "regexp" + "time" ) // FormatValidator is an interface for custom format validators. @@ -50,13 +51,13 @@ const ( FormatOfStringDate = `^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])$` // FormatOfStringDateTime is a RFC3339 date-time format regexp, for example "2017-07-21T17:32:28Z". - FormatOfStringDateTime = `^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)[0-9]{2}:[0-9]{2})$` + FormatOfStringDateTime = `^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)([0-1][0-9]|2[0-3]):[0-5][0-9])$` ) func init() { DefineStringFormatValidator("byte", NewRegexpFormatValidator(FormatOfStringByte)) - DefineStringFormatValidator("date", NewRegexpFormatValidator(FormatOfStringDate)) - DefineStringFormatValidator("date-time", NewRegexpFormatValidator(FormatOfStringDateTime)) + DefineStringFormatValidator("date", newDateFormatValidator(FormatOfStringDate)) + DefineStringFormatValidator("date-time", newDateFormatValidator(FormatOfStringDateTime)) DefineIntegerFormatValidator("int32", NewRangeFormatValidator(int64(math.MinInt32), int64(math.MaxInt32))) DefineIntegerFormatValidator("int64", NewRangeFormatValidator(int64(math.MinInt64), int64(math.MaxInt64))) } @@ -129,6 +130,19 @@ func NewRegexpFormatValidator(pattern string) StringFormatValidator { return stringRegexpFormatValidator{re: re} } +// newDateFormatValidator matches the value against pattern, which only matches strings starting with +// a YYYY-MM-DD date, then checks that its month has this day, as RFC 3339 requires (section 5.7). +func newDateFormatValidator(pattern string) StringFormatValidator { + re := NewRegexpFormatValidator(pattern) + return NewCallbackValidator(func(value string) error { + if err := re.Validate(value); err != nil { + return err + } + _, err := time.Parse(time.DateOnly, value[:len(time.DateOnly)]) + return err + }) +} + // NewCallbackValidator creates a new FormatValidator that uses a callback function to validate the value. func NewCallbackValidator[T any](fn func(T) error) FormatValidator[T] { return callbackValidator[T]{fn: fn} diff --git a/openapi3/testdata/apis_guru_openapi_directory/amazonaws_com_devicefarm_2015_06_23_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/amazonaws_com_devicefarm_2015_06_23_openapi_yaml__validate index acabb8087..1bcbaac6e 100644 --- a/openapi3/testdata/apis_guru_openapi_directory/amazonaws_com_devicefarm_2015_06_23_openapi_yaml__validate +++ b/openapi3/testdata/apis_guru_openapi_directory/amazonaws_com_devicefarm_2015_06_23_openapi_yaml__validate @@ -1 +1 @@ -invalid components: schema "CreateProjectResult": invalid example: Error at "/project": doesn't match schema due to: Error at "/created": doesn't match schema due to: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)[0-9]{2}:[0-9]{2})$" +invalid components: schema "CreateProjectResult": invalid example: Error at "/project": doesn't match schema due to: Error at "/created": doesn't match schema due to: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)([0-1][0-9]|2[0-3]):[0-5][0-9])$" diff --git a/openapi3/testdata/apis_guru_openapi_directory/amazonaws_com_inspector_2016_02_16_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/amazonaws_com_inspector_2016_02_16_openapi_yaml__validate index 89f3545a4..5cc00bd92 100644 --- a/openapi3/testdata/apis_guru_openapi_directory/amazonaws_com_inspector_2016_02_16_openapi_yaml__validate +++ b/openapi3/testdata/apis_guru_openapi_directory/amazonaws_com_inspector_2016_02_16_openapi_yaml__validate @@ -1 +1 @@ -invalid components: schema "DescribeAssessmentRunsResponse": invalid example: Error at "/assessmentRuns": doesn't match schema due to: Error at "/0/completedAt": doesn't match schema due to: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)[0-9]{2}:[0-9]{2})$" | Error at "/0/createdAt": doesn't match schema due to: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)[0-9]{2}:[0-9]{2})$" | Error at "/0/startedAt": doesn't match schema due to: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)[0-9]{2}:[0-9]{2})$" | Error at "/0/stateChangedAt": doesn't match schema due to: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)[0-9]{2}:[0-9]{2})$" | Error at "/0/stateChanges": doesn't match schema due to: Error at "/0/stateChangedAt": doesn't match schema due to: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)[0-9]{2}:[0-9]{2})$" | Error at "/1/stateChangedAt": doesn't match schema due to: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)[0-9]{2}:[0-9]{2})$" | Error at "/2/stateChangedAt": doesn't match schema due to: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)[0-9]{2}:[0-9]{2})$" | Error at "/3/stateChangedAt": doesn't match schema due to: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)[0-9]{2}:[0-9]{2})$" | Error at "/4/stateChangedAt": doesn't match schema due to: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)[0-9]{2}:[0-9]{2})$" | Error at "/5/stateChangedAt": doesn't match schema due to: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)[0-9]{2}:[0-9]{2})$" | Error at "/6/stateChangedAt": doesn't match schema due to: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)[0-9]{2}:[0-9]{2})$" | Error at "/7/stateChangedAt": doesn't match schema due to: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)[0-9]{2}:[0-9]{2})$" +invalid components: schema "DescribeAssessmentRunsResponse": invalid example: Error at "/assessmentRuns": doesn't match schema due to: Error at "/0/completedAt": doesn't match schema due to: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)([0-1][0-9]|2[0-3]):[0-5][0-9])$" | Error at "/0/createdAt": doesn't match schema due to: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)([0-1][0-9]|2[0-3]):[0-5][0-9])$" | Error at "/0/startedAt": doesn't match schema due to: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)([0-1][0-9]|2[0-3]):[0-5][0-9])$" | Error at "/0/stateChangedAt": doesn't match schema due to: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)([0-1][0-9]|2[0-3]):[0-5][0-9])$" | Error at "/0/stateChanges": doesn't match schema due to: Error at "/0/stateChangedAt": doesn't match schema due to: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)([0-1][0-9]|2[0-3]):[0-5][0-9])$" | Error at "/1/stateChangedAt": doesn't match schema due to: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)([0-1][0-9]|2[0-3]):[0-5][0-9])$" | Error at "/2/stateChangedAt": doesn't match schema due to: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)([0-1][0-9]|2[0-3]):[0-5][0-9])$" | Error at "/3/stateChangedAt": doesn't match schema due to: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)([0-1][0-9]|2[0-3]):[0-5][0-9])$" | Error at "/4/stateChangedAt": doesn't match schema due to: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)([0-1][0-9]|2[0-3]):[0-5][0-9])$" | Error at "/5/stateChangedAt": doesn't match schema due to: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)([0-1][0-9]|2[0-3]):[0-5][0-9])$" | Error at "/6/stateChangedAt": doesn't match schema due to: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)([0-1][0-9]|2[0-3]):[0-5][0-9])$" | Error at "/7/stateChangedAt": doesn't match schema due to: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)([0-1][0-9]|2[0-3]):[0-5][0-9])$" diff --git a/openapi3/testdata/apis_guru_openapi_directory/amazonaws_com_organizations_2016_11_28_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/amazonaws_com_organizations_2016_11_28_openapi_yaml__validate index f34fbabe9..129ff0241 100644 --- a/openapi3/testdata/apis_guru_openapi_directory/amazonaws_com_organizations_2016_11_28_openapi_yaml__validate +++ b/openapi3/testdata/apis_guru_openapi_directory/amazonaws_com_organizations_2016_11_28_openapi_yaml__validate @@ -1 +1 @@ -invalid components: schema "AcceptHandshakeResponse": invalid example: Error at "/Handshake": doesn't match schema due to: Error at "/ExpirationTimestamp": doesn't match schema due to: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)[0-9]{2}:[0-9]{2})$" | Error at "/RequestedTimestamp": doesn't match schema due to: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)[0-9]{2}:[0-9]{2})$" +invalid components: schema "AcceptHandshakeResponse": invalid example: Error at "/Handshake": doesn't match schema due to: Error at "/ExpirationTimestamp": doesn't match schema due to: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)([0-1][0-9]|2[0-3]):[0-5][0-9])$" | Error at "/RequestedTimestamp": doesn't match schema due to: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)([0-1][0-9]|2[0-3]):[0-5][0-9])$" diff --git a/openapi3/testdata/apis_guru_openapi_directory/amazonaws_com_secretsmanager_2017_10_17_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/amazonaws_com_secretsmanager_2017_10_17_openapi_yaml__validate index 75743b5de..06fc18a09 100644 --- a/openapi3/testdata/apis_guru_openapi_directory/amazonaws_com_secretsmanager_2017_10_17_openapi_yaml__validate +++ b/openapi3/testdata/apis_guru_openapi_directory/amazonaws_com_secretsmanager_2017_10_17_openapi_yaml__validate @@ -1 +1 @@ -invalid components: schema "DeleteSecretResponse": invalid example: Error at "/DeletionDate": doesn't match schema due to: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)[0-9]{2}:[0-9]{2})$" +invalid components: schema "DeleteSecretResponse": invalid example: Error at "/DeletionDate": doesn't match schema due to: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)([0-1][0-9]|2[0-3]):[0-5][0-9])$" diff --git a/openapi3/testdata/apis_guru_openapi_directory/amazonaws_com_securityhub_2018_10_26_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/amazonaws_com_securityhub_2018_10_26_openapi_yaml__validate index aba9d53d3..39482ab98 100644 --- a/openapi3/testdata/apis_guru_openapi_directory/amazonaws_com_securityhub_2018_10_26_openapi_yaml__validate +++ b/openapi3/testdata/apis_guru_openapi_directory/amazonaws_com_securityhub_2018_10_26_openapi_yaml__validate @@ -1 +1 @@ -invalid components: schema "TagKey": error parsing regexp: invalid or unsupported Perl syntax: `(?!` +invalid components: schema "GetFindingHistoryResponse": invalid example: Error at "/Records": doesn't match schema due to: Error at "/0/UpdateTime": doesn't match schema due to: string doesn't match the format "date-time": parsing time "2021-09-31": day out of range diff --git a/openapi3/testdata/apis_guru_openapi_directory/amazonaws_com_streams_dynamodb_2012_08_10_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/amazonaws_com_streams_dynamodb_2012_08_10_openapi_yaml__validate index 85ff28342..24780edb2 100644 --- a/openapi3/testdata/apis_guru_openapi_directory/amazonaws_com_streams_dynamodb_2012_08_10_openapi_yaml__validate +++ b/openapi3/testdata/apis_guru_openapi_directory/amazonaws_com_streams_dynamodb_2012_08_10_openapi_yaml__validate @@ -1 +1 @@ -invalid components: schema "DescribeStreamOutput": invalid example: Error at "/StreamDescription": doesn't match schema due to: Error at "/CreationRequestDateTime": doesn't match schema due to: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)[0-9]{2}:[0-9]{2})$" +invalid components: schema "DescribeStreamOutput": invalid example: Error at "/StreamDescription": doesn't match schema due to: Error at "/CreationRequestDateTime": doesn't match schema due to: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)([0-1][0-9]|2[0-3]):[0-5][0-9])$" diff --git a/openapi3/testdata/apis_guru_openapi_directory/amazonaws_com_waf_2015_08_24_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/amazonaws_com_waf_2015_08_24_openapi_yaml__validate index 9f74482e4..250baf228 100644 --- a/openapi3/testdata/apis_guru_openapi_directory/amazonaws_com_waf_2015_08_24_openapi_yaml__validate +++ b/openapi3/testdata/apis_guru_openapi_directory/amazonaws_com_waf_2015_08_24_openapi_yaml__validate @@ -1 +1 @@ -invalid components: schema "GetSampledRequestsResponse": invalid example: Error at "/SampledRequests": doesn't match schema due to: Error at "/0/Timestamp": doesn't match schema due to: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)[0-9]{2}:[0-9]{2})$" | Error at "/TimeWindow": doesn't match schema due to: Error at "/EndTime": doesn't match schema due to: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)[0-9]{2}:[0-9]{2})$" | Error at "/StartTime": doesn't match schema due to: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)[0-9]{2}:[0-9]{2})$" +invalid components: schema "GetSampledRequestsResponse": invalid example: Error at "/SampledRequests": doesn't match schema due to: Error at "/0/Timestamp": doesn't match schema due to: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)([0-1][0-9]|2[0-3]):[0-5][0-9])$" | Error at "/TimeWindow": doesn't match schema due to: Error at "/EndTime": doesn't match schema due to: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)([0-1][0-9]|2[0-3]):[0-5][0-9])$" | Error at "/StartTime": doesn't match schema due to: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)([0-1][0-9]|2[0-3]):[0-5][0-9])$" diff --git a/openapi3/testdata/apis_guru_openapi_directory/amazonaws_com_waf_regional_2016_11_28_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/amazonaws_com_waf_regional_2016_11_28_openapi_yaml__validate index 9f74482e4..250baf228 100644 --- a/openapi3/testdata/apis_guru_openapi_directory/amazonaws_com_waf_regional_2016_11_28_openapi_yaml__validate +++ b/openapi3/testdata/apis_guru_openapi_directory/amazonaws_com_waf_regional_2016_11_28_openapi_yaml__validate @@ -1 +1 @@ -invalid components: schema "GetSampledRequestsResponse": invalid example: Error at "/SampledRequests": doesn't match schema due to: Error at "/0/Timestamp": doesn't match schema due to: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)[0-9]{2}:[0-9]{2})$" | Error at "/TimeWindow": doesn't match schema due to: Error at "/EndTime": doesn't match schema due to: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)[0-9]{2}:[0-9]{2})$" | Error at "/StartTime": doesn't match schema due to: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)[0-9]{2}:[0-9]{2})$" +invalid components: schema "GetSampledRequestsResponse": invalid example: Error at "/SampledRequests": doesn't match schema due to: Error at "/0/Timestamp": doesn't match schema due to: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)([0-1][0-9]|2[0-3]):[0-5][0-9])$" | Error at "/TimeWindow": doesn't match schema due to: Error at "/EndTime": doesn't match schema due to: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)([0-1][0-9]|2[0-3]):[0-5][0-9])$" | Error at "/StartTime": doesn't match schema due to: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)([0-1][0-9]|2[0-3]):[0-5][0-9])$" diff --git a/openapi3/testdata/apis_guru_openapi_directory/ato_gov_au_0_0_6_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/ato_gov_au_0_0_6_openapi_yaml__validate index 798fb4a98..b25cdb954 100644 --- a/openapi3/testdata/apis_guru_openapi_directory/ato_gov_au_0_0_6_openapi_yaml__validate +++ b/openapi3/testdata/apis_guru_openapi_directory/ato_gov_au_0_0_6_openapi_yaml__validate @@ -1 +1 @@ -invalid components: schema "address": invalid example: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)[0-9]{2}:[0-9]{2})$" +invalid components: schema "address": invalid example: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)([0-1][0-9]|2[0-3]):[0-5][0-9])$" diff --git a/openapi3/testdata/apis_guru_openapi_directory/bigredcloud_com_v1_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/bigredcloud_com_v1_openapi_yaml__validate index ecf6ae60c..b8a650326 100644 --- a/openapi3/testdata/apis_guru_openapi_directory/bigredcloud_com_v1_openapi_yaml__validate +++ b/openapi3/testdata/apis_guru_openapi_directory/bigredcloud_com_v1_openapi_yaml__validate @@ -1 +1 @@ -invalid components: schema "BatchItem_CashPaymentDto_": invalid example: Error at "/entryDate": string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)[0-9]{2}:[0-9]{2})$" | Error at "/procDate": string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)[0-9]{2}:[0-9]{2})$" +invalid components: schema "BatchItem_CashPaymentDto_": invalid example: Error at "/entryDate": string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)([0-1][0-9]|2[0-3]):[0-5][0-9])$" | Error at "/procDate": string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)([0-1][0-9]|2[0-3]):[0-5][0-9])$" diff --git a/openapi3/testdata/apis_guru_openapi_directory/extpose_com_1_0_0_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/extpose_com_1_0_0_openapi_yaml__validate index 1676ab0e1..7c559cf4a 100644 --- a/openapi3/testdata/apis_guru_openapi_directory/extpose_com_1_0_0_openapi_yaml__validate +++ b/openapi3/testdata/apis_guru_openapi_directory/extpose_com_1_0_0_openapi_yaml__validate @@ -1 +1 @@ -invalid components: schema "Extension": invalid example: Error at "/update_ts": string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)[0-9]{2}:[0-9]{2})$" +invalid components: schema "Extension": invalid example: Error at "/update_ts": string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)([0-1][0-9]|2[0-3]):[0-5][0-9])$" diff --git a/openapi3/testdata/apis_guru_openapi_directory/giphy_com_1_0_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/giphy_com_1_0_openapi_yaml__validate index c75deb45f..c0e6945e0 100644 --- a/openapi3/testdata/apis_guru_openapi_directory/giphy_com_1_0_openapi_yaml__validate +++ b/openapi3/testdata/apis_guru_openapi_directory/giphy_com_1_0_openapi_yaml__validate @@ -1 +1 @@ -invalid components: schema "Gif": invalid example: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)[0-9]{2}:[0-9]{2})$" +invalid components: schema "Gif": invalid example: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)([0-1][0-9]|2[0-3]):[0-5][0-9])$" diff --git a/openapi3/testdata/apis_guru_openapi_directory/github_com_ghec_1_1_4_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/github_com_ghec_1_1_4_openapi_yaml__validate index ac78d6dd1..e7ace4883 100644 --- a/openapi3/testdata/apis_guru_openapi_directory/github_com_ghec_1_1_4_openapi_yaml__validate +++ b/openapi3/testdata/apis_guru_openapi_directory/github_com_ghec_1_1_4_openapi_yaml__validate @@ -1 +1 @@ -invalid components: schema "announcement": invalid example: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)[0-9]{2}:[0-9]{2})$" +invalid components: schema "announcement": invalid example: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)([0-1][0-9]|2[0-3]):[0-5][0-9])$" diff --git a/openapi3/testdata/apis_guru_openapi_directory/github_com_ghec_2022_11_28_1_1_4_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/github_com_ghec_2022_11_28_1_1_4_openapi_yaml__validate index ac78d6dd1..e7ace4883 100644 --- a/openapi3/testdata/apis_guru_openapi_directory/github_com_ghec_2022_11_28_1_1_4_openapi_yaml__validate +++ b/openapi3/testdata/apis_guru_openapi_directory/github_com_ghec_2022_11_28_1_1_4_openapi_yaml__validate @@ -1 +1 @@ -invalid components: schema "announcement": invalid example: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)[0-9]{2}:[0-9]{2})$" +invalid components: schema "announcement": invalid example: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)([0-1][0-9]|2[0-3]):[0-5][0-9])$" diff --git a/openapi3/testdata/apis_guru_openapi_directory/github_com_ghes_3_0_1_1_4_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/github_com_ghes_3_0_1_1_4_openapi_yaml__validate index ac78d6dd1..e7ace4883 100644 --- a/openapi3/testdata/apis_guru_openapi_directory/github_com_ghes_3_0_1_1_4_openapi_yaml__validate +++ b/openapi3/testdata/apis_guru_openapi_directory/github_com_ghes_3_0_1_1_4_openapi_yaml__validate @@ -1 +1 @@ -invalid components: schema "announcement": invalid example: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)[0-9]{2}:[0-9]{2})$" +invalid components: schema "announcement": invalid example: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)([0-1][0-9]|2[0-3]):[0-5][0-9])$" diff --git a/openapi3/testdata/apis_guru_openapi_directory/github_com_ghes_3_1_1_1_4_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/github_com_ghes_3_1_1_1_4_openapi_yaml__validate index ac78d6dd1..e7ace4883 100644 --- a/openapi3/testdata/apis_guru_openapi_directory/github_com_ghes_3_1_1_1_4_openapi_yaml__validate +++ b/openapi3/testdata/apis_guru_openapi_directory/github_com_ghes_3_1_1_1_4_openapi_yaml__validate @@ -1 +1 @@ -invalid components: schema "announcement": invalid example: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)[0-9]{2}:[0-9]{2})$" +invalid components: schema "announcement": invalid example: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)([0-1][0-9]|2[0-3]):[0-5][0-9])$" diff --git a/openapi3/testdata/apis_guru_openapi_directory/github_com_ghes_3_2_1_1_4_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/github_com_ghes_3_2_1_1_4_openapi_yaml__validate index ac78d6dd1..e7ace4883 100644 --- a/openapi3/testdata/apis_guru_openapi_directory/github_com_ghes_3_2_1_1_4_openapi_yaml__validate +++ b/openapi3/testdata/apis_guru_openapi_directory/github_com_ghes_3_2_1_1_4_openapi_yaml__validate @@ -1 +1 @@ -invalid components: schema "announcement": invalid example: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)[0-9]{2}:[0-9]{2})$" +invalid components: schema "announcement": invalid example: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)([0-1][0-9]|2[0-3]):[0-5][0-9])$" diff --git a/openapi3/testdata/apis_guru_openapi_directory/github_com_ghes_3_3_1_1_4_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/github_com_ghes_3_3_1_1_4_openapi_yaml__validate index ac78d6dd1..e7ace4883 100644 --- a/openapi3/testdata/apis_guru_openapi_directory/github_com_ghes_3_3_1_1_4_openapi_yaml__validate +++ b/openapi3/testdata/apis_guru_openapi_directory/github_com_ghes_3_3_1_1_4_openapi_yaml__validate @@ -1 +1 @@ -invalid components: schema "announcement": invalid example: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)[0-9]{2}:[0-9]{2})$" +invalid components: schema "announcement": invalid example: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)([0-1][0-9]|2[0-3]):[0-5][0-9])$" diff --git a/openapi3/testdata/apis_guru_openapi_directory/github_com_ghes_3_4_1_1_4_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/github_com_ghes_3_4_1_1_4_openapi_yaml__validate index ac78d6dd1..e7ace4883 100644 --- a/openapi3/testdata/apis_guru_openapi_directory/github_com_ghes_3_4_1_1_4_openapi_yaml__validate +++ b/openapi3/testdata/apis_guru_openapi_directory/github_com_ghes_3_4_1_1_4_openapi_yaml__validate @@ -1 +1 @@ -invalid components: schema "announcement": invalid example: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)[0-9]{2}:[0-9]{2})$" +invalid components: schema "announcement": invalid example: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)([0-1][0-9]|2[0-3]):[0-5][0-9])$" diff --git a/openapi3/testdata/apis_guru_openapi_directory/github_com_ghes_3_5_1_1_4_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/github_com_ghes_3_5_1_1_4_openapi_yaml__validate index ac78d6dd1..e7ace4883 100644 --- a/openapi3/testdata/apis_guru_openapi_directory/github_com_ghes_3_5_1_1_4_openapi_yaml__validate +++ b/openapi3/testdata/apis_guru_openapi_directory/github_com_ghes_3_5_1_1_4_openapi_yaml__validate @@ -1 +1 @@ -invalid components: schema "announcement": invalid example: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)[0-9]{2}:[0-9]{2})$" +invalid components: schema "announcement": invalid example: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)([0-1][0-9]|2[0-3]):[0-5][0-9])$" diff --git a/openapi3/testdata/apis_guru_openapi_directory/github_com_ghes_3_6_1_1_4_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/github_com_ghes_3_6_1_1_4_openapi_yaml__validate index ac78d6dd1..e7ace4883 100644 --- a/openapi3/testdata/apis_guru_openapi_directory/github_com_ghes_3_6_1_1_4_openapi_yaml__validate +++ b/openapi3/testdata/apis_guru_openapi_directory/github_com_ghes_3_6_1_1_4_openapi_yaml__validate @@ -1 +1 @@ -invalid components: schema "announcement": invalid example: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)[0-9]{2}:[0-9]{2})$" +invalid components: schema "announcement": invalid example: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)([0-1][0-9]|2[0-3]):[0-5][0-9])$" diff --git a/openapi3/testdata/apis_guru_openapi_directory/github_com_ghes_3_7_1_1_4_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/github_com_ghes_3_7_1_1_4_openapi_yaml__validate index ac78d6dd1..e7ace4883 100644 --- a/openapi3/testdata/apis_guru_openapi_directory/github_com_ghes_3_7_1_1_4_openapi_yaml__validate +++ b/openapi3/testdata/apis_guru_openapi_directory/github_com_ghes_3_7_1_1_4_openapi_yaml__validate @@ -1 +1 @@ -invalid components: schema "announcement": invalid example: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)[0-9]{2}:[0-9]{2})$" +invalid components: schema "announcement": invalid example: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)([0-1][0-9]|2[0-3]):[0-5][0-9])$" diff --git a/openapi3/testdata/apis_guru_openapi_directory/github_com_ghes_3_8_1_1_4_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/github_com_ghes_3_8_1_1_4_openapi_yaml__validate index ac78d6dd1..e7ace4883 100644 --- a/openapi3/testdata/apis_guru_openapi_directory/github_com_ghes_3_8_1_1_4_openapi_yaml__validate +++ b/openapi3/testdata/apis_guru_openapi_directory/github_com_ghes_3_8_1_1_4_openapi_yaml__validate @@ -1 +1 @@ -invalid components: schema "announcement": invalid example: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)[0-9]{2}:[0-9]{2})$" +invalid components: schema "announcement": invalid example: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)([0-1][0-9]|2[0-3]):[0-5][0-9])$" diff --git a/openapi3/testdata/apis_guru_openapi_directory/github_com_github_ae_1_1_4_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/github_com_github_ae_1_1_4_openapi_yaml__validate index ac78d6dd1..e7ace4883 100644 --- a/openapi3/testdata/apis_guru_openapi_directory/github_com_github_ae_1_1_4_openapi_yaml__validate +++ b/openapi3/testdata/apis_guru_openapi_directory/github_com_github_ae_1_1_4_openapi_yaml__validate @@ -1 +1 @@ -invalid components: schema "announcement": invalid example: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)[0-9]{2}:[0-9]{2})$" +invalid components: schema "announcement": invalid example: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)([0-1][0-9]|2[0-3]):[0-5][0-9])$" diff --git a/openapi3/testdata/apis_guru_openapi_directory/linode_com_4_151_1_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/linode_com_4_151_1_openapi_yaml__validate index 66be7cc5e..6639a349a 100644 --- a/openapi3/testdata/apis_guru_openapi_directory/linode_com_4_151_1_openapi_yaml__validate +++ b/openapi3/testdata/apis_guru_openapi_directory/linode_com_4_151_1_openapi_yaml__validate @@ -1 +1 @@ -invalid components: schema "Account": invalid example: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)[0-9]{2}:[0-9]{2})$" +invalid components: schema "Account": invalid example: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)([0-1][0-9]|2[0-3]):[0-5][0-9])$" diff --git a/openapi3/testdata/apis_guru_openapi_directory/meteosource_com_v1_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/meteosource_com_v1_openapi_yaml__validate index 725c955fe..fcfad3045 100644 --- a/openapi3/testdata/apis_guru_openapi_directory/meteosource_com_v1_openapi_yaml__validate +++ b/openapi3/testdata/apis_guru_openapi_directory/meteosource_com_v1_openapi_yaml__validate @@ -1 +1 @@ -invalid components: schema "AirQuality_PointData": invalid example: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)[0-9]{2}:[0-9]{2})$" +invalid components: schema "AirQuality_PointData": invalid example: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)([0-1][0-9]|2[0-3]):[0-5][0-9])$" diff --git a/openapi3/testdata/apis_guru_openapi_directory/sinao_app_1_1_0_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/sinao_app_1_1_0_openapi_yaml__validate index b5e336dba..d55e1273d 100644 --- a/openapi3/testdata/apis_guru_openapi_directory/sinao_app_1_1_0_openapi_yaml__validate +++ b/openapi3/testdata/apis_guru_openapi_directory/sinao_app_1_1_0_openapi_yaml__validate @@ -1 +1 @@ -invalid paths: invalid path /apps/{appId}/productstocks/{id}/rental/back: invalid operation POST: parameter "current_return_date" schema is invalid: invalid default: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)[0-9]{2}:[0-9]{2})$" +invalid paths: invalid path /apps/{appId}/productstocks/{id}/rental/back: invalid operation POST: parameter "current_return_date" schema is invalid: invalid default: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)([0-1][0-9]|2[0-3]):[0-5][0-9])$" diff --git a/openapi3/testdata/apis_guru_openapi_directory/spinitron_com_1_0_0_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/spinitron_com_1_0_0_openapi_yaml__validate index e2a9c0f22..86c796bc9 100644 --- a/openapi3/testdata/apis_guru_openapi_directory/spinitron_com_1_0_0_openapi_yaml__validate +++ b/openapi3/testdata/apis_guru_openapi_directory/spinitron_com_1_0_0_openapi_yaml__validate @@ -1 +1 @@ -invalid components: schema "Playlist": invalid example: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)[0-9]{2}:[0-9]{2})$" +invalid components: schema "Playlist": invalid example: string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)([0-1][0-9]|2[0-3]):[0-5][0-9])$" diff --git a/openapi3/testdata/apis_guru_openapi_directory/svix_com_1_4_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/svix_com_1_4_openapi_yaml__validate index 944cc3b93..7514ff3be 100644 --- a/openapi3/testdata/apis_guru_openapi_directory/svix_com_1_4_openapi_yaml__validate +++ b/openapi3/testdata/apis_guru_openapi_directory/svix_com_1_4_openapi_yaml__validate @@ -1 +1 @@ -invalid components: schema "EndpointDisabledEvent": invalid example: Error at "/data/failSince": string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)[0-9]{2}:[0-9]{2})$" +invalid components: schema "EndpointDisabledEvent": invalid example: Error at "/data/failSince": string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)([0-1][0-9]|2[0-3]):[0-5][0-9])$" diff --git a/openapi3/testdata/apis_guru_openapi_directory/trashnothing_com_1_3_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/trashnothing_com_1_3_openapi_yaml__validate index 9ce7a298e..533ccd743 100644 --- a/openapi3/testdata/apis_guru_openapi_directory/trashnothing_com_1_3_openapi_yaml__validate +++ b/openapi3/testdata/apis_guru_openapi_directory/trashnothing_com_1_3_openapi_yaml__validate @@ -1,4 +1,4 @@ -invalid components: schema "Feedback": invalid example: Error at "/date": string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)[0-9]{2}:[0-9]{2})$" | Error at "/reviewer_user_id": value must be a string +invalid components: schema "Feedback": invalid example: Error at "/date": string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)([0-1][0-9]|2[0-3]):[0-5][0-9])$" | Error at "/reviewer_user_id": value must be a string Schema: { "description": "The user ID of the user that submitted the feedback.", diff --git a/openapi3/testdata/apis_guru_openapi_directory/twitter_com_current_2_62_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/twitter_com_current_2_62_openapi_yaml__validate index 0a83aee3a..0cc186c6e 100644 --- a/openapi3/testdata/apis_guru_openapi_directory/twitter_com_current_2_62_openapi_yaml__validate +++ b/openapi3/testdata/apis_guru_openapi_directory/twitter_com_current_2_62_openapi_yaml__validate @@ -1,4 +1,4 @@ -invalid components: schema "Expansions": invalid example: Error at "/created_at": string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)[0-9]{2}:[0-9]{2})$" | Error at "/edit_history_tweet_ids": property "edit_history_tweet_ids" is missing +invalid components: schema "Expansions": invalid example: Error at "/created_at": string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)([0-1][0-9]|2[0-3]):[0-5][0-9])$" | Error at "/edit_history_tweet_ids": property "edit_history_tweet_ids" is missing Schema: { "example": { diff --git a/openapi3/testdata/apis_guru_openapi_directory/vtex_local_License_Manager_API_1_0_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/vtex_local_License_Manager_API_1_0_openapi_yaml__validate index b5896bc72..6148079b2 100644 --- a/openapi3/testdata/apis_guru_openapi_directory/vtex_local_License_Manager_API_1_0_openapi_yaml__validate +++ b/openapi3/testdata/apis_guru_openapi_directory/vtex_local_License_Manager_API_1_0_openapi_yaml__validate @@ -1 +1 @@ -invalid paths: invalid path /api/vlm/account: invalid operation GET: invalid example: Error at "/appKeys/0/createdIn": string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)[0-9]{2}:[0-9]{2})$" | Error at "/appKeys/1/createdIn": string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)[0-9]{2}:[0-9]{2})$" | Error at "/creationDate": string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)[0-9]{2}:[0-9]{2})$" +invalid paths: invalid path /api/vlm/account: invalid operation GET: invalid example: Error at "/appKeys/0/createdIn": string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)([0-1][0-9]|2[0-3]):[0-5][0-9])$" | Error at "/appKeys/1/createdIn": string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)([0-1][0-9]|2[0-3]):[0-5][0-9])$" | Error at "/creationDate": string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)([0-1][0-9]|2[0-3]):[0-5][0-9])$" diff --git a/openapi3/testdata/apis_guru_openapi_directory/zoom_us_2_0_0_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/zoom_us_2_0_0_openapi_yaml__validate index 9662cd931..ba710a57b 100644 --- a/openapi3/testdata/apis_guru_openapi_directory/zoom_us_2_0_0_openapi_yaml__validate +++ b/openapi3/testdata/apis_guru_openapi_directory/zoom_us_2_0_0_openapi_yaml__validate @@ -37,7 +37,7 @@ Schema: Value: "integer" - And Error at "/accounts/0/created_at": string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)[0-9]{2}:[0-9]{2})$" | Error at "/accounts/0/seats": value must be an integer + And Error at "/accounts/0/created_at": string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)([0-1][0-9]|2[0-3]):[0-5][0-9])$" | Error at "/accounts/0/seats": value must be an integer Schema: { "description": "Account seats.", @@ -46,4 +46,4 @@ Schema: Value: "integer" - | Error at "/accounts/0/subscription_end_time": string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)[0-9]{2}:[0-9]{2})$" | Error at "/accounts/0/subscription_start_time": string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)[0-9]{2}:[0-9]{2})$" + | Error at "/accounts/0/subscription_end_time": string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)([0-1][0-9]|2[0-3]):[0-5][0-9])$" | Error at "/accounts/0/subscription_start_time": string doesn't match the format "date-time": string doesn't match pattern "^[0-9]{4}-(0[1-9]|10|11|12)-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)([0-1][0-9]|2[0-3]):[0-5][0-9])$" From 4daab6cdc402cc8a2bf9fc348c400685e41871a9 Mon Sep 17 00:00:00 2001 From: yi111 <153097222+Yi-111-a@users.noreply.github.com> Date: Thu, 5 Nov 2026 16:06:14 +0800 Subject: [PATCH 66/78] openapi3: stop InternalizeRefs prefix trimming at the filesystem root (#1421) --- openapi3/internalize_refs.go | 3 ++- openapi3/internalize_refs_test.go | 37 +++++++++++++++++++++++++++++++ 2 files changed, 39 insertions(+), 1 deletion(-) diff --git a/openapi3/internalize_refs.go b/openapi3/internalize_refs.go index a908823f9..842cc987f 100644 --- a/openapi3/internalize_refs.go +++ b/openapi3/internalize_refs.go @@ -74,7 +74,8 @@ func DefaultRefNameResolver(doc *T, ref ComponentRef) string { // Trim the common prefix with the root doc path. if doc.url != nil && filePath != "" { - for commonDir := path.Dir(doc.url.Path); /*no common prefix*/ commonDir != "."; commonDir = path.Dir(commonDir) { + // path.Dir of an absolute path ends at "/", never at ".". + for commonDir := path.Dir(doc.url.Path); /*no common prefix*/ commonDir != "." && commonDir != "/"; commonDir = path.Dir(commonDir) { if p, found := cutDirectories(filePath, commonDir); found { filePath = p break diff --git a/openapi3/internalize_refs_test.go b/openapi3/internalize_refs_test.go index 402466440..2f5d8ce22 100644 --- a/openapi3/internalize_refs_test.go +++ b/openapi3/internalize_refs_test.go @@ -2,8 +2,10 @@ package openapi3_test import ( "os" + "path/filepath" "regexp" "testing" + "time" "github.com/stretchr/testify/require" @@ -74,3 +76,38 @@ func TestInternalizeRefs(t *testing.T) { }) } } + +func TestInternalizeRefsAbsolutePath(t *testing.T) { + t.Parallel() + + ctx := t.Context() + + filename, err := filepath.Abs("testdata/recursiveRef/openapi.yml") + require.NoError(t, err) + + sl := openapi3.NewLoader() + sl.IsExternalRefsAllowed = true + doc, err := sl.LoadFromFile(filename) + require.NoError(t, err, "loading test file") + + done := make(chan struct{}) + go func() { + defer close(done) + doc.InternalizeRefs(ctx, nil) + }() + select { + case <-done: + case <-time.After(10 * time.Second): + t.Fatal("InternalizeRefs did not return for a document loaded from an absolute path") + } + + err = doc.Validate(ctx) + require.NoError(t, err, "validating internalized spec") + + actual, err := doc.MarshalJSON() + require.NoError(t, err, "marshaling internalized spec") + + expected, err := os.ReadFile("testdata/recursiveRef/openapi.yml.internalized.yml") + require.NoError(t, err) + require.JSONEq(t, string(expected), string(actual)) +} From 06b0438f0efcc6f146878737de6a61ce9a3590ea Mon Sep 17 00:00:00 2001 From: Jeremy Levartovsky <140487034+JayOfTheKeyboard@users.noreply.github.com> Date: Fri, 6 Nov 2026 00:43:48 +1100 Subject: [PATCH 67/78] openapi3: resolve refs under a header's content (#1424) --- openapi3/loader.go | 5 ++ openapi3/loader_header_content_test.go | 63 ++++++++++++++++++++++++++ 2 files changed, 68 insertions(+) create mode 100644 openapi3/loader_header_content_test.go diff --git a/openapi3/loader.go b/openapi3/loader.go index e767e60d6..ddfc7d319 100644 --- a/openapi3/loader.go +++ b/openapi3/loader.go @@ -833,6 +833,11 @@ func (loader *Loader) resolveHeaderRef(doc *T, component *HeaderRef, documentPat return nil } + for _, name := range componentNames(value.Content) { + if err := loader.resolveMediaTypeRefs(doc, value.Content[name], documentPath); err != nil { + return err + } + } if schema := value.Schema; schema != nil { if err := loader.resolveSchemaRef(doc, schema, documentPath, []string{}); err != nil { return err diff --git a/openapi3/loader_header_content_test.go b/openapi3/loader_header_content_test.go new file mode 100644 index 000000000..db503a60f --- /dev/null +++ b/openapi3/loader_header_content_test.go @@ -0,0 +1,63 @@ +package openapi3_test + +import ( + "context" + "testing" + + "github.com/stretchr/testify/require" + + "github.com/getkin/kin-openapi/openapi3" +) + +func TestLoaderResolvesHeaderContent(t *testing.T) { + t.Parallel() + + spec := []byte(` +openapi: 3.0.0 +info: {title: t, version: "1"} +paths: + /x: + get: + responses: + '200': + description: d + headers: + h: + content: + application/json: + schema: {$ref: '#/components/schemas/S'} +components: + schemas: + S: {type: string} +`[1:]) + + loader := openapi3.NewLoader() + doc, err := loader.LoadFromData(spec) + require.NoError(t, err) + schema := doc.Paths.Value("/x").Get.Responses.Value("200").Value.Headers["h"].Value.Content["application/json"].Schema + require.NotNil(t, schema.Value) + require.NoError(t, doc.Validate(context.Background())) +} + +func TestLoaderRejectsNullSchemaInHeaderContent(t *testing.T) { + t.Parallel() + + spec := []byte(` +openapi: 3.0.0 +info: {title: t, version: "1"} +paths: {} +components: + headers: + h: + content: + application/json: + schema: + properties: + p: +`[1:]) + + loader := openapi3.NewLoader() + doc, err := loader.LoadFromData(spec) + require.EqualError(t, err, `invalid schema: value MUST be an object`) + require.Nil(t, doc) +} From 13bce606dca3ad8a3b119b813e07faf585d9a571 Mon Sep 17 00:00:00 2001 From: Firas Yousfi <135891367+fyousfi-ionos@users.noreply.github.com> Date: Thu, 5 Nov 2026 21:37:08 +0100 Subject: [PATCH 68/78] openapi3filter: reject an empty query value instead of filling in the default (#1427) --- openapi3filter/issue1255_test.go | 1 + openapi3filter/issue1426_test.go | 78 ++++++++++++++++++++++++++++++ openapi3filter/validate_request.go | 4 +- 3 files changed, 81 insertions(+), 2 deletions(-) create mode 100644 openapi3filter/issue1426_test.go diff --git a/openapi3filter/issue1255_test.go b/openapi3filter/issue1255_test.go index cd17eef32..8b1ed0845 100644 --- a/openapi3filter/issue1255_test.go +++ b/openapi3filter/issue1255_test.go @@ -22,6 +22,7 @@ paths: - name: flag in: query required: false + allowEmptyValue: true schema: type: boolean default: false diff --git a/openapi3filter/issue1426_test.go b/openapi3filter/issue1426_test.go new file mode 100644 index 000000000..22bbcedd4 --- /dev/null +++ b/openapi3filter/issue1426_test.go @@ -0,0 +1,78 @@ +package openapi3filter + +import ( + "net/http" + "testing" + + "github.com/stretchr/testify/require" +) + +func TestIssue1426EmptyQueryValueWithDefault(t *testing.T) { + t.Parallel() + + const spec = ` +openapi: 3.0.3 +info: + title: repro + version: 1.0.0 +paths: + /items: + get: + parameters: + - name: limit + in: query + schema: + type: integer + default: 100 + - name: offset + in: query + allowEmptyValue: true + schema: + type: integer + default: 0 + responses: + '200': + description: ok +` + + testcases := []struct { + name string + url string + wantErr error + wantQuery string + }{{ + name: "missing parameter gets the default", + url: "/items", + wantQuery: "limit=100&offset=0", + }, { + name: "empty parameter is rejected", + url: "/items?limit=", + wantErr: ErrInvalidEmptyValue, + }, { + name: "empty parameter with allowEmptyValue gets the default", + url: "/items?offset=", + wantQuery: "limit=100&offset=0", + }} + for _, tc := range testcases { + t.Run(tc.name, func(t *testing.T) { + req, err := http.NewRequest(http.MethodGet, tc.url, nil) + require.NoError(t, err) + + router := setupTestRouter(t, spec) + route, pathParams, err := router.FindRoute(req) + require.NoError(t, err) + + err = ValidateRequest(t.Context(), &RequestValidationInput{ + Request: req, + PathParams: pathParams, + Route: route, + }) + if tc.wantErr != nil { + require.ErrorIs(t, err, tc.wantErr) + return + } + require.NoError(t, err) + require.Equal(t, tc.wantQuery, req.URL.RawQuery) + }) + } +} diff --git a/openapi3filter/validate_request.go b/openapi3filter/validate_request.go index 30bcb92cf..eca486bd8 100644 --- a/openapi3filter/validate_request.go +++ b/openapi3filter/validate_request.go @@ -197,8 +197,8 @@ func ValidateParameter(ctx context.Context, input *RequestValidationInput, param schema = parameter.Schema.Value } - // Set default value if needed - if !options.SkipSettingDefaults && value == nil && schema != nil { + // Set the default only when the parameter is not sent, or sent empty with allowEmptyValue: true + if !options.SkipSettingDefaults && value == nil && (!found || parameter.AllowEmptyValue) && schema != nil { value = schema.Default for _, subSchema := range schema.AllOf { if subSchema.Value.Default != nil { From 74fda395d76696dbefa00fb56d54705d7d3c8449 Mon Sep 17 00:00:00 2001 From: Xinliang Zheng Date: Fri, 6 Nov 2026 04:43:02 +0800 Subject: [PATCH 69/78] openapi3: reuse root components when internalizing refs (#1425) --- openapi3/helpers.go | 7 +- openapi3/internalize_refs_test.go | 104 ++++++++++++++++++ .../recursiveRef/openapi.yml.internalized.yml | 38 ++----- .../testref.openapi.yml.internalized.yml | 6 +- 4 files changed, 116 insertions(+), 39 deletions(-) diff --git a/openapi3/helpers.go b/openapi3/helpers.go index 62e8457cc..fd606a6b6 100644 --- a/openapi3/helpers.go +++ b/openapi3/helpers.go @@ -232,12 +232,9 @@ func ReferencesComponentInRootDocument(doc *T, ref ComponentRef) (string, bool) // Something like: ../openapi.yaml#/components/schemas/myElement for _, name := range componentNames(components) { s := components[name] - // Must be a reference to a YAML file. - if !isWholeDocumentReference(s.RefString()) { - continue - } - // Is the schema a ref to the same resource. + // The resolved path retains the target and fragment even when + // internalization has cleared or rewritten the component's Ref. if !refersToSameDocument(s, ref) { continue } diff --git a/openapi3/internalize_refs_test.go b/openapi3/internalize_refs_test.go index 2f5d8ce22..e58942d9d 100644 --- a/openapi3/internalize_refs_test.go +++ b/openapi3/internalize_refs_test.go @@ -1,6 +1,7 @@ package openapi3_test import ( + "fmt" "os" "path/filepath" "regexp" @@ -77,6 +78,109 @@ func TestInternalizeRefs(t *testing.T) { } } +func TestInternalizeRefsReusesRootSchema(t *testing.T) { + t.Parallel() + + for _, version := range []string{"3.0.3", "3.1.0"} { + for _, fragment := range []bool{false, true} { + for _, wrapper := range []string{"Box", "Wrapper"} { + t.Run(fmt.Sprintf("%s/fragment=%t/%s", version, fragment, wrapper), func(t *testing.T) { + t.Parallel() + + dir := t.TempDir() + itemRef, wrapperRef := "./schemas/Item.yaml", "./schemas/Wrapper.yaml" + files := map[string]string{ + "schemas/Item.yaml": "type: string\n", + "schemas/Wrapper.yaml": `type: object +properties: + item: + $ref: ./Item.yaml +`, + } + if fragment { + itemRef = "./common.yaml#/components/schemas/Item" + wrapperRef = "./common.yaml#/components/schemas/Wrapper" + files = map[string]string{ + "common.yaml": `components: + schemas: + Item: + type: string + Wrapper: + type: object + properties: + item: + $ref: '#/components/schemas/Item' +`, + } + } + files["openapi.yaml"] = fmt.Sprintf(`openapi: %s +info: + title: Root component references + version: "1" +paths: + /item: + get: + responses: + "200": + description: An item + content: + application/json: + schema: + $ref: %s + "201": + description: A wrapper + content: + application/json: + schema: + $ref: %s +components: + schemas: + Item: + $ref: %s + %s: + $ref: %s +`, version, itemRef, wrapperRef, itemRef, wrapper, wrapperRef) + for name, data := range files { + filename := filepath.Join(dir, name) + require.NoError(t, os.MkdirAll(filepath.Dir(filename), 0o700)) + require.NoError(t, os.WriteFile(filename, []byte(data), 0o600)) + } + + loader := openapi3.NewLoader() + loader.IsExternalRefsAllowed = true + doc, err := loader.LoadFromFile(filepath.Join(dir, "openapi.yaml")) + require.NoError(t, err) + require.NoError(t, doc.Validate(t.Context())) + + doc.InternalizeRefs(t.Context(), nil) + + require.Len(t, doc.Components.Schemas, 2) + require.Empty(t, doc.Components.Schemas["Item"].Ref) + require.Empty(t, doc.Components.Schemas[wrapper].Ref) + require.Equal(t, "#/components/schemas/Item", doc.Components.Schemas[wrapper].Value.Properties["item"].Ref) + responseSchema := doc.Paths.Value("/item").Get.Responses.Status(200).Value.Content.Get("application/json").Schema + require.Equal(t, "#/components/schemas/Item", responseSchema.Ref) + wrapperSchema := doc.Paths.Value("/item").Get.Responses.Status(201).Value.Content.Get("application/json").Schema + require.Equal(t, "#/components/schemas/"+wrapper, wrapperSchema.Ref) + require.NoError(t, doc.Validate(t.Context())) + + data, err := doc.MarshalJSON() + require.NoError(t, err) + internalLoader := openapi3.NewLoader() + reloaded, err := internalLoader.LoadFromData(data) + require.NoError(t, err) + require.NoError(t, reloaded.Validate(t.Context())) + + doc.InternalizeRefs(t.Context(), nil) + again, err := doc.MarshalJSON() + require.NoError(t, err) + require.JSONEq(t, string(data), string(again)) + }) + } + } + } +} + func TestInternalizeRefsAbsolutePath(t *testing.T) { t.Parallel() diff --git a/openapi3/testdata/recursiveRef/openapi.yml.internalized.yml b/openapi3/testdata/recursiveRef/openapi.yml.internalized.yml index a987ab095..9eb4ef047 100644 --- a/openapi3/testdata/recursiveRef/openapi.yml.internalized.yml +++ b/openapi3/testdata/recursiveRef/openapi.yml.internalized.yml @@ -22,38 +22,26 @@ } }, "schemas": { - "components_Bar": { + "Bar": { "example": "bar", "type": "string" }, - "components_Foo": { + "Cat": { "properties": { - "bar": { - "$ref": "#/components/schemas/components_Bar" + "cat": { + "$ref": "#/components/schemas/Cat" } }, "type": "object" }, - "components_Foo_Foo2": { - "properties": { - "foo": { - "$ref": "#/components/schemas/components_Foo" - } - }, + "Error": { + "title": "ErrorDetails", "type": "object" }, - "Bar": { - "example": "bar", - "type": "string" - }, - "Error":{ - "title":"ErrorDetails", - "type":"object" - }, "Foo": { "properties": { "bar": { - "$ref": "#/components/schemas/components_Bar" + "$ref": "#/components/schemas/Bar" } }, "type": "object" @@ -61,15 +49,7 @@ "Foo2": { "properties": { "foo": { - "$ref": "#/components/schemas/components_Foo" - } - }, - "type": "object" - }, - "Cat": { - "properties": { - "cat": { - "$ref": "#/components/schemas/Cat" + "$ref": "#/components/schemas/Foo" } }, "type": "object" @@ -102,7 +82,7 @@ "schema": { "properties": { "foo2": { - "$ref": "#/components/schemas/components_Foo_Foo2" + "$ref": "#/components/schemas/Foo2" } }, "type": "object" diff --git a/openapi3/testdata/testref.openapi.yml.internalized.yml b/openapi3/testdata/testref.openapi.yml.internalized.yml index cf4856d8a..16bcd9997 100644 --- a/openapi3/testdata/testref.openapi.yml.internalized.yml +++ b/openapi3/testdata/testref.openapi.yml.internalized.yml @@ -3,9 +3,6 @@ "schemas": { "AnotherTestSchema": { "type": "string" - }, - "components.openapi_Name": { - "type": "string" } } }, @@ -14,6 +11,5 @@ "version": "1" }, "openapi": "3.0.0", - "paths": { - } + "paths": {} } From 352287abab6fa0d2db6287fa887f008050a31791 Mon Sep 17 00:00:00 2001 From: nk-batman21 <40377381+nk-batman21@users.noreply.github.com> Date: Fri, 6 Nov 2026 14:30:03 +0700 Subject: [PATCH 70/78] openapi3filter: read OpenAPI 3.1 contentMediaType data without a registered decoder (#1388) --- openapi3filter/req_resp_decoder.go | 3 +- openapi3filter/upload_arbitrary_file_test.go | 91 ++++++++++++++++++++ 2 files changed, 93 insertions(+), 1 deletion(-) diff --git a/openapi3filter/req_resp_decoder.go b/openapi3filter/req_resp_decoder.go index dddb1d902..8303ea0ec 100644 --- a/openapi3filter/req_resp_decoder.go +++ b/openapi3filter/req_resp_decoder.go @@ -1459,7 +1459,8 @@ func decodeBody(body io.Reader, header http.Header, schema *openapi3.SchemaRef, // A binary part with no registered decoder (e.g. image/png) is read as // raw bytes: encoding.contentType restricts the accepted media types but // does not require a registered decoder. - if isBinary(schema) { + // OpenAPI 3.1 describes such data with contentMediaType instead. + if isBinary(schema) || (schema != nil && schema.Value != nil && schema.Value.ContentMediaType != "") { value, err := FileBodyDecoder(body, header, schema, encFn) return mediaType, value, err } diff --git a/openapi3filter/upload_arbitrary_file_test.go b/openapi3filter/upload_arbitrary_file_test.go index c2e357d4b..075755878 100644 --- a/openapi3filter/upload_arbitrary_file_test.go +++ b/openapi3filter/upload_arbitrary_file_test.go @@ -115,3 +115,94 @@ paths: } } } + +func TestValidateUploadBinaryFileOpenAPI31(t *testing.T) { + t.Parallel() + + // OpenAPI 3.1 describes binary data with contentMediaType instead of format: binary. + const spec = ` +openapi: 3.1.0 +info: + title: 'Validator' + version: 0.0.1 +paths: + /test: + post: + requestBody: + required: true + content: + multipart/form-data: + schema: + type: object + properties: + image: + contentMediaType: image/png + typedImage: + type: string + contentMediaType: image/png + encodedImage: + type: string + contentMediaType: image/png + contentEncoding: base64 + text: + type: string + responses: + '200': + description: Created +` + + loader := openapi3.NewLoader() + doc, err := loader.LoadFromData([]byte(spec)) + require.NoError(t, err) + + err = doc.Validate(loader.Context) + require.NoError(t, err) + + router, err := gorillamux.NewRouter(doc) + require.NoError(t, err) + + tests := []struct { + part, data, wantErr string + }{ + {part: "image", data: "\x89PNG\r\n\x1a\n"}, + {part: "typedImage", data: "\x89PNG\r\n\x1a\n"}, + {part: "encodedImage", data: "iVBORw0KGgo="}, + {part: "text", data: "\x89PNG\r\n\x1a\n", wantErr: `unsupported content type "image/png"`}, + } + for _, tt := range tests { + t.Run(tt.part, func(t *testing.T) { + body := &bytes.Buffer{} + writer := multipart.NewWriter(body) + h := make(textproto.MIMEHeader) + h.Set("Content-Disposition", `form-data; name="`+tt.part+`"; filename="image.png"`) + h.Set("Content-Type", "image/png") + fw, err := writer.CreatePart(h) + require.NoError(t, err) + _, err = fw.Write([]byte(tt.data)) + require.NoError(t, err) + require.NoError(t, writer.Close()) + + req, err := http.NewRequest(http.MethodPost, "/test", body) + require.NoError(t, err) + req.Header.Set("Content-Type", writer.FormDataContentType()) + + route, pathParams, err := router.FindRoute(req) + require.NoError(t, err) + + err = openapi3filter.ValidateRequestBody( + t.Context(), + &openapi3filter.RequestValidationInput{ + Request: req, + PathParams: pathParams, + Route: route, + }, + route.Operation.RequestBody.Value, + ) + if tt.wantErr != "" { + require.ErrorContains(t, err, tt.wantErr) + return + } + require.NoError(t, err) + }) + } +} From 6f0e56106736cad3f581b2a806d971a18ab06c0e Mon Sep 17 00:00:00 2001 From: Pierre Fenoll Date: Fri, 6 Nov 2026 18:48:37 +0100 Subject: [PATCH 71/78] openapi3: validate the callbacks of an operation (#1429) Co-authored-by: Claude Opus 5.5 --- openapi3/callback.go | 31 +++++- openapi3/operation.go | 14 +++ openapi3/operation_test.go | 94 +++++++++++++++++++ openapi3/path_item.go | 7 +- .../fuzz/FuzzInternalizeRefs/2a6b863bcd9f692f | 3 + 5 files changed, 147 insertions(+), 2 deletions(-) create mode 100644 openapi3/testdata/fuzz/FuzzInternalizeRefs/2a6b863bcd9f692f diff --git a/openapi3/callback.go b/openapi3/callback.go index 6350d7947..05ef7eda6 100644 --- a/openapi3/callback.go +++ b/openapi3/callback.go @@ -37,13 +37,42 @@ func WithCallback(cb string, pathItem *PathItem) NewCallbackOption { // Validate returns an error if Callback does not comply with the OpenAPI spec. func (callback *Callback) Validate(ctx context.Context, opts ...ValidationOption) error { ctx = WithValidationOptions(ctx, opts...) + return callback.validate(ctx, nil) +} + +// validate skips the callbacks in visiting, those being validated further up: +// an operation of a callback may name that same callback among its own +// callbacks. +func (callback *Callback) validate(ctx context.Context, visiting map[*Callback]struct{}) error { + if _, ok := visiting[callback]; ok { + return nil + } + if visiting == nil { + visiting = make(map[*Callback]struct{}) + } + visiting[callback] = struct{}{} + defer delete(visiting, callback) for _, key := range callback.Keys() { v := callback.Value(key) - if err := v.Validate(ctx); err != nil { + if err := v.validate(ctx, visiting); err != nil { return err } } return validateExtensions(ctx, callback.Extensions, callback.Origin) } + +// validate is CallbackRef.Validate passing visiting on to Callback.validate. +func (x *CallbackRef) validate(ctx context.Context, visiting map[*Callback]struct{}) error { + if x == nil { + return newUnresolvedRef("", nil) + } + if err := x.validateExtras(ctx); err != nil { + return err + } + if v := x.Value; v != nil { + return v.validate(ctx, visiting) + } + return newUnresolvedRef(x.Ref, x.Origin) +} diff --git a/openapi3/operation.go b/openapi3/operation.go index 06ce48408..ff9eb1954 100644 --- a/openapi3/operation.go +++ b/openapi3/operation.go @@ -199,6 +199,11 @@ func (operation *Operation) AddResponse(status int, response *Response) { // Validate returns an error if Operation does not comply with the OpenAPI spec. func (operation *Operation) Validate(ctx context.Context, opts ...ValidationOption) error { ctx = WithValidationOptions(ctx, opts...) + return operation.validate(ctx, nil) +} + +// validate passes visiting on to Callback.validate. +func (operation *Operation) validate(ctx context.Context, visiting map[*Callback]struct{}) error { me := newErrCollector(ctx) if v := operation.Parameters; v != nil { @@ -223,6 +228,15 @@ func (operation *Operation) Validate(ctx context.Context, opts ...ValidationOpti } } + for _, name := range componentNames(operation.Callbacks) { + wrap := func(e error) error { + return &SectionValidationError{Section: "callback " + strconv.Quote(name), Cause: e} + } + if err := me.emitWrapped(wrap, operation.Callbacks[name].validate(ctx, visiting)); err != nil { + return err + } + } + if v := operation.ExternalDocs; v != nil { wrap := func(e error) error { return &SectionValidationError{Section: "external docs", Cause: e} } if err := me.emitWrapped(wrap, v.Validate(ctx)); err != nil { diff --git a/openapi3/operation_test.go b/openapi3/operation_test.go index 587e40fa9..eb3f50332 100644 --- a/openapi3/operation_test.go +++ b/openapi3/operation_test.go @@ -213,3 +213,97 @@ func TestOperationMissingResponsesWithMultiError(t *testing.T) { var target *openapi3.OperationResponsesRequired require.ErrorAs(t, err, &target) } + +func TestOperationValidatesCallbacks(t *testing.T) { + for _, tc := range []struct { + name, spec, err string + }{ + { + name: "invalid schema under a callback", + spec: ` +openapi: 3.0.3 +info: {title: t, version: "1"} +paths: + /a: + post: + responses: {"200": {description: d}} + callbacks: + cb: + '{$request.body#/url}': + post: + requestBody: + content: + application/json: + schema: {type: string, bogus: true} + responses: {"200": {description: d}} +`, + err: "extra sibling fields: [bogus]", + }, + { + name: "callback naming itself among its operation's callbacks", + spec: ` +openapi: 3.0.3 +info: {title: t, version: "1"} +paths: + /a: + post: + responses: {"200": {description: d}} + callbacks: + cb: {$ref: '#/components/callbacks/CB'} +components: + callbacks: + CB: + '{$request.body#/url}': + post: + responses: {"200": {description: d}} + callbacks: + again: {$ref: '#/components/callbacks/CB'} +`, + }, + { + name: "invalid schema under two callbacks naming each other", + spec: ` +openapi: 3.0.3 +info: {title: t, version: "1"} +paths: + /a: + post: + responses: {"200": {description: d}} + callbacks: + cb: {$ref: '#/components/callbacks/A'} +components: + callbacks: + A: + '{$request.body#/url}': + post: + responses: {"200": {description: d}} + callbacks: + toB: {$ref: '#/components/callbacks/B'} + B: + '{$request.body#/url}': + post: + requestBody: + content: + application/json: + schema: {type: string, bogus: true} + responses: {"200": {description: d}} + callbacks: + toA: {$ref: '#/components/callbacks/A'} +`, + err: "extra sibling fields: [bogus]", + }, + } { + t.Run(tc.name, func(t *testing.T) { + loader := openapi3.NewLoader() + doc, err := loader.LoadFromData([]byte(tc.spec)) + require.NoError(t, err) + err = doc.Validate(t.Context()) + if tc.err == "" { + require.NoError(t, err) + return + } + require.ErrorContains(t, err, `invalid callback "`) + require.ErrorContains(t, err, tc.err) + }) + } +} diff --git a/openapi3/path_item.go b/openapi3/path_item.go index 9a7129cd3..6560c99c2 100644 --- a/openapi3/path_item.go +++ b/openapi3/path_item.go @@ -346,6 +346,11 @@ func (pathItem *PathItem) SetOperation(method string, operation *Operation) { // Validate returns an error if PathItem does not comply with the OpenAPI spec. func (pathItem *PathItem) Validate(ctx context.Context, opts ...ValidationOption) error { ctx = WithValidationOptions(ctx, opts...) + return pathItem.validate(ctx, nil) +} + +// validate passes visiting on to Callback.validate. +func (pathItem *PathItem) validate(ctx context.Context, visiting map[*Callback]struct{}) error { me := newErrCollector(ctx) if !getValidationOptions(ctx).isOpenAPI32OrLater { @@ -388,7 +393,7 @@ func (pathItem *PathItem) Validate(ctx context.Context, opts ...ValidationOption for _, method := range componentNames(operations) { operation := operations[method] wrapOp := func(e error) error { return &OperationValidationError{Method: method, Cause: e} } - if err := me.emitWrapped(wrapOp, operation.Validate(ctx)); err != nil { + if err := me.emitWrapped(wrapOp, operation.validate(ctx, visiting)); err != nil { return err } } diff --git a/openapi3/testdata/fuzz/FuzzInternalizeRefs/2a6b863bcd9f692f b/openapi3/testdata/fuzz/FuzzInternalizeRefs/2a6b863bcd9f692f new file mode 100644 index 000000000..7a280aba6 --- /dev/null +++ b/openapi3/testdata/fuzz/FuzzInternalizeRefs/2a6b863bcd9f692f @@ -0,0 +1,3 @@ +go test fuzz v1 +[]byte("openapi: '3'\ninfo:\n version: 0.0.1\n title: 'test'\npaths:\n /test1:\n post:\n requestBody:\n content:\n application/json:\n schema:\n type: object\n responses:\n '200':\n description: 'test'\n callbacks:\n callback1:\n '{$request.body#/callback}':\n post:\n requestBody:\n content:\n application/json:\n schema:\n $ref: '#/components/schemas/test'\n responses:\n '200':\n description: 'test'\n /test2:\n post:\n requestBody:\n content:\n plication/json:\n schema:\n type: object\n responses:\n '200':\n description: 'test'\n callbacks:\n callback2:\n '{$request.body#/callback}':\n post:\n requestBody:\n content:\n application/json:\n schema:\n $ref: ' ents/schemas/test'\n responses:\n '200':\n description: 'test'\ncomponents:\n schemas:\n test:\n type: string\n") +[]byte("openapi: '3'\ninfo:\n version: 0.0.1\n title: 'test'\npaths:\n /test1:\n post:\n requestBody:\n content:\n application/json:\n schema:\n type: object\n responses:\n '200':\n description: 'test'\n callbacks:\n callback1:\n '{$request.body#/callback}':\n post:\n requestBody:\n content:\n application/json:\n schema:\n $ref: '#/components/schemas/test'\n responses:\n '200':\n description: 'test'\n /test2:\n post:\n requestBody:\n content:\n application/json:\n schema:\n type: object\n responses:\n '200':\n description: 'test'\n callbacks:\n callback2:\n '{$request.body#/callback}':\n post:\n requestBody:\n content:\n application/json:\n schema:\n $ref: '#/components/schemas/test'\n responses:\n '200':\n description: 'test'\ncomponents:\n schemas:\n test:\n type: string\n") From 83df2b6b7f15623739fb6ecfee15411d925210f2 Mon Sep 17 00:00:00 2001 From: Pierre Fenoll Date: Fri, 6 Nov 2026 19:05:42 +0100 Subject: [PATCH 72/78] fuzzing: add ./fetch-fuzz-crashers.sh [--days N] (#1428) Signed-off-by: Pierre Fenoll --- .github/workflows/go.yml | 5 +- fetch-fuzz-crashers.sh | 243 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 245 insertions(+), 3 deletions(-) create mode 100755 fetch-fuzz-crashers.sh diff --git a/.github/workflows/go.yml b/.github/workflows/go.yml index bb01caff0..f35394a73 100644 --- a/.github/workflows/go.yml +++ b/.github/workflows/go.yml @@ -77,9 +77,8 @@ jobs: # TODO: drop once 1.26 & 1.27 Go no longer experiences flaky memory corruptions - if: runner.os == 'Windows' run: | - for i in 1 2 3 4 5; do + for _ in $(seq 1 20); do go test -count=10 -short ./... && exit 0 - echo "::warning::attempt $i/5 failed" done exit 1 - run: go test -count=2 -short -covermode=atomic ./... @@ -102,7 +101,7 @@ jobs: - if: runner.os == 'Linux' name: Did you mean %q run: | - ! git grep -E "'[%].'" + ! git grep -E "'[%].'" -- '*.go' '*.tmpl' - if: runner.os == 'Linux' name: Also add yaml tags diff --git a/fetch-fuzz-crashers.sh b/fetch-fuzz-crashers.sh new file mode 100755 index 000000000..ca74b5671 --- /dev/null +++ b/fetch-fuzz-crashers.sh @@ -0,0 +1,243 @@ +#!/usr/bin/env bash +# fetch-fuzz-crashers.sh — pull the failing inputs that the `fuzz` workflow +# uploaded (artifacts named crashers-) for runs on master, drop +# each one into /testdata/fuzz//, and keep only those that +# still fail on the current checkout, one per distinct failure. +# +# No gh and no auth needed: artifacts are listed through the public REST API +# (60 requests/hour anonymously; one request per 100 artifacts) and, since +# GitHub refuses anonymous artifact downloads even on public repos, fetched +# through https://nightly.link. If GITHUB_TOKEN is set it is used instead, +# for both listing and downloading, straight from api.github.com. +# +# Inputs that fail the same way are duplicates; only the smallest is kept. +# "The same way" is: a panic or fatal error raised from the same kin-openapi +# function and line, a stack overflow cycling through the same kin-openapi +# functions, a timeout stuck in the same place, or a test failure reported +# from the same line with the same message (numbers and quoted text ignored). +# +# Usage: ./fetch-fuzz-crashers.sh [--days N] +# --days N look back N days (default 30; GitHub keeps artifacts 90 days) +# +# Env: REPO (getkin/kin-openapi), TEST_TIMEOUT (60s), GITHUB_TOKEN (optional) +# Requires: bash 4+, curl, jq, unzip, go. Run from the root of a kin-openapi +# checkout. Prints the kept files on stdout, e.g. for `| xargs git add`. + +set -euo pipefail + +REPO=${REPO:-getkin/kin-openapi} +TEST_TIMEOUT=${TEST_TIMEOUT:-60s} +DAYS=30 +MODULE=github.com/getkin/kin-openapi/ + +log() { printf '\033[1;34m==>\033[0m %s\n' "$*" >&2; } +warn() { printf '\033[1;33m!!\033[0m %s\n' "$*" >&2; } +die() { printf '\033[1;31mxx\033[0m %s\n' "$*" >&2; exit 1; } +cmd() { # echo a command, single-quoting the args that need it + local a q= + for a; do + if [[ $a =~ ^[A-Za-z0-9_./=:,+-]+$ ]]; then q+=" $a"; else q+=" '${a//\'/\'\\\'\'}'"; fi + done + printf '\033[2m $%s\033[0m\n' "$q" >&2 +} +crash() { printf '\033[1;31m CRASH\033[0m \033[1m%s\033[0m\n' "$*" >&2; } +usage() { sed -n '2,/^$/p' "$0" | sed 's/^# \{0,1\}//'; exit "${1:-0}"; } + +while (($#)); do + case $1 in + --days) [[ ${2:-} =~ ^[0-9]+$ ]] || die "--days needs a number"; DAYS=$2; shift ;; + -h|--help) usage ;; + *) warn "unknown argument: $1"; usage 1 ;; + esac + shift +done + +for bin in curl jq unzip go; do + command -v "$bin" >/dev/null || die "missing dependency: $bin" +done +grep -q "^module ${MODULE%/}\$" go.mod 2>/dev/null \ + || die "run this from the root of a kin-openapi checkout" + +# GNU date, then BSD/macOS date +since=$(date -u -d "-$DAYS days" +%Y-%m-%dT%H:%M:%SZ 2>/dev/null \ + || date -u -v "-${DAYS}d" +%Y-%m-%dT%H:%M:%SZ) + +auth=() +[[ -n ${GITHUB_TOKEN:-} ]] && auth=(-H "Authorization: Bearer $GITHUB_TOKEN") +api() { curl -fsSL "${auth[@]}" -H 'Accept: application/vnd.github+json' "https://api.github.com/$1"; } + +tmp=$(mktemp -d); trap 'rm -rf "$tmp"' EXIT + +# ------------------------------------------------------------ list ---- +# Repo-wide artifact list, newest first: stop paging once past $since. +# Keep crashers-* from runs on master of this repo itself (fork PRs from a +# branch that happens to be called master have a different head repo). +log "listing crashers-* artifacts from master since $since" +: >"$tmp/artifacts.tsv" +page=1 +while :; do + json=$(api "repos/$REPO/actions/artifacts?per_page=100&page=$page") \ + || die "GitHub API request failed (anonymous rate limit is 60/hour; set GITHUB_TOKEN?)" + jq -r --arg since "$since" '.artifacts[] + | select(.created_at >= $since and (.expired | not) + and (.name | startswith("crashers-")) + and .workflow_run.head_branch == "master" + and .workflow_run.head_repository_id == .workflow_run.repository_id) + | [.id, .name, .workflow_run.id, .created_at] | @tsv' <<<"$json" >>"$tmp/artifacts.tsv" + # The order is only roughly by date: page on until a whole page is too old. + n=$(jq '.artifacts | length' <<<"$json") + newest=$(jq -r '[.artifacts[].created_at] | max // ""' <<<"$json") + ((n == 100)) && [[ $newest > $since ]] || break + ((page++)) +done +total=$(wc -l <"$tmp/artifacts.tsv" | tr -d ' ') +((total)) || { log "no crasher artifacts in the last $DAYS days"; exit 0; } +log "$total artifacts" + +# ------------------------------------------------------- download ---- +download() { # $1 artifact id $2 output zip + if [[ -n ${GITHUB_TOKEN:-} ]]; then + curl -fsSL "${auth[@]}" -o "$2" "https://api.github.com/repos/$REPO/actions/artifacts/$1/zip" + else + curl -fsSL -o "$2" "https://nightly.link/$REPO/actions/artifacts/$1.zip" + fi +} + +# Fuzz target -> package dir, from where `func FuzzX(f *testing.F)` lives. +declare -A pkg_of=() +pkg_for() { # $1 target + if [[ -z ${pkg_of[$1]+x} ]]; then + local f; f=$(grep -rlE --include='*_test.go' "^func $1\(f \*testing\.F\)" . || true) + f=${f%%$'\n'*} + pkg_of[$1]=${f:+$(dirname "${f#./}")} + fi + printf '%s' "${pkg_of[$1]}" +} + +# Returns 0 = input fails (reproduces), 1 = passes, 2 = could not run. +replay() { # $1 pkg dir $2 target $3 corpus file name $4 logfile + local rc=0 args=(go test -count=1 -timeout "$TEST_TIMEOUT" -run "^$2\$/^$3\$" -v "./$1") + cmd "${args[@]}" + "${args[@]}" >"$4" 2>&1 || rc=$? + if grep -qE '\[build failed\]|\[setup failed\]|^# ' "$4"; then return 2; fi + if ((rc == 0)); then + grep -qE -- "--- PASS: $2/$3( |$)" "$4" && return 1 + return 2 # exit 0 but the entry never ran + fi + grep -qE -- '--- FAIL:|^panic:|test timed out|fatal error:' "$4" && return 0 + return 2 +} + +# kin-openapi frames of goroutine dumps in a log, as " ", +# with call arguments and absolute paths dropped. +module_frames() { # $1 logfile + awk -v mod="$MODULE" ' + /^goroutine [0-9]+ .*\[.*\]:$/ { g++; next } # "goroutine 7 [running]:", or with gp=… m=… after fatal errors + g && /^[^\t]/ && index($0, mod) == 1 { + fn = substr($0, length(mod) + 1); sub(/\([^()]*\)$/, "", fn) + if ((getline loc) <= 0) exit + sub(/^\t/, "", loc); sub(/ \+0x.*$/, "", loc); n = split(loc, p, "/") # also drops fp= sp= pc= + print g, fn, p[n] + }' "$1" +} + +# One line naming how an input fails, so that the same bug found through +# different inputs (or different targets) collapses to one signature. +signature() { # $1 logfile $2 target + local log=$1 s + if grep -qE '^(runtime: goroutine stack exceeds|fatal error: stack overflow)' "$log"; then + # The overflow can hit anywhere in the cycle: name the set of functions. + s=$(module_frames "$log" | awk '$1 == 1 && n++ < 200 { print $2 }' | sort -u | paste -sd, -) + printf 'stack overflow through %s' "${s:-?}" + elif grep -qE '^panic: test timed out' "$log"; then + # Goroutine dumps: first non-test kin-openapi frame found anywhere. + s=$(module_frames "$log" | awk '$3 !~ /_test\.go:/ { print $2, $3; exit }') + printf 'timeout in %s' "${s:-?}" + elif grep -qE '^(panic|fatal error):' "$log"; then + s=$(module_frames "$log" | awk '$1 == 1 { print $2, $3; exit }') + printf 'panic in %s' "${s:-?}" + else + # t.Error/t.Fatal (or testify): where it was reported, and what it said + # with the input-dependent bits (numbers, quoted text) blanked out. + s=$(awk ' + !loc && match($0, /^ +[A-Za-z0-9_]+\.go:[0-9]+: ?/) { + loc = substr($0, 1, RLENGTH); gsub(/^ +|: ?$/, "", loc) + msg = substr($0, RLENGTH + 1); next + } + loc && msg == "" && match($0, /^[ \t]*Error:[ \t]*/) { msg = substr($0, RLENGTH + 1) } + END { print loc; print msg }' "$log") + local loc=${s%%$'\n'*} msg=${s#*$'\n'} + # shellcheck disable=SC2016 # literal backticks + msg=$(sed -E 's/"([^"\\]|\\.)*"/"…"/g; s/`[^`]*`/`…`/g; s/[0-9]+/N/g' <<<"$msg") + printf '%s fails at %s: %s' "$2" "${loc:-?}" "${msg:0:160}" + fi +} + +in_git=0; git rev-parse --verify -q HEAD >/dev/null 2>&1 && in_git=1 +declare -A seen=() keep_of=() size_of=() +dropped=0 dupes=0 skipped=0 +while IFS=$'\t' read -r id name run created; do + log "$name (run $run, $created)" + d=$tmp/$id; mkdir -p "$d/x" + if ! download "$id" "$d/a.zip"; then + warn " download failed: https://github.com/$REPO/actions/runs/$run"; continue + fi + unzip -qo "$d/a.zip" -d "$d/x" || { warn " bad zip"; continue; } + + # The artifact is every testdata/fuzz/** file in the CI workspace, so it + # also carries the committed seed corpus: only files new to us matter. + while IFS= read -r -d '' f; do + base=${f##*/}; target=${f%/*}; target=${target##*/} + [[ $base =~ ^[A-Za-z0-9._-]+$ && $target =~ ^Fuzz[A-Za-z0-9_]*$ ]] || continue + IFS= read -r first <"$f" || true + [[ $first == 'go test fuzz v1' ]] || continue + [[ -z ${seen[$target/$base]+x} ]] || continue + seen[$target/$base]=1 + pkg=$(pkg_for "$target") + [[ -n $pkg ]] || { warn " $target/$base: no such fuzz target in this checkout"; ((++skipped)); continue; } + dest=$pkg/testdata/fuzz/$target/$base + # Already here: committed (or no git) means seed corpus, skip it. Present + # but not in HEAD means an earlier run of this script kept it: replay it + # too, so that new inputs are deduplicated against it. + existed=0 + if [[ -e $dest ]]; then + if ((!in_git)) || git cat-file -e "HEAD:$dest" 2>/dev/null; then continue; fi + existed=1 + else + mkdir -p "${dest%/*}"; cp "$f" "$dest" + fi + rc=0; replay "$pkg" "$target" "$base" "$d/test.log" || rc=$? + # never delete what was there before this run unless it is a duplicate + if ((existed && rc != 0)); then + log " already here, left alone: $dest"; continue + fi + case $rc in + 0) sig=$(signature "$d/test.log" "$target") + size=$(wc -c <"$dest" | tr -d ' ') + if [[ -z ${keep_of[$sig]+x} ]]; then + crash "$dest ($size bytes)"; printf ' %s\n' "$sig" >&2 + keep_of[$sig]=$dest; size_of[$sig]=$size + elif ((size < size_of[$sig])); then + log " same failure as ${keep_of[$sig]}, but smaller: keeping $dest instead" + crash "$dest ($size bytes)"; printf ' %s\n' "$sig" >&2 + rm -f "${keep_of[$sig]}"; rmdir -p "${keep_of[$sig]%/*}" 2>/dev/null || true + keep_of[$sig]=$dest; size_of[$sig]=$size; ((++dupes)) + else + log " same failure as ${keep_of[$sig]}, dropped: $dest" + rm -f "$dest"; ((++dupes)) + fi ;; + 1) log " passes now, dropped: $dest"; rm -f "$dest"; ((++dropped)) ;; + *) warn " could not replay $dest:"; tail -n 15 "$d/test.log" | sed 's/^/ /' >&2 + rm -f "$dest"; ((++skipped)) ;; + esac + rmdir -p "${dest%/*}" 2>/dev/null || true # if we just created it empty + done < <(find "$d/x" -type f -path '*testdata/fuzz/*' -print0) +done <"$tmp/artifacts.tsv" + +echo >&2 +log "${#keep_of[@]} distinct reproducing crashers ($dupes duplicates, $dropped no longer failing, $skipped skipped)" +for sig in "${!keep_of[@]}"; do + printf '\033[1;31m%s\033[0m\t%s\n' "${keep_of[$sig]}" "$sig" >&2 +done +((${#keep_of[@]})) && printf '%s\n' "${keep_of[@]}" +exit 0 From ec0a820715ab71656bc139e99bea2213f2fc05dc Mon Sep 17 00:00:00 2001 From: Pierre Fenoll Date: Fri, 6 Nov 2026 19:12:30 +0100 Subject: [PATCH 73/78] openapi3: internalize the refs next to a $ref in OpenAPI 3.1 (#1430) Co-authored-by: Claude Opus 5.5 --- openapi3/internalize_refs.go | 54 ++++++++++--------- openapi3/internalize_refs_test.go | 50 +++++++++++++++++ .../ref-sibling-empty-conjunct | 4 ++ 3 files changed, 83 insertions(+), 25 deletions(-) create mode 100644 openapi3/testdata/fuzz/FuzzInternalizeRefsCustomResolver/ref-sibling-empty-conjunct diff --git a/openapi3/internalize_refs.go b/openapi3/internalize_refs.go index 842cc987f..0664e51fb 100644 --- a/openapi3/internalize_refs.go +++ b/openapi3/internalize_refs.go @@ -351,6 +351,28 @@ func (doc *T) addCallbackToSpec(c *CallbackRef, refNameResolver RefNameResolver, return true } +// derefSchemaRef moves s into the root document when it points elsewhere, +// then does the same for the refs within the schema it holds. +func (doc *T) derefSchemaRef(s *SchemaRef, refNameResolver RefNameResolver, parentIsExternal bool) (isExternal bool) { + isExternal = doc.addSchemaToSpec(s, refNameResolver, parentIsExternal) + if s == nil { + return + } + if s.target == nil { + doc.derefSchema(s.Value, refNameResolver, isExternal || parentIsExternal) + return + } + // A $ref with siblings has a copy of its target as Value, with the siblings + // applied. Each schema in it is either the target's, which lives where the + // $ref points, or the siblings', which live next to the $ref, in the + // document of its parent. The siblings are what gets written out next to + // the $ref, even those Value left out, such as a conjunct that constrains + // nothing. + doc.derefSchema(s.target, refNameResolver, isExternal || parentIsExternal) + doc.derefSchema(s.sibling, refNameResolver, parentIsExternal) + return +} + func (doc *T) derefSchema(s *Schema, refNameResolver RefNameResolver, parentIsExternal bool) { if s == nil || doc.isVisitedSchema(s) { return @@ -358,10 +380,7 @@ func (doc *T) derefSchema(s *Schema, refNameResolver RefNameResolver, parentIsEx for _, list := range []SchemaRefs{s.AllOf, s.AnyOf, s.OneOf, s.PrefixItems} { for _, s2 := range list { - isExternal := doc.addSchemaToSpec(s2, refNameResolver, parentIsExternal) - if s2 != nil { - doc.derefSchema(s2.Value, refNameResolver, isExternal || parentIsExternal) - } + doc.derefSchemaRef(s2, refNameResolver, parentIsExternal) } } @@ -378,19 +397,14 @@ func (doc *T) derefSchema(s *Schema, refNameResolver RefNameResolver, parentIsEx if s2.RefPath() == nil { continue } - isExternal := doc.addSchemaToSpec(s2, refNameResolver, parentIsExternal) - doc.derefSchema(s2.Value, refNameResolver, isExternal || parentIsExternal) + doc.derefSchemaRef(s2, refNameResolver, parentIsExternal) s.Discriminator.Mapping[k] = MappingRef(*s2) } } for _, schemas := range []Schemas{s.Properties, s.PatternProperties, s.DependentSchemas, s.Defs} { for _, name := range componentNames(schemas) { - s2 := schemas[name] - isExternal := doc.addSchemaToSpec(s2, refNameResolver, parentIsExternal) - if s2 != nil { - doc.derefSchema(s2.Value, refNameResolver, isExternal || parentIsExternal) - } + doc.derefSchemaRef(schemas[name], refNameResolver, parentIsExternal) } } for _, ref := range []*SchemaRef{ @@ -398,10 +412,7 @@ func (doc *T) derefSchema(s *Schema, refNameResolver RefNameResolver, parentIsEx s.Contains, s.PropertyNames, s.If, s.Then, s.Else, s.ContentSchema, s.UnevaluatedItems.Schema, s.UnevaluatedProperties.Schema, } { - isExternal := doc.addSchemaToSpec(ref, refNameResolver, parentIsExternal) - if ref != nil { - doc.derefSchema(ref.Value, refNameResolver, isExternal || parentIsExternal) - } + doc.derefSchemaRef(ref, refNameResolver, parentIsExternal) } } @@ -429,10 +440,7 @@ func (doc *T) derefContent(c Content, refNameResolver RefNameResolver, parentIsE if mediatype == nil { continue } - isExternal := doc.addSchemaToSpec(mediatype.Schema, refNameResolver, parentIsExternal) - if mediatype.Schema != nil { - doc.derefSchema(mediatype.Schema.Value, refNameResolver, isExternal || parentIsExternal) - } + doc.derefSchemaRef(mediatype.Schema, refNameResolver, parentIsExternal) doc.derefExamples(mediatype.Examples, refNameResolver, parentIsExternal) for _, name := range componentNames(mediatype.Encoding) { e := mediatype.Encoding[name] @@ -475,11 +483,8 @@ func (doc *T) derefResponseBodies(es ResponseBodies, refNameResolver RefNameReso } func (doc *T) derefParameter(p Parameter, refNameResolver RefNameResolver, parentIsExternal bool) { - isExternal := doc.addSchemaToSpec(p.Schema, refNameResolver, parentIsExternal) doc.derefContent(p.Content, refNameResolver, parentIsExternal) - if p.Schema != nil { - doc.derefSchema(p.Schema.Value, refNameResolver, isExternal || parentIsExternal) - } + doc.derefSchemaRef(p.Schema, refNameResolver, parentIsExternal) } func (doc *T) derefRequestBody(r RequestBody, refNameResolver RefNameResolver, parentIsExternal bool) { @@ -550,10 +555,9 @@ func (doc *T) InternalizeRefs(ctx context.Context, refNameResolver func(*T, Comp if components := doc.Components; components != nil { for _, name := range componentNames(components.Schemas) { schema := components.Schemas[name] - isExternal := doc.addSchemaToSpec(schema, refNameResolver, false) + doc.derefSchemaRef(schema, refNameResolver, false) if schema != nil && schema.Value != nil { schema.Ref = "" // always dereference the top level - doc.derefSchema(schema.Value, refNameResolver, isExternal) } } for _, name := range componentNames(components.Parameters) { diff --git a/openapi3/internalize_refs_test.go b/openapi3/internalize_refs_test.go index e58942d9d..c6759db5d 100644 --- a/openapi3/internalize_refs_test.go +++ b/openapi3/internalize_refs_test.go @@ -1,6 +1,7 @@ package openapi3_test import ( + "encoding/json" "fmt" "os" "path/filepath" @@ -215,3 +216,52 @@ func TestInternalizeRefsAbsolutePath(t *testing.T) { require.NoError(t, err) require.JSONEq(t, string(expected), string(actual)) } + +// In OpenAPI 3.1 the fields next to a $ref are written out next to it, so the +// refs within them are internalized too, whether or not they constrain +// anything, and they keep naming schemas of the document holding the $ref. +func TestInternalizeRefsUnderRefSiblings(t *testing.T) { + t.Parallel() + + for name, tc := range map[string]struct{ property, want string }{ + "sibling constraining nothing": { + property: `{"$ref": "other.json#/Obj", "properties": {"q": {"$ref": "other.json#/Any"}}}`, + want: `{"$ref": "#/components/schemas/other_Obj", "properties": {"q": {"$ref": "#/components/schemas/other_Any"}}}`, + }, + "sibling next to an annotation": { + property: `{"$ref": "other.json#/Obj", "description": "d", "properties": {"q": {"$ref": "other.json#/Any"}}}`, + want: `{"$ref": "#/components/schemas/other_Obj", "description": "d", "properties": {"q": {"$ref": "#/components/schemas/other_Any"}}}`, + }, + "sibling naming a schema of the root": { + property: `{"$ref": "other.json#/Obj", "properties": {"q": {"$ref": "#/components/schemas/Str"}}}`, + want: `{"$ref": "#/components/schemas/other_Obj", "properties": {"q": {"$ref": "#/components/schemas/Str"}}}`, + }, + } { + t.Run(name, func(t *testing.T) { + t.Parallel() + + dir := t.TempDir() + root := `{"openapi": "3.1.0", "info": {"title": "t", "version": "1"}, "paths": {}, +"components": {"schemas": {"Str": {"type": "string"}, "X": {"properties": {"p": ` + tc.property + `}}}}}` + require.NoError(t, os.WriteFile(filepath.Join(dir, "openapi.json"), []byte(root), 0o644)) + require.NoError(t, os.WriteFile(filepath.Join(dir, "other.json"), []byte(`{"Obj": {"type": "object"}, "Any": {}}`), 0o644)) + + loader := openapi3.NewLoader() + loader.IsExternalRefsAllowed = true + doc, err := loader.LoadFromFile(filepath.Join(dir, "openapi.json")) + require.NoError(t, err) + doc.InternalizeRefs(t.Context(), nil) + + got, err := json.Marshal(doc.Components.Schemas["X"].Value.Properties["p"]) + require.NoError(t, err) + require.JSONEq(t, tc.want, string(got)) + require.NotContains(t, doc.Components.Schemas, "openapi_Str") + + strict := openapi3.NewLoader() + data, err := doc.MarshalJSON() + require.NoError(t, err) + _, err = strict.LoadFromData(data) + require.NoError(t, err) + }) + } +} diff --git a/openapi3/testdata/fuzz/FuzzInternalizeRefsCustomResolver/ref-sibling-empty-conjunct b/openapi3/testdata/fuzz/FuzzInternalizeRefsCustomResolver/ref-sibling-empty-conjunct new file mode 100644 index 000000000..5738e3a92 --- /dev/null +++ b/openapi3/testdata/fuzz/FuzzInternalizeRefsCustomResolver/ref-sibling-empty-conjunct @@ -0,0 +1,4 @@ +go test fuzz v1 +[]byte("openapi: 3.1.0\ncomponents:\n schemas:\n 0:\n $ref: A\n properties:\n 0:\n $ref: 0A") +[]byte("{}") +string("0") From fe68b90de43875ab25ebd5d3e90d25c10761e1e7 Mon Sep 17 00:00:00 2001 From: Pierre Fenoll Date: Fri, 6 Nov 2026 19:30:51 +0100 Subject: [PATCH 74/78] openapi3: internalize the examples of parameters and headers (#1431) Co-authored-by: Claude Opus 5.5 --- openapi3/internalize_refs.go | 1 + openapi3/internalize_refs_test.go | 34 +++++++++++++++++++ .../fuzz/FuzzInternalizeRefs/58ce399243a3690e | 3 ++ 3 files changed, 38 insertions(+) create mode 100644 openapi3/testdata/fuzz/FuzzInternalizeRefs/58ce399243a3690e diff --git a/openapi3/internalize_refs.go b/openapi3/internalize_refs.go index 0664e51fb..9d28d3b06 100644 --- a/openapi3/internalize_refs.go +++ b/openapi3/internalize_refs.go @@ -483,6 +483,7 @@ func (doc *T) derefResponseBodies(es ResponseBodies, refNameResolver RefNameReso } func (doc *T) derefParameter(p Parameter, refNameResolver RefNameResolver, parentIsExternal bool) { + doc.derefExamples(p.Examples, refNameResolver, parentIsExternal) doc.derefContent(p.Content, refNameResolver, parentIsExternal) doc.derefSchemaRef(p.Schema, refNameResolver, parentIsExternal) } diff --git a/openapi3/internalize_refs_test.go b/openapi3/internalize_refs_test.go index c6759db5d..85fb8a59a 100644 --- a/openapi3/internalize_refs_test.go +++ b/openapi3/internalize_refs_test.go @@ -182,6 +182,40 @@ components: } } +func TestInternalizeRefsParameterAndHeaderExamples(t *testing.T) { + t.Parallel() + + dir := t.TempDir() + root := `{"openapi": "3.0.3", "info": {"title": "t", "version": "1"}, +"paths": {"/a": {"get": { + "parameters": [{"name": "q", "in": "query", "schema": {"type": "string"}, "examples": {"e": {"$ref": "other.json#/components/examples/P"}}}], + "responses": {"200": {"description": "d", "headers": {"h": {"schema": {"type": "string"}, "examples": {"e": {"$ref": "other.json#/components/examples/H"}}}}}}}}}, +"components": {"headers": {"H": {"schema": {"type": "string"}, "examples": {"e": {"$ref": "other.json#/components/examples/C"}}}}}}` + other := `{"components": {"examples": {"P": {"value": "p"}, "H": {"value": "h"}, "C": {"value": "c"}}}}` + require.NoError(t, os.WriteFile(filepath.Join(dir, "openapi.json"), []byte(root), 0o644)) + require.NoError(t, os.WriteFile(filepath.Join(dir, "other.json"), []byte(other), 0o644)) + + loader := openapi3.NewLoader() + loader.IsExternalRefsAllowed = true + doc, err := loader.LoadFromFile(filepath.Join(dir, "openapi.json")) + require.NoError(t, err) + doc.InternalizeRefs(t.Context(), nil) + + op := doc.Paths.Value("/a").Get + require.Equal(t, "#/components/examples/other_P", op.Parameters[0].Value.Examples["e"].Ref) + require.Equal(t, "#/components/examples/other_H", op.Responses.Value("200").Value.Headers["h"].Value.Examples["e"].Ref) + require.Equal(t, "#/components/examples/other_C", doc.Components.Headers["H"].Value.Examples["e"].Ref) + for _, name := range []string{"other_P", "other_H", "other_C"} { + require.Contains(t, doc.Components.Examples, name) + } + + data, err := doc.MarshalJSON() + require.NoError(t, err) + strict := openapi3.NewLoader() + _, err = strict.LoadFromData(data) + require.NoError(t, err) +} + func TestInternalizeRefsAbsolutePath(t *testing.T) { t.Parallel() diff --git a/openapi3/testdata/fuzz/FuzzInternalizeRefs/58ce399243a3690e b/openapi3/testdata/fuzz/FuzzInternalizeRefs/58ce399243a3690e new file mode 100644 index 000000000..de6d341b8 --- /dev/null +++ b/openapi3/testdata/fuzz/FuzzInternalizeRefs/58ce399243a3690e @@ -0,0 +1,3 @@ +go test fuzz v1 +[]byte("components:\n headers:\n 0: \n examples:\n 0:\n $ref: 0A") +[]byte("0:") From b523491b9c613d0d06ed556171132699cff655d1 Mon Sep 17 00:00:00 2001 From: Pierre Fenoll Date: Sat, 7 Nov 2026 09:20:25 +0100 Subject: [PATCH 75/78] openapi2, openapi3: skip the json decode when data cannot be json, wrap both errors (#1432) Co-authored-by: Claude Opus 5.5 --- openapi2/marsh.go | 28 +++++++++++-- openapi2/marsh_test.go | 42 +++++++++++++++++++ openapi3/marsh.go | 28 +++++++++++-- openapi3/marsh_test.go | 42 +++++++++++++++++++ openapi3/origin_test.go | 6 +-- .../bunq_com_1_0_openapi_yaml__load | 2 +- .../codat_io_assess_1_0_openapi_yaml__load | 2 +- .../docusign_net_v2_1_openapi_yaml__load | 2 +- .../sendgrid_com_1_0_0_openapi_yaml__load | 2 +- 9 files changed, 137 insertions(+), 17 deletions(-) diff --git a/openapi2/marsh.go b/openapi2/marsh.go index 30c458810..a3411e6a3 100644 --- a/openapi2/marsh.go +++ b/openapi2/marsh.go @@ -1,6 +1,7 @@ package openapi2 import ( + "bytes" "fmt" "strings" @@ -20,8 +21,10 @@ func unmarshal(data []byte, v any) error { var jsonErr, yamlErr error // See https://github.com/getkin/kin-openapi/issues/680 - if jsonErr = unmarshalJSON(data, v); jsonErr == nil { - return nil + if mayBeJSON(data) { + if jsonErr = unmarshalJSON(data, v); jsonErr == nil { + return nil + } } // UnmarshalStrict(data, v) TODO: investigate how ymlv3 handles duplicate map keys @@ -29,6 +32,23 @@ func unmarshal(data []byte, v any) error { return nil } - // If both unmarshaling attempts fail, return a new error that includes both errors - return fmt.Errorf("failed to unmarshal data: json error: %v, yaml error: %v", jsonErr, yamlErr) + // Every attempt failed: return what each one said + return unmarshalErrors(jsonErr, yamlErr) +} + +// mayBeJSON reports whether data could hold a JSON value: whether its first +// byte past JSON's whitespace can start one. Data that cannot is not tried as +// JSON, so a YAML document's error is not followed by the JSON parser's +// complaint about its first byte. +func mayBeJSON(data []byte) bool { + data = bytes.TrimLeft(data, " \t\r\n") + return len(data) != 0 && strings.IndexByte(`{["-0123456789tfn`, data[0]) >= 0 +} + +// unmarshalErrors wraps the error of each decode that was attempted. +func unmarshalErrors(jsonErr, yamlErr error) error { + if jsonErr == nil { + return fmt.Errorf("failed to unmarshal data: yaml error: %w", yamlErr) + } + return fmt.Errorf("failed to unmarshal data: json error: %w, yaml error: %w", jsonErr, yamlErr) } diff --git a/openapi2/marsh_test.go b/openapi2/marsh_test.go index 68826932e..6f39fc135 100644 --- a/openapi2/marsh_test.go +++ b/openapi2/marsh_test.go @@ -1,6 +1,7 @@ package openapi2 import ( + "errors" "testing" "github.com/stretchr/testify/require" @@ -65,3 +66,44 @@ paths: err := unmarshal(v2, &doc) require.NoError(t, err) } + +func TestMayBeJSON(t *testing.T) { + t.Parallel() + + for data, expected := range map[string]bool{ + ``: false, + " \t\r\n": false, + `swagger: '2.0'`: false, + `# comment`: false, + "\ufeff{}": false, + ` {}`: true, + "\n[]": true, + `"s"`: true, + `-1`: true, + `---`: true, + `42`: true, + `true`: true, + `false`: true, + `null`: true, + } { + require.Equal(t, expected, mayBeJSON([]byte(data)), "%q", data) + } +} + +func TestUnmarshalErrorWrapsTheDecodersTried(t *testing.T) { + t.Parallel() + + var doc T + err := unmarshal([]byte("swagger: '2.0'\ninfo: 42\n"), &doc) + require.ErrorContains(t, err, "failed to unmarshal data: yaml error: ") + msg := err.Error() + require.NotContains(t, msg, "json error") + require.Error(t, errors.Unwrap(err)) + + err = unmarshal([]byte(`{"swagger": "2.0", "info": 42}`), &doc) + require.ErrorContains(t, err, "failed to unmarshal data: json error: ") + require.ErrorContains(t, err, ", yaml error: ") + var wrapped interface{ Unwrap() []error } + require.ErrorAs(t, err, &wrapped) + require.Len(t, wrapped.Unwrap(), 2) +} diff --git a/openapi3/marsh.go b/openapi3/marsh.go index d50f25b72..73b4e2568 100644 --- a/openapi3/marsh.go +++ b/openapi3/marsh.go @@ -1,6 +1,7 @@ package openapi3 import ( + "bytes" "fmt" "net/url" "strings" @@ -24,8 +25,10 @@ func unmarshal(data []byte, v any, includeOrigin bool, location *url.URL) (*orig var jsonErr, yamlErr error // See https://github.com/getkin/kin-openapi/issues/680 - if jsonErr = unmarshalJSON(data, v); jsonErr == nil { - return nil, nil + if mayBeJSON(data) { + if jsonErr = unmarshalJSON(data, v); jsonErr == nil { + return nil, nil + } } // UnmarshalStrict(data, v) TODO: investigate how ymlv3 handles duplicate map keys @@ -43,6 +46,23 @@ func unmarshal(data []byte, v any, includeOrigin bool, location *url.URL) (*orig yamlErr = err } - // If both unmarshaling attempts fail, return a new error that includes both errors - return nil, fmt.Errorf("failed to unmarshal data: json error: %v, yaml error: %v", jsonErr, yamlErr) + // Every attempt failed: return what each one said + return nil, unmarshalErrors(jsonErr, yamlErr) +} + +// mayBeJSON reports whether data could hold a JSON value: whether its first +// byte past JSON's whitespace can start one. Data that cannot is not tried as +// JSON, so a YAML document's error is not followed by the JSON parser's +// complaint about its first byte. +func mayBeJSON(data []byte) bool { + data = bytes.TrimLeft(data, " \t\r\n") + return len(data) != 0 && strings.IndexByte(`{["-0123456789tfn`, data[0]) >= 0 +} + +// unmarshalErrors wraps the error of each decode that was attempted. +func unmarshalErrors(jsonErr, yamlErr error) error { + if jsonErr == nil { + return fmt.Errorf("failed to unmarshal data: yaml error: %w", yamlErr) + } + return fmt.Errorf("failed to unmarshal data: json error: %w, yaml error: %w", jsonErr, yamlErr) } diff --git a/openapi3/marsh_test.go b/openapi3/marsh_test.go index 583c1e5f1..be554acce 100644 --- a/openapi3/marsh_test.go +++ b/openapi3/marsh_test.go @@ -1,6 +1,7 @@ package openapi3_test import ( + "errors" "testing" "github.com/stretchr/testify/require" @@ -84,3 +85,44 @@ paths: err = doc.Validate(sl.Context) require.NoError(t, err) } + +func TestUnmarshalErrorWrapsTheDecodersTried(t *testing.T) { + t.Parallel() + + const yamlSpec = ` +openapi: 3.0.3 +info: {title: t, version: v} +paths: {} +components: + schemas: + A: + type: 123 +` + const jsonSpec = ` +{"openapi": "3.0.3", "info": {"title": "t", "version": "v"}, "paths": {}, + "components": {"schemas": {"A": {"type": 123}}}} +` + + t.Run("yaml is not tried as json", func(t *testing.T) { + t.Parallel() + + loader := openapi3.NewLoader() + _, err := loader.LoadFromData([]byte(yamlSpec)) + require.ErrorContains(t, err, "failed to unmarshal data: yaml error: ") + msg := err.Error() + require.NotContains(t, msg, "json error") + require.Error(t, errors.Unwrap(err)) + }) + + t.Run("json reports both decoders", func(t *testing.T) { + t.Parallel() + + loader := openapi3.NewLoader() + _, err := loader.LoadFromData([]byte(jsonSpec)) + require.ErrorContains(t, err, "failed to unmarshal data: json error: ") + require.ErrorContains(t, err, ", yaml error: ") + var wrapped interface{ Unwrap() []error } + require.ErrorAs(t, err, &wrapped) + require.Len(t, wrapped.Unwrap(), 2) + }) +} diff --git a/openapi3/origin_test.go b/openapi3/origin_test.go index 500ab3d54..37b43211f 100644 --- a/openapi3/origin_test.go +++ b/openapi3/origin_test.go @@ -637,11 +637,7 @@ components: _, err := loader.LoadFromData([]byte(data)) require.Error(t, err) - jsonErr := `invalid character 'p' looking for beginning of value` - if openapi3.UsingJSONv2 { - jsonErr = `jsontext: invalid character 'p' at start of value after offset 1` - } - require.Equal(t, `failed to unmarshal data: json error: `+jsonErr+`, yaml error: error converting YAML to JSON: yaml: unmarshal errors: + require.Equal(t, `failed to unmarshal data: yaml error: error converting YAML to JSON: yaml: unmarshal errors: line 0: mapping key "__origin__" already defined at line 17`, err.Error()) } diff --git a/openapi3/testdata/apis_guru_openapi_directory/bunq_com_1_0_openapi_yaml__load b/openapi3/testdata/apis_guru_openapi_directory/bunq_com_1_0_openapi_yaml__load index d5df1457e..1bdb69451 100644 --- a/openapi3/testdata/apis_guru_openapi_directory/bunq_com_1_0_openapi_yaml__load +++ b/openapi3/testdata/apis_guru_openapi_directory/bunq_com_1_0_openapi_yaml__load @@ -1 +1 @@ -failed to unmarshal data: json error: jsontext: invalid character 'o' at start of value, yaml error: error converting YAML to JSON: yaml: line 1142: did not find expected key +failed to unmarshal data: yaml error: error converting YAML to JSON: yaml: line 1142: did not find expected key diff --git a/openapi3/testdata/apis_guru_openapi_directory/codat_io_assess_1_0_openapi_yaml__load b/openapi3/testdata/apis_guru_openapi_directory/codat_io_assess_1_0_openapi_yaml__load index e639668ef..f971e1637 100644 --- a/openapi3/testdata/apis_guru_openapi_directory/codat_io_assess_1_0_openapi_yaml__load +++ b/openapi3/testdata/apis_guru_openapi_directory/codat_io_assess_1_0_openapi_yaml__load @@ -1 +1 @@ -failed to unmarshal data: json error: jsontext: invalid character 'o' at start of value, yaml error: error unmarshaling JSON: while decoding JSON: json: cannot unmarshal object into Go struct field .components.schemas.ExcelStatus.examples of type []interface {} +failed to unmarshal data: yaml error: error unmarshaling JSON: while decoding JSON: json: cannot unmarshal object into Go struct field .components.schemas.ExcelStatus.examples of type []interface {} diff --git a/openapi3/testdata/apis_guru_openapi_directory/docusign_net_v2_1_openapi_yaml__load b/openapi3/testdata/apis_guru_openapi_directory/docusign_net_v2_1_openapi_yaml__load index 4ec5fbaaf..f690ae309 100644 --- a/openapi3/testdata/apis_guru_openapi_directory/docusign_net_v2_1_openapi_yaml__load +++ b/openapi3/testdata/apis_guru_openapi_directory/docusign_net_v2_1_openapi_yaml__load @@ -1 +1 @@ -failed to unmarshal data: json error: jsontext: invalid character 'o' at start of value, yaml error: error converting YAML to JSON: yaml: control characters are not allowed +failed to unmarshal data: yaml error: error converting YAML to JSON: yaml: control characters are not allowed diff --git a/openapi3/testdata/apis_guru_openapi_directory/sendgrid_com_1_0_0_openapi_yaml__load b/openapi3/testdata/apis_guru_openapi_directory/sendgrid_com_1_0_0_openapi_yaml__load index 4ec5fbaaf..f690ae309 100644 --- a/openapi3/testdata/apis_guru_openapi_directory/sendgrid_com_1_0_0_openapi_yaml__load +++ b/openapi3/testdata/apis_guru_openapi_directory/sendgrid_com_1_0_0_openapi_yaml__load @@ -1 +1 @@ -failed to unmarshal data: json error: jsontext: invalid character 'o' at start of value, yaml error: error converting YAML to JSON: yaml: control characters are not allowed +failed to unmarshal data: yaml error: error converting YAML to JSON: yaml: control characters are not allowed From 340e8d170cb1674c81c6da947a6396231682da94 Mon Sep 17 00:00:00 2001 From: Reuven Harrison Date: Sat, 7 Nov 2026 11:40:55 +0200 Subject: [PATCH 76/78] openapi3: switch the loader to the native decode The loader read a YAML document by converting it to map[string]any, re-serialising that to JSON text and parsing it again, because these types implement UnmarshalJSON and not UnmarshalYAML. Positions cannot survive that trip, so they were smuggled through as synthetic __origin__ nodes and reapplied by a reflection walk afterwards. The UnmarshalYAML methods are already here. This points the loader at them: a document is parsed once, the types are built from its nodes, and the origins come off those same nodes. The __origin__ consumer layer goes with the round trip, and the loader decodes against go-yaml v4. internal/yamlconv keeps the conversion to JSON for the types that still reach a document that way. A column is a byte count in v4 where the fork counted characters, so internal/nodeindex measures a line the same way. Types.UnmarshalYAML now takes a *yaml.Node, the shape every other type here already uses. That is a breaking change for a caller that invokes it directly rather than through the yaml package. Co-Authored-By: Claude Opus 5 --- .github/docs/openapi3.txt | 12 +- go.mod | 3 +- go.sum | 2 + internal/nodeindex/fuzz_test.go | 2 +- internal/nodeindex/nodeindex.go | 11 +- internal/nodeindex/nodeindex_test.go | 24 +- internal/yamlconv/yamlconv.go | 81 +++ internal/yamlconv/yamlconv_test.go | 61 ++ openapi2/issue1135_test.go | 4 +- openapi3/additionalProperties_test.go | 2 +- openapi3/case_strict_jsonv1_test.go | 32 - openapi3/case_strict_jsonv2_test.go | 32 - openapi3/case_strict_test.go | 52 ++ openapi3/end_positions_test.go | 58 ++ openapi3/fuzz_test.go | 4 +- openapi3/issue241_test.go | 2 +- openapi3/issue883_test.go | 21 +- openapi3/issue972_test.go | 4 +- openapi3/loader.go | 61 +- openapi3/marsh.go | 108 +++- openapi3/marsh_test.go | 9 +- openapi3/native_e2e_test.go | 99 +++ openapi3/native_scalars_test.go | 91 ++- openapi3/native_yaml.go | 171 +++++- openapi3/native_yaml_alias_cycle_test.go | 35 ++ openapi3/native_yaml_direct_test.go | 2 +- openapi3/native_yaml_local_tag_test.go | 34 + openapi3/native_yaml_path.go | 89 +++ openapi3/native_yaml_path_test.go | 73 +++ openapi3/native_yaml_refs.go | 2 +- openapi3/native_yaml_shadow.go | 69 ++- openapi3/native_yaml_special.go | 43 +- openapi3/native_yaml_test.go | 10 +- openapi3/nativeyaml.tmpl | 9 +- openapi3/non_finite_test.go | 58 ++ openapi3/openapi3_test.go | 12 +- openapi3/origin.go | 580 ++++++++++-------- openapi3/origin_concurrency_test.go | 82 +++ openapi3/origin_load_test.go | 4 +- openapi3/origin_release_test.go | 20 + openapi3/origin_test.go | 12 +- openapi3/refs.go | 11 +- openapi3/refs.tmpl | 3 +- openapi3/schema.go | 18 - openapi3/schema_test.go | 4 +- .../bunq_com_1_0_openapi_yaml__load | 2 +- .../codat_io_assess_1_0_openapi_yaml__load | 2 +- .../docusign_net_v2_1_openapi_yaml__load | 1 - .../sendgrid_com_1_0_0_openapi_yaml__load | 1 - .../sendgrid_com_1_0_0_openapi_yaml__validate | 328 ++++++++++ .../statsocial_com_1_0_0_openapi_yaml__load | 1 - .../next-line-escape-in-key | 3 + .../fuzz/FuzzLoadFromData/8fffb2caad2dd727 | 2 + .../fuzz/FuzzLoadFromData/alias-cycle | 2 + .../fuzz/FuzzLoadFromData/c306b42e54f99d7f | 2 + .../testdata/fuzz/FuzzLoadFromData/self-merge | 2 + .../fuzz/FuzzLoadWithOrigins/5b22ca46d0928a97 | 2 + .../fuzz/FuzzLoadWithOrigins/77207dd31798d4c6 | 2 + .../fuzz/FuzzLoadWithOrigins/f64677a72b839120 | 2 + .../fuzz/FuzzYAMLMatchesJSON/bddb72bfc04e1cae | 2 + openapi3/yaml_fuzz_test.go | 6 +- openapi3filter/req_resp_decoder.go | 2 +- 62 files changed, 1951 insertions(+), 527 deletions(-) create mode 100644 internal/yamlconv/yamlconv.go create mode 100644 internal/yamlconv/yamlconv_test.go create mode 100644 openapi3/case_strict_test.go create mode 100644 openapi3/end_positions_test.go create mode 100644 openapi3/native_e2e_test.go create mode 100644 openapi3/native_yaml_alias_cycle_test.go create mode 100644 openapi3/native_yaml_local_tag_test.go create mode 100644 openapi3/native_yaml_path.go create mode 100644 openapi3/native_yaml_path_test.go create mode 100644 openapi3/non_finite_test.go create mode 100644 openapi3/origin_concurrency_test.go create mode 100644 openapi3/origin_release_test.go delete mode 100644 openapi3/testdata/apis_guru_openapi_directory/docusign_net_v2_1_openapi_yaml__load delete mode 100644 openapi3/testdata/apis_guru_openapi_directory/sendgrid_com_1_0_0_openapi_yaml__load create mode 100644 openapi3/testdata/apis_guru_openapi_directory/sendgrid_com_1_0_0_openapi_yaml__validate delete mode 100644 openapi3/testdata/apis_guru_openapi_directory/statsocial_com_1_0_0_openapi_yaml__load create mode 100644 openapi3/testdata/fuzz/FuzzInternalizeRefs/next-line-escape-in-key create mode 100644 openapi3/testdata/fuzz/FuzzLoadFromData/8fffb2caad2dd727 create mode 100644 openapi3/testdata/fuzz/FuzzLoadFromData/alias-cycle create mode 100644 openapi3/testdata/fuzz/FuzzLoadFromData/c306b42e54f99d7f create mode 100644 openapi3/testdata/fuzz/FuzzLoadFromData/self-merge create mode 100644 openapi3/testdata/fuzz/FuzzLoadWithOrigins/5b22ca46d0928a97 create mode 100644 openapi3/testdata/fuzz/FuzzLoadWithOrigins/77207dd31798d4c6 create mode 100644 openapi3/testdata/fuzz/FuzzLoadWithOrigins/f64677a72b839120 create mode 100644 openapi3/testdata/fuzz/FuzzYAMLMatchesJSON/bddb72bfc04e1cae diff --git a/.github/docs/openapi3.txt b/.github/docs/openapi3.txt index 49ccc2c04..b43f7cffa 100644 --- a/.github/docs/openapi3.txt +++ b/.github/docs/openapi3.txt @@ -4019,6 +4019,8 @@ func (doc *T) UnmarshalJSON(data []byte) error UnmarshalJSON sets T to a copy of data. func (doc *T) UnmarshalYAML(node *yaml.Node) error + T is the document root, so no parent stamps its Origin.Key. It takes its own + first key instead, the same rule a sequence item follows. func (doc *T) Validate(ctx context.Context, opts ...ValidationOption) error Validate returns an error if T does not comply with the OpenAPI spec. @@ -4255,12 +4257,10 @@ func (types *Types) Slice() []string func (types *Types) UnmarshalJSON(data []byte) error -func (types *Types) UnmarshalYAML(unmarshal func(any) error) error - UnmarshalYAML accepts a single type as well as a sequence of types, - mirroring UnmarshalJSON. Swagger 2 and OpenAPI 3.0 documents always - write `type` as a scalar, so decoding such a document into openapi2.T or - openapi3.T straight from YAML would otherwise fail with "cannot unmarshal - !!str into Types". +func (types *Types) UnmarshalYAML(node *yaml.Node) error + Types is a string or a list of strings. Swagger 2 and OpenAPI 3.0 documents + always write `type` as a scalar, so the single-string case is what decoding + such a document into openapi2.T or openapi3.T relies on. func (types *Types) With(typs ...string) With adds the given types to the receiver, skipping those already present. diff --git a/go.mod b/go.mod index 99b358918..2e503f17e 100644 --- a/go.mod +++ b/go.mod @@ -6,16 +6,17 @@ require ( github.com/go-openapi/jsonpointer v0.22.5 github.com/gorilla/mux v1.8.0 github.com/oasdiff/yaml v0.1.3 - github.com/oasdiff/yaml3 v0.0.16 github.com/santhosh-tekuri/jsonschema/v6 v6.0.3 github.com/stretchr/testify v1.9.0 go.yaml.in/yaml/v3 v3.0.5 + go.yaml.in/yaml/v4 v4.0.0 ) require ( github.com/davecgh/go-spew v1.1.1 // indirect github.com/go-openapi/swag/jsonname v0.25.5 // indirect github.com/kr/text v0.2.0 // indirect + github.com/oasdiff/yaml3 v0.0.16 // indirect github.com/pmezard/go-difflib v1.0.0 // indirect golang.org/x/text v0.14.0 // indirect gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c // indirect diff --git a/go.sum b/go.sum index d3b97759b..7fafef818 100644 --- a/go.sum +++ b/go.sum @@ -29,6 +29,8 @@ github.com/stretchr/testify v1.9.0 h1:HtqpIVDClZ4nwg75+f6Lvsy/wHu+3BoSGCbBAcpTsT github.com/stretchr/testify v1.9.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY= go.yaml.in/yaml/v3 v3.0.5 h1:N6y/pJk8buWs9NY5ERU2HSMfm+IuD/OtfdAnq6kESPw= go.yaml.in/yaml/v3 v3.0.5/go.mod h1:HVTZu1O7/Vkt2N+BFy8Zza+lnLsABggaTM2ZpNIGuKg= +go.yaml.in/yaml/v4 v4.0.0 h1:/LG1pNO84Z4l603j/xMn69CcS5OYhMQ/f7l2LoQUGuw= +go.yaml.in/yaml/v4 v4.0.0/go.mod h1:aZqd9kCMsGL7AuUv/m/PvWLdg5sjJsZ4oHDEnfPPfY0= golang.org/x/text v0.14.0 h1:ScX5w1eTa3QqT8oi6+ziP7dTV1S2+ALU0bI+0zXKWiQ= golang.org/x/text v0.14.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU= gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0= diff --git a/internal/nodeindex/fuzz_test.go b/internal/nodeindex/fuzz_test.go index 041aef7ab..987283c39 100644 --- a/internal/nodeindex/fuzz_test.go +++ b/internal/nodeindex/fuzz_test.go @@ -3,8 +3,8 @@ package nodeindex_test import ( "testing" - yaml "github.com/oasdiff/yaml3" "github.com/stretchr/testify/require" + "go.yaml.in/yaml/v4" "github.com/getkin/kin-openapi/internal/fuzzing" "github.com/getkin/kin-openapi/internal/nodeindex" diff --git a/internal/nodeindex/nodeindex.go b/internal/nodeindex/nodeindex.go index 2e7cd4e55..21649ff79 100644 --- a/internal/nodeindex/nodeindex.go +++ b/internal/nodeindex/nodeindex.go @@ -13,9 +13,8 @@ package nodeindex import ( "bytes" - "unicode/utf8" - yaml "github.com/oasdiff/yaml3" + "go.yaml.in/yaml/v4" ) // Index answers where the block headed by a key ends. @@ -40,10 +39,8 @@ type Index struct { // anchorKey is the key heading each anchored node, so an alias can report // where the content it points at is defined. anchorKey map[*yaml.Node]*yaml.Node - // lineLen is each line's length in characters, giving the column a block's - // last line stops at: the parser counts a column per character, not per - // byte, so a line holding any multi-byte one would otherwise end past its - // own width. indent is its leading-space count, or -1 when the line holds + // lineLen is each line's length, giving the column a block's last line + // stops at. indent is its leading-space count, or -1 when the line holds // nothing, which is what extend walks. lineLen []int indent []int @@ -57,7 +54,7 @@ func New(root *yaml.Node, data []byte) *Index { } ix := &Index{end: map[*yaml.Node]int{}, anchorKey: map[*yaml.Node]*yaml.Node{}} for _, line := range splitLines(data) { - ix.lineLen = append(ix.lineLen, utf8.RuneCount(line)) + ix.lineLen = append(ix.lineLen, len(line)) if t := bytes.TrimRight(line, " \t"); len(t) == 0 { ix.indent = append(ix.indent, -1) } else { diff --git a/internal/nodeindex/nodeindex_test.go b/internal/nodeindex/nodeindex_test.go index 527ed9db0..19f3b3809 100644 --- a/internal/nodeindex/nodeindex_test.go +++ b/internal/nodeindex/nodeindex_test.go @@ -4,8 +4,8 @@ import ( "strings" "testing" - yaml "github.com/oasdiff/yaml3" "github.com/stretchr/testify/require" + "go.yaml.in/yaml/v4" "github.com/getkin/kin-openapi/internal/nodeindex" ) @@ -93,28 +93,6 @@ func TestNilIndex(t *testing.T) { require.Nil(t, nodeindex.New(nil, nil)) } -// A column counts characters, as the parser's own columns do, so a multi-byte -// character does not push the end of a block past the width of its line. -func TestEndOfCountsCharactersNotBytes(t *testing.T) { - t.Parallel() - - for name, src := range map[string]string{ - "ascii": "a: \"hello\"\nb: 2\n", - "multi-byte": "a: \"h\u00e9llo\"\nb: 2\n", - } { - t.Run(name, func(t *testing.T) { - t.Parallel() - - root := parse(t, src) - ix := nodeindex.New(root, []byte(src)) - - line, column := ix.EndOf(root.Content[0].Content[1]) - require.Equal(t, 1, line) - require.Equal(t, 11, column, pastTheLastCharacter) - }) - } -} - // A line break is not a character on the line it ends, so the same document // ends its nodes in the same place with either ending. Git checks files out // with CRLF endings on Windows. diff --git a/internal/yamlconv/yamlconv.go b/internal/yamlconv/yamlconv.go new file mode 100644 index 000000000..e5be1b6cc --- /dev/null +++ b/internal/yamlconv/yamlconv.go @@ -0,0 +1,81 @@ +// Package yamlconv converts between YAML and types that describe themselves +// with json tags and MarshalJSON/UnmarshalJSON methods. +// +// YAML reaches such a type through JSON, so its methods run and extensions are +// carried. Two things have to be reconciled first, both of which YAML resolves +// and JSON cannot represent. +package yamlconv + +import ( + "encoding/json" + + "go.yaml.in/yaml/v4" +) + +// PrepareForJSON retags the scalars that would not survive the conversion. +// +// A date-shaped scalar resolves to a timestamp, which has no JSON form, so it +// is retagged and keeps the text the document gave it. A scalar written with +// the tag outright is left alone, being a deliberate request for that type. +// +// A mapping key resolves too: the unquoted 200: written in most specs for a +// status code is an integer, 18_24 is 1824 and .0 is the number zero. +// Retagging the key names the member by the text that spells it, which is the +// name the typed decode reads. JSON has no other name to offer: encoding/json +// refuses a map[any]any, and encoding/json/v2 refuses one holding a float key +// and renumbers an integer one, 18_24 to 1824 and 0x2A to 42. A key's own tag +// goes the same way, a member name being a string however the key is written. +// +// Interim: https://github.com/yaml/go-yaml/issues/452 asks for an option to +// leave a timestamp-shaped scalar a string, and +// https://github.com/yaml/go-yaml/issues/491 for a mapping key to be read as +// its text. Either one removes the retag it covers. +func PrepareForJSON(n *yaml.Node) { + if n == nil { + return + } + if n.Kind == yaml.ScalarNode && n.Tag == "!!timestamp" && n.Style != yaml.TaggedStyle { + n.Tag = "!!str" + } + if n.Kind == yaml.MappingNode { + for i := 0; i < len(n.Content); i += 2 { + if k := n.Content[i]; k.Kind == yaml.ScalarNode && k.Tag != "!!str" { + k.Tag = "!!str" + } + } + } + for _, c := range n.Content { + PrepareForJSON(c) + } +} + +// Unmarshal decodes YAML into v via JSON, so v's UnmarshalJSON runs. +func Unmarshal(data []byte, v any) error { + var root yaml.Node + if err := yaml.Unmarshal(data, &root); err != nil { + return err + } + PrepareForJSON(&root) + var generic any + if err := root.Decode(&generic); err != nil { + return err + } + j, err := json.Marshal(generic) + if err != nil { + return err + } + return json.Unmarshal(j, v) +} + +// Marshal renders v as YAML via JSON, so v's MarshalJSON runs. +func Marshal(v any) ([]byte, error) { + j, err := json.Marshal(v) + if err != nil { + return nil, err + } + var generic any + if err := json.Unmarshal(j, &generic); err != nil { + return nil, err + } + return yaml.Dump(generic) +} diff --git a/internal/yamlconv/yamlconv_test.go b/internal/yamlconv/yamlconv_test.go new file mode 100644 index 000000000..f6d33be01 --- /dev/null +++ b/internal/yamlconv/yamlconv_test.go @@ -0,0 +1,61 @@ +package yamlconv_test + +import ( + "encoding/json" + "testing" + + "github.com/stretchr/testify/require" + + "github.com/getkin/kin-openapi/internal/yamlconv" +) + +// A scalar whose resolved type JSON cannot name arrives as the text the +// document wrote it with, so the document survives the conversion and keeps +// the member names it spells. +func TestUnmarshalRetagsResolvedScalars(t *testing.T) { + for _, tt := range []struct { + name string + yaml string + json string + }{ + { + name: "a date-shaped scalar keeps its text", + yaml: "x-date: 2020-06-11\n", + json: `{"x-date":"2020-06-11"}`, + }, + { + name: "and so does a date-time one", + yaml: "x-ts: 2020-06-11T16:32:50-03:00\n", + json: `{"x-ts":"2020-06-11T16:32:50-03:00"}`, + }, + { + name: "a tagged timestamp asks for a time and gets one", + yaml: "x-date: !!timestamp 2020-06-11\n", + json: `{"x-date":"2020-06-11T00:00:00Z"}`, + }, + { + name: "a key is named by the text that spells it", + yaml: "x-keys: {18_24: a, 1.5: b, 200: c, 0x2A: d, .0: e}\n", + json: `{"x-keys":{"18_24":"a","1.5":"b","200":"c","0x2A":"d",".0":"e"}}`, + }, + { + name: "at any depth", + yaml: "x-deep: {a: {200: b}}\n", + json: `{"x-deep":{"a":{"200":"b"}}}`, + }, + { + name: "a tagged key is named by its text as well", + yaml: "x-keys: {!!timestamp 2020-06-11: a}\n", + json: `{"x-keys":{"2020-06-11":"a"}}`, + }, + } { + t.Run(tt.name, func(t *testing.T) { + var got map[string]any + require.NoError(t, yamlconv.Unmarshal([]byte(tt.yaml), &got)) + + data, err := json.Marshal(got) + require.NoError(t, err) + require.JSONEq(t, tt.json, string(data)) + }) + } +} diff --git a/openapi2/issue1135_test.go b/openapi2/issue1135_test.go index e73def7a2..6aefd1122 100644 --- a/openapi2/issue1135_test.go +++ b/openapi2/issue1135_test.go @@ -3,8 +3,8 @@ package openapi2_test import ( "testing" - yaml "github.com/oasdiff/yaml3" "github.com/stretchr/testify/require" + "go.yaml.in/yaml/v4" "github.com/getkin/kin-openapi/openapi2" "github.com/getkin/kin-openapi/openapi3" @@ -51,7 +51,7 @@ func TestIssue1135MarshalYAML(t *testing.T) { t.Parallel() types := &openapi3.Types{"string"} - data, err := yaml.Marshal(types) + data, err := yaml.Dump(types) require.NoError(t, err) require.Equal(t, "string\n", string(data)) diff --git a/openapi3/additionalProperties_test.go b/openapi3/additionalProperties_test.go index a84939236..fee49b23a 100644 --- a/openapi3/additionalProperties_test.go +++ b/openapi3/additionalProperties_test.go @@ -5,8 +5,8 @@ import ( "os" "testing" - yaml "github.com/oasdiff/yaml3" "github.com/stretchr/testify/require" + "go.yaml.in/yaml/v4" "github.com/getkin/kin-openapi/openapi3" ) diff --git a/openapi3/case_strict_jsonv1_test.go b/openapi3/case_strict_jsonv1_test.go index 4c4a4c3b5..34a16bd8d 100644 --- a/openapi3/case_strict_jsonv1_test.go +++ b/openapi3/case_strict_jsonv1_test.go @@ -11,38 +11,6 @@ import ( "github.com/getkin/kin-openapi/openapi3" ) -// TestKeysOnlyMatchFieldsOfTheSameCase records how encoding/json v1, which -// ignores case:strict, matches keys to fields regardless of case: such keys -// fill the field and are also kept as extensions, so the document marshals -// both keys and does not load again. -func TestKeysOnlyMatchFieldsOfTheSameCase(t *testing.T) { - t.Parallel() - - const spec = "Components:\n schemas:\n SChemAs:\n 0:" - - loader := openapi3.NewLoader() - doc, err := loader.LoadFromData([]byte(spec)) - require.NoError(t, err) - - require.NotNil(t, doc.Components) - require.Empty(t, doc.Components.Schemas) - require.Equal(t, map[string]any{"SChemAs": map[string]any{"0": nil}}, doc.Components.Extensions) - require.Equal(t, map[string]any{ - "Components": map[string]any{ - "schemas": nil, - "SChemAs": map[string]any{"0": nil}, - }, - }, doc.Extensions) - - once, err := doc.MarshalJSON() - require.NoError(t, err) - require.JSONEq(t, `{"openapi": "", "info": null, "paths": null, "Components": {"schemas": null, "SChemAs": {"0": null}}, "components": {"SChemAs": {"0": null}}}`, string(once)) - - loader = openapi3.NewLoader() - _, err = loader.LoadFromData(once) - require.EqualError(t, err, "invalid schema: value MUST be an object") -} - func TestFieldsIgnoreKeysOfAnotherCase(t *testing.T) { t.Parallel() diff --git a/openapi3/case_strict_jsonv2_test.go b/openapi3/case_strict_jsonv2_test.go index 3d683c9cc..aa5e1a7e7 100644 --- a/openapi3/case_strict_jsonv2_test.go +++ b/openapi3/case_strict_jsonv2_test.go @@ -11,38 +11,6 @@ import ( "github.com/getkin/kin-openapi/openapi3" ) -// TestKeysOnlyMatchFieldsOfTheSameCase covers keys that differ from a known -// field only in case: the json:",case:strict" tags make encoding/json keep -// them as extensions rather than fill the field. -func TestKeysOnlyMatchFieldsOfTheSameCase(t *testing.T) { - t.Parallel() - - const spec = "Components:\n schemas:\n SChemAs:\n 0:" - - loader := openapi3.NewLoader() - doc, err := loader.LoadFromData([]byte(spec)) - require.NoError(t, err) - - require.Nil(t, doc.Components) - require.Equal(t, map[string]any{ - "Components": map[string]any{ - "schemas": nil, - "SChemAs": map[string]any{"0": nil}, - }, - }, doc.Extensions) - - once, err := doc.MarshalJSON() - require.NoError(t, err) - require.JSONEq(t, `{"openapi": "", "info": null, "paths": null, "Components": {"schemas": null, "SChemAs": {"0": null}}}`, string(once)) - - loader = openapi3.NewLoader() - reloaded, err := loader.LoadFromData(once) - require.NoError(t, err) - twice, err := reloaded.MarshalJSON() - require.NoError(t, err) - require.JSONEq(t, string(once), string(twice)) -} - func TestFieldsIgnoreKeysOfAnotherCase(t *testing.T) { t.Parallel() diff --git a/openapi3/case_strict_test.go b/openapi3/case_strict_test.go new file mode 100644 index 000000000..eecd6705e --- /dev/null +++ b/openapi3/case_strict_test.go @@ -0,0 +1,52 @@ +package openapi3_test + +import ( + "testing" + + "github.com/stretchr/testify/require" + + "github.com/getkin/kin-openapi/openapi3" +) + +// TestKeysOnlyMatchFieldsOfTheSameCase covers keys that differ from a known +// field only in case. A document decodes from its nodes, where a key matches a +// field by name and nothing else, so such a key is an extension rather than a +// value for the field it resembles. That holds whichever encoding/json the +// build has, since the json package decodes no document here. +func TestKeysOnlyMatchFieldsOfTheSameCase(t *testing.T) { + t.Parallel() + + const spec = "Components:\n schemas:\n SChemAs:\n 0:" + + loader := openapi3.NewLoader() + doc, err := loader.LoadFromData([]byte(spec)) + require.NoError(t, err) + + require.Nil(t, doc.Components) + require.Equal(t, map[string]any{ + "Components": map[string]any{ + "schemas": nil, + "SChemAs": map[string]any{"0": nil}, + }, + }, doc.Extensions) + + once, err := doc.MarshalJSON() + require.NoError(t, err) + require.JSONEq(t, `{"openapi": "", "info": null, "paths": null, "Components": {"schemas": null, "SChemAs": {"0": null}}}`, string(once)) + + loader = openapi3.NewLoader() + reloaded, err := loader.LoadFromData(once) + require.NoError(t, err) + + require.Nil(t, reloaded.Components) + require.Equal(t, map[string]any{ + "Components": map[string]any{ + "schemas": nil, + "SChemAs": map[string]any{"0": nil}, + }, + }, reloaded.Extensions) + + twice, err := reloaded.MarshalJSON() + require.NoError(t, err) + require.JSONEq(t, string(once), string(twice)) +} diff --git a/openapi3/end_positions_test.go b/openapi3/end_positions_test.go new file mode 100644 index 000000000..af8bb0487 --- /dev/null +++ b/openapi3/end_positions_test.go @@ -0,0 +1,58 @@ +package openapi3 + +import ( + "testing" + + "github.com/stretchr/testify/require" +) + +// A block ending in a multi-line scalar reaches the end of that scalar. The +// scalar is one node whose Line is where it starts, so the lines below it hang +// off nothing and a subtree walk alone stops short. +func TestEndPositions_BlockScalarAtEndOfBlock(t *testing.T) { + spec := ` +openapi: 3.0.0 +info: + title: t + version: "1" +paths: + /a: + get: + responses: + "200": + description: | + first line + second line + + after a blank line + /b: + get: + responses: + "200": + description: ok +`[1:] + + loader := NewLoader() + loader.IncludeOrigin = true + doc, err := loader.LoadFromData([]byte(spec)) + require.NoError(t, err) + + // /a spans to the last line of the description, line 14, not to line 10 + // where the scalar starts. + a := doc.Paths.Value("/a").Origin + require.NotNil(t, a) + require.NotNil(t, a.Key) + require.Equal(t, 6, a.Key.Line) + require.Equal(t, 14, a.Key.EndLine, "block must reach the end of the trailing block scalar") + + // The blank line inside the scalar is part of it; the one after is not. + get := doc.Paths.Value("/a").Get.Origin + require.NotNil(t, get) + require.Equal(t, 14, get.Key.EndLine) + + // The following sibling is unaffected. + b := doc.Paths.Value("/b").Origin + require.NotNil(t, b) + require.Equal(t, 15, b.Key.Line) + require.Equal(t, 19, b.Key.EndLine) +} diff --git a/openapi3/fuzz_test.go b/openapi3/fuzz_test.go index 14716a6ff..65c4fbaaf 100644 --- a/openapi3/fuzz_test.go +++ b/openapi3/fuzz_test.go @@ -9,7 +9,7 @@ import ( "testing" "github.com/stretchr/testify/require" - yaml "go.yaml.in/yaml/v3" + "go.yaml.in/yaml/v4" "github.com/getkin/kin-openapi/internal/fuzzing" "github.com/getkin/kin-openapi/openapi3" @@ -241,7 +241,7 @@ func FuzzMarshalYAML(f *testing.F) { return } - y, err := yaml.Marshal(doc) + y, err := yaml.Dump(doc) require.NoError(t, err) back, err := newFuzzLoader().LoadFromData(y) require.NoError(t, err, "yaml:\n%s", y) diff --git a/openapi3/issue241_test.go b/openapi3/issue241_test.go index 5b5268b03..ceca2d92a 100644 --- a/openapi3/issue241_test.go +++ b/openapi3/issue241_test.go @@ -5,8 +5,8 @@ import ( "os" "testing" - yaml "github.com/oasdiff/yaml3" "github.com/stretchr/testify/require" + "go.yaml.in/yaml/v4" "github.com/getkin/kin-openapi/openapi3" ) diff --git a/openapi3/issue883_test.go b/openapi3/issue883_test.go index fa5f063b7..625346d86 100644 --- a/openapi3/issue883_test.go +++ b/openapi3/issue883_test.go @@ -3,10 +3,10 @@ package openapi3_test import ( "testing" - yaml "github.com/oasdiff/yaml" - yamlv3 "github.com/oasdiff/yaml3" "github.com/stretchr/testify/require" + "go.yaml.in/yaml/v4" + "github.com/getkin/kin-openapi/internal/yamlconv" "github.com/getkin/kin-openapi/openapi3" ) @@ -40,8 +40,8 @@ paths: require.NoError(t, err) require.NotNil(t, doc.Paths) - t.Run("Roundtrip using yaml pkg", func(t *testing.T) { - justPaths, err := yaml.Marshal(doc.Paths) + t.Run("Roundtrip through yamlconv", func(t *testing.T) { + justPaths, err := yamlconv.Marshal(doc.Paths) require.NoError(t, err) require.NotNil(t, doc.Paths) require.YAMLEq(t, ` @@ -53,19 +53,19 @@ paths: description: OK `[1:], string(justPaths)) - marshalledYaml, err := yaml.Marshal(doc) + marshalledYaml, err := yamlconv.Marshal(doc) require.NoError(t, err) require.NotNil(t, doc.Paths) require.YAMLEq(t, spec, string(marshalledYaml)) var newDoc openapi3.T - _, err = yaml.Unmarshal(marshalledYaml, &newDoc, yaml.DecodeOpts{DisableTimestamps: true}) + err = yamlconv.Unmarshal(marshalledYaml, &newDoc) require.NoError(t, err) require.NotNil(t, newDoc.Paths) require.Equal(t, doc, &newDoc) }) - t.Run("Roundtrip yaml.v3", func(t *testing.T) { + t.Run("Roundtrip through the yaml pkg", func(t *testing.T) { justPaths, err := doc.Paths.MarshalJSON() require.NoError(t, err) require.NotNil(t, doc.Paths) @@ -78,7 +78,7 @@ paths: description: OK `[1:], string(justPaths)) - justPaths, err = yamlv3.Marshal(doc.Paths) + justPaths, err = yaml.Dump(doc.Paths) require.NoError(t, err) require.NotNil(t, doc.Paths) require.YAMLEq(t, ` @@ -90,14 +90,13 @@ paths: description: OK `[1:], string(justPaths)) - marshalledYaml, err := yamlv3.Marshal(doc) + marshalledYaml, err := yaml.Dump(doc) require.NoError(t, err) require.NotNil(t, doc.Paths) require.YAMLEq(t, spec, string(marshalledYaml)) - t.Skip("TODO: impl https://pkg.go.dev/github.com/oasdiff/yaml3#Unmarshaler on maplike types") var newDoc openapi3.T - err = yamlv3.Unmarshal(marshalledYaml, &newDoc) + err = yaml.Unmarshal(marshalledYaml, &newDoc) require.NoError(t, err) require.NotNil(t, newDoc.Paths) require.Equal(t, doc, &newDoc) diff --git a/openapi3/issue972_test.go b/openapi3/issue972_test.go index 23922236d..db69f4458 100644 --- a/openapi3/issue972_test.go +++ b/openapi3/issue972_test.go @@ -3,8 +3,8 @@ package openapi3_test import ( "testing" - yaml "github.com/oasdiff/yaml3" "github.com/stretchr/testify/assert" + "go.yaml.in/yaml/v4" "github.com/getkin/kin-openapi/openapi3" ) @@ -63,7 +63,7 @@ info: assert.NoError(t, err) } - txt, err := yaml.Marshal(doc) + txt, err := yaml.Dump(doc) assert.NoError(t, err) assert.NotEmpty(t, txt) } diff --git a/openapi3/loader.go b/openapi3/loader.go index ddfc7d319..f6066527d 100644 --- a/openapi3/loader.go +++ b/openapi3/loader.go @@ -15,6 +15,8 @@ import ( "reflect" "strconv" "strings" + + "go.yaml.in/yaml/v4" ) func failedToResolveRefFragmentPart(value, what string) error { @@ -59,11 +61,12 @@ type Loader struct { visitedDocuments map[string]*T - // originTrees retains each loaded document's origin tree, keyed by the - // document itself so insert and lookup cannot disagree, populated when - // IncludeOrigin is set. resolveComponent uses it to re-attach origins to - // components that lose them in the generic-map path, without re-reading - // or re-parsing the file. + // originTrees retains a loaded document's parsed node tree, keyed by the + // document itself so insert and lookup cannot disagree. Populated only for + // the documents rememberOriginTree keeps, which is the condition described + // there. resolveComponent uses it to re-attach origins to components that + // lose them in the generic-map path, without re-reading or re-parsing the + // file. originTrees map[*T]*originTree visitedRefs map[string]struct{} @@ -162,8 +165,9 @@ func (loader *Loader) loadSingleElementFromURI(ref string, rootPath *url.URL, el return resolvedPath, nil } -// rememberOriginTree retains doc's origin tree for attachOriginToResolved. -// tree is nil when IncludeOrigin is off or the data took the json path. +// rememberOriginTree retains doc's parsed node tree for +// attachOriginToResolved. tree is nil when origins are off or the data took +// the json path. // // The tree is kept only for a document a $ref can reach into untyped, which is // what attachOriginToResolved exists to re-origin. In practice that means a @@ -180,8 +184,8 @@ func (loader *Loader) loadSingleElementFromURI(ref string, rootPath *url.URL, el // undefined by the same rule, so a document carrying one keeps its tree too, // whether or not anything ever points at it.) // -// Worth the condition: on a 22 MB spec the retained tree was a third of -// everything the loader held. +// Worth the condition: the node tree is most of what a loaded document +// costs, so keeping one per document would dominate the loader's memory. func (loader *Loader) rememberOriginTree(doc *T, tree *originTree) { if tree == nil || len(doc.Extensions) == 0 { return @@ -611,10 +615,11 @@ func (loader *Loader) resolveComponent(doc *T, ref string, path *url.URL, resolv // attachOriginToResolved re-attaches source origins to a component resolved // through the generic-map path: a $ref to a schema under an arbitrary top-level // key lands in T.Extensions, and the json round-trip in resolveComponent strips -// its origin. It walks the document's retained origin tree (see originTrees, -// populated when the document was first unmarshaled: no re-read, no re-parse) -// down to the ref fragment and applies that subtree, so the object carries the -// same origins a typed resolution would, with the original file's line numbers. +// its origin. It walks the document's retained node tree (see originTrees, +// kept when the document was first unmarshaled: no re-read, no re-parse) down +// to the ref fragment and decodes that subtree, which runs the type's +// UnmarshalYAML and so produces origins, giving the object what a typed +// resolution would have, with the original file's line numbers. // Best-effort: a missing tree or fragment leaves the object without origins. func (loader *Loader) attachOriginToResolved(resolved any, componentDoc *T, fragment string) { if !loader.IncludeOrigin { @@ -624,15 +629,41 @@ func (loader *Loader) attachOriginToResolved(resolved any, componentDoc *T, frag if tree == nil { return } + // Stamp against the file this tree came from, not the document being + // loaded. The lock is held across the decode below, so nothing that decode + // reaches may load a document: that would wait here for a lock this call + // holds, and hang rather than fail. + originMu.Lock() + defer originMu.Unlock() + // Set rather than inherited: resolution runs after the load that produced + // the tree, so no decode is in progress and there is nothing to inherit. + originState.Store(&originDecode{file: tree.file, ends: tree.ends}) + defer originState.Store(nil) + + node := tree.node + // Walk the retained node tree down to the fragment and decode that subtree + // into the resolved value, which runs its UnmarshalYAML and so produces + // origins. The generic-map resolution path that produced `resolved` has + // none, because an extension value decodes as plain data. + var keyNode *yaml.Node for part := range strings.SplitSeq(strings.Trim(fragment, "/"), "/") { if part == "" { continue } - if tree = tree.Fields[unescapeRefString(part)]; tree == nil { + if keyNode, node = mappingEntry(node, unescapeRefString(part)); node == nil { return } } - applyOrigins(resolved, tree) + // Defensive: the json round trip in the caller already decoded this data + // into this type, so a failure here means the two decode paths disagree, + // which nothing is known to trigger. The object is resolved either way, so + // a failure costs positions rather than the load. + if err := node.Decode(resolved); err != nil { + return + } + // The key location is normally stamped by the mapping above, which does not + // run on this path: the last fragment part is that key. + setOriginKey(reflect.ValueOf(resolved), keyNode, node, tree.file) } func readableType(x any) string { diff --git a/openapi3/marsh.go b/openapi3/marsh.go index 73b4e2568..ef41ec122 100644 --- a/openapi3/marsh.go +++ b/openapi3/marsh.go @@ -6,7 +6,9 @@ import ( "net/url" "strings" - "github.com/oasdiff/yaml" + "go.yaml.in/yaml/v4" + + "github.com/getkin/kin-openapi/internal/nodeindex" ) func unmarshalError(jsonUnmarshalErr error) error { @@ -18,32 +20,40 @@ func unmarshalError(jsonUnmarshalErr error) error { return jsonUnmarshalErr } -// unmarshal decodes data into v. It returns the document origin tree when -// includeOrigin is set and the data took the yaml path (json input carries no -// origins), so the caller can retain it (see Loader.originTrees). +// unmarshal decodes data into v, trying yaml first and json for what the yaml +// parser will not accept. It returns the document's parsed node tree when +// origins were asked for and the data took the yaml path (json input carries +// none), so the caller can retain it (see Loader.originTrees). func unmarshal(data []byte, v any, includeOrigin bool, location *url.URL) (*originTree, error) { - var jsonErr, yamlErr error + var file string + if location != nil { + file = location.String() + } - // See https://github.com/getkin/kin-openapi/issues/680 - if mayBeJSON(data) { - if jsonErr = unmarshalJSON(data, v); jsonErr == nil { + // A raw U+0085 is a character to json and a line break to yaml, which + // folds it into a space, so a json document holding one is read by the + // json path and carries no origins. It is the only character json leaves + // raw that yaml breaks a line on: json escapes every other one, U+2028 + // included, and yaml reads U+00A0 as content. + if bytes.Contains(data, []byte("\u0085")) && mayBeJSON(data) { + if unmarshalJSON(data, v) == nil { return nil, nil } } - // UnmarshalStrict(data, v) TODO: investigate how ymlv3 handles duplicate map keys - var file string - if location != nil { - file = location.String() - } - if tree, err := yaml.Unmarshal(data, v, yaml.DecodeOpts{ - Origin: yaml.OriginOpt{Enabled: includeOrigin, File: file}, - DisableTimestamps: true, - }); err == nil { - applyOrigins(v, tree) + tree, yamlErr := unmarshalYAML(data, v, includeOrigin, file) + if yamlErr == nil { return tree, nil - } else { - yamlErr = err + } + + // Most importantly duplicate keys, which json resolves last-one-wins and + // yaml rejects. Such documents load as they always did, without origins. + // See https://github.com/getkin/kin-openapi/issues/680 + var jsonErr error + if mayBeJSON(data) { + if jsonErr = unmarshalJSON(data, v); jsonErr == nil { + return nil, nil + } } // Every attempt failed: return what each one said @@ -66,3 +76,61 @@ func unmarshalErrors(jsonErr, yamlErr error) error { } return fmt.Errorf("failed to unmarshal data: json error: %w, yaml error: %w", jsonErr, yamlErr) } + +// unmarshalYAML decodes data into v in one parse, straight into the types via +// UnmarshalYAML, with origins read off the nodes. A JSON document gets origins +// too, since JSON parses as YAML. +func unmarshalYAML(data []byte, v any, includeOrigin bool, file string) (*originTree, error) { + var root yaml.Node + if err := yaml.Unmarshal(data, &root); err != nil { + return nil, err + } + if err := prepareScalars(&root); err != nil { + return nil, err + } + + var ends *nodeindex.Index + if includeOrigin { + var release func() + ends, release = installOriginState(&root, data, file) + defer release() + } + + if err := root.Decode(v); err != nil { + return nil, nameFields(err, &root) + } + if !includeOrigin { + return nil, nil + } + + // Retained so a $ref to an arbitrary top-level key can be decoded from its + // own node; that path resolves through plain data, which carries no + // positions. + node := &root + if root.Kind == yaml.DocumentNode && len(root.Content) > 0 { + node = root.Content[0] + } + stampRootOrigin(v, node) + return &originTree{node: node, file: file, ends: ends}, nil +} + +// installOriginState gives the decode about to run the file and index its +// UnmarshalYAML calls read, and returns the index along with the release to +// call when the decode ends. +// +// The state is the only thing a decode shares with another, so it is held under +// the lock, and a decode that produces no origins neither installs nor takes +// it. Releasing matters beyond the lock: the state holds an index over the +// whole node tree, which leaving it set would pin until the next decode +// replaced it, whether or not anything kept the tree. A caller that does need +// it gets it on the returned originTree. +func installOriginState(root *yaml.Node, data []byte, file string) (*nodeindex.Index, func()) { + originMu.Lock() + // Ends are derived from the tree, the parser reporting only starts. + ends := nodeindex.New(root, data) + originState.Store(&originDecode{file: file, ends: ends}) + return ends, func() { + originState.Store(nil) + originMu.Unlock() + } +} diff --git a/openapi3/marsh_test.go b/openapi3/marsh_test.go index be554acce..df3306d74 100644 --- a/openapi3/marsh_test.go +++ b/openapi3/marsh_test.go @@ -43,11 +43,10 @@ paths: sl := openapi3.NewLoader() _, err := sl.LoadFromData(spec) - if openapi3.UsingJSONv2 { - require.ErrorContains(t, err, `json: cannot unmarshal object into Go struct field .paths.~1categories.get.responses.200.content.application~1json.schema.allOf of type openapi3.SchemaRefs`) - } else { - require.ErrorContains(t, err, `json: cannot unmarshal object into field Schema.allOf of type openapi3.SchemaRefs`) - } + // The parser reports the line, having decoded the document itself + // rather than a json rendering of it, and the position names the field. + require.ErrorContains(t, err, "line 24: cannot construct !!map into openapi3.SchemaRefs"+ + " in /paths/~1categories/get/responses/200/content/application~1json/schema/allOf") } spec := []byte(` diff --git a/openapi3/native_e2e_test.go b/openapi3/native_e2e_test.go new file mode 100644 index 000000000..9352c5281 --- /dev/null +++ b/openapi3/native_e2e_test.go @@ -0,0 +1,99 @@ +package openapi3 + +import ( + "bytes" + "encoding/json" + "os" + "path/filepath" + "strings" + "testing" + + "github.com/stretchr/testify/require" + "go.yaml.in/yaml/v4" +) + +// A raw U+0085 is a character to json and a line break to yaml, which folds it +// into a space. A json document that holds one keeps it, in a name as much as +// in a value. +func TestNativeE2E_JSONKeepsARawNextLine(t *testing.T) { + const src = "{\"openapi\":\"3.0.0\",\"info\":{\"title\":\"t\",\"version\":\"1\"},\"paths\":{}," + + "\"x-a\":\"b\u0085c\",\"x-\u0085\":1}" + + loader := NewLoader() + doc, err := loader.LoadFromData([]byte(src)) + require.NoError(t, err) + require.Equal(t, "b\u0085c", doc.Extensions["x-a"]) + require.Contains(t, doc.Extensions, "x-\u0085") + + // The document reads back as itself, which is what the fuzzers assert over + // the corpus. + out, err := json.Marshal(doc) + require.NoError(t, err) + require.JSONEq(t, src, string(out)) +} + +// A complete document decoded through UnmarshalYAML must equal the same +// document decoded as JSON. +func TestNativeE2E_WholeDocument(t *testing.T) { + // Every full document in testdata, so this is breadth rather than a + // hand-picked sample. + paths, err := filepath.Glob("testdata/*.y*ml") + require.NoError(t, err) + var ran int + for _, path := range paths { + data, err := os.ReadFile(path) + if err != nil || !bytes.HasPrefix(bytes.TrimSpace(data), []byte("openapi:")) { + continue + } + ran++ + t.Run(path, func(t *testing.T) { + // Reference: the JSON path, via a plain YAML->JSON conversion. + var asAny any + require.NoError(t, yaml.Unmarshal(data, &asAny)) + jsonBytes, err := json.Marshal(asAny) + require.NoError(t, err) + var viaJSON T + require.NoError(t, json.Unmarshal(jsonBytes, &viaJSON)) + + // Native: straight from the node tree. + var viaYAML T + require.NoError(t, yaml.Unmarshal(data, &viaYAML)) + + want, err := json.Marshal(&viaJSON) + require.NoError(t, err) + got, err := json.Marshal(&viaYAML) + require.NoError(t, err) + require.JSONEq(t, string(want), string(got), "native decode should match the JSON path") + }) + } + require.Positive(t, ran, "should have found documents to compare") +} + +// Path items and operations must carry an origin naming their own key. +func TestNativeE2E_OriginsReachOperations(t *testing.T) { + data, err := os.ReadFile("testdata/callbacks.yml") + require.NoError(t, err) + var doc T + // Through unmarshal rather than the yaml package: origins are stamped only + // for the tree a decode indexed. + _, err = unmarshal(data, &doc, true, nil) + require.NoError(t, err) + require.NotNil(t, doc.Paths) + + var checked int + for path, pi := range doc.Paths.Map() { + require.NotNil(t, pi.Origin, "path item %q has no origin", path) + require.NotNil(t, pi.Origin.Key, "path item %q has no key origin", path) + require.Equal(t, path, pi.Origin.Key.Name) + require.Positive(t, pi.Origin.Key.Line) + for method, op := range pi.Operations() { + require.NotNil(t, op.Origin, "%s %s has no origin", method, path) + require.NotNil(t, op.Origin.Key, "%s %s has no key origin", method, path) + // Operations() reports the method uppercased; the origin names + // the key as it appears in the document. + require.Equal(t, strings.ToLower(method), op.Origin.Key.Name) + checked++ + } + } + require.Positive(t, checked, "should have checked some operations") +} diff --git a/openapi3/native_scalars_test.go b/openapi3/native_scalars_test.go index 637c7e415..e3b1df051 100644 --- a/openapi3/native_scalars_test.go +++ b/openapi3/native_scalars_test.go @@ -4,7 +4,7 @@ import ( "testing" "github.com/stretchr/testify/require" - goyaml "go.yaml.in/yaml/v3" + "go.yaml.in/yaml/v4" ) // YAML resolves more scalar forms than JSON does, so a value reaching an @@ -22,8 +22,8 @@ x-nested: {n: 7, list: [1, 2]} example: 42 default: 0x10 ` - var node goyaml.Node - require.NoError(t, goyaml.Unmarshal([]byte(src), &node)) + var node yaml.Node + require.NoError(t, yaml.Unmarshal([]byte(src), &node)) require.NoError(t, prepareScalars(&node)) var s Schema @@ -57,8 +57,8 @@ default: 0x10 // did not. func TestNativeScalars_DeclaredIntegerFieldsKeepPrecision(t *testing.T) { const src = "type: integer\nmaxLength: 9007199254740993\n" - var node goyaml.Node - require.NoError(t, goyaml.Unmarshal([]byte(src), &node)) + var node yaml.Node + require.NoError(t, yaml.Unmarshal([]byte(src), &node)) var s Schema require.NoError(t, node.Content[0].Decode(&s)) @@ -70,8 +70,8 @@ func TestNativeScalars_DeclaredIntegerFieldsKeepPrecision(t *testing.T) { // a time.Time would marshal to text that reads back as a string. func TestNativeScalars_Timestamps(t *testing.T) { const src = "example: 2020-06-11T16:32:50Z\n" - var node goyaml.Node - require.NoError(t, goyaml.Unmarshal([]byte(src), &node)) + var node yaml.Node + require.NoError(t, yaml.Unmarshal([]byte(src), &node)) require.NoError(t, prepareScalars(&node)) var s Schema @@ -79,8 +79,8 @@ func TestNativeScalars_Timestamps(t *testing.T) { require.IsType(t, "", s.Example, "a date-shaped example stays a string") const tagged = "example: !!timestamp 2020-06-11T16:32:50Z\n" - var taggedNode goyaml.Node - require.NoError(t, goyaml.Unmarshal([]byte(tagged), &taggedNode)) + var taggedNode yaml.Node + require.NoError(t, yaml.Unmarshal([]byte(tagged), &taggedNode)) require.NoError(t, prepareScalars(&taggedNode)) var ts Schema @@ -92,8 +92,8 @@ func TestNativeScalars_Timestamps(t *testing.T) { func decodeNative(t *testing.T, src string, v any) error { t.Helper() - var node goyaml.Node - require.NoError(t, goyaml.Unmarshal([]byte(src), &node)) + var node yaml.Node + require.NoError(t, yaml.Unmarshal([]byte(src), &node)) if err := prepareScalars(&node); err != nil { return err } @@ -160,11 +160,76 @@ func TestNativeScalars_NullKeyNamesNothing(t *testing.T) { var extension, example Schema require.ErrorContains(t, decodeNative(t, "x-k: {null: a}\n", &extension), "mapping key is null") require.ErrorContains(t, decodeNative(t, "example: {null: a}\n", &example), "mapping key is null") +} + +// A null key is refused wherever it is written, not only where the mapping it +// sits in is decoded into an any. A mapping decoded into a map[string]T drops +// the member silently, which would let a document load holding less than it +// says, and a struct's extensions would record the text that spells the null +// as a name. The key's own line is what the error names. +func TestNativeScalars_NullKeyIsRefusedWhereverItIsWritten(t *testing.T) { + const head = "openapi: 3.0.0\ninfo: {title: t, version: \"1\"}\npaths: {}\n" + for _, test := range []struct { + name, src, want string + }{ + {"in an extension", head + "x-a: {null: 1}\n", "line 4: mapping key is null"}, + {"at the top level", head + "null: 1\n", "line 4: mapping key is null"}, + { + "under properties", + head + "components:\n schemas:\n A:\n properties:\n null: {}\n", + "line 8: mapping key is null", + }, + { + "beside a property named null", + head + "components:\n schemas:\n A:\n properties:\n ~: {}\n \"null\": {type: string}\n", + "line 8: mapping key is null", + }, + {"written as a bare colon", ":", "line 1: mapping key is null"}, + {"on its own line", head + "x-a:\n : 1\n", "line 5: mapping key is null"}, + } { + t.Run(test.name, func(t *testing.T) { + loader := NewLoader() + _, err := loader.LoadFromData([]byte(test.src)) + require.ErrorContains(t, err, test.want) + }) + } +} + +// A field error says what is wrong and the decoder says where, so the message +// carries the position once. +func TestNativeScalars_StringFieldErrorCarriesOnePosition(t *testing.T) { + var s Schema + require.EqualError(t, decodeNative(t, "type: 7\n", &s), + `yaml: construct errors: line 1: cannot unmarshal !!int into string field "type"`) +} - // Every other scalar has a name. +// A key names the text the document wrote it as, wherever it is read: the +// components a $ref addresses by name, and a mapping decoded into an any. +func TestNativeScalars_KeysAreTheirText(t *testing.T) { var named Schema require.NoError(t, decodeNative(t, "x-k: {1: a, true: b, 1.5: c, 0x2A: d}\n", &named)) - require.Equal(t, map[string]any{"1": "a", "true": "b", "1.5": "c", "42": "d"}, named.Extensions["x-k"]) + require.Equal(t, map[string]any{"1": "a", "true": "b", "1.5": "c", "0x2A": "d"}, named.Extensions["x-k"]) + + // Read as the value it resolves to instead, a key would name whatever + // another notation of the same number names, and the two would be one + // member with no telling which value it holds. + var same Schema + require.NoError(t, decodeNative(t, "x-k: {.0: a, 0: b, 18_24: c, 1824: d}\n", &same)) + require.Equal(t, map[string]any{".0": "a", "0": "b", "18_24": "c", "1824": "d"}, same.Extensions["x-k"]) + + // A key written as an alias says what the anchored scalar says, while the + // anchor's own use keeps the value it resolves to. + var aliased Schema + require.NoError(t, decodeNative(t, "x-a: &a 0x2A\nx-k:\n *a: v\n", &aliased)) + require.Equal(t, map[string]any{"0x2A": "v"}, aliased.Extensions["x-k"]) + require.Equal(t, float64(42), aliased.Extensions["x-a"]) + + // Two keys written the same text are the duplicate they are, through an + // alias as much as written out. + var dup, dupAlias Schema + require.ErrorContains(t, decodeNative(t, "x-k: {0: a, '0': b}\n", &dup), `mapping key "0" already defined`) + require.ErrorContains(t, decodeNative(t, "x-a: &a 18_24\nx-k:\n *a: v\n 18_24: w\n", &dupAlias), + `mapping key "18_24" already defined`) } // A requirement written as an alias is the mapping it points at, so a null in diff --git a/openapi3/native_yaml.go b/openapi3/native_yaml.go index d7e10e0a0..35bf69505 100644 --- a/openapi3/native_yaml.go +++ b/openapi3/native_yaml.go @@ -9,7 +9,7 @@ import ( "strings" "sync" - yaml "go.yaml.in/yaml/v3" + "go.yaml.in/yaml/v4" ) var knownYAMLFieldsCache sync.Map // reflect.Type -> map[string]struct{} @@ -95,13 +95,14 @@ func normalizeDecoded(v any) (any, error) { return v, nil } -// keyName is the name a non-string key is written under. YAML resolves a key -// the way it resolves any scalar, and a document's names are strings, so a -// scalar key is spelled out. +// keyName is the name a key that is not a string is written under. A scalar +// key reaches the decoder already retagged by nameKeys, so what is left here +// is a key that is not a scalar at all -- a sequence or a mapping, which YAML +// allows and a document's names, being strings, do not describe. // -// A null key spells nothing. It names no member of the document, and the json -// path has no key to decode it into, so a document that uses one is refused -// rather than given a made-up name. +// A null key spells nothing, and nameKeys refuses the document it appears in. +// The guard here is what keeps a null reaching the decoder another way from +// being given a made-up name. func keyName(k any) (string, error) { if k == nil { return "", errors.New("mapping key is null, so it names nothing") @@ -162,26 +163,6 @@ func mappingPairsOf(node *yaml.Node, expanding map[*yaml.Node]struct{}) [][2]*ya return pairs } -// mappingValue returns the value node for key, or nil. -func mappingValue(node *yaml.Node, key string) *yaml.Node { - _, v := mappingEntry(node, key) - return v -} - -// mappingEntry returns both halves of a mapping entry. Merge keys are applied, -// so a field a merge brought in is found here the same as one written in place. -func mappingEntry(node *yaml.Node, key string) (*yaml.Node, *yaml.Node) { - if node.Kind != yaml.MappingNode { - return nil, nil - } - for _, kv := range mappingPairs(node) { - if kv[0].Value == key { - return kv[0], kv[1] - } - } - return nil, nil -} - // isMergeKey reports whether k is a merge key rather than an ordinary one. // Only a plain << merges; quoted, it is a member actually named "<<", which // the json path keeps and so must this. @@ -347,11 +328,21 @@ func decodeMapping[T, S any](node *yaml.Node, shadow *S) (map[string]any, error) // targetTypeError names T where a decoder error names the shadow type S, which // exists only to stop the decode recursing and means nothing to a reader. func targetTypeError[T, S any](err error) error { + shadow, target := reflect.TypeFor[S]().String(), reflect.TypeFor[T]().String() + // Rename in place and hand back the error the decoder gave us. Returning a + // different type instead makes the decoder treat this as an error of its + // own and prefix it with the position again, once per nesting level. + var loadErrs *yaml.LoadErrors + if errors.As(err, &loadErrs) { + for _, e := range loadErrs.Errors { + e.Message = strings.ReplaceAll(e.Message, shadow, target) + } + return loadErrs + } var typeErr *yaml.TypeError if !errors.As(err, &typeErr) { return err } - shadow, target := reflect.TypeFor[S]().String(), reflect.TypeFor[T]().String() for i, message := range typeErr.Errors { typeErr.Errors[i] = strings.ReplaceAll(message, shadow, target) } @@ -518,29 +509,149 @@ func requireStringScalar(node *yaml.Node, key string) error { case "", strTag, nullTag, timestampTag: return nil } - return fmt.Errorf("yaml: line %d: cannot unmarshal %s into string field %q", node.Line, node.Tag, key) + return fmt.Errorf("cannot unmarshal %s into string field %q", node.Tag, key) } // prepareScalars walks the tree once, which is the one place every scalar is // seen before the decode reads it. func prepareScalars(n *yaml.Node) error { + var hasAlias bool + if err := prepareNode(n, &hasAlias); err != nil { + return err + } + if hasAlias { + return checkAliasCycles(n) + } + return nil +} + +func prepareNode(n *yaml.Node, hasAlias *bool) error { if n == nil { return nil } + if n.Kind == yaml.AliasNode { + *hasAlias = true + } if n.Kind == yaml.ScalarNode { + stripLocalTag(n) stripTimestamp(n) if err := checkFinite(n); err != nil { return err } } + if n.Kind == yaml.MappingNode { + if err := nameKeys(n); err != nil { + return err + } + } for _, c := range n.Content { - if err := prepareScalars(c); err != nil { + if err := prepareNode(c, hasAlias); err != nil { return err } } return nil } +// checkAliasCycles refuses a document in which an alias leads back to a node +// it sits inside, such as e: &a {properties: {p: *a}}. +// +// go-yaml refuses one too, but only within a single decode: it records the +// aliases it is expanding on the decoder. The native path decodes each typed +// value with a Node.Decode of its own, so every step starts with nothing +// recorded and the expansion recurses until the stack is exhausted, which is +// fatal rather than a panic a caller could recover. +// +// A node is walked once whatever number of aliases reach it, so the check is +// linear in the size of the tree even where expanding it would not be. +func checkAliasCycles(root *yaml.Node) error { + const ( + onPath = iota + 1 + done + ) + state := make(map[*yaml.Node]uint8) + var walk func(n *yaml.Node) error + walk = func(n *yaml.Node) error { + switch state[n] { + case onPath: + return fmt.Errorf("anchor %q value contains itself", n.Anchor) + case done: + return nil + } + state[n] = onPath + if n.Kind == yaml.AliasNode && n.Alias != nil { + if err := walk(n.Alias); err != nil { + return err + } + } + for _, c := range n.Content { + if err := walk(c); err != nil { + return err + } + } + state[n] = done + return nil + } + return walk(root) +} + +// nameKeys retags a scalar mapping key as a string, so the name it is read +// under is the text the document wrote. +// +// A document's names are strings, but YAML resolves a key like any other +// scalar, so .0 and 0 both resolve to the number zero and name the same +// member, as do 18_24 and 1824. Which of two such keys survives is then +// whichever the decoder writes last. The typed decode already reads a key's +// text; this gives a mapping decoded into an any the same reading, and leaves +// two keys written the same text to the duplicate-key error they are. +// +// A merge key is left alone, being an instruction rather than a name. A null +// key is refused, there being no name to read a member under: a typed mapping +// drops it, where decoding into an any reads the text that spelled the null, +// so the same key would name different things depending on where it sits. +// +// Interim: https://github.com/yaml/go-yaml/issues/491 asks for an option to +// read a mapping key as its text, which removes the retag. +func nameKeys(n *yaml.Node) error { + for i := 0; i+1 < len(n.Content); i += 2 { + k := n.Content[i] + if isMergeKey(k) { + continue + } + // A key written as an alias names what the anchored scalar says, read + // from a copy so the anchor's own use keeps the type it resolves to, + // and left at the line the alias is written on, where the member is + // declared. + if k.Kind == yaml.AliasNode && k.Alias != nil && k.Alias.Kind == yaml.ScalarNode { + named := *k.Alias + named.Anchor = "" + named.Line, named.Column = k.Line, k.Column + n.Content[i], k = &named, &named + } + if k.Kind != yaml.ScalarNode || k.Tag == strTag { + continue + } + if k.Tag == nullTag { + return fmt.Errorf("line %d: mapping key is null, so it names nothing", k.Line) + } + k.Tag = strTag + } + return nil +} + +// stripLocalTag retags a scalar carrying an application's own tag, such as +// !md in description: !md hello, as a string. +// +// go-yaml decodes such a scalar only into an any, so a document whose author +// tagged a field for a tool of their own was refused. The json path read it +// as the text it wrote, whatever that text looks like: description: !md hello +// is "hello" and x-n: !n 42 is "42". A standard tag (!!int, !!str, ...) +// starts with two marks and is left to the decoder. +func stripLocalTag(n *yaml.Node) { + if strings.HasPrefix(n.Tag, "!") && !strings.HasPrefix(n.Tag, "!!") { + n.Tag = strTag + } +} + // stripTimestamp retags a date-shaped scalar as a string. // // YAML 1.1 resolves an untagged scalar such as 2020-06-11T16:32:50-03:00 to a diff --git a/openapi3/native_yaml_alias_cycle_test.go b/openapi3/native_yaml_alias_cycle_test.go new file mode 100644 index 000000000..6a8884c8d --- /dev/null +++ b/openapi3/native_yaml_alias_cycle_test.go @@ -0,0 +1,35 @@ +package openapi3 + +import ( + "testing" + + "github.com/stretchr/testify/require" +) + +// An alias that leads back to a node it sits inside is refused, rather than +// expanded until the stack runs out, which no recover can catch. +func TestNativeYAMLAliasCycle(t *testing.T) { + const head = "openapi: 3.1.0\ninfo: {title: t, version: '1'}\npaths: {}\n" + + for name, doc := range map[string]string{ + "property": head + "components:\n schemas:\n e: &a\n properties:\n p: *a\n", + "items": head + "components:\n schemas:\n e: &a\n items: *a\n", + "nested": head + "components:\n schemas:\n e: &a\n allOf:\n - properties:\n p:\n items: *a\n", + "mutual": head + "components:\n schemas:\n a: &a\n items: &b\n not: *a\n b: *b\n", + "untyped": "components:\n schemas:\n e: &base\n properties:\n 2: *base\n", + } { + t.Run(name, func(t *testing.T) { + loader := NewLoader() + _, err := loader.LoadFromData([]byte(doc)) + require.ErrorContains(t, err, "value contains itself") + }) + } + + t.Run("shared", func(t *testing.T) { + doc := head + "components:\n schemas:\n s: &s {type: string}\n o:\n properties:\n a: *s\n b: *s\n items: *s\n" + loader := NewLoader() + got, err := loader.LoadFromData([]byte(doc)) + require.NoError(t, err) + require.Equal(t, "string", got.Components.Schemas["o"].Value.Properties["b"].Value.Type.Slice()[0]) + }) +} diff --git a/openapi3/native_yaml_direct_test.go b/openapi3/native_yaml_direct_test.go index b2c37495e..7886254e8 100644 --- a/openapi3/native_yaml_direct_test.go +++ b/openapi3/native_yaml_direct_test.go @@ -5,7 +5,7 @@ import ( "testing" "github.com/stretchr/testify/require" - yaml "go.yaml.in/yaml/v3" + "go.yaml.in/yaml/v4" "github.com/getkin/kin-openapi/openapi3" ) diff --git a/openapi3/native_yaml_local_tag_test.go b/openapi3/native_yaml_local_tag_test.go new file mode 100644 index 000000000..513bf01db --- /dev/null +++ b/openapi3/native_yaml_local_tag_test.go @@ -0,0 +1,34 @@ +package openapi3 + +import ( + "testing" + + "github.com/stretchr/testify/require" +) + +// A scalar carrying an application's own tag reads as the text it wrote, as it +// does on the json path, whatever field it sits in. +func TestNativeYAMLLocalTag(t *testing.T) { + doc := []byte(`openapi: 3.0.0 +info: + title: t + version: !v '1' + description: !md hello + x-n: !n 42 + x-m: !m {a: !b true} + x-s: !s [1, x] +paths: {} +components: + schemas: + S: + type: !0 string +`) + loader := NewLoader() + got, err := loader.LoadFromData(doc) + require.NoError(t, err) + + info, err := got.Info.MarshalJSON() + require.NoError(t, err) + require.JSONEq(t, `{"title":"t","version":"1","description":"hello","x-n":"42","x-m":{"a":"true"},"x-s":[1,"x"]}`, string(info)) + require.True(t, got.Components.Schemas["S"].Value.Type.Is("string")) +} diff --git a/openapi3/native_yaml_path.go b/openapi3/native_yaml_path.go new file mode 100644 index 000000000..52fd41b3d --- /dev/null +++ b/openapi3/native_yaml_path.go @@ -0,0 +1,89 @@ +package openapi3 + +import ( + "errors" + "strconv" + "strings" + + "go.yaml.in/yaml/v4" +) + +// nameFields adds the path of the node each error is about to its message, so +// a construct error names the field and not only the line. The parser reports +// a position, which the tree turns back into a path. +// +// An error whose position no node starts at, or which is about the document +// itself, keeps the message it came with. +func nameFields(err error, root *yaml.Node) error { + var loadErrs *yaml.LoadErrors + if !errors.As(err, &loadErrs) { + return err + } + + for _, e := range loadErrs.Errors { + if path, ok := nodePath(root, e.Mark.Line, e.Mark.Column); ok { + e.Message += " in " + path + } + } + return err +} + +// nodePath returns the JSON pointer of the node starting at line and column, +// and false when no node starts there or the node is the document's root, +// which has no path to name. +func nodePath(root *yaml.Node, line, column int) (string, bool) { + if root == nil || line == 0 || column == 0 { + return "", false + } + + node := root + if node.Kind == yaml.DocumentNode && len(node.Content) > 0 { + node = node.Content[0] + } + + path, ok := searchNode(node, line, column, nil) + if !ok || path == "" { + return "", false + } + return path, true +} + +// searchNode returns the pointer of the node under node that starts at line and +// column, where path names node itself. The shallowest match wins: a mapping +// and its first key start in the same place, and it is the mapping that an +// error about the mapping's type is reported at. +func searchNode(node *yaml.Node, line, column int, path []string) (string, bool) { + if node == nil { + return "", false + } + if node.Line == line && node.Column == column { + return pointerOf(path), true + } + + switch node.Kind { + case yaml.MappingNode: + for i := 0; i+1 < len(node.Content); i += 2 { + if found, ok := searchNode(node.Content[i+1], line, column, append(path, node.Content[i].Value)); ok { + return found, true + } + } + case yaml.SequenceNode: + for i, item := range node.Content { + if found, ok := searchNode(item, line, column, append(path, strconv.Itoa(i))); ok { + return found, true + } + } + } + return "", false +} + +// pointerOf writes path as an RFC 6901 JSON pointer, the form a $ref names a +// component with. +func pointerOf(path []string) string { + var b strings.Builder + for _, name := range path { + b.WriteByte('/') + b.WriteString(strings.ReplaceAll(strings.ReplaceAll(name, "~", "~0"), "/", "~1")) + } + return b.String() +} diff --git a/openapi3/native_yaml_path_test.go b/openapi3/native_yaml_path_test.go new file mode 100644 index 000000000..55b0bbd7e --- /dev/null +++ b/openapi3/native_yaml_path_test.go @@ -0,0 +1,73 @@ +package openapi3_test + +import ( + "testing" + + "github.com/stretchr/testify/require" + + "github.com/getkin/kin-openapi/openapi3" +) + +func TestUnmarshalErrorNamesTheField(t *testing.T) { + t.Parallel() + + for _, tt := range []struct { + name string + spec string + want string + }{ + { + name: "a scalar of the wrong type", + spec: ` +openapi: 3.0.1 +info: {version: v1, title: t} +paths: {} +components: + schemas: + S: + type: object + minItems: not-a-number +`, + want: "line 8: cannot construct !!str `not-a-n...` into uint64 in /components/schemas/S/minItems", + }, + { + name: "an item of a sequence, under a key holding a tilde", + spec: ` +openapi: 3.0.1 +info: {version: v1, title: t} +paths: {} +components: + schemas: + a~b: + type: object + required: + - ok + - {not: a string} +`, + want: "line 10: cannot construct !!map into string in /components/schemas/a~0b/required/1", + }, + { + name: "a path, whose slash is escaped", + spec: ` +openapi: 3.0.1 +info: {version: v1, title: t} +paths: + /p: + get: + responses: + '200': + description: '' + parameters: 3 +`, + want: "line 9: cannot construct !!int `3` into openapi3.Parameters in /paths/~1p/get/parameters", + }, + } { + t.Run(tt.name, func(t *testing.T) { + t.Parallel() + + loader := openapi3.NewLoader() + _, err := loader.LoadFromData([]byte(tt.spec[1:])) + require.ErrorContains(t, err, tt.want) + }) + } +} diff --git a/openapi3/native_yaml_refs.go b/openapi3/native_yaml_refs.go index 1923f7aba..3859493f5 100644 --- a/openapi3/native_yaml_refs.go +++ b/openapi3/native_yaml_refs.go @@ -5,7 +5,7 @@ package openapi3 import ( "strings" - yaml "go.yaml.in/yaml/v3" + "go.yaml.in/yaml/v4" ) // refYAMLFields are the keys the wrapper declares itself, so they are not diff --git a/openapi3/native_yaml_shadow.go b/openapi3/native_yaml_shadow.go index 4cbcd56bf..e9c6e0055 100644 --- a/openapi3/native_yaml_shadow.go +++ b/openapi3/native_yaml_shadow.go @@ -2,15 +2,15 @@ package openapi3 import ( - yaml "go.yaml.in/yaml/v3" + "go.yaml.in/yaml/v4" ) // UnmarshalYAML for the types whose YAML form is a mapping of declared fields // plus extensions. // // The local shadow type is what stops the decoder recursing into this method; -// converting the receiver to it decodes in place, so only the field the decoder -// skips is set afterwards. Everything else is in decodeMapping. +// converting the receiver to it decodes in place, so only the two fields the +// decoder skips are set afterwards. Everything else is in decodeMapping. // UnmarshalYAML sets Components from node. func (components *Components) UnmarshalYAML(node *yaml.Node) error { @@ -19,7 +19,8 @@ func (components *Components) UnmarshalYAML(node *yaml.Node) error { if err != nil { return err } - components.Extensions = ext + components.Extensions, components.Origin = ext, originFromNode(node, nativeOriginFile()) + setChildOriginKeys(node, components, nativeOriginFile()) return nil } @@ -30,7 +31,8 @@ func (contact *Contact) UnmarshalYAML(node *yaml.Node) error { if err != nil { return err } - contact.Extensions = ext + contact.Extensions, contact.Origin = ext, originFromNode(node, nativeOriginFile()) + setChildOriginKeys(node, contact, nativeOriginFile()) return nil } @@ -41,7 +43,8 @@ func (discriminator *Discriminator) UnmarshalYAML(node *yaml.Node) error { if err != nil { return err } - discriminator.Extensions = ext + discriminator.Extensions, discriminator.Origin = ext, originFromNode(node, nativeOriginFile()) + setChildOriginKeys(node, discriminator, nativeOriginFile()) return nil } @@ -52,7 +55,8 @@ func (encoding *Encoding) UnmarshalYAML(node *yaml.Node) error { if err != nil { return err } - encoding.Extensions = ext + encoding.Extensions, encoding.Origin = ext, originFromNode(node, nativeOriginFile()) + setChildOriginKeys(node, encoding, nativeOriginFile()) return nil } @@ -63,7 +67,8 @@ func (example *Example) UnmarshalYAML(node *yaml.Node) error { if err != nil { return err } - example.Extensions = ext + example.Extensions, example.Origin = ext, originFromNode(node, nativeOriginFile()) + setChildOriginKeys(node, example, nativeOriginFile()) return nil } @@ -74,7 +79,8 @@ func (e *ExternalDocs) UnmarshalYAML(node *yaml.Node) error { if err != nil { return err } - e.Extensions = ext + e.Extensions, e.Origin = ext, originFromNode(node, nativeOriginFile()) + setChildOriginKeys(node, e, nativeOriginFile()) return nil } @@ -85,7 +91,8 @@ func (info *Info) UnmarshalYAML(node *yaml.Node) error { if err != nil { return err } - info.Extensions = ext + info.Extensions, info.Origin = ext, originFromNode(node, nativeOriginFile()) + setChildOriginKeys(node, info, nativeOriginFile()) return nil } @@ -96,7 +103,8 @@ func (license *License) UnmarshalYAML(node *yaml.Node) error { if err != nil { return err } - license.Extensions = ext + license.Extensions, license.Origin = ext, originFromNode(node, nativeOriginFile()) + setChildOriginKeys(node, license, nativeOriginFile()) return nil } @@ -107,7 +115,8 @@ func (link *Link) UnmarshalYAML(node *yaml.Node) error { if err != nil { return err } - link.Extensions = ext + link.Extensions, link.Origin = ext, originFromNode(node, nativeOriginFile()) + setChildOriginKeys(node, link, nativeOriginFile()) return nil } @@ -118,7 +127,8 @@ func (mediaType *MediaType) UnmarshalYAML(node *yaml.Node) error { if err != nil { return err } - mediaType.Extensions = ext + mediaType.Extensions, mediaType.Origin = ext, originFromNode(node, nativeOriginFile()) + setChildOriginKeys(node, mediaType, nativeOriginFile()) return nil } @@ -129,7 +139,8 @@ func (flow *OAuthFlow) UnmarshalYAML(node *yaml.Node) error { if err != nil { return err } - flow.Extensions = ext + flow.Extensions, flow.Origin = ext, originFromNode(node, nativeOriginFile()) + setChildOriginKeys(node, flow, nativeOriginFile()) return nil } @@ -140,7 +151,8 @@ func (flows *OAuthFlows) UnmarshalYAML(node *yaml.Node) error { if err != nil { return err } - flows.Extensions = ext + flows.Extensions, flows.Origin = ext, originFromNode(node, nativeOriginFile()) + setChildOriginKeys(node, flows, nativeOriginFile()) return nil } @@ -151,7 +163,8 @@ func (parameter *Parameter) UnmarshalYAML(node *yaml.Node) error { if err != nil { return err } - parameter.Extensions = ext + parameter.Extensions, parameter.Origin = ext, originFromNode(node, nativeOriginFile()) + setChildOriginKeys(node, parameter, nativeOriginFile()) return nil } @@ -162,7 +175,8 @@ func (pathItem *PathItem) UnmarshalYAML(node *yaml.Node) error { if err != nil { return err } - pathItem.Extensions = ext + pathItem.Extensions, pathItem.Origin = ext, originFromNode(node, nativeOriginFile()) + setChildOriginKeys(node, pathItem, nativeOriginFile()) return nil } @@ -173,7 +187,8 @@ func (requestBody *RequestBody) UnmarshalYAML(node *yaml.Node) error { if err != nil { return err } - requestBody.Extensions = ext + requestBody.Extensions, requestBody.Origin = ext, originFromNode(node, nativeOriginFile()) + setChildOriginKeys(node, requestBody, nativeOriginFile()) return nil } @@ -184,7 +199,8 @@ func (response *Response) UnmarshalYAML(node *yaml.Node) error { if err != nil { return err } - response.Extensions = ext + response.Extensions, response.Origin = ext, originFromNode(node, nativeOriginFile()) + setChildOriginKeys(node, response, nativeOriginFile()) return nil } @@ -195,7 +211,8 @@ func (ss *SecurityScheme) UnmarshalYAML(node *yaml.Node) error { if err != nil { return err } - ss.Extensions = ext + ss.Extensions, ss.Origin = ext, originFromNode(node, nativeOriginFile()) + setChildOriginKeys(node, ss, nativeOriginFile()) return nil } @@ -206,7 +223,8 @@ func (server *Server) UnmarshalYAML(node *yaml.Node) error { if err != nil { return err } - server.Extensions = ext + server.Extensions, server.Origin = ext, originFromNode(node, nativeOriginFile()) + setChildOriginKeys(node, server, nativeOriginFile()) return nil } @@ -217,7 +235,8 @@ func (serverVariable *ServerVariable) UnmarshalYAML(node *yaml.Node) error { if err != nil { return err } - serverVariable.Extensions = ext + serverVariable.Extensions, serverVariable.Origin = ext, originFromNode(node, nativeOriginFile()) + setChildOriginKeys(node, serverVariable, nativeOriginFile()) return nil } @@ -228,7 +247,8 @@ func (t *Tag) UnmarshalYAML(node *yaml.Node) error { if err != nil { return err } - t.Extensions = ext + t.Extensions, t.Origin = ext, originFromNode(node, nativeOriginFile()) + setChildOriginKeys(node, t, nativeOriginFile()) return nil } @@ -239,6 +259,7 @@ func (xml *XML) UnmarshalYAML(node *yaml.Node) error { if err != nil { return err } - xml.Extensions = ext + xml.Extensions, xml.Origin = ext, originFromNode(node, nativeOriginFile()) + setChildOriginKeys(node, xml, nativeOriginFile()) return nil } diff --git a/openapi3/native_yaml_special.go b/openapi3/native_yaml_special.go index df283c75f..8b5cc3606 100644 --- a/openapi3/native_yaml_special.go +++ b/openapi3/native_yaml_special.go @@ -4,9 +4,10 @@ package openapi3 // rather than declared fields, and for the union-typed values. import ( + "reflect" "strings" - yaml "go.yaml.in/yaml/v3" + "go.yaml.in/yaml/v4" ) // unmarshalMaplikeYAML decodes a mapping whose x- keys are extensions and whose @@ -33,6 +34,8 @@ func unmarshalMaplikeYAML[V any](node *yaml.Node, ext *map[string]any, out *map[ return err } (*out)[k] = &vv + // The key node is in hand here, so no reflection is needed to find it. + setOriginKey(reflect.ValueOf(&vv), kv[0], kv[1], nativeOriginFile()) } return nil } @@ -69,6 +72,22 @@ func (header *Header) UnmarshalYAML(node *yaml.Node) error { return header.Parameter.UnmarshalYAML(node) } +// Types is a string or a list of strings. Swagger 2 and OpenAPI 3.0 documents +// always write `type` as a scalar, so the single-string case is what decoding +// such a document into openapi2.T or openapi3.T relies on. +func (types *Types) UnmarshalYAML(node *yaml.Node) error { + var list []string + if err := node.Decode(&list); err != nil { + var s string + if err := node.Decode(&s); err != nil { + return err + } + list = []string{s} + } + *types = list + return nil +} + // BoolSchema is `true`/`false` or a schema. func (bs *BoolSchema) UnmarshalYAML(node *yaml.Node) error { if node.Kind == yaml.ScalarNode { @@ -100,7 +119,7 @@ func (schema *Schema) UnmarshalYAML(node *yaml.Node) error { if err := node.Decode(&b); err != nil { return err } - schema.Always = &b + schema.Always, schema.Origin = &b, originFromNode(node, nativeOriginFile()) return nil } @@ -109,7 +128,8 @@ func (schema *Schema) UnmarshalYAML(node *yaml.Node) error { if err != nil { return err } - schema.Extensions = ext + schema.Extensions, schema.Origin = ext, originFromNode(node, nativeOriginFile()) + setChildOriginKeys(node, schema, nativeOriginFile()) return nil } @@ -142,20 +162,33 @@ func (operation *Operation) UnmarshalYAML(node *yaml.Node) error { if err != nil { return err } - operation.Extensions = ext + operation.Extensions, operation.Origin = ext, originFromNode(node, nativeOriginFile()) if v := mappingValue(node, "responses"); v != nil && v.Tag == nullTag { operation.Responses = &Responses{explicitlyNull: true} } + setChildOriginKeys(node, operation, nativeOriginFile()) return nil } +// T is the document root, so no parent stamps its Origin.Key. It takes its own +// first key instead, the same rule a sequence item follows. func (doc *T) UnmarshalYAML(node *yaml.Node) error { type bis T ext, err := decodeMapping[T](node, (*bis)(doc)) if err != nil { return err } - doc.Extensions = ext + doc.Extensions, doc.Origin = ext, originFromNode(node, nativeOriginFile()) + if doc.Origin != nil && node.Kind == yaml.MappingNode && len(node.Content) > 0 { + first := node.Content[0] + doc.Origin.Key = &Location{ + File: nativeOriginFile(), + Line: first.Line, + Column: first.Column, + Name: first.Value, + } + } + setChildOriginKeys(node, doc, nativeOriginFile()) return nil } diff --git a/openapi3/native_yaml_test.go b/openapi3/native_yaml_test.go index 1aef1f9bd..859f86e26 100644 --- a/openapi3/native_yaml_test.go +++ b/openapi3/native_yaml_test.go @@ -6,7 +6,7 @@ import ( "testing" "github.com/stretchr/testify/require" - goyaml "go.yaml.in/yaml/v3" + "go.yaml.in/yaml/v4" ) const nativeSrc = `"200": @@ -32,7 +32,7 @@ func TestNativeStock_MatchesJSONPath(t *testing.T) { require.NoError(t, json.Unmarshal(jsonBytes, &viaJSON)) var viaNode Responses - require.NoError(t, goyaml.Unmarshal([]byte(nativeSrc), &viaNode)) + require.NoError(t, yaml.Unmarshal([]byte(nativeSrc), &viaNode)) want, err := json.Marshal(&viaJSON) require.NoError(t, err) @@ -58,7 +58,7 @@ func TestNativeStock_OriginsAtDepth(t *testing.T) { func yamlToJSON(src string) ([]byte, error) { var v any - if err := goyaml.Unmarshal([]byte(src), &v); err != nil { + if err := yaml.Unmarshal([]byte(src), &v); err != nil { return nil, err } return json.Marshal(v) @@ -76,7 +76,7 @@ func TestNativeStock_TypeErrorNamesTheTarget(t *testing.T) { {"info", &Info{}, "openapi3.Info"}, } { t.Run(test.name, func(t *testing.T) { - err := goyaml.Unmarshal([]byte("GET /anything\n"), test.target) + err := yaml.Unmarshal([]byte("GET /anything\n"), test.target) require.ErrorContains(t, err, test.expect) require.NotContains(t, fmt.Sprint(err), "bis", "the shadow type is an implementation detail") }) @@ -93,7 +93,7 @@ func TestNativeStock_UnderscoredKeyStaysAString(t *testing.T) { type: object ` var components Components - require.NoError(t, goyaml.Unmarshal([]byte(src), &components)) + require.NoError(t, yaml.Unmarshal([]byte(src), &components)) require.Contains(t, components.Schemas, "18_24") require.Contains(t, components.Schemas, "25_34") } diff --git a/openapi3/nativeyaml.tmpl b/openapi3/nativeyaml.tmpl index 645defa5a..1b6ed64e3 100644 --- a/openapi3/nativeyaml.tmpl +++ b/openapi3/nativeyaml.tmpl @@ -2,15 +2,15 @@ package {{ .Package }} import ( - yaml "go.yaml.in/yaml/v3" + "go.yaml.in/yaml/v4" ) // UnmarshalYAML for the types whose YAML form is a mapping of declared fields // plus extensions. // // The local shadow type is what stops the decoder recursing into this method; -// converting the receiver to it decodes in place, so only the field the decoder -// skips is set afterwards. Everything else is in decodeMapping. +// converting the receiver to it decodes in place, so only the two fields the +// decoder skips are set afterwards. Everything else is in decodeMapping. {{ range $type := .Types }} // UnmarshalYAML sets {{ $type.Name }} from node. func ({{ $type.Recv }} *{{ $type.Name }}) UnmarshalYAML(node *yaml.Node) error { @@ -19,7 +19,8 @@ func ({{ $type.Recv }} *{{ $type.Name }}) UnmarshalYAML(node *yaml.Node) error { if err != nil { return err } - {{ $type.Recv }}.Extensions = ext + {{ $type.Recv }}.Extensions, {{ $type.Recv }}.Origin = ext, originFromNode(node, nativeOriginFile()) + setChildOriginKeys(node, {{ $type.Recv }}, nativeOriginFile()) return nil } {{ end -}} diff --git a/openapi3/non_finite_test.go b/openapi3/non_finite_test.go new file mode 100644 index 000000000..2bdf733b8 --- /dev/null +++ b/openapi3/non_finite_test.go @@ -0,0 +1,58 @@ +package openapi3_test + +import ( + "fmt" + "testing" + + "github.com/stretchr/testify/require" + + "github.com/getkin/kin-openapi/openapi3" +) + +// YAML has infinity and NaN and JSON does not, so a document carrying one +// cannot be written back. It is refused where it is read, naming the line, +// rather than at the marshal that would otherwise fail later. +func TestNonFiniteNumbersAreRefused(t *testing.T) { + t.Parallel() + + const header = "openapi: 3.1.0\ninfo: {title: t, version: \"1\"}\npaths: {}\n" + + for _, tt := range []struct { + name, doc, want string + }{ + {name: "schema bound", doc: "components:\n schemas:\n S: {type: number, maximum: .inf}\n", want: "line 6: .inf"}, + {name: "negative bound", doc: "components:\n schemas:\n S: {type: number, minimum: -.inf}\n", want: "line 6: -.inf"}, + {name: "extension", doc: "x-ratio: .NaN\n", want: "line 4: .NaN"}, + {name: "inside a sequence", doc: "x-list: [1, +.inf]\n", want: "line 4: +.inf"}, + {name: "explicitly tagged", doc: "x-ratio: !!float .inf\n", want: "line 4: .inf"}, + } { + t.Run(tt.name, func(t *testing.T) { + t.Parallel() + + loader := openapi3.NewLoader() + _, err := loader.LoadFromData([]byte(header + tt.doc)) + require.Error(t, err) + require.ErrorContains(t, err, tt.want) + require.ErrorContains(t, err, noJSONRepresentation) + }) + } +} + +const noJSONRepresentation = "has no JSON representation" + +// A float JSON can represent, and a quoted one that is a string, both load. +func TestFiniteNumbersAndQuotedInfinityLoad(t *testing.T) { + t.Parallel() + + const spec = "openapi: 3.1.0\ninfo: {title: t, version: \"1\"}\npaths: {}\nx-big: 1e308\nx-text: '.inf'\n" + + loader := openapi3.NewLoader() + doc, err := loader.LoadFromData([]byte(spec)) + require.NoError(t, err) + require.InDelta(t, 1e308, doc.Extensions["x-big"], 0) + require.Equal(t, ".inf", doc.Extensions["x-text"]) + + out, err := doc.MarshalJSON() + require.NoError(t, err) + require.Contains(t, string(out), fmt.Sprintf("%v", 1e308)) +} diff --git a/openapi3/openapi3_test.go b/openapi3/openapi3_test.go index 6109ea892..a7601ef9b 100644 --- a/openapi3/openapi3_test.go +++ b/openapi3/openapi3_test.go @@ -6,10 +6,10 @@ import ( "strings" "testing" - "github.com/oasdiff/yaml" "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require" + "github.com/getkin/kin-openapi/internal/yamlconv" "github.com/getkin/kin-openapi/openapi3" ) @@ -59,13 +59,13 @@ func TestRefsYAML(t *testing.T) { loader := openapi3.NewLoader() t.Log("Marshal *T to YAML") - data, err := yaml.Marshal(spec()) + data, err := yamlconv.Marshal(spec()) require.NoError(t, err) require.NotEmpty(t, data) t.Log("Unmarshal *T from YAML") docA := &openapi3.T{} - _, err = yaml.Unmarshal(specYAML, &docA, yaml.DecodeOpts{DisableTimestamps: true}) + err = yamlconv.Unmarshal(specYAML, &docA) require.NoError(t, err) require.NotEmpty(t, data) @@ -84,9 +84,9 @@ func TestRefsYAML(t *testing.T) { require.NoError(t, err) t.Log("Ensure representations match") - dataA, err := yaml.Marshal(docA) + dataA, err := yamlconv.Marshal(docA) require.NoError(t, err) - dataB, err := yaml.Marshal(docB) + dataB, err := yamlconv.Marshal(docB) require.NoError(t, err) require.YAMLEq(t, string(data), string(specYAML)) require.YAMLEq(t, string(data), string(dataA)) @@ -438,7 +438,7 @@ components: tt := tests[i] t.Run(tt.name, func(t *testing.T) { doc := &openapi3.T{} - _, err := yaml.Unmarshal([]byte(tt.spec), &doc, yaml.DecodeOpts{DisableTimestamps: true}) + err := yamlconv.Unmarshal([]byte(tt.spec), &doc) require.NoError(t, err) err = doc.Validate(t.Context()) diff --git a/openapi3/origin.go b/openapi3/origin.go index c41166f43..e55e8edb0 100644 --- a/openapi3/origin.go +++ b/openapi3/origin.go @@ -1,12 +1,25 @@ package openapi3 +// Origin records where each element of a document came from: the position of +// the key that heads a collection, of each of its fields, and of the scalar +// items in its sequence-valued fields. +// +// The positions are read from the nodes as the document decodes. A node knows +// where it starts, so the only piece it cannot supply is Key -- the key above +// it belongs to the parent, which stamps it. + import ( "encoding/json" "reflect" "slices" + "sort" "strings" + "sync" + "sync/atomic" - "github.com/oasdiff/yaml" + "go.yaml.in/yaml/v4" + + "github.com/getkin/kin-openapi/internal/nodeindex" ) var originPtrType = reflect.TypeFor[*Origin]() @@ -108,296 +121,385 @@ type Location struct { EndColumn int `json:"endColumn,omitempty,case:strict" yaml:"endColumn,omitempty"` } -// originFromSeq parses the compact []any sequence produced by yaml3's addOrigin. +// originTree is a decoded document's node tree together with what the origins +// read off it were stamped against. A $ref resolved later decodes a subtree of +// this, and must stamp the file the subtree came from rather than whichever +// document happened to be decoded last. +type originTree struct { + node *yaml.Node + file string + ends *nodeindex.Index +} + +// originDecode is what a decode has to reach from UnmarshalYAML, which +// receives a node and nothing else: the file to stamp into origins, and the +// index of the tree being decoded. A nil state means no decode is in progress +// and nothing gets an origin. // -// Format: [file, key_name, key_line, key_col, nf, f1_name, f1_delta, f1_col, ..., ns, s1_name, s1_count, s1_l0_delta, s1_c0, ...] -func originFromSeq(s []any) *Origin { - // Need at least: file, key_name, key_line, key_col, nf, ns - if len(s) < 6 { - return nil - } - file, _ := s[0].(string) - keyName, _ := s[1].(string) - keyLine := toInt(s[2]) - keyCol := toInt(s[3]) - - o := &Origin{ - Key: &Location{ - File: file, - Line: keyLine, - Column: keyCol, - Name: keyName, - }, - } - - idx := 4 - nf := toInt(s[idx]) - idx++ - if nf > 0 && idx+nf*3 <= len(s) { - o.Fields = make(FieldLocations, 0, nf) - for range nf { - fname, _ := s[idx].(string) - delta := toInt(s[idx+1]) - col := toInt(s[idx+2]) - o.Fields = append(o.Fields, Location{ - File: file, - Line: keyLine + delta, - Column: col, - Name: fname, - }) - idx += 3 - } - } +// A file recorded on the node itself would remove the need for state beside +// the call, but go-yaml's Node has no field for it. +// +// Interim: https://github.com/yaml/go-yaml/pull/392 passes a context through +// the decode, which carries both of these to the call that needs them and +// retires this type, the state below and the lock with it. +type originDecode struct { + file string + ends *nodeindex.Index +} - if idx >= len(s) { - return o +// originState points at the decode in progress. It is read atomically because +// a caller that hands openapi3 types to the yaml package decodes in its own +// goroutine, outside the lock a decode holds, and so reads this while another +// goroutine is writing it. +// +// One immutable value, published and replaced, is the whole of it: no counter, +// no compare-and-swap, nothing the atomic package's own warning about +// hand-rolled synchronisation is about. Guarding it with an RWMutex instead +// measures the same, single and in parallel, and costs two things: a second +// primitive beside the mutex that already serialises decodes, and a rule that +// the write lock must never be held across a decode, since the decode reads +// this itself and would deadlock. A reader here cannot block or deadlock, and +// the only rule is not to mutate what was published. +var originState atomic.Pointer[originDecode] + +// originMu serialises decodes, since there is one state above for all of them. +// The cost is that decodes wait on each other even when each has its own +// Loader, which TestIssue741 does. +var originMu sync.Mutex + +// Shared machinery for the UnmarshalYAML methods: extension collection, and +// origins read from the node being decoded. +// +// Origins record where an element starts, not where it ends. A consumer that +// needs the extent of a block derives it from the next key or sequence item at +// the same or shallower indentation. + +func nativeOriginFile() string { + if st := originState.Load(); st != nil { + return st.file } - ns := toInt(s[idx]) - idx++ - if ns > 0 { - o.Sequences = make(map[string][]Location, ns) - for range ns { - if idx >= len(s) { - break - } - sname, _ := s[idx].(string) - idx++ - if idx >= len(s) { - break - } - count := toInt(s[idx]) - idx++ - locs := make([]Location, 0, count) - for j := 0; j < count && idx+2 < len(s); j++ { - name, _ := s[idx].(string) - delta := toInt(s[idx+1]) - col := toInt(s[idx+2]) - locs = append(locs, Location{File: file, Line: keyLine + delta, Column: col, Name: name}) - idx += 3 - } - o.Sequences[sname] = locs - } + return "" +} + +// originsApply reports whether node belongs to the decode in progress. A +// caller handing openapi3 types to the yaml package decodes a tree no decode +// here indexed, and gets no origins rather than another document's. +func originsApply(node *yaml.Node) bool { + st := originState.Load() + if st == nil { + return false } + return st.ends.Has(node) +} + +// mappingValue returns the value node for key, or nil. +func mappingValue(node *yaml.Node, key string) *yaml.Node { + _, v := mappingEntry(node, key) + return v +} - // Trailing block end (yaml3 >= the end-position release): end_delta, end_col. - // Reconstruct the end of the whole block on Origin.Key so a consumer can - // extract the entire element. Older origin sequences omit these, leaving - // EndLine/EndColumn zero. end_col == 0 means no end information was recorded. - if o.Key != nil && idx+1 < len(s) { - if endCol := toInt(s[idx+1]); endCol > 0 { - o.Key.EndLine = keyLine + toInt(s[idx]) - o.Key.EndColumn = endCol +// mappingEntry returns both halves of a mapping entry, the key being what a +// value's origin records as its own location. Merge keys are applied, so a +// field a merge brought in is found here the same as one written in place. +func mappingEntry(node *yaml.Node, key string) (*yaml.Node, *yaml.Node) { + if node.Kind != yaml.MappingNode { + return nil, nil + } + for _, kv := range mappingPairs(node) { + if kv[0].Value == key { + return kv[0], kv[1] } } - return o + return nil, nil } -// toInt converts numeric types to int. Handles int/uint64 from YAML decoding. -func toInt(v any) int { - switch n := v.(type) { - case int: - return n - case uint64: - return int(n) +// originFromNode builds the origin data a mapping can see for itself: where +// each of its field keys is, and where the scalar items of its sequence-valued +// fields are. +// +// Origin.Key is not set here -- it is the location of the key heading this +// mapping in its parent, which a node does not know. See setChildOriginKeys. +func originFromNode(node *yaml.Node, file string) *Origin { + // Origins are opt-in: without this every decode pays for them. + if !originsApply(node) { + return nil } - return 0 -} + if node == nil || node.Kind != yaml.MappingNode { + return nil + } + o := &Origin{} + for i := 0; i+1 < len(node.Content); i += 2 { + k, v := node.Content[i], node.Content[i+1] + if o.Fields == nil { + o.Fields = make(FieldLocations, 0, len(node.Content)/2) + } + o.Fields = append(o.Fields, Location{File: file, Line: k.Line, Column: k.Column, Name: k.Value}) -// isScalarValuedMapField reports whether v is a non-empty map whose element -// type is a scalar (string, bool, or a numeric kind). Such a map decodes -// without an Origin field of its own, unlike a pointer- or struct-valued map -// whose elements each carry their own Origin. -func isScalarValuedMapField(v reflect.Value) bool { - if v.Kind() != reflect.Map || v.IsNil() || v.Len() == 0 { - return false + if v.Kind != yaml.SequenceNode { + continue + } + var locs []Location + for _, item := range v.Content { + if item.Kind == yaml.ScalarNode { + locs = append(locs, Location{File: file, Line: item.Line, Column: item.Column, Name: item.Value}) + } + } + if len(locs) > 0 { + if o.Sequences == nil { + o.Sequences = make(map[string][]Location) + } + o.Sequences[k.Value] = locs + } } - switch v.Type().Elem().Kind() { - case reflect.String, reflect.Bool, - reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64, - reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64, - reflect.Float32, reflect.Float64: - return true + if o.Fields == nil && o.Sequences == nil { + return nil } - return false + return o } -// recordMapKeyLocations moves the map-key locations from a scalar-valued map's -// own subtree onto parentOrigin.Sequences[field], so each key is addressable by -// name (the same shape used for sequence items). It is a no-op when the child -// carries no origin data. Keys are sorted for deterministic output. +// setChildOriginKeys sets Origin.Key on the immediate children of a mapping, +// from the key node heading each one. // -// childOrigin is discarded here, and nothing else holds its Fields, so the -// slice is sorted and handed over in place rather than copied. -func recordMapKeyLocations(parentOrigin *Origin, field string, childTree *yaml.OriginTree) { - s, ok := childTree.Origin.([]any) - if !ok { +// This is the only origin data a node cannot supply for itself: UnmarshalYAML +// receives the value node, and Key is the position of the key above it. Each +// child sets its own children's keys in turn, so one level per call covers the +// tree. +func setChildOriginKeys(node *yaml.Node, container any, file string) { + if !originsApply(node) { return } - childOrigin := originFromSeq(s) - if childOrigin == nil || len(childOrigin.Fields) == 0 { + if node == nil || node.Kind != yaml.MappingNode { return } - locs := childOrigin.Fields - slices.SortFunc(locs, func(a, b Location) int { return strings.Compare(a.Name, b.Name) }) - if parentOrigin.Sequences == nil { - parentOrigin.Sequences = make(map[string][]Location) + v := reflect.ValueOf(container) + for v.Kind() == reflect.Pointer || v.Kind() == reflect.Interface { + if v.IsNil() { + return + } + v = v.Elem() } - parentOrigin.Sequences[field] = locs -} + for i := 0; i+1 < len(node.Content); i += 2 { + keyNode, valNode := node.Content[i], node.Content[i+1] + child := childByKey(v, keyNode.Value) + if !child.IsValid() { + continue + } + setOriginKey(child, keyNode, valNode, file) + recordScalarMapKeys(v, child, keyNode, valNode, file) -// applyOrigins walks a Go struct tree and a parallel OriginTree, setting -// Origin fields on each struct from the extracted origin data. -func applyOrigins(v any, tree *yaml.OriginTree) { - if tree == nil { - return + switch c := deref(child); c.Kind() { + case reflect.Map: + // A map-valued field (Content, Headers, Links) holds children of + // its own, keyed in valNode. The generic map decoder gives them no + // hook of their own, so descend. + if c.CanInterface() { + setChildOriginKeys(valNode, c.Interface(), file) + } + case reflect.Slice: + // A sequence item has no key above it, so it takes its own first + // key as its Key. + if valNode.Kind != yaml.SequenceNode { + continue + } + for j := 0; j < len(valNode.Content) && j < c.Len(); j++ { + item := valNode.Content[j] + if item.Kind == yaml.MappingNode && len(item.Content) > 0 { + setOriginKey(c.Index(j), item.Content[0], item, file) + } + } + } } - applyOriginsToValue(reflect.ValueOf(v), tree) } -func applyOriginsToValue(val reflect.Value, tree *yaml.OriginTree) { - // Keep track of the last pointer so we can pass it to struct handlers - // (needed for calling methods like Map() on maplike types). - var ptr reflect.Value - for val.Kind() == reflect.Pointer || val.Kind() == reflect.Interface { - if val.IsNil() { - return - } - if val.Kind() == reflect.Pointer { - ptr = val +func deref(v reflect.Value) reflect.Value { + for v.Kind() == reflect.Pointer || v.Kind() == reflect.Interface { + if v.IsNil() { + return v } - val = val.Elem() + v = v.Elem() } + return v +} - switch val.Kind() { - case reflect.Struct: - applyOriginsToStruct(val, ptr, tree) +// childByKey finds the struct field or map entry a mapping key decoded into. +func childByKey(v reflect.Value, key string) reflect.Value { + switch v.Kind() { case reflect.Map: - applyOriginsToMap(val, tree) - case reflect.Slice: - applyOriginsToSlice(val, tree) + if v.IsNil() { + return reflect.Value{} + } + return v.MapIndex(reflect.ValueOf(key)) + case reflect.Struct: + t := v.Type() + for i := range t.NumField() { + f := t.Field(i) + if !f.IsExported() { + continue + } + if name, _, _ := strings.Cut(f.Tag.Get("yaml"), ","); name == key { + return v.Field(i) + } + } } + return reflect.Value{} } -func applyOriginsToStruct(val reflect.Value, ptr reflect.Value, tree *yaml.OriginTree) { - typ := val.Type() - - // Set Origin field for structs whose Origin field has a "-" json tag. - var structOrigin *Origin - if tree.Origin != nil { - if sf, ok := typ.FieldByName("Origin"); ok && sf.Type == originPtrType { - tag := sf.Tag.Get("json") - if tag == "-" { - if s, ok := tree.Origin.([]any); ok { - structOrigin = originFromSeq(s) - val.FieldByName("Origin").Set(reflect.ValueOf(structOrigin)) - } - } +// setOriginKey stamps Key on a child carrying an *Origin, from the key's own +// position. The extent of what the key heads is the consumer's to derive. +func setOriginKey(child reflect.Value, keyNode, valNode *yaml.Node, file string) { + if !originsApply(keyNode) { + return + } + keyNode, valNode = resolveAlias(keyNode, valNode) + for child.Kind() == reflect.Pointer || child.Kind() == reflect.Interface { + if child.IsNil() { + return } + child = child.Elem() + } + if child.Kind() != reflect.Struct { + return + } + f := child.FieldByName("Origin") + if !f.IsValid() || f.Type() != originPtrType || !f.CanSet() { + // No origin of its own; it may still wrap something that has one. + descendToWrapped(child, keyNode, valNode, file) + return } + if f.IsNil() { + f.Set(reflect.ValueOf(&Origin{})) + } + key := withEnd(Location{ + File: file, + Line: keyNode.Line, + Column: keyNode.Column, + Name: keyNode.Value, + }, valNode) + f.Interface().(*Origin).Key = &key + // A wrapper and the thing it holds occupy the same node, so both carry + // that node's origin. Value is the $ref wrappers; Schema is BoolSchema, + // which holds either a bool or a schema. + descendToWrapped(child, keyNode, valNode, file) +} - // Recurse into exported struct fields using json tags - for i := range typ.NumField() { - sf := typ.Field(i) - if !sf.IsExported() { - continue - } - tag := jsonTagName(sf) - if tag == "" || tag == "-" { - continue - } - childTree := tree.Fields[tag] - if childTree == nil { - continue - } - // A scalar-valued map (e.g. OAuth scopes: map[string]string) decodes into - // a Go map that has no Origin field of its own, so its per-key locations — - // present in the child subtree — would otherwise be lost. Record them on - // this struct's Origin as a named sequence so a consumer can locate each - // entry by key. Object- or pointer-valued maps are excluded: their values - // carry their own Origin via the recursion below. - if structOrigin != nil && isScalarValuedMapField(val.Field(i)) { - recordMapKeyLocations(structOrigin, tag, childTree) +// descendToWrapped stamps the thing a wrapper holds, which occupies the same +// node. Value is the $ref wrappers; Schema is BoolSchema, which holds either a +// bool or a schema. +func descendToWrapped(child reflect.Value, keyNode, valNode *yaml.Node, file string) { + if child.Kind() != reflect.Struct { + return + } + for _, name := range [...]string{"Value", "Schema"} { + if inner := child.FieldByName(name); inner.IsValid() { + setOriginKey(inner, keyNode, valNode, file) } - applyOriginsToValue(val.Field(i), childTree) } +} - // Handle wrapper types whose inner struct has no json tag: - // - *Ref types (e.g. SchemaRef, ResponseRef) have a "Value" field - // - BoolSchema (AdditionalProperties, UnevaluatedProperties, UnevaluatedItems) has a "Schema" field - // The origin tree data applies to the inner struct, not a sub-key. - for _, fieldName := range []string{"Value", "Schema"} { - vf := val.FieldByName(fieldName) - if !vf.IsValid() || vf.Kind() != reflect.Pointer || vf.IsNil() { - continue - } - sf, _ := typ.FieldByName(fieldName) - if sf.Tag.Get("json") == "" { - applyOriginsToValue(vf, tree) +// stampRootOrigin gives a document root the position of the document itself. +// +// Origin.Key is normally the key heading a mapping in its parent, stamped by +// that parent. A root has none -- an externally $ref'd file may be a bare +// schema -- so it takes the root node's own position and an empty name. +// Applied only when nothing has already set Key, so a type that supplies its +// own keeps it. +func stampRootOrigin(v any, node *yaml.Node) { + if !originsApply(node) { + return + } + rv := reflect.ValueOf(v) + for rv.Kind() == reflect.Pointer || rv.Kind() == reflect.Interface { + if rv.IsNil() { + return } + rv = rv.Elem() } + if rv.Kind() != reflect.Struct { + return + } + stampOriginKey(rv, node) - // Handle "maplike" types (Paths, Responses, Callback) whose items are - // stored in an unexported map accessible via a Map() method. - // Use the original pointer (if available) since dereferenced values - // are not addressable. - receiver := val - if ptr.IsValid() { - receiver = ptr - } else if val.CanAddr() { - receiver = val.Addr() - } - if receiver.Kind() == reflect.Pointer { - if mapMethod := receiver.MethodByName("Map"); mapMethod.IsValid() { - results := mapMethod.Call(nil) - if len(results) == 1 { - applyOriginsToMap(results[0], tree) - } - } + // A file holding a bare component decodes to a ref wrapper, so the object + // written at the root is the one the wrapper holds. A wrapper whose file + // holds a $ref has no value yet, and the value it later resolves to was + // written elsewhere. + if value := rv.FieldByName("Value"); value.IsValid() && value.Kind() == reflect.Pointer && !value.IsNil() { + stampRootOrigin(value.Interface(), node) } } -func applyOriginsToMap(val reflect.Value, tree *yaml.OriginTree) { - if tree.Fields == nil { +// stampOriginKey sets Origin.Key on rv from node, leaving one already set. +func stampOriginKey(rv reflect.Value, node *yaml.Node) { + f := rv.FieldByName("Origin") + if !f.IsValid() || f.Type() != originPtrType || !f.CanSet() || f.IsNil() { return } - for _, key := range val.MapKeys() { - childTree := tree.Fields[key.String()] - if childTree == nil { - continue - } - elem := val.MapIndex(key) - // Map values are not addressable. For pointer-typed values we can - // recurse directly. For value types we must copy, apply, and set back. - if elem.Kind() == reflect.Pointer || elem.Kind() == reflect.Interface { - applyOriginsToValue(elem, childTree) - } else if elem.Kind() == reflect.Struct { - // Copy to a settable value - cp := reflect.New(elem.Type()).Elem() - cp.Set(elem) - applyOriginsToStruct(cp, reflect.Value{}, childTree) - val.SetMapIndex(key, cp) - } + o := f.Interface().(*Origin) + if o.Key != nil { + return } + key := withEnd(Location{File: nativeOriginFile(), Line: node.Line, Column: node.Column}, node) + o.Key = &key } -func applyOriginsToSlice(val reflect.Value, tree *yaml.OriginTree) { - for i := 0; i < val.Len() && i < len(tree.Items); i++ { - if tree.Items[i] != nil { - applyOriginsToValue(val.Index(i), tree.Items[i]) - } +// recordScalarMapKeys records where each key of a scalar-valued map sits. +// +// A map[string]string -- scopes on an OAuth flow, say -- decodes to a plain Go +// map with nowhere to hang an Origin of its own, so its keys are recorded on +// the enclosing struct's Origin under the field name, sorted by key. +func recordScalarMapKeys(container, child reflect.Value, keyNode, valNode *yaml.Node, file string) { + if child.Kind() != reflect.Map || valNode == nil || valNode.Kind != yaml.MappingNode { + return } + // A map of structs or pointers carries origins on its values instead. + switch child.Type().Elem().Kind() { + case reflect.Struct, reflect.Pointer, reflect.Interface, reflect.Map, reflect.Slice: + return + } + f := container.FieldByName("Origin") + if !f.IsValid() || f.Type() != originPtrType || !f.CanSet() { + return + } + if f.IsNil() { + f.Set(reflect.ValueOf(&Origin{})) + } + var locs []Location + for i := 0; i+1 < len(valNode.Content); i += 2 { + k := valNode.Content[i] + locs = append(locs, Location{File: file, Line: k.Line, Column: k.Column, Name: k.Value}) + } + if len(locs) == 0 { + return + } + sort.Slice(locs, func(i, j int) bool { return locs[i].Name < locs[j].Name }) + o := f.Interface().(*Origin) + if o.Sequences == nil { + o.Sequences = make(map[string][]Location) + } + o.Sequences[keyNode.Value] = locs } -// jsonTagName returns the JSON field name from a struct field's json tag. -func jsonTagName(f reflect.StructField) string { - tag := f.Tag.Get("json") - if tag == "" { - return "" +// withEnd returns loc carrying the extent of the block node heads. +func withEnd(loc Location, node *yaml.Node) Location { + if st := originState.Load(); st != nil { + loc.EndLine, loc.EndColumn = st.ends.EndOf(node) } - name, _, _ := strings.Cut(tag, ",") - return name + return loc } -// originTree aliases the decoder-side origin tree, so the loader and marsh can -// carry it without referencing the yaml package directly. -type originTree = yaml.OriginTree +// resolveAlias follows an alias to the node it points at, together with the key +// that node was defined under. An aliased schema is the anchored one, so its +// origin is where that content was written, not where it was referred to. +func resolveAlias(keyNode, valNode *yaml.Node) (*yaml.Node, *yaml.Node) { + if valNode == nil || valNode.Kind != yaml.AliasNode || valNode.Alias == nil { + return keyNode, valNode + } + st := originState.Load() + if st == nil { + return keyNode, valNode.Alias + } + if k, ok := st.ends.AnchorKey(valNode.Alias); ok { + return k, valNode.Alias + } + return keyNode, valNode.Alias +} diff --git a/openapi3/origin_concurrency_test.go b/openapi3/origin_concurrency_test.go new file mode 100644 index 000000000..c1b35c5dd --- /dev/null +++ b/openapi3/origin_concurrency_test.go @@ -0,0 +1,82 @@ +package openapi3 + +import ( + "sync" + "testing" + + "go.yaml.in/yaml/v4" +) + +const concurrentSpec = ` +openapi: 3.0.0 +info: {title: t, version: "1"} +paths: + /a: + get: + responses: + "200": {description: ok} +` + +// A decode reaches UnmarshalYAML through package state, so a caller handing +// these types to the yaml package itself decodes while another goroutine holds +// that state. Such a decode indexed no tree, so it gets no origins, and reads +// the state without racing the decode that set it. +// +// Run with -race, which the workflow does by name. Skipped in -short mode: the +// concurrency is the point of the test, and the Windows runners already retry +// the short suite around flaky memory corruption in Go 1.26 and 1.27. +func TestConcurrentDecodeDoesNotLeakOrigins(t *testing.T) { + if testing.Short() { + t.Skip("decodes concurrently; runs in the dedicated -race step") + } + + var wg sync.WaitGroup + wg.Add(3) + + go func() { + defer wg.Done() + for range 50 { + loader := NewLoader() + loader.IncludeOrigin = true + if _, err := loader.LoadFromData([]byte(concurrentSpec)); err != nil { + t.Error(err) + return + } + } + }() + + go func() { + defer wg.Done() + for range 50 { + var doc T + if err := yaml.Unmarshal([]byte(concurrentSpec), &doc); err != nil { + t.Error(err) + return + } + if doc.Info != nil && doc.Info.Origin != nil { + t.Error("a decode through the yaml package took the origins of a decode running beside it") + return + } + } + }() + + // A Loader that asked for no origins holds no lock, so it runs beside the + // one above rather than waiting for it, and must still come back bare. + go func() { + defer wg.Done() + for range 50 { + loader := NewLoader() + doc, err := loader.LoadFromData([]byte(concurrentSpec)) + if err != nil { + t.Error(err) + return + } + if doc.Info.Origin != nil { + t.Error("a load that asked for no origins took the origins of a decode running beside it") + return + } + } + }() + + wg.Wait() +} diff --git a/openapi3/origin_load_test.go b/openapi3/origin_load_test.go index 9de9d7a57..5a7e54020 100644 --- a/openapi3/origin_load_test.go +++ b/openapi3/origin_load_test.go @@ -6,9 +6,7 @@ import ( "github.com/stretchr/testify/require" ) -// TestOrigin_LoadAllTestdata verifies that enabling origin tracking does not -// break loading of any spec in the testdata directory. It catches regressions -// where __origin__ leaks into fields and causes unmarshal failures or panics. +// Enabling origin tracking must not break loading any spec in testdata. func TestOrigin_LoadAllTestdata(t *testing.T) { t.Parallel() diff --git a/openapi3/origin_release_test.go b/openapi3/origin_release_test.go new file mode 100644 index 000000000..f5bfadf4c --- /dev/null +++ b/openapi3/origin_release_test.go @@ -0,0 +1,20 @@ +package openapi3 + +import ( + "testing" + + "github.com/stretchr/testify/require" +) + +// A decode releases its per-decode state when it ends. That state indexes the +// whole node tree, so leaving it set pins that tree until the next decode +// replaces it, and does so for every caller whether or not rememberOriginTree +// kept the tree. On a 25 MB spec that tree is most of what a load holds. +func TestUnmarshalReleasesPerDecodeState(t *testing.T) { + loader := NewLoader() + loader.IncludeOrigin = true + _, err := loader.LoadFromData([]byte("openapi: 3.0.0\ninfo: {title: t, version: \"1\"}\npaths: {}\n")) + require.NoError(t, err) + + require.Nil(t, originState.Load(), "the decode state outlived its decode, pinning the node tree it indexes") +} diff --git a/openapi3/origin_test.go b/openapi3/origin_test.go index 37b43211f..487d57822 100644 --- a/openapi3/origin_test.go +++ b/openapi3/origin_test.go @@ -635,10 +635,14 @@ components: loader := openapi3.NewLoader() loader.IncludeOrigin = true - _, err := loader.LoadFromData([]byte(data)) - require.Error(t, err) - require.Equal(t, `failed to unmarshal data: yaml error: error converting YAML to JSON: yaml: unmarshal errors: - line 0: mapping key "__origin__" already defined at line 17`, err.Error()) + doc, err := loader.LoadFromData([]byte(data)) + require.NoError(t, err) + + // "__origin__" is an ordinary property name: positions travel beside the + // document rather than inside it, so no key is reserved. + properties := doc.Components.Schemas["Foo"].Value.Properties + require.Contains(t, properties, "__origin__") + require.True(t, properties["__origin__"].Value.Type.Is("string")) } // TestOrigin_ExtensionValuesStripped verifies that __origin__ metadata injected diff --git a/openapi3/refs.go b/openapi3/refs.go index afab87acd..766e719cf 100644 --- a/openapi3/refs.go +++ b/openapi3/refs.go @@ -9,7 +9,7 @@ import ( "strings" "github.com/go-openapi/jsonpointer" - yaml "go.yaml.in/yaml/v3" + "go.yaml.in/yaml/v4" ) // CallbackRef represents either a Callback or a $ref to a Callback. @@ -91,6 +91,7 @@ func (x CallbackRef) MarshalJSON() ([]byte, error) { // UnmarshalYAML sets CallbackRef from node. func (x *CallbackRef) UnmarshalYAML(node *yaml.Node) error { + x.Origin = originFromNode(node, nativeOriginFile()) if !unmarshalRefYAML(node, &x.Ref, &x.Summary, &x.Description, &x.Extensions, &x.extra, &x.siblingExtras) { return node.Decode(&x.Value) } @@ -266,6 +267,7 @@ func (x ExampleRef) MarshalJSON() ([]byte, error) { // UnmarshalYAML sets ExampleRef from node. func (x *ExampleRef) UnmarshalYAML(node *yaml.Node) error { + x.Origin = originFromNode(node, nativeOriginFile()) if !unmarshalRefYAML(node, &x.Ref, &x.Summary, &x.Description, &x.Extensions, &x.extra, &x.siblingExtras) { return node.Decode(&x.Value) } @@ -441,6 +443,7 @@ func (x HeaderRef) MarshalJSON() ([]byte, error) { // UnmarshalYAML sets HeaderRef from node. func (x *HeaderRef) UnmarshalYAML(node *yaml.Node) error { + x.Origin = originFromNode(node, nativeOriginFile()) if !unmarshalRefYAML(node, &x.Ref, &x.Summary, &x.Description, &x.Extensions, &x.extra, &x.siblingExtras) { return node.Decode(&x.Value) } @@ -616,6 +619,7 @@ func (x LinkRef) MarshalJSON() ([]byte, error) { // UnmarshalYAML sets LinkRef from node. func (x *LinkRef) UnmarshalYAML(node *yaml.Node) error { + x.Origin = originFromNode(node, nativeOriginFile()) if !unmarshalRefYAML(node, &x.Ref, &x.Summary, &x.Description, &x.Extensions, &x.extra, &x.siblingExtras) { return node.Decode(&x.Value) } @@ -791,6 +795,7 @@ func (x ParameterRef) MarshalJSON() ([]byte, error) { // UnmarshalYAML sets ParameterRef from node. func (x *ParameterRef) UnmarshalYAML(node *yaml.Node) error { + x.Origin = originFromNode(node, nativeOriginFile()) if !unmarshalRefYAML(node, &x.Ref, &x.Summary, &x.Description, &x.Extensions, &x.extra, &x.siblingExtras) { return node.Decode(&x.Value) } @@ -966,6 +971,7 @@ func (x RequestBodyRef) MarshalJSON() ([]byte, error) { // UnmarshalYAML sets RequestBodyRef from node. func (x *RequestBodyRef) UnmarshalYAML(node *yaml.Node) error { + x.Origin = originFromNode(node, nativeOriginFile()) if !unmarshalRefYAML(node, &x.Ref, &x.Summary, &x.Description, &x.Extensions, &x.extra, &x.siblingExtras) { return node.Decode(&x.Value) } @@ -1141,6 +1147,7 @@ func (x ResponseRef) MarshalJSON() ([]byte, error) { // UnmarshalYAML sets ResponseRef from node. func (x *ResponseRef) UnmarshalYAML(node *yaml.Node) error { + x.Origin = originFromNode(node, nativeOriginFile()) if !unmarshalRefYAML(node, &x.Ref, &x.Summary, &x.Description, &x.Extensions, &x.extra, &x.siblingExtras) { return node.Decode(&x.Value) } @@ -1337,6 +1344,7 @@ func (x SchemaRef) MarshalJSON() ([]byte, error) { // UnmarshalYAML sets SchemaRef from node. func (x *SchemaRef) UnmarshalYAML(node *yaml.Node) error { + x.Origin = originFromNode(node, nativeOriginFile()) if !unmarshalRefYAML(node, &x.Ref, nil, nil, &x.Extensions, &x.extra, &x.siblingExtras) { return node.Decode(&x.Value) } @@ -1544,6 +1552,7 @@ func (x SecuritySchemeRef) MarshalJSON() ([]byte, error) { // UnmarshalYAML sets SecuritySchemeRef from node. func (x *SecuritySchemeRef) UnmarshalYAML(node *yaml.Node) error { + x.Origin = originFromNode(node, nativeOriginFile()) if !unmarshalRefYAML(node, &x.Ref, &x.Summary, &x.Description, &x.Extensions, &x.extra, &x.siblingExtras) { return node.Decode(&x.Value) } diff --git a/openapi3/refs.tmpl b/openapi3/refs.tmpl index 3b2669ad3..e761d8001 100644 --- a/openapi3/refs.tmpl +++ b/openapi3/refs.tmpl @@ -9,7 +9,7 @@ import ( "strings" "github.com/go-openapi/jsonpointer" - yaml "go.yaml.in/yaml/v3" + "go.yaml.in/yaml/v4" ) {{ range $type := .Types }} // {{ $type.Name }}Ref represents either a {{ $type.Name }} or a $ref to a {{ $type.Name }}. @@ -126,6 +126,7 @@ func (x {{ $type.Name }}Ref) MarshalJSON() ([]byte, error) { // UnmarshalYAML sets {{ $type.Name }}Ref from node. func (x *{{ $type.Name }}Ref) UnmarshalYAML(node *yaml.Node) error { + x.Origin = originFromNode(node, nativeOriginFile()) if !unmarshalRefYAML(node, &x.Ref{{ if ne $type.Name "Schema" }}, &x.Summary, &x.Description{{ else }}, nil, nil{{ end }}, &x.Extensions, &x.extra, &x.siblingExtras) { return node.Decode(&x.Value) } diff --git a/openapi3/schema.go b/openapi3/schema.go index 938d667cb..4f915ed8f 100644 --- a/openapi3/schema.go +++ b/openapi3/schema.go @@ -402,24 +402,6 @@ func (types *Types) UnmarshalJSON(data []byte) error { return nil } -// UnmarshalYAML accepts a single type as well as a sequence of types, mirroring -// UnmarshalJSON. Swagger 2 and OpenAPI 3.0 documents always write `type` as a -// scalar, so decoding such a document into openapi2.T or openapi3.T straight -// from YAML would otherwise fail with "cannot unmarshal !!str into Types". -func (types *Types) UnmarshalYAML(unmarshal func(any) error) error { - var single string - if err := unmarshal(&single); err == nil { - *types = Types{single} - return nil - } - var multiple []string - if err := unmarshal(&multiple); err != nil { - return err - } - *types = Types(multiple) - return nil -} - // BoolSchema represents a JSON Schema keyword that can be either a boolean or a schema object. // Used for additionalProperties, unevaluatedProperties, and unevaluatedItems. type BoolSchema struct { diff --git a/openapi3/schema_test.go b/openapi3/schema_test.go index 8b5761ad5..7e7bd84ae 100644 --- a/openapi3/schema_test.go +++ b/openapi3/schema_test.go @@ -9,8 +9,8 @@ import ( "strings" "testing" - yaml "github.com/oasdiff/yaml3" "github.com/stretchr/testify/require" + "go.yaml.in/yaml/v4" ) type schemaExample struct { @@ -75,7 +75,7 @@ func validateSchemaJSON(t *testing.T, schema *Schema, value any, opts ...SchemaV } func validateSchemaYAML(t *testing.T, schema *Schema, value any, opts ...SchemaValidationOption) error { - data, err := yaml.Marshal(value) + data, err := yaml.Dump(value) require.NoError(t, err) var val any err = yaml.Unmarshal(data, &val) diff --git a/openapi3/testdata/apis_guru_openapi_directory/bunq_com_1_0_openapi_yaml__load b/openapi3/testdata/apis_guru_openapi_directory/bunq_com_1_0_openapi_yaml__load index 1bdb69451..cb8af1ae4 100644 --- a/openapi3/testdata/apis_guru_openapi_directory/bunq_com_1_0_openapi_yaml__load +++ b/openapi3/testdata/apis_guru_openapi_directory/bunq_com_1_0_openapi_yaml__load @@ -1 +1 @@ -failed to unmarshal data: yaml error: error converting YAML to JSON: yaml: line 1142: did not find expected key +failed to unmarshal data: yaml error: yaml: line 1143: did not find expected key diff --git a/openapi3/testdata/apis_guru_openapi_directory/codat_io_assess_1_0_openapi_yaml__load b/openapi3/testdata/apis_guru_openapi_directory/codat_io_assess_1_0_openapi_yaml__load index f971e1637..af09db55b 100644 --- a/openapi3/testdata/apis_guru_openapi_directory/codat_io_assess_1_0_openapi_yaml__load +++ b/openapi3/testdata/apis_guru_openapi_directory/codat_io_assess_1_0_openapi_yaml__load @@ -1 +1 @@ -failed to unmarshal data: yaml error: error unmarshaling JSON: while decoding JSON: json: cannot unmarshal object into Go struct field .components.schemas.ExcelStatus.examples of type []interface {} +failed to unmarshal data: yaml error: yaml: construct errors: line 4692: cannot construct !!map into []interface {} in /components/schemas/ExcelStatus/examples diff --git a/openapi3/testdata/apis_guru_openapi_directory/docusign_net_v2_1_openapi_yaml__load b/openapi3/testdata/apis_guru_openapi_directory/docusign_net_v2_1_openapi_yaml__load deleted file mode 100644 index f690ae309..000000000 --- a/openapi3/testdata/apis_guru_openapi_directory/docusign_net_v2_1_openapi_yaml__load +++ /dev/null @@ -1 +0,0 @@ -failed to unmarshal data: yaml error: error converting YAML to JSON: yaml: control characters are not allowed diff --git a/openapi3/testdata/apis_guru_openapi_directory/sendgrid_com_1_0_0_openapi_yaml__load b/openapi3/testdata/apis_guru_openapi_directory/sendgrid_com_1_0_0_openapi_yaml__load deleted file mode 100644 index f690ae309..000000000 --- a/openapi3/testdata/apis_guru_openapi_directory/sendgrid_com_1_0_0_openapi_yaml__load +++ /dev/null @@ -1 +0,0 @@ -failed to unmarshal data: yaml error: error converting YAML to JSON: yaml: control characters are not allowed diff --git a/openapi3/testdata/apis_guru_openapi_directory/sendgrid_com_1_0_0_openapi_yaml__validate b/openapi3/testdata/apis_guru_openapi_directory/sendgrid_com_1_0_0_openapi_yaml__validate new file mode 100644 index 000000000..2f6ba769b --- /dev/null +++ b/openapi3/testdata/apis_guru_openapi_directory/sendgrid_com_1_0_0_openapi_yaml__validate @@ -0,0 +1,328 @@ +invalid components: schema "full-segment": invalid example: doesn't match schema due to: Error at "/contacts_sample/0/city": string doesn't match the regular expression "^[a-zA-Z\u0080-\u024F\s\/\-\)\(\`\.\"\']+$" +Schema: + { + "description": "City associated with the contact. This is a reserved field.", + "pattern": "^[a-zA-Z\\u0080-\\u024F\\s\\/\\-\\)\\(\\`\\.\\\"\\']+$", + "type": "string" + } + +Value: + "œȎţȸÛ\tč\u000bCŁ" + | Error at "/contacts_sample/0/id": property "id" is missing +Schema: + { + "example": { + "address_line_1": "street address / P.O. box / CompanyName / c/o", + "address_line_2": "apartment, suite, unit, building, floor etc", + "alternate_emails": [ + "abcd@yahoo.com", + "abcd@hotmail.com" + ], + "city": "Redwood City", + "country": "USA", + "custom_fields": { + "custom_field_name1": "custom_field_value1", + "custom_field_name2": "custom_field_value2" + }, + "email": "abcd@gmail.com", + "first_name": "Ab", + "id": "47d23ab0-d895-4359-a0d1-ffc7a6fc7e70", + "last_name": "Cd", + "postal_code": 94063, + "state_province_region": "CA" + }, + "properties": { + "address_line_1": { + "description": "First line of address of the contact. This is a reserved field.", + "type": "string" + }, + "address_line_2": { + "description": "Second line of address of the contact. This is a reserved field.", + "type": "string" + }, + "alternate_emails": { + "description": "Alternate emails of the contact. This is a reserved field.", + "items": { + "format": "email", + "maxLength": 254, + "minLength": 3, + "type": "string" + }, + "type": "array", + "uniqueItems": true + }, + "city": { + "description": "City associated with the contact. This is a reserved field.", + "pattern": "^[a-zA-Z\\u0080-\\u024F\\s\\/\\-\\)\\(\\`\\.\\\"\\']+$", + "type": "string" + }, + "country": { + "description": "Country associated with the address of the contact. This is a reserved field.", + "type": "string" + }, + "custom_fields": { + "description": "The user may choose to create up to 120 custom fields or none at all. This is not a reserved field.", + "properties": { + "": { + "type": "string" + }, + "custom_field_name1": { + "type": "string" + }, + "custom_field_name2": { + "type": "string" + } + }, + "type": "object" + }, + "email": { + "description": "Email of the contact. This is a reserved field.", + "format": "email", + "maxLength": 254, + "minLength": 3, + "type": "string" + }, + "first_name": { + "description": "First name of the contact. This is a reserved field.", + "minLength": 1, + "type": "string" + }, + "id": { + "description": "ID assigned to a contact when added to the system.", + "format": "uuid", + "maxLength": 36, + "pattern": "[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}", + "type": "string" + }, + "last_name": { + "description": "Last name of the contact. This is a reserved field.", + "minLength": 1, + "type": "string" + }, + "list_ids": { + "description": "IDs of all lists the contact is part of", + "items": { + "format": "uuid", + "type": "string" + }, + "type": "array", + "uniqueItems": true + }, + "postal_code": { + "description": "Zipcode associated with the address of the contact. This is a reserved field.", + "type": "integer" + }, + "segment_ids": { + "description": "IDs of all segments the contact is part of", + "items": { + "format": "uuid", + "type": "string" + }, + "type": "array", + "uniqueItems": true + }, + "state_province_region": { + "description": "State associated with the contact. This is a reserved field.", + "type": "string" + } + }, + "required": [ + "id", + "email", + "alternate_emails", + "first_name", + "last_name", + "address_line_1", + "address_line_2", + "city", + "state_province_region", + "postal_code", + "country", + "custom_fields" + ], + "title": "contact_response", + "type": "object" + } + +Value: + { + "address_line_1": "sunt aliqua", + "address_line_2": "sit proident Lorem veniam labore", + "alternate_emails": [ + "yKDUP11FDch@QoU.vwy", + "ZNSN5@czAMqPi.at", + "7wr51kFVVKlcBSH@DWxOueOZepetzBrku.qosk", + "iib-ObtO7Fxz5@vLJPRIFKPOqJGCEqcIDab.ypn" + ], + "city": "œȎţȸÛ\tč\u000bCŁ", + "contact_id": "c1183ada-b784-49ac-9b1f-50e73578a6dc", + "country": "do reprehenderit qui", + "custom_fields": { + "custom_field_name1": "esse", + "custom_field_name2": "in consectetur ut aliqua sint" + }, + "first_name": "est", + "last_name": "eiusmod in laboris velit cupidatat", + "postal_code": 30296612, + "primary_email": "ft88@d.izxx", + "state_province_region": "ut proident" + } + | Error at "/contacts_sample/0/email": property "email" is missing +Schema: + { + "example": { + "address_line_1": "street address / P.O. box / CompanyName / c/o", + "address_line_2": "apartment, suite, unit, building, floor etc", + "alternate_emails": [ + "abcd@yahoo.com", + "abcd@hotmail.com" + ], + "city": "Redwood City", + "country": "USA", + "custom_fields": { + "custom_field_name1": "custom_field_value1", + "custom_field_name2": "custom_field_value2" + }, + "email": "abcd@gmail.com", + "first_name": "Ab", + "id": "47d23ab0-d895-4359-a0d1-ffc7a6fc7e70", + "last_name": "Cd", + "postal_code": 94063, + "state_province_region": "CA" + }, + "properties": { + "address_line_1": { + "description": "First line of address of the contact. This is a reserved field.", + "type": "string" + }, + "address_line_2": { + "description": "Second line of address of the contact. This is a reserved field.", + "type": "string" + }, + "alternate_emails": { + "description": "Alternate emails of the contact. This is a reserved field.", + "items": { + "format": "email", + "maxLength": 254, + "minLength": 3, + "type": "string" + }, + "type": "array", + "uniqueItems": true + }, + "city": { + "description": "City associated with the contact. This is a reserved field.", + "pattern": "^[a-zA-Z\\u0080-\\u024F\\s\\/\\-\\)\\(\\`\\.\\\"\\']+$", + "type": "string" + }, + "country": { + "description": "Country associated with the address of the contact. This is a reserved field.", + "type": "string" + }, + "custom_fields": { + "description": "The user may choose to create up to 120 custom fields or none at all. This is not a reserved field.", + "properties": { + "": { + "type": "string" + }, + "custom_field_name1": { + "type": "string" + }, + "custom_field_name2": { + "type": "string" + } + }, + "type": "object" + }, + "email": { + "description": "Email of the contact. This is a reserved field.", + "format": "email", + "maxLength": 254, + "minLength": 3, + "type": "string" + }, + "first_name": { + "description": "First name of the contact. This is a reserved field.", + "minLength": 1, + "type": "string" + }, + "id": { + "description": "ID assigned to a contact when added to the system.", + "format": "uuid", + "maxLength": 36, + "pattern": "[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}", + "type": "string" + }, + "last_name": { + "description": "Last name of the contact. This is a reserved field.", + "minLength": 1, + "type": "string" + }, + "list_ids": { + "description": "IDs of all lists the contact is part of", + "items": { + "format": "uuid", + "type": "string" + }, + "type": "array", + "uniqueItems": true + }, + "postal_code": { + "description": "Zipcode associated with the address of the contact. This is a reserved field.", + "type": "integer" + }, + "segment_ids": { + "description": "IDs of all segments the contact is part of", + "items": { + "format": "uuid", + "type": "string" + }, + "type": "array", + "uniqueItems": true + }, + "state_province_region": { + "description": "State associated with the contact. This is a reserved field.", + "type": "string" + } + }, + "required": [ + "id", + "email", + "alternate_emails", + "first_name", + "last_name", + "address_line_1", + "address_line_2", + "city", + "state_province_region", + "postal_code", + "country", + "custom_fields" + ], + "title": "contact_response", + "type": "object" + } + +Value: + { + "address_line_1": "sunt aliqua", + "address_line_2": "sit proident Lorem veniam labore", + "alternate_emails": [ + "yKDUP11FDch@QoU.vwy", + "ZNSN5@czAMqPi.at", + "7wr51kFVVKlcBSH@DWxOueOZepetzBrku.qosk", + "iib-ObtO7Fxz5@vLJPRIFKPOqJGCEqcIDab.ypn" + ], + "city": "œȎţȸÛ\tč\u000bCŁ", + "contact_id": "c1183ada-b784-49ac-9b1f-50e73578a6dc", + "country": "do reprehenderit qui", + "custom_fields": { + "custom_field_name1": "esse", + "custom_field_name2": "in consectetur ut aliqua sint" + }, + "first_name": "est", + "last_name": "eiusmod in laboris velit cupidatat", + "postal_code": 30296612, + "primary_email": "ft88@d.izxx", + "state_province_region": "ut proident" + } diff --git a/openapi3/testdata/apis_guru_openapi_directory/statsocial_com_1_0_0_openapi_yaml__load b/openapi3/testdata/apis_guru_openapi_directory/statsocial_com_1_0_0_openapi_yaml__load deleted file mode 100644 index 89cfda0c5..000000000 --- a/openapi3/testdata/apis_guru_openapi_directory/statsocial_com_1_0_0_openapi_yaml__load +++ /dev/null @@ -1 +0,0 @@ -failed to resolve "18_24" in fragment in URI: "#/components/schemas/18_24": map key "18_24" not found diff --git a/openapi3/testdata/fuzz/FuzzInternalizeRefs/next-line-escape-in-key b/openapi3/testdata/fuzz/FuzzInternalizeRefs/next-line-escape-in-key new file mode 100644 index 000000000..379d666d8 --- /dev/null +++ b/openapi3/testdata/fuzz/FuzzInternalizeRefs/next-line-escape-in-key @@ -0,0 +1,3 @@ +go test fuzz v1 +[]byte("{\"\\N\"}") +[]byte("0") diff --git a/openapi3/testdata/fuzz/FuzzLoadFromData/8fffb2caad2dd727 b/openapi3/testdata/fuzz/FuzzLoadFromData/8fffb2caad2dd727 new file mode 100644 index 000000000..fa28f892c --- /dev/null +++ b/openapi3/testdata/fuzz/FuzzLoadFromData/8fffb2caad2dd727 @@ -0,0 +1,2 @@ +go test fuzz v1 +[]byte("openapi: 0\ncomponents:\n schemas:\n 00:\n type: string\n example: !!timestamp 0000-1-10") diff --git a/openapi3/testdata/fuzz/FuzzLoadFromData/alias-cycle b/openapi3/testdata/fuzz/FuzzLoadFromData/alias-cycle new file mode 100644 index 000000000..dba300040 --- /dev/null +++ b/openapi3/testdata/fuzz/FuzzLoadFromData/alias-cycle @@ -0,0 +1,2 @@ +go test fuzz v1 +[]byte("components:\n schemas:\n e: &base\n properties:\n 2: *base\n") diff --git a/openapi3/testdata/fuzz/FuzzLoadFromData/c306b42e54f99d7f b/openapi3/testdata/fuzz/FuzzLoadFromData/c306b42e54f99d7f new file mode 100644 index 000000000..56cda7913 --- /dev/null +++ b/openapi3/testdata/fuzz/FuzzLoadFromData/c306b42e54f99d7f @@ -0,0 +1,2 @@ +go test fuzz v1 +[]byte("components:\n schemas:\n 0:\n $ref:\n") diff --git a/openapi3/testdata/fuzz/FuzzLoadFromData/self-merge b/openapi3/testdata/fuzz/FuzzLoadFromData/self-merge new file mode 100644 index 000000000..3f1e6d8a5 --- /dev/null +++ b/openapi3/testdata/fuzz/FuzzLoadFromData/self-merge @@ -0,0 +1,2 @@ +go test fuzz v1 +[]byte("openapi: 3.0.0\ninfo: {title: t, version: v}\npaths: &a\n <<: *a\n") diff --git a/openapi3/testdata/fuzz/FuzzLoadWithOrigins/5b22ca46d0928a97 b/openapi3/testdata/fuzz/FuzzLoadWithOrigins/5b22ca46d0928a97 new file mode 100644 index 000000000..0df387c7b --- /dev/null +++ b/openapi3/testdata/fuzz/FuzzLoadWithOrigins/5b22ca46d0928a97 @@ -0,0 +1,2 @@ +go test fuzz v1 +[]byte("1:\n0:\n.0: 70") diff --git a/openapi3/testdata/fuzz/FuzzLoadWithOrigins/77207dd31798d4c6 b/openapi3/testdata/fuzz/FuzzLoadWithOrigins/77207dd31798d4c6 new file mode 100644 index 000000000..506256284 --- /dev/null +++ b/openapi3/testdata/fuzz/FuzzLoadWithOrigins/77207dd31798d4c6 @@ -0,0 +1,2 @@ +go test fuzz v1 +[]byte("? 0") diff --git a/openapi3/testdata/fuzz/FuzzLoadWithOrigins/f64677a72b839120 b/openapi3/testdata/fuzz/FuzzLoadWithOrigins/f64677a72b839120 new file mode 100644 index 000000000..4343b96c4 --- /dev/null +++ b/openapi3/testdata/fuzz/FuzzLoadWithOrigins/f64677a72b839120 @@ -0,0 +1,2 @@ +go test fuzz v1 +[]byte("0:\n 00:\n1: !000000\n 0:\n 000:\n 00001: \n 000000000000:\n 0000:\n 0000000000000000: A\n 2:\n 0:\n 0:\n000002:\n 00:\n7:\n8: \n 0:\n 0:\n000000000009:\n0000000000A:\n 0000000000:\n9:\n 12") diff --git a/openapi3/testdata/fuzz/FuzzYAMLMatchesJSON/bddb72bfc04e1cae b/openapi3/testdata/fuzz/FuzzYAMLMatchesJSON/bddb72bfc04e1cae new file mode 100644 index 000000000..f932a6808 --- /dev/null +++ b/openapi3/testdata/fuzz/FuzzYAMLMatchesJSON/bddb72bfc04e1cae @@ -0,0 +1,2 @@ +go test fuzz v1 +[]byte("paths:\n 0:\n get:\n responses:\n 0:") diff --git a/openapi3/yaml_fuzz_test.go b/openapi3/yaml_fuzz_test.go index 598c80e21..ed5e2b8de 100644 --- a/openapi3/yaml_fuzz_test.go +++ b/openapi3/yaml_fuzz_test.go @@ -5,7 +5,7 @@ import ( "testing" "github.com/stretchr/testify/require" - yaml "go.yaml.in/yaml/v3" + "go.yaml.in/yaml/v4" "github.com/getkin/kin-openapi/internal/fuzzing" ) @@ -91,7 +91,7 @@ components: format: date-time example: 2020-06-11T16:32:50-03:00 x-ts: !!timestamp 2001-01-01 - x-keys: {18_24: a, 0x2A: b, 1.5: c, true: d} + x-keys: {18_24: a, 0x2A: b, 1.5: c, true: d, .0: e, 0: f} I: type: integer enum: [0x2A, 4_2, 052, 42] @@ -212,7 +212,7 @@ func FuzzYAMLMatchesJSON(f *testing.F) { if fuzzing.LosesInYAML(generic) { return } - y, err := yaml.Marshal(generic) + y, err := yaml.Dump(generic) require.NoError(t, err) var back T diff --git a/openapi3filter/req_resp_decoder.go b/openapi3filter/req_resp_decoder.go index 8303ea0ec..d59fdb0ca 100644 --- a/openapi3filter/req_resp_decoder.go +++ b/openapi3filter/req_resp_decoder.go @@ -20,7 +20,7 @@ import ( "strings" "sync" - yaml "github.com/oasdiff/yaml3" + "go.yaml.in/yaml/v4" "github.com/getkin/kin-openapi/openapi3" ) From 9813bd920141419c7095f80ed2a64805103d6733 Mon Sep 17 00:00:00 2001 From: Reuven Harrison Date: Sat, 7 Nov 2026 11:41:27 +0200 Subject: [PATCH 77/78] openapi2: decode a swagger document without the yaml fork openapi2 reads a document by converting YAML to JSON and decoding that, since its types implement UnmarshalJSON and not UnmarshalYAML. That is what internal/yamlconv does, on the stock parser, so the last use of the fork goes and both fork modules go with it. The conversion retags what the fork handled behind a DecodeOpts: a date-shaped scalar, since a JSON value has no timestamp, and a mapping key, since a member is named by the text that spells the key. openapi2.UnmarshalFromData exports the decode. The v3 side has Loader for this and openapi2 had no entry point of its own. The goldens move because a decode error is now the json package's own, without the wrapper the fork put in front of it. Co-Authored-By: Claude Opus 5 --- .github/docs/openapi2.txt | 7 +++++++ cmd/validate/main.go | 6 +++--- go.mod | 3 --- go.sum | 6 ------ openapi2/fuzz_test.go | 9 ++++----- openapi2/marsh.go | 13 ++++++++++--- openapi2/marsh_test.go | 2 +- openapi2/openapi2_test.go | 7 +++---- .../powerdns_local_0_0_13_swagger_yaml__load | 2 +- openapi2/v2_apis_guru_openapi_directory_test.go | 4 ++-- openapi2conv/fuzz_test.go | 8 ++++++-- openapi2conv/issue1062_test.go | 4 ++-- openapi2conv/issue1069_test.go | 4 ++-- openapi2conv/issue187_test.go | 8 ++++---- openapi2conv/issue558_test.go | 4 ++-- 15 files changed, 47 insertions(+), 40 deletions(-) diff --git a/.github/docs/openapi2.txt b/.github/docs/openapi2.txt index 8b5d379b2..beb32cc9b 100644 --- a/.github/docs/openapi2.txt +++ b/.github/docs/openapi2.txt @@ -7,6 +7,13 @@ backwards-compatible with version 2, version 3 elements have been used. See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md +FUNCTIONS + +func UnmarshalFromData(data []byte, doc *T) error + UnmarshalFromData loads a document from swagger 2.0 bytes in either JSON or + YAML. The v3 side has Loader for this; here the whole job is the decode. + + TYPES type Header struct { diff --git a/cmd/validate/main.go b/cmd/validate/main.go index b742a9611..ff9a5080a 100644 --- a/cmd/validate/main.go +++ b/cmd/validate/main.go @@ -6,7 +6,7 @@ import ( "os" "strings" - "github.com/oasdiff/yaml" + "go.yaml.in/yaml/v4" "github.com/getkin/kin-openapi/openapi2" "github.com/getkin/kin-openapi/openapi3" @@ -53,7 +53,7 @@ func main() { OpenAPI string `json:"openapi" yaml:"openapi"` Swagger string `json:"swagger" yaml:"swagger"` } - if _, err := yaml.Unmarshal(data, &vd, yaml.DecodeOpts{DisableTimestamps: true}); err != nil { + if err := yaml.Unmarshal(data, &vd); err != nil { log.Fatal(err) } @@ -109,7 +109,7 @@ func main() { } var doc openapi2.T - if _, err := yaml.Unmarshal(data, &doc, yaml.DecodeOpts{DisableTimestamps: true}); err != nil { + if err := openapi2.UnmarshalFromData(data, &doc); err != nil { log.Fatalln("Loading error:", err) } diff --git a/go.mod b/go.mod index 2e503f17e..33f0d2f53 100644 --- a/go.mod +++ b/go.mod @@ -5,10 +5,8 @@ go 1.25 require ( github.com/go-openapi/jsonpointer v0.22.5 github.com/gorilla/mux v1.8.0 - github.com/oasdiff/yaml v0.1.3 github.com/santhosh-tekuri/jsonschema/v6 v6.0.3 github.com/stretchr/testify v1.9.0 - go.yaml.in/yaml/v3 v3.0.5 go.yaml.in/yaml/v4 v4.0.0 ) @@ -16,7 +14,6 @@ require ( github.com/davecgh/go-spew v1.1.1 // indirect github.com/go-openapi/swag/jsonname v0.25.5 // indirect github.com/kr/text v0.2.0 // indirect - github.com/oasdiff/yaml3 v0.0.16 // indirect github.com/pmezard/go-difflib v1.0.0 // indirect golang.org/x/text v0.14.0 // indirect gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c // indirect diff --git a/go.sum b/go.sum index 7fafef818..f4e53241f 100644 --- a/go.sum +++ b/go.sum @@ -17,18 +17,12 @@ github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ= github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI= github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY= github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE= -github.com/oasdiff/yaml v0.1.3 h1:TdwO8e1G1F+bN++LzHj6IWExcuqMjQ1xK8KRYWTffWE= -github.com/oasdiff/yaml v0.1.3/go.mod h1:vxzaFi+b+l+FWC/2NZMm+yD4DzyzwPCwaeLj1x1XfMg= -github.com/oasdiff/yaml3 v0.0.16 h1:NlDF/1oIOhmOvrEb9eH6Sbuubp3gZNS4A+MKST5/p0Q= -github.com/oasdiff/yaml3 v0.0.16/go.mod h1:csto2xfDjYccdUn/yw/bPjj/cYTdp6HtFA0J4TWG+gg= github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM= github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4= github.com/santhosh-tekuri/jsonschema/v6 v6.0.3 h1:1EYB5IzjZawrrnELUi78f9fPu57HuXjmddZPjrls/28= github.com/santhosh-tekuri/jsonschema/v6 v6.0.3/go.mod h1:JXeL+ps8p7/KNMjDQk3TCwPpBy0wYklyWTfbkIzdIFU= github.com/stretchr/testify v1.9.0 h1:HtqpIVDClZ4nwg75+f6Lvsy/wHu+3BoSGCbBAcpTsTg= github.com/stretchr/testify v1.9.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY= -go.yaml.in/yaml/v3 v3.0.5 h1:N6y/pJk8buWs9NY5ERU2HSMfm+IuD/OtfdAnq6kESPw= -go.yaml.in/yaml/v3 v3.0.5/go.mod h1:HVTZu1O7/Vkt2N+BFy8Zza+lnLsABggaTM2ZpNIGuKg= go.yaml.in/yaml/v4 v4.0.0 h1:/LG1pNO84Z4l603j/xMn69CcS5OYhMQ/f7l2LoQUGuw= go.yaml.in/yaml/v4 v4.0.0/go.mod h1:aZqd9kCMsGL7AuUv/m/PvWLdg5sjJsZ4oHDEnfPPfY0= golang.org/x/text v0.14.0 h1:ScX5w1eTa3QqT8oi6+ziP7dTV1S2+ALU0bI+0zXKWiQ= diff --git a/openapi2/fuzz_test.go b/openapi2/fuzz_test.go index d87c5674d..386fa709e 100644 --- a/openapi2/fuzz_test.go +++ b/openapi2/fuzz_test.go @@ -5,7 +5,7 @@ import ( "testing" "github.com/stretchr/testify/require" - yaml "go.yaml.in/yaml/v3" + "go.yaml.in/yaml/v4" "github.com/getkin/kin-openapi/internal/fuzzing" ) @@ -67,10 +67,9 @@ definitions: if fuzzing.LosesInYAML(generic) { return } - // Emitted from the generic form: going through JSON and back, as - // oasdiff/yaml's Marshal does, refuses keys longer than YAML allows - // implicit keys to be, which the emitter writes as explicit "? " keys. - y, err := yaml.Marshal(generic) + // Emitted from the generic form, the bytes the JSON assertions above + // ran on, so a difference here is the YAML round trip and nothing else. + y, err := yaml.Dump(generic) require.NoError(t, err) var fromYAML T require.NoError(t, unmarshal(y, &fromYAML), "yaml:\n%s", y) diff --git a/openapi2/marsh.go b/openapi2/marsh.go index a3411e6a3..927560e15 100644 --- a/openapi2/marsh.go +++ b/openapi2/marsh.go @@ -5,7 +5,7 @@ import ( "fmt" "strings" - "github.com/oasdiff/yaml" + "github.com/getkin/kin-openapi/internal/yamlconv" ) func unmarshalError(jsonUnmarshalErr error) error { @@ -27,8 +27,9 @@ func unmarshal(data []byte, v any) error { } } - // UnmarshalStrict(data, v) TODO: investigate how ymlv3 handles duplicate map keys - if _, yamlErr = yaml.Unmarshal(data, v, yaml.DecodeOpts{DisableTimestamps: true}); yamlErr == nil { + // YAML reaches these types through JSON, since they implement + // UnmarshalJSON and not UnmarshalYAML. + if yamlErr = yamlconv.Unmarshal(data, v); yamlErr == nil { return nil } @@ -52,3 +53,9 @@ func unmarshalErrors(jsonErr, yamlErr error) error { } return fmt.Errorf("failed to unmarshal data: json error: %w, yaml error: %w", jsonErr, yamlErr) } + +// UnmarshalFromData loads a document from swagger 2.0 bytes in either JSON or +// YAML. The v3 side has Loader for this; here the whole job is the decode. +func UnmarshalFromData(data []byte, doc *T) error { + return unmarshal(data, doc) +} diff --git a/openapi2/marsh_test.go b/openapi2/marsh_test.go index 6f39fc135..d61b9fde0 100644 --- a/openapi2/marsh_test.go +++ b/openapi2/marsh_test.go @@ -35,7 +35,7 @@ paths: var doc T err := unmarshal(v2, &doc) if UsingJSONv2 { - require.ErrorContains(t, err, `json: cannot unmarshal object into Go struct field .paths.~1ping.post.parameters of type openapi2.Parameters`) + require.ErrorContains(t, err, `json: cannot unmarshal object into Go struct field T.paths.~1ping.post.parameters of type openapi2.Parameters`) } else { require.ErrorContains(t, err, `json: cannot unmarshal object into field Operation.parameters of type openapi2.Parameters`) } diff --git a/openapi2/openapi2_test.go b/openapi2/openapi2_test.go index c385215d1..b9cefb638 100644 --- a/openapi2/openapi2_test.go +++ b/openapi2/openapi2_test.go @@ -6,8 +6,7 @@ import ( "os" "reflect" - "github.com/oasdiff/yaml" - + "github.com/getkin/kin-openapi/internal/yamlconv" "github.com/getkin/kin-openapi/openapi2" ) @@ -37,12 +36,12 @@ func Example() { fmt.Println("objects doc & docAgainFromJSON should be the same") } - outputYAML, err := yaml.Marshal(doc) + outputYAML, err := yamlconv.Marshal(doc) if err != nil { panic(err) } var docAgainFromYAML openapi2.T - if _, err = yaml.Unmarshal(outputYAML, &docAgainFromYAML, yaml.DecodeOpts{DisableTimestamps: true}); err != nil { + if err = yamlconv.Unmarshal(outputYAML, &docAgainFromYAML); err != nil { panic(err) } if !reflect.DeepEqual(doc, docAgainFromYAML) { diff --git a/openapi2/testdata/apis_guru_openapi_directory/powerdns_local_0_0_13_swagger_yaml__load b/openapi2/testdata/apis_guru_openapi_directory/powerdns_local_0_0_13_swagger_yaml__load index 3fd4ef7b1..ad27007f9 100644 --- a/openapi2/testdata/apis_guru_openapi_directory/powerdns_local_0_0_13_swagger_yaml__load +++ b/openapi2/testdata/apis_guru_openapi_directory/powerdns_local_0_0_13_swagger_yaml__load @@ -1 +1 @@ -error unmarshaling JSON: while decoding JSON: json: cannot unmarshal array into Go struct field .paths.~1servers~1{server_id}~1statistics.get.responses.200.schema.items of type openapi2.Schema: json: cannot unmarshal JSON array into openapi2.Schema +json: cannot unmarshal array into Go struct field T.paths.~1servers~1{server_id}~1statistics.get.responses.200.schema.items of type openapi2.Schema: json: cannot unmarshal JSON array into openapi2.Schema diff --git a/openapi2/v2_apis_guru_openapi_directory_test.go b/openapi2/v2_apis_guru_openapi_directory_test.go index 03c46e02d..22f77083f 100644 --- a/openapi2/v2_apis_guru_openapi_directory_test.go +++ b/openapi2/v2_apis_guru_openapi_directory_test.go @@ -13,9 +13,9 @@ import ( "sync" "testing" - "github.com/oasdiff/yaml" "github.com/stretchr/testify/require" + "github.com/getkin/kin-openapi/internal/yamlconv" "github.com/getkin/kin-openapi/openapi2" ) @@ -195,7 +195,7 @@ func TestV2ApisGuruOpenapiDirectory(t *testing.T) { require.NoError(t, err) var doc openapi2.T - _, err = yaml.Unmarshal(data, &doc, yaml.DecodeOpts{DisableTimestamps: true}) + err = yamlconv.Unmarshal(data, &doc) golden(t, err, shortName, "load") }) } diff --git a/openapi2conv/fuzz_test.go b/openapi2conv/fuzz_test.go index 3d214d312..1a7b21aab 100644 --- a/openapi2conv/fuzz_test.go +++ b/openapi2conv/fuzz_test.go @@ -6,10 +6,10 @@ import ( "path/filepath" "testing" - "github.com/oasdiff/yaml" "github.com/stretchr/testify/require" "github.com/getkin/kin-openapi/internal/fuzzing" + "github.com/getkin/kin-openapi/internal/yamlconv" "github.com/getkin/kin-openapi/openapi2" "github.com/getkin/kin-openapi/openapi2conv" "github.com/getkin/kin-openapi/openapi3" @@ -33,7 +33,11 @@ func FuzzToV3(f *testing.F) { // The corpus is YAML, which this target does not decode, so it goes in as // JSON. It is read from openapi3, the one copy the fuzz workflow fetches. for _, seed := range fuzzing.APIsGuru(f, "../openapi3/testdata", "swagger:") { - if data, err := yaml.YAMLToJSON(seed); err == nil && len(data) <= maxFuzzInput { + var doc any + if yamlconv.Unmarshal(seed, &doc) != nil { + continue + } + if data, err := json.Marshal(doc); err == nil && len(data) <= maxFuzzInput { f.Add(data) } } diff --git a/openapi2conv/issue1062_test.go b/openapi2conv/issue1062_test.go index dddf39b11..71769a1a9 100644 --- a/openapi2conv/issue1062_test.go +++ b/openapi2conv/issue1062_test.go @@ -3,9 +3,9 @@ package openapi2conv_test import ( "testing" - "github.com/oasdiff/yaml" "github.com/stretchr/testify/require" + "github.com/getkin/kin-openapi/internal/yamlconv" "github.com/getkin/kin-openapi/openapi2conv" "github.com/getkin/kin-openapi/openapi3" ) @@ -61,7 +61,7 @@ components: ` var doc3 openapi3.T - _, err := yaml.Unmarshal([]byte(v3Spec), &doc3, yaml.DecodeOpts{DisableTimestamps: true}) + err := yamlconv.Unmarshal([]byte(v3Spec), &doc3) require.NoError(t, err, "unmarshal v3 spec") // Pre-fix: this call panicked with diff --git a/openapi2conv/issue1069_test.go b/openapi2conv/issue1069_test.go index 1f13dab9b..c07bff95f 100644 --- a/openapi2conv/issue1069_test.go +++ b/openapi2conv/issue1069_test.go @@ -3,10 +3,10 @@ package openapi2conv_test import ( "testing" - "github.com/oasdiff/yaml" "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require" + "github.com/getkin/kin-openapi/internal/yamlconv" "github.com/getkin/kin-openapi/openapi2" "github.com/getkin/kin-openapi/openapi2conv" "github.com/getkin/kin-openapi/openapi3" @@ -203,7 +203,7 @@ paths: for _, tt := range tests { t.Run(tt.name, func(t *testing.T) { var doc3 openapi3.T - _, err := yaml.Unmarshal([]byte(tt.v3Spec), &doc3, yaml.DecodeOpts{DisableTimestamps: true}) + err := yamlconv.Unmarshal([]byte(tt.v3Spec), &doc3) require.NoError(t, err) v2, err := openapi2conv.FromV3(&doc3) diff --git a/openapi2conv/issue187_test.go b/openapi2conv/issue187_test.go index ee2d6658f..399c9d05d 100644 --- a/openapi2conv/issue187_test.go +++ b/openapi2conv/issue187_test.go @@ -4,9 +4,9 @@ import ( "encoding/json" "testing" - "github.com/oasdiff/yaml" "github.com/stretchr/testify/require" + "github.com/getkin/kin-openapi/internal/yamlconv" "github.com/getkin/kin-openapi/openapi2" "github.com/getkin/kin-openapi/openapi2conv" "github.com/getkin/kin-openapi/openapi3" @@ -23,7 +23,7 @@ func v2v3JSON(spec2 []byte) (doc3 *openapi3.T, err error) { func v2v3YAML(spec2 []byte) (doc3 *openapi3.T, err error) { var doc2 openapi2.T - if _, err = yaml.Unmarshal(spec2, &doc2, yaml.DecodeOpts{DisableTimestamps: true}); err != nil { + if err = yamlconv.Unmarshal(spec2, &doc2); err != nil { return } doc3, err = openapi2conv.ToV3(&doc2) @@ -141,7 +141,7 @@ definitions: doc3, err := v2v3YAML([]byte(spec)) require.NoError(t, err) - spec3, err := yaml.Marshal(doc3) + spec3, err := yamlconv.Marshal(doc3) require.NoError(t, err) const expected = `components: schemas: @@ -191,7 +191,7 @@ securityDefinitions: doc3, err := v2v3YAML([]byte(spec)) require.NoError(t, err) require.NotNil(t, doc3.Components.SecuritySchemes["OAuth2Application"].Value.Flows.ClientCredentials) - _, err = yaml.Marshal(doc3) + _, err = yamlconv.Marshal(doc3) require.NoError(t, err) doc2, err := openapi2conv.FromV3(doc3) diff --git a/openapi2conv/issue558_test.go b/openapi2conv/issue558_test.go index c1b689ba3..9de9458d6 100644 --- a/openapi2conv/issue558_test.go +++ b/openapi2conv/issue558_test.go @@ -3,9 +3,9 @@ package openapi2conv_test import ( "testing" - "github.com/oasdiff/yaml" "github.com/stretchr/testify/require" + "github.com/getkin/kin-openapi/internal/yamlconv" "github.com/getkin/kin-openapi/openapi2conv" ) @@ -32,7 +32,7 @@ paths: doc3, err := v2v3YAML([]byte(spec)) require.NoError(t, err) require.NotEmpty(t, doc3.Paths.Value("/test").Get.Deprecated) - _, err = yaml.Marshal(doc3) + _, err = yamlconv.Marshal(doc3) require.NoError(t, err) doc2, err := openapi2conv.FromV3(doc3) From 8e02f32df924dad2f013c86c7327cc8f6554f060 Mon Sep 17 00:00:00 2001 From: Reuven Harrison Date: Sat, 7 Nov 2026 11:41:34 +0200 Subject: [PATCH 78/78] ci: run the origin concurrency test under -race TestConcurrentDecodeDoesNotLeakOrigins loads the same document from several goroutines and asserts each one gets its own origins. The state it covers is per-decode, so a leak between decodes shows up as a data race before it shows up as a wrong position. Co-Authored-By: Claude Opus 5 --- .github/workflows/go.yml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.github/workflows/go.yml b/.github/workflows/go.yml index f35394a73..e0293d2ee 100644 --- a/.github/workflows/go.yml +++ b/.github/workflows/go.yml @@ -91,6 +91,9 @@ jobs: - run: go test -v -count=10 -run TestIssue741 -race ./... env: CGO_ENABLED: '1' + - run: go test -v -count=10 -run TestConcurrentDecodeDoesNotLeakOrigins -race ./... + env: + CGO_ENABLED: '1' - run: git --no-pager diff --exit-code - if: runner.os == 'Linux'