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 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.

[tx3stn]

Updated to check the version and added a unit test to make sure it doesn't error for 3.1 specs.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.59%. Comparing base (3785db7) to head (a010558).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #482   +/-   ##
=======================================
  Coverage   99.59%   99.59%           
=======================================
  Files         189      189           
  Lines       22462    22473   +11     
=======================================
+ Hits        22371    22382   +11     
  Misses         57       57           
  Partials       34       34           

Flag	Coverage Δ
unittests	99.59% <100.00%> (+<0.01%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[daveshanley]

LGTM, thanks for updating! really glad to see you're still on the platform. Great contributors and hackers like you are too rare!