feat: inject a custom document loader into schema/spec validation (#272)

Building a schema validator expands the schema's $ref, and validating a
specification resolves and expands $ref (schemas, parameters, responses, and the
whole-spec expansion). All of these resolved documents through the spec package's
global loader, with no way for a caller to supply their own.

Add WithPathLoader, an option-aware loader on SchemaValidatorOptions, consumed by
every path that loads documents during validation:

  - newSchemaValidator uses spec.ExpandSchemaWithOptions (instead of the
    default-settings ExpandSchema).
  - resolveParam / expandResponseRef use spec.ExpandParameterWithOptions and
    spec.ExpandResponseWithOptions.
  - SpecValidator.resolveRef passes the loader through spec.ResolveRefWithBase.
  - validateReferencesValid passes it to loads.Document.Expanded (no-op when unset:
    loads falls back to the document's own loader).
  - NewSpecValidator and the package-level Spec now accept ...Option, applied to
    the internal schema options after the built-in defaults, so a caller can
    inject the loader into spec validation. Backward compatible: existing
    two-argument calls are unaffected.

The injected loader may carry any go-openapi/swag/loading options — a custom HTTP
client or timeout, authentication or custom headers, an embedded or rooted file
system, and so on. One important use is confining loading of untrusted input
(loading.WithRoot to confine local reads, loading.WithHTTPClient to restrict
remote fetches, or a restricted loader from go-openapi/loads), which closes the
arbitrary-file-read / SSRF surface that the unsandboxed default otherwise exposes.
Left unset, behavior is unchanged.

Bumps spec to v0.22.9 (for the option-aware expanders), analysis to v0.25.5,
loads to v0.25.0 and swag to v0.27.3.

Signed-off-by: Frederic BIDON <fredbi@yahoo.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: fredbi

go.mod

@@ -1,27 +1,27 @@
 module github.com/go-openapi/validate
 
 require (
-	github.com/go-openapi/analysis v0.25.3
+	github.com/go-openapi/analysis v0.25.5
 	github.com/go-openapi/errors v0.22.8
 	github.com/go-openapi/jsonpointer v1.0.0
-	github.com/go-openapi/loads v0.24.0
-	github.com/go-openapi/spec v0.22.6
+	github.com/go-openapi/loads v0.25.0
+	github.com/go-openapi/spec v0.22.9
 	github.com/go-openapi/strfmt v0.27.0
-	github.com/go-openapi/swag/conv v0.27.0
-	github.com/go-openapi/swag/fileutils v0.27.0
-	github.com/go-openapi/swag/jsonutils v0.27.0
-	github.com/go-openapi/swag/stringutils v0.27.0
+	github.com/go-openapi/swag/conv v0.27.3
+	github.com/go-openapi/swag/fileutils v0.27.3
+	github.com/go-openapi/swag/jsonutils v0.27.3
+	github.com/go-openapi/swag/loading v0.27.3
+	github.com/go-openapi/swag/stringutils v0.27.3
 	github.com/go-openapi/testify/v2 v2.6.0
 	go.yaml.in/yaml/v3 v3.0.4
 )
 
 require (
-	github.com/go-openapi/jsonreference v0.21.6 // indirect
-	github.com/go-openapi/swag/jsonname v0.26.1 // indirect
-	github.com/go-openapi/swag/loading v0.26.1 // indirect
-	github.com/go-openapi/swag/mangling v0.26.1 // indirect
-	github.com/go-openapi/swag/typeutils v0.27.0 // indirect
-	github.com/go-openapi/swag/yamlutils v0.26.1 // indirect
+	github.com/go-openapi/jsonreference v1.0.0 // indirect
+	github.com/go-openapi/swag/mangling v0.27.3 // indirect
+	github.com/go-openapi/swag/pools v0.27.3 // indirect
+	github.com/go-openapi/swag/typeutils v0.27.3 // indirect
+	github.com/go-openapi/swag/yamlutils v0.27.3 // indirect
 	github.com/go-viper/mapstructure/v2 v2.5.0 // indirect
 	github.com/google/uuid v1.6.0 // indirect
 	github.com/oklog/ulid/v2 v2.1.1 // indirect

go.sum

@@ -1,37 +1,37 @@
-github.com/go-openapi/analysis v0.25.3 h1:4zlcg85pd2xq3sEgjW887n1IpwCpCqTmqeT6dP9OxDw=
-github.com/go-openapi/analysis v0.25.3/go.mod h1:6PEmUIra9/rn6SPstzbrMkhFAsMB2qm7g6E+4DRFyCU=
+github.com/go-openapi/analysis v0.25.5 h1:xPYEvTb90o1y0epuiOPAoG4QqahjP3cdp5xNlHeKJRI=
+github.com/go-openapi/analysis v0.25.5/go.mod h1:d3UGtQC5uq5Kqqqis2VH09Km/v3vwsWrYkbp4gdm+Rc=
 github.com/go-openapi/errors v0.22.8 h1:oP7sW7TWc3wFFjrzzj0nI83H2qMBkNjNfSd+XRejk/I=
 github.com/go-openapi/errors v0.22.8/go.mod h1:BuUoHcYrU6E7V9gfj1I5wLQqgtIHnup/alXZ8KdgQ0w=
 github.com/go-openapi/jsonpointer v1.0.0 h1:kR9tHqY0CtZaOPVFm622dPVNhrvYpwr4uCxgL3h1H8s=
 github.com/go-openapi/jsonpointer v1.0.0/go.mod h1:Z3rw7dWu1p9IgitXCFamSlA5lmDiklEB6vkaxcNZW5Y=
-github.com/go-openapi/jsonreference v0.21.6 h1:NZ5nGfnaM1n4I43Xjm1e5/M2GjOwQwndQz22uhxwD+Y=
-github.com/go-openapi/jsonreference v0.21.6/go.mod h1:xzbgtQ3ZbWxvET3AxdzCJlJt6vkovbf+IfSPJjD0tUY=
-github.com/go-openapi/loads v0.24.0 h1:4LLorXRPTzIN9V6ngMUZbAscsBOUBk3Oa8cClu/bFrQ=
-github.com/go-openapi/loads v0.24.0/go.mod h1:xQMgX+hw5xRAhGrcDXxeMw78IFqUpIzhleu3HqPhyF4=
-github.com/go-openapi/spec v0.22.6 h1:Tyy1pLaNCM8GBCFLoGYLonjJi6zykqyLCjXLc19ZPic=
-github.com/go-openapi/spec v0.22.6/go.mod h1:HZvTHat+iH0PALQRWhrqIHtU/PEqxqd89fu0MxGlMeM=
+github.com/go-openapi/jsonreference v1.0.0 h1:jlmTr6torcd1YgDQvSfNmRtKzYDO4FGBkrAdlAVWnpY=
+github.com/go-openapi/jsonreference v1.0.0/go.mod h1:jtwdyGbJk0Xhe5Y+rwtglQP6Sb1WZST4rT32LWB+sv0=
+github.com/go-openapi/loads v0.25.0 h1:74Bc2snfaVlsHzwdQj/3gsA9XJz3daXTJVs+4ZaK7jI=
+github.com/go-openapi/loads v0.25.0/go.mod h1:JFBw4SIB9+PTIFHDfcXuSSy5h6aWzjtUCrPYyx3qWU8=
+github.com/go-openapi/spec v0.22.9 h1:/vKIFDcGKp0ktZWGbym/tJEWbk6/XOEmAVU0kqKMH+w=
+github.com/go-openapi/spec v0.22.9/go.mod h1:b/mNUYIOQOyIiUzUzXEE8xzyZqf93KvM9hQGP91yfl0=
 github.com/go-openapi/strfmt v0.27.0 h1:kbcTeaD9TXuXD0hhMXzuYa1sdTo6+dWGvwjW93E80IM=
 github.com/go-openapi/strfmt v0.27.0/go.mod h1:s/qhDqfY72irigXUGJmtgid2Rm+3tnz3k8hZaRmvWYc=
-github.com/go-openapi/swag/conv v0.27.0 h1:EKOH4feXrvdo8DbSsXSAqRT8fz1epEnS5O2IfXUOzE8=
-github.com/go-openapi/swag/conv v0.27.0/go.mod h1:pfiv0uKQTbaGApk8Zs/lZV3uSjmSpa2FO1y183YngN8=
-github.com/go-openapi/swag/fileutils v0.27.0 h1:ib5jMUqGq5tY1EyO4inlrabsaeDAleFU+XD1FXQcgp8=
-github.com/go-openapi/swag/fileutils v0.27.0/go.mod h1:VvJFZLTZS0AI854gEQz5tk7dBESdLjiNUMSZ/th2ry8=
-github.com/go-openapi/swag/jsonname v0.26.1 h1:VReupaV6WxlAsCn0e4DUfgV6bPmINnPpyJDLqSfNPcE=
-github.com/go-openapi/swag/jsonname v0.26.1/go.mod h1:OvdW6BoWoj33pTfi7x9vFrgmT+fk7aw0BRwvCE0YOuc=
-github.com/go-openapi/swag/jsonutils v0.27.0 h1:VYtd9jEQYeU4j8q5vdn5KWotF4vKywhGdMBrALtAsfE=
-github.com/go-openapi/swag/jsonutils v0.27.0/go.mod h1:U7pb8AGuwhok3RDicHeHwSG4L3PXSq6PAL98Aon632g=
-github.com/go-openapi/swag/jsonutils/fixtures_test v0.27.0 h1:+d7C7Ur/SsGg/UZ9G0JEovnfRqtMNZCJQGKc2h/ojoE=
-github.com/go-openapi/swag/jsonutils/fixtures_test v0.27.0/go.mod h1:mofwUWx70wvskwESqRJ//k/9kURmCgyJl5m5Ppoh5kY=
-github.com/go-openapi/swag/loading v0.26.1 h1:E9K4wqXeROlhjFQ13K9zMz6ojFGXIggGe+ad1odrK9w=
-github.com/go-openapi/swag/loading v0.26.1/go.mod h1:3qvRIlWzWdq1HvmldwmuJ2ohpcAryN6xVt2OTKd0/7E=
-github.com/go-openapi/swag/mangling v0.26.1 h1:gpYI4WuPKFJJVjV5cDLGlDVJhFIxYjQc7yN5eEb4CqM=
-github.com/go-openapi/swag/mangling v0.26.1/go.mod h1:POETDH01hqAdASXfw7ISEd9bCOE6xBHOt8NHmGZRmYM=
-github.com/go-openapi/swag/stringutils v0.27.0 h1:Of7w/HljWsNZvuxsUAnw3n+hCOyI6HLJOxW2kQRAxio=
-github.com/go-openapi/swag/stringutils v0.27.0/go.mod h1:lzRN95CxXmA03XcDWHLOb6nOMcxCqR5rGY0lOgsfRoM=
-github.com/go-openapi/swag/typeutils v0.27.0 h1:aCf4MSGo8NLwZP8Q6t32DWLJSvl/WwNqgmEG+xJ6v2o=
-github.com/go-openapi/swag/typeutils v0.27.0/go.mod h1:Srm0xFNRZ1Y+vCxJclo5qzx8aj+1pAKda/YfFPrG0dQ=
-github.com/go-openapi/swag/yamlutils v0.26.1 h1:0TSLK+lXs9vfIhAWzBeI/lOzEnIoot6WTCO1aAeWFTk=
-github.com/go-openapi/swag/yamlutils v0.26.1/go.mod h1:7W5b7PRX9MxwL7TjeG7H8HkyBGRsIDRObhyMWFgBI2M=
+github.com/go-openapi/swag/conv v0.27.3 h1:iqJFmGEjmX3AY0lSszABFqRVqOSt99XS0LzNIMJYuhU=
+github.com/go-openapi/swag/conv v0.27.3/go.mod h1:nPRmN6jgNme99hpf+nM0auDZGALWIqlwhisKPK/bQhQ=
+github.com/go-openapi/swag/fileutils v0.27.3 h1:3UVoZ2RLaIs1lt+2jcKzL8RM3Yk0rmsDE9FLA/HGxFE=
+github.com/go-openapi/swag/fileutils v0.27.3/go.mod h1:VvJFZLTZS0AI854gEQz5tk7dBESdLjiNUMSZ/th2ry8=
+github.com/go-openapi/swag/jsonutils v0.27.3 h1:1DEz+O82frtSMBcos/7XIn1GnpNTbsD4Bru4Dc/uhRc=
+github.com/go-openapi/swag/jsonutils v0.27.3/go.mod h1:qiDCoQvzkMxrV3G8FLEdIU5L+EFYc0zcDOHWT3Yofvo=
+github.com/go-openapi/swag/jsonutils/fixtures_test v0.27.3 h1:h/eT9kmGCDdFLJF29lOhzLtF0FmP1AX2MhLJWVebsb8=
+github.com/go-openapi/swag/jsonutils/fixtures_test v0.27.3/go.mod h1:mofwUWx70wvskwESqRJ//k/9kURmCgyJl5m5Ppoh5kY=
+github.com/go-openapi/swag/loading v0.27.3 h1:L9nQkEgzU7QgFQL+pLEMfGUKxeM4pWwGwbET9Z3weW0=
+github.com/go-openapi/swag/loading v0.27.3/go.mod h1:rJ0NeaKsF4CVPnMGjPQl7JlSHzvD0bc2DKXLss1hiuE=
+github.com/go-openapi/swag/mangling v0.27.3 h1:gRzzD1PAUoLTtGMgI3KpBmCSOlTuLTFWnviLxLcTnyg=
+github.com/go-openapi/swag/mangling v0.27.3/go.mod h1:jtBE2+V+3pILxOR7Vgce+Cwp6A2PgZbvVqfNntbVs0w=
+github.com/go-openapi/swag/pools v0.27.3 h1:gXjImP3F6/56wRRcFgEPld084Y6u2gs21ikPBt8NKBk=
+github.com/go-openapi/swag/pools v0.27.3/go.mod h1:kVQefhSK5RWuRe7BXsL8htgBPAMpN7HDGpGEknqugeE=
+github.com/go-openapi/swag/stringutils v0.27.3 h1:Ru28hnbAvN5wycALQYy8IobHvASq+FUFMlp1QzLM0JI=
+github.com/go-openapi/swag/stringutils v0.27.3/go.mod h1:lzRN95CxXmA03XcDWHLOb6nOMcxCqR5rGY0lOgsfRoM=
+github.com/go-openapi/swag/typeutils v0.27.3 h1:l6SSrx5eR5/WVwrGNzN6bQ9WqL04mrxNBl9YgQ3rcJ4=
+github.com/go-openapi/swag/typeutils v0.27.3/go.mod h1:Srm0xFNRZ1Y+vCxJclo5qzx8aj+1pAKda/YfFPrG0dQ=
+github.com/go-openapi/swag/yamlutils v0.27.3 h1:cRFCAoYtslYn9L9T0xWryHy1t7c1MACC+DMj3CLvwvs=
+github.com/go-openapi/swag/yamlutils v0.27.3/go.mod h1:6JYBGj8sw/NawMllyZY+cTA8Mzk2etS3ZBASdcyPsiU=
 github.com/go-openapi/testify/enable/yaml/v2 v2.6.0 h1:gGHwAJ0R/5jU8BEGDbfRNR3hL68dAVi84WuOApp29B0=
 github.com/go-openapi/testify/enable/yaml/v2 v2.6.0/go.mod h1:tY+St1SGq4NFl0QIqdTY4aEdbChAHxhyB77XQi9iJCo=
 github.com/go-openapi/testify/v2 v2.6.0 h1:5PKH2HE7YJ/LuRPQGvSxBRlFXNQhSetBLlGAgUEu3ug=

helpers.go

@@ -242,9 +242,9 @@ func (h *paramHelper) resolveParam(path, method, operationID string, param *spec
 	res := new(Result)
 	isRef := param.Ref.String() != ""
 	if s.spec.SpecFilePath() == "" {
-		err = spec.ExpandParameterWithRoot(param, s.spec.Spec(), nil)
+		err = spec.ExpandParameterWithOptions(param, s.spec.Spec(), nil, s.schemaOptions.expandOptions(""))
 	} else {
-		err = spec.ExpandParameter(param, s.spec.SpecFilePath())
+		err = spec.ExpandParameterWithOptions(param, nil, nil, s.schemaOptions.expandOptions(s.spec.SpecFilePath()))
 	}
 	if err != nil { // Safeguard
 		// NOTE: we may enter here when the whole parameter is an unresolved $ref
@@ -295,9 +295,9 @@ func (r *responseHelper) expandResponseRef(
 	res := new(Result)
 	if s.spec.SpecFilePath() == "" {
 		// there is no physical document to resolve $ref in response
-		err = spec.ExpandResponseWithRoot(response, s.spec.Spec(), nil)
+		err = spec.ExpandResponseWithOptions(response, s.spec.Spec(), nil, s.schemaOptions.expandOptions(""))
 	} else {
-		err = spec.ExpandResponse(response, s.spec.SpecFilePath())
+		err = spec.ExpandResponseWithOptions(response, nil, nil, s.schemaOptions.expandOptions(s.spec.SpecFilePath()))
 	}
 	if err != nil { // Safeguard
 		// NOTE: we may enter here when the whole response is an unresolved $ref.

schema.go

@@ -63,18 +63,18 @@ func newSchemaValidator(schema *spec.Schema, rootSchema any, root string, format
 		rootSchema = schema
 	}
 
+	if opts == nil {
+		opts = new(SchemaValidatorOptions)
+	}
+
 	if schema.ID != "" || schema.Ref.String() != "" || schema.Ref.IsRoot() {
-		err := spec.ExpandSchema(schema, rootSchema, nil)
+		err := spec.ExpandSchemaWithOptions(schema, rootSchema, nil, opts.expandOptions(""))
 		if err != nil {
 			msg := invalidSchemaProvidedMsg(err).Error()
 			panic(msg)
 		}
 	}
 
-	if opts == nil {
-		opts = new(SchemaValidatorOptions)
-	}
-
 	var s *SchemaValidator
 	if opts.recycleValidators {
 		s = pools.poolOfSchemaValidators.BorrowValidator()

schema_loader_test.go

@@ -0,0 +1,55 @@
+// SPDX-FileCopyrightText: Copyright 2015-2025 go-swagger maintainers
+// SPDX-License-Identifier: Apache-2.0
+
+package validate
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/go-openapi/spec"
+	"github.com/go-openapi/strfmt"
+	"github.com/go-openapi/swag/loading"
+	"github.com/go-openapi/testify/v2/assert"
+	"github.com/go-openapi/testify/v2/require"
+)
+
+// TestSchemaValidator_WithPathLoader verifies that a document loader injected through
+// WithPathLoader is the one used to resolve a remote $ref when building a schema validator — the
+// hook a caller uses to confine loading when validating input from an untrusted source.
+func TestSchemaValidator_WithPathLoader(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		_, _ = w.Write([]byte(`{"type":"string"}`))
+	}))
+	defer srv.Close()
+
+	var calls int
+	loader := func(pth string, opts ...loading.Option) (json.RawMessage, error) {
+		calls++
+		return loading.LoadFromFileOrHTTP(pth, opts...)
+	}
+
+	schema := &spec.Schema{SchemaProps: spec.SchemaProps{Ref: spec.MustCreateRef(srv.URL + "/schema.json")}}
+	v := NewSchemaValidator(schema, nil, "", strfmt.Default, WithPathLoader(loader))
+
+	require.NotNil(t, v)
+	assert.TrueT(t, calls > 0, "expected the injected loader to resolve the remote $ref")
+}
+
+// TestSpecValidator_WithPathLoader verifies that WithPathLoader passed to the spec validator
+// constructors reaches the schema options consumed by both the schema validation and the $ref
+// resolution ($ref resolveRef) performed during spec validation.
+func TestSpecValidator_WithPathLoader(t *testing.T) {
+	loader := func(string, ...loading.Option) (json.RawMessage, error) { return nil, nil }
+
+	s := NewSpecValidator(spec.MustLoadSwagger20Schema(), strfmt.Default, WithPathLoader(loader))
+	require.NotNil(t, s.schemaOptions)
+	require.NotNil(t, s.schemaOptions.pathLoaderWithOptions,
+		"WithPathLoader must reach the spec validator's schema options (used by resolveRef and schema validation)")
+
+	// built-in defaults are still applied alongside the injected option
+	assert.TrueT(t, s.schemaOptions.EnableObjectArrayTypeCheck)
+	assert.TrueT(t, s.schemaOptions.recycleValidators)
+}

schema_option.go

@@ -3,13 +3,21 @@
 
 package validate
 
+import (
+	"encoding/json"
+
+	"github.com/go-openapi/spec"
+	"github.com/go-openapi/swag/loading"
+)
+
 // SchemaValidatorOptions defines optional rules for schema validation.
 type SchemaValidatorOptions struct {
 	EnableObjectArrayTypeCheck    bool
 	EnableArrayMustHaveItemsCheck bool
 	recycleValidators             bool
 	recycleResult                 bool
 	skipSchemataResult            bool
+	pathLoaderWithOptions         func(string, ...loading.Option) (json.RawMessage, error)
 }
 
 // Option sets optional rules for schema validation.
@@ -60,6 +68,23 @@ func WithSkipSchemataResult(enable bool) Option {
 	}
 }
 
+// WithPathLoader injects the document loader used to resolve remote and relative $ref while
+// validating a schema or specification. It matches the option-aware loader signature of
+// github.com/go-openapi/swag/loading (and go-openapi/loads).
+//
+// This lets validation resolve references through a caller-provided loader instead of the spec
+// package's global default. The loader may carry any loading options — a custom HTTP client or
+// timeout, authentication or custom headers, an embedded or rooted file system, and so on.
+//
+// One important use is confining loading of untrusted input: build the loader with loading.WithRoot
+// (to confine local reads) and loading.WithHTTPClient (to restrict remote fetches), or use a
+// restricted loader from go-openapi/loads. Left unset, the spec package default loader is used.
+func WithPathLoader(loader func(string, ...loading.Option) (json.RawMessage, error)) Option {
+	return func(svo *SchemaValidatorOptions) {
+		svo.pathLoaderWithOptions = loader
+	}
+}
+
 // Options returns the current set of options.
 func (svo SchemaValidatorOptions) Options() []Option {
 	return []Option{
@@ -68,5 +93,17 @@ func (svo SchemaValidatorOptions) Options() []Option {
 		WithRecycleValidators(svo.recycleValidators),
 		withRecycleResults(svo.recycleResult),
 		WithSkipSchemataResult(svo.skipSchemataResult),
+		WithPathLoader(svo.pathLoaderWithOptions),
+	}
+}
+
+// expandOptions builds the spec expand options for schema/$ref expansion during validation,
+// carrying the injected loader (when set) so resolution can be confined. relativeBase is used for
+// base-path-relative resolution; it is ignored by [spec.ExpandSchemaWithOptions], which derives the
+// base from the root.
+func (svo *SchemaValidatorOptions) expandOptions(relativeBase string) *spec.ExpandOptions {
+	return &spec.ExpandOptions{
+		RelativeBase:          relativeBase,
+		PathLoaderWithOptions: svo.pathLoaderWithOptions,
 	}
 }

spec.go

@@ -25,6 +25,9 @@ import (
 //
 // Returns an error flattening in a single standard error, all validation messages.
 //
+// Options are forwarded to the underlying [SpecValidator]; in particular [WithPathLoader] injects a
+// confined document loader for validating a specification from an untrusted source.
+//
 //   - Proposal for enhancement: $ref should not have siblings
 //   - Proposal for enhancement: make sure documentation reflects all checks and warnings
 //   - Proposal for enhancement: check on discriminators
@@ -35,8 +38,8 @@ import (
 //   - Proposal for enhancement: check on required properties to support anyOf, allOf, oneOf
 //
 // NOTE: SecurityScopes are maps: no need to check uniqueness.
-func Spec(doc *loads.Document, formats strfmt.Registry) error {
-	errs, _ /*warns*/ := NewSpecValidator(doc.Schema(), formats).Validate(doc)
+func Spec(doc *loads.Document, formats strfmt.Registry, options ...Option) error {
+	errs, _ /*warns*/ := NewSpecValidator(doc.Schema(), formats, options...).Validate(doc)
 	if errs.HasErrors() {
 		return errors.CompositeValidationError(errs.Errors...)
 	}
@@ -55,14 +58,20 @@ type SpecValidator struct {
 }
 
 // NewSpecValidator creates a new swagger spec validator instance.
-func NewSpecValidator(schema *spec.Schema, formats strfmt.Registry) *SpecValidator {
-	// schema options that apply to all called validators
+//
+// Options apply to the schema validators used internally. In particular, [WithPathLoader] injects
+// the document loader used to resolve $ref while validating the specification — set a confined
+// loader when validating a specification from an untrusted source (see the package "Security"
+// notes on [WithPathLoader]).
+func NewSpecValidator(schema *spec.Schema, formats strfmt.Registry, options ...Option) *SpecValidator {
+	// schema options that apply to all called validators: built-in defaults first, then
+	// caller-supplied options (which may add a loader or override a default).
 	schemaOptions := new(SchemaValidatorOptions)
-	for _, o := range []Option{
+	for _, o := range append([]Option{
 		SwaggerSchema(true),
 		WithRecycleValidators(true),
 		// withRecycleResults(true),
-	} {
+	}, options...) {
 		o(schemaOptions)
 	}
 
@@ -252,7 +261,7 @@ func (s *SpecValidator) validateDuplicatePropertyNames() *Result {
 
 func (s *SpecValidator) resolveRef(ref *spec.Ref) (*spec.Schema, error) {
 	if s.spec.SpecFilePath() != "" {
-		return spec.ResolveRefWithBase(s.spec.Spec(), ref, &spec.ExpandOptions{RelativeBase: s.spec.SpecFilePath()})
+		return spec.ResolveRefWithBase(s.spec.Spec(), ref, s.schemaOptions.expandOptions(s.spec.SpecFilePath()))
 	}
 	// NOTE: it looks like with the new spec resolver, this code is now unrecheable
 	return spec.ResolveRef(s.spec.Spec(), ref)
@@ -789,7 +798,10 @@ func (s *SpecValidator) validateReferencesValid() *Result {
 		// NOTE: with default settings, loads.Document.Expanded()
 		// stops on first error. Anyhow, the expand option to continue
 		// on errors fails to report errors at all.
-		exp, err := s.spec.Expanded()
+		//
+		// Pass the injected loader (if any) so whole-spec expansion is confined too. When no loader
+		// is set, this is a no-op: loads falls back to the document's own loader.
+		exp, err := s.spec.Expanded(s.schemaOptions.expandOptions(""))
 		if err != nil {
 			res.AddErrors(unresolvedReferencesMsg(err))
 		}