openapi3: support format conditional on `doc.openapi` version #744

cboitel · 2023-01-17T21:30:35Z

Implements string format improvements in issue #582 with openapi minor version support.

You can now define a string formats available for some minor version
by default, string formats apply to all minor versions (>= 3.0)
filters do enforce string formats according to document's OpenAPI version

openapi3filter/validate_request.go

openapi3filter/validate_response.go

cboitel · 2023-01-18T21:01:15Z

@fenollp finally made up with implementing a string format support based on OpenAPI minor version

openapi3/version_test.go

fenollp

Hey! Thanks for this. This is going to the right direction. I mostly have comments on the API design.

fenollp · 2023-05-18T09:55:58Z

openapi3/schema_formats.go

+func (format *Format) add(minMinorVersion uint64, vFormat *versionedFormat, override bool) {
+	if format != nil {
+		if format.versionedFormats == nil {
+			format.versionedFormats = make([]*versionedFormat, minMinorVersion+1)


This is allocating a lot of unused space. I'd rather you use a dynamically-sized map. Use an additional slice for ordered map keys.

Did that so it is very fast to determine format to use for a specific minor version when validating.

Since number of minor versions won't be too big, I don't think this can be an memory issue.

fenollp · 2023-05-18T09:58:41Z

openapi3/schema_formats.go

+	return nil
+}
+
+func (format Format) DefinedForMinorVersion(minorVersion uint64) bool {


This seems unused.

Will have to determine if we keep it so one can determine if a definition already exists for a specific minor version. Since format does not expose its content, this is the only way for one to know about it.

If we keep, I will need to add tests

fenollp · 2023-05-18T10:13:12Z

openapi3/schema_formats.go

+
+// DefineStringFormatStartingWithOpenAPIMinorVersion defines a new regexp pattern for a given format to apply for a minor version of OpenAPI 3
+// override allows to enforce regex usage to all subsequent minor versions of OpenAPI
+func DefineStringFormatStartingWithOpenAPIMinorVersion(name string, fromMinorVersion uint64, pattern string, override bool) {


Why uint64? uint8 or even uint16 is large enough.

I like the idea but I'd rather have a simpler API:

a shorter method such as the existing DefineStringFormat (extend with variadic args)

make override=true the only behavior. API users will simply make multiple calls to cut specific ranges

turn fromMinorVersion into a float (f32 if for all Y, 3.Y can be expressed and I believe it's a yes) so users can see DefineStringFormat(name, pattern, 3.1). The call should panic on non-nil non-floats and compare minors with a 0.4 epsilon.

(yes, I'm asking to extend the existing 2 methods with a variadic float)

uint64 comes from the string parsing function used when parsing OpenAPI document
=> Go string parsing returns a uint64
=> Casting to uint8 would require minor version

Since most processors are 64 bits, using an uint8/uint64 does save memory nor it brings performance gain.

Gone with the variadic options. have a look

fenollp · 2023-05-18T10:15:01Z

openapi3/schema_formats_test.go

+func TestStringFormatsStartingWithOpenAPIMinorVersion(t *testing.T) {
+	DefineStringFormatStartingWithOpenAPIMinorVersion("test", 0, "test0", false)
+	for i := uint64(0); i < 10; i++ {
+		if assert.Contains(t, SchemaStringFormats, "test") &&


Please prefer the require package over assert. This makes for fewer nesting.

fenollp · 2023-05-18T10:16:48Z

openapi3/schema_validation_settings.go

@@ -18,6 +18,8 @@ type schemaValidationSettings struct {
 	defaultsSet         func()

 	customizeMessageError func(err *SchemaError) string
+
+	openapiMinorVersion uint64 // defaults to 0 (3.0.z)


uint8 is enough

see discussion earlier

openapi3/version.go

fenollp · 2023-05-18T10:26:31Z

openapi3/version.go

+}
+
+// MinorVersion returns minor version from string assuming 0 is the default
+func (oai Version) Minor() uint64 {


uint64 seems too big. Also why not return the two possible errors? (or edit func doc)

I see you introduced this for use by the schema validation settings. Let's return a float then :)

fenollp · 2023-05-18T10:32:48Z

.github/docs/openapi3.txt

@@ -3,18 +3,21 @@ const TypeArray = "array" ...
 const FormatOfStringForUUIDOfRFC4122 = `^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$` ...
 const SerializationSimple = "simple" ...
 var SchemaErrorDetailsDisabled = false ...
+var ErrInvalidVersion ...


What's your rationale to export this?

So one can check at loading time he got an invalid error version, not some other kind of error.

go.mod

openapi3/schema_test.go

fenollp · 2023-06-18T11:59:55Z

@cboitel Hey there. Do you need help moving this forward?

cboitel · 2023-06-18T12:21:31Z

Nope. Just missed it while I was on vacations. Will get back to it next week.

cboitel · 2023-07-30T16:35:31Z

@fenollp

I had a hard time to rebase.

Finally found it was related to some new/existing tests defining string formats for uuid but not restoring string formats to original value.

I created a new Save/Restore/RestoreDefault functions for string formats so one can easily do that like we need in our tests.

I will now address your earlier comments in the upcoming days.

…ilable

cboitel changed the title ~~582 enhance format support 2~~ #582 enhance format support Jan 17, 2023

github-advanced-security bot found potential problems Jan 17, 2023

View reviewed changes

openapi3filter/validate_request.go Fixed Show resolved Hide resolved

openapi3filter/validate_request.go Fixed Show resolved Hide resolved

openapi3filter/validate_response.go Fixed Show resolved Hide resolved

openapi3filter/validate_response.go Fixed Show resolved Hide resolved

cboitel force-pushed the 582-enhance-format-support-2 branch 2 times, most recently from 3301b24 to ab2416b Compare January 17, 2023 22:18

fenollp requested changes Jan 20, 2023

View reviewed changes

openapi3/version_test.go Show resolved Hide resolved

fenollp requested changes May 18, 2023

View reviewed changes

fenollp changed the title ~~#582 enhance format support~~ openapi3: support format conditional on doc.openapi version May 18, 2023

fenollp mentioned this pull request Jun 22, 2023

Which version of OpenAPI spec does Validate(context.Context, ...ValidationOption) method validate against? #812

Closed

cboitel force-pushed the 582-enhance-format-support-2 branch 2 times, most recently from 6855e99 to bb0e0e5 Compare July 30, 2023 16:23

cboitel force-pushed the 582-enhance-format-support-2 branch 2 times, most recently from eaa7245 to 0e202c6 Compare July 31, 2023 11:50

cboitel added 5 commits September 17, 2023 14:47

feat getkin#582: implement openapi version validation

96f4c5e

feat getkin#582: add minor version support to string formats

9c0054f

fix getkin#582: enhance date string formats

21c4aa6

fix getkin#582: define OpenAPI 3.1 string formats

bcbbb97

feat getkin#582: use OpenAPI minor version during validation when ava…

355d474

…ilable

cboitel force-pushed the 582-enhance-format-support-2 branch from 0e202c6 to 355d474 Compare September 17, 2023 12:48

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

openapi3: support format conditional on `doc.openapi` version #744

openapi3: support format conditional on `doc.openapi` version #744

cboitel commented Jan 17, 2023

cboitel commented Jan 18, 2023

fenollp left a comment

fenollp May 18, 2023

cboitel Jul 30, 2023 •

edited

fenollp May 18, 2023

cboitel Jul 30, 2023

fenollp May 18, 2023

fenollp May 18, 2023

cboitel Jul 30, 2023

cboitel Jul 31, 2023

fenollp May 18, 2023

fenollp May 18, 2023

cboitel Jul 30, 2023

fenollp May 18, 2023

fenollp May 18, 2023

fenollp May 18, 2023

cboitel Jul 30, 2023

fenollp commented Jun 18, 2023

cboitel commented Jun 18, 2023

cboitel commented Jul 30, 2023

openapi3: support format conditional on doc.openapi version #744

Are you sure you want to change the base?

openapi3: support format conditional on doc.openapi version #744

Conversation

cboitel commented Jan 17, 2023

cboitel commented Jan 18, 2023

fenollp left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cboitel Jul 30, 2023 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

fenollp commented Jun 18, 2023

cboitel commented Jun 18, 2023

cboitel commented Jul 30, 2023

openapi3: support format conditional on `doc.openapi` version #744

openapi3: support format conditional on `doc.openapi` version #744

cboitel Jul 30, 2023 •

edited