add StrictValidation to BundleCompositionConfig to support more user friendly errors on invalid specs

[tx3stn]

Add a StrictValidation field to BundleCompositionConfig to handle reporting errors when trying to compose the bundle.

Scenario

I've run into an issue using the bundler, where an invalid spec was causing a confusing error which states a file did not exist, if a component was trying to refer to another component whilst including an invalid sibling ref node, i.e.:

spec:

openapi: 3.0.0 info: title: Historical Shipping Option Repro version: 1.0.0 paths: /shipments: post: requestBody: required: true content: application/json: schema: $ref: ./components/HistoricalShippingOption.json responses: '200': description: ok

./components/CountryCode.json

{ "type": "string", "description": "Country code in ISO 3166 ALPHA-2 format", "enum": [ "US", "CA", "GB", "DE", "FR" ] }

./components/HistoricalShippingOption.json

{ "title": "HistoricalShippingOption", "type": "object", "properties": { "country_code": { "$ref": "CountryCode.json", "description": "this should not be here" } }, "required": [ "country_code" ] }

Warning

This is invalid, the country_code property should not have a description with the $ref.

Deleting this description key fixes everything, but teams using this have been confused by how this error is reported.

The bundle gets created incorrectly, and linting then says rolodex count not find file for the external ref CountryCode.json, which is confusing as it's not that the file can't be found, it's the input is invalid.

Example code for bundling:

docConfig := &datamodel.DocumentConfiguration{ AllowFileReferences: true, AllowRemoteReferences: true, BasePath: c.basePath, BundleInlineRefs: false, ExtractRefsSequentially: true, Logger: slogLogger, MergeReferencedProperties: false, RecomposeRefs: true, SpecFilePath: c.inputFile,	} compositionConfig := &bundler.BundleCompositionConfig{ Delimiter: "__",	} bundled, err := bundler.BundleBytesComposed( specBytes, docConfig, compositionConfig,	)

When I build with these changes and enable the StrictValidation my specific error gets flagged, which avoids the confusion of the file not found errors that are currently flagged.

[daveshanley]

This is allowed in OpenAPI 3.1+

What happens then?

[daveshanley]

This is a nice upgrade, but it does not look version sensitive, 3.1+ allows $ref siblings.

[daveshanley]

@tx3stn you still there mate?

[daveshanley]

@tx3stn you still there mate?

I get so sad when really great contributors from the community walk into my life, and then suddenly, they're gone again.

[tx3stn]

Sorry! Been swamped lately and haven't had a chance to look at GitHub for a while.

Yep, so this issue we were running into that prompted me to look into this in the first place was a version 3.0 and 3.1 mismatch that came from teams generating specs with fastapi which always generates a 3.1 spec, but allows you to say it's a 3.0 spec, which the oas3-schema rule in vacuum then threw errors about which led me here.

So I can make the strict validation rule version aware, and then validation rules can be checked based on spec version, or we can can this if it's too limited to a specifc error scenario?

[daveshanley]

hey! glad to see you're still active, so many good souls come and go on this platform.

I would make it version aware, it's a good upgrade, it just needs to be aware of the version it's operating against.