Skip to content

Conversation

@tx3stn
Copy link

@tx3stn tx3stn commented Nov 18, 2025

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.

@tx3stn tx3stn changed the title handle errors when a reference has sibling properties add a StrictValidation to BundleCompositionConfig to support more user friendly errors on invalid specs Nov 18, 2025
@tx3stn tx3stn changed the title add a StrictValidation to BundleCompositionConfig to support more user friendly errors on invalid specs add StrictValidation to BundleCompositionConfig to support more user friendly errors on invalid specs Nov 18, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant