openapi3: add JoinFunc callback for custom path resolution

Replace the colon-specific handling with a general-purpose JoinFunc
callback on Loader. This lets callers override how relative $ref paths
are resolved against the base path — useful when loading specs from
non-filesystem sources (git objects, remote archives, etc.) where the
base path follows a different convention than filesystem paths.

When JoinFunc is nil (the default), behavior is unchanged.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: reuvenharrison

openapi3/loader.go

@@ -41,6 +41,13 @@ type Loader struct {
 	// ReadFromURIFunc allows overriding the any file/URL reading func
 	ReadFromURIFunc ReadFromURIFunc
 
+	// JoinFunc allows overriding how relative $ref paths are resolved against
+	// a base path. When set, it is called instead of the default join logic
+	// that uses path.Dir and path.Join. This is useful when loading specs from
+	// non-filesystem sources (e.g. git objects, remote archives) where the base
+	// path follows a different convention than filesystem paths.
+	JoinFunc func(basePath *url.URL, relativePath *url.URL) *url.URL
+
 	Context context.Context
 
 	rootDir      string
@@ -107,7 +114,7 @@ func (loader *Loader) loadSingleElementFromURI(ref string, rootPath *url.URL, el
 		}
 	}
 
-	resolvedPath, err := resolvePathWithRef(ref, rootPath)
+	resolvedPath, err := loader.resolvePathWithRef(ref, rootPath)
 	if err != nil {
 		return nil, err
 	}
@@ -273,42 +280,36 @@ func (loader *Loader) ResolveRefsIn(doc *T, location *url.URL) (err error) {
 	return
 }
 
-func join(basePath *url.URL, relativePath *url.URL) *url.URL {
+func defaultJoin(basePath *url.URL, relativePath *url.URL) *url.URL {
 	if basePath == nil {
 		return relativePath
 	}
 	newPath := *basePath
-	// Handle git ref paths like "origin/main:openapi.yaml" where ":"
-	// separates the ref from the file path. path.Dir does not understand
-	// this syntax and would treat the colon as a regular character.
-	if i := strings.IndexByte(newPath.Path, ':'); i >= 0 {
-		prefix := newPath.Path[:i+1] // e.g. "origin/main:"
-		filePath := newPath.Path[i+1:]
-		newPath.Path = prefix + path.Join(path.Dir(filePath), relativePath.Path)
-	} else {
-		newPath.Path = path.Join(path.Dir(newPath.Path), relativePath.Path)
-	}
+	newPath.Path = path.Join(path.Dir(newPath.Path), relativePath.Path)
 	return &newPath
 }
 
-func resolvePath(basePath *url.URL, componentPath *url.URL) *url.URL {
+func (loader *Loader) resolvePath(basePath *url.URL, componentPath *url.URL) *url.URL {
 	if is_file(componentPath) {
 		// support absolute paths
 		if filepath.IsAbs(componentPath.Path) {
 			return componentPath
 		}
-		return join(basePath, componentPath)
+		if loader.JoinFunc != nil {
+			return loader.JoinFunc(basePath, componentPath)
+		}
+		return defaultJoin(basePath, componentPath)
 	}
 	return componentPath
 }
 
-func resolvePathWithRef(ref string, rootPath *url.URL) (*url.URL, error) {
+func (loader *Loader) resolvePathWithRef(ref string, rootPath *url.URL) (*url.URL, error) {
 	parsedURL, err := url.Parse(ref)
 	if err != nil {
 		return nil, fmt.Errorf("cannot parse reference: %q: %w", ref, err)
 	}
 
-	resolvedPath := resolvePath(rootPath, parsedURL)
+	resolvedPath := loader.resolvePath(rootPath, parsedURL)
 	resolvedPath.Fragment = parsedURL.Fragment
 	return resolvedPath, nil
 }
@@ -333,7 +334,7 @@ func (loader *Loader) resolveRefPath(ref string, path *url.URL) (*url.URL, error
 		}
 	}
 
-	resolvedPath, err := resolvePathWithRef(ref, path)
+	resolvedPath, err := loader.resolvePathWithRef(ref, path)
 	if err != nil {
 		return nil, err
 	}

openapi3/loader_example_test.go

@@ -0,0 +1,89 @@
+package openapi3_test
+
+import (
+	"fmt"
+	"net/url"
+	"os"
+	"path"
+	"path/filepath"
+	"strings"
+
+	"github.com/getkin/kin-openapi/openapi3"
+)
+
+// ExampleLoader_JoinFunc demonstrates how to use JoinFunc to load a multi-file
+// OpenAPI spec from a virtual path scheme (e.g. git refs like "rev:file.yaml").
+//
+// When loading specs from non-filesystem sources via LoadFromDataWithPath and
+// ReadFromURIFunc, the base path may use a custom prefix convention. The default
+// path resolution uses path.Dir which does not understand such prefixes. JoinFunc
+// lets the caller override path resolution to preserve the prefix.
+func ExampleLoader_JoinFunc() {
+	// Set up test files in a temp directory.
+	dir, _ := os.MkdirTemp("", "joinfunc-example")
+	defer os.RemoveAll(dir)
+
+	root := `openapi: "3.0.0"
+info:
+  title: Pet API
+  version: "1.0"
+paths: {}
+components:
+  schemas:
+    Pet:
+      $ref: "./schemas/pet.yaml"
+`
+	pet := `type: object
+properties:
+  name:
+    type: string
+`
+	os.MkdirAll(filepath.Join(dir, "schemas"), 0o755)
+	os.WriteFile(filepath.Join(dir, "root.yaml"), []byte(root), 0o644)
+	os.WriteFile(filepath.Join(dir, "schemas", "pet.yaml"), []byte(pet), 0o644)
+
+	// Use a "rev:" prefix to simulate a virtual path scheme.
+	const prefix = "rev:"
+
+	loader := openapi3.NewLoader()
+	loader.IsExternalRefsAllowed = true
+
+	// ReadFromURIFunc strips the prefix and reads from the real filesystem.
+	loader.ReadFromURIFunc = func(loader *openapi3.Loader, location *url.URL) ([]byte, error) {
+		p := location.Path
+		if strings.HasPrefix(p, prefix) {
+			p = p[len(prefix):]
+		}
+		return os.ReadFile(filepath.Join(dir, filepath.FromSlash(p)))
+	}
+
+	// JoinFunc preserves the prefix when resolving relative $ref paths.
+	// Without this, path.Dir("rev:root.yaml") returns "." and $ref resolution breaks.
+	loader.JoinFunc = func(basePath *url.URL, relativePath *url.URL) *url.URL {
+		if basePath == nil {
+			return relativePath
+		}
+		result := *basePath
+		base := basePath.Path
+		if i := strings.IndexByte(base, ':'); i >= 0 {
+			pfx := base[:i+1]
+			filePart := base[i+1:]
+			result.Path = pfx + path.Join(path.Dir(filePart), relativePath.Path)
+		} else {
+			result.Path = path.Join(path.Dir(base), relativePath.Path)
+		}
+		return &result
+	}
+
+	rootContent, _ := os.ReadFile(filepath.Join(dir, "root.yaml"))
+	doc, err := loader.LoadFromDataWithPath(rootContent, &url.URL{Path: prefix + "root.yaml"})
+	if err != nil {
+		fmt.Println("error:", err)
+		return
+	}
+
+	petSchema := doc.Components.Schemas["Pet"]
+	nameType := petSchema.Value.Properties["name"].Value.Type.Slice()[0]
+	fmt.Println("Pet.name type:", nameType)
+	// Output: Pet.name type: string
+}

openapi3/loader_test.go

@@ -7,6 +7,9 @@ import (
 	"net/http"
 	"net/http/httptest"
 	"net/url"
+	"os"
+	"path"
+	"path/filepath"
 	"strings"
 	"testing"
 
@@ -673,36 +676,30 @@ func TestReadFromIoReader_Nil(t *testing.T) {
 	require.EqualError(t, err, "invalid reader: <nil>")
 }
 
-func TestJoinGitRefPath(t *testing.T) {
+func TestDefaultJoin(t *testing.T) {
 	tests := []struct {
 		name     string
 		base     string
 		rel      string
 		expected string
 	}{
 		{
-			name:     "git ref with relative path",
-			base:     "origin/main:openapi.yaml",
+			name:     "relative path",
+			base:     "/home/user/openapi.yaml",
 			rel:      "schemas/pet.yaml",
-			expected: "origin/main:schemas/pet.yaml",
+			expected: "/home/user/schemas/pet.yaml",
 		},
 		{
-			name:     "git ref with dot-slash relative path",
-			base:     "origin/main:openapi.yaml",
+			name:     "dot-slash relative path",
+			base:     "/home/user/openapi.yaml",
 			rel:      "./schemas/pet.yaml",
-			expected: "origin/main:schemas/pet.yaml",
+			expected: "/home/user/schemas/pet.yaml",
 		},
 		{
-			name:     "git ref with nested base path",
-			base:     "origin/main:api/v1/openapi.yaml",
+			name:     "parent directory",
+			base:     "/home/user/api/v1/openapi.yaml",
 			rel:      "../common/types.yaml",
-			expected: "origin/main:api/common/types.yaml",
-		},
-		{
-			name:     "regular path without colon",
-			base:     "/home/user/openapi.yaml",
-			rel:      "schemas/pet.yaml",
-			expected: "/home/user/schemas/pet.yaml",
+			expected: "/home/user/api/common/types.yaml",
 		},
 		{
 			name:     "nil base returns relative",
@@ -716,13 +713,76 @@ func TestJoinGitRefPath(t *testing.T) {
 		t.Run(tt.name, func(t *testing.T) {
 			rel := &url.URL{Path: tt.rel}
 			if tt.base == "" {
-				result := join(nil, rel)
+				result := defaultJoin(nil, rel)
 				require.Equal(t, tt.expected, result.Path)
 				return
 			}
 			base := &url.URL{Path: tt.base}
-			result := join(base, rel)
+			result := defaultJoin(base, rel)
 			require.Equal(t, tt.expected, result.Path)
 		})
 	}
 }
+
+func TestJoinFunc(t *testing.T) {
+	// Create a multi-file spec in a temp directory
+	dir := t.TempDir()
+
+	root := `openapi: "3.0.0"
+info:
+  title: Test
+  version: "1.0"
+paths: {}
+components:
+  schemas:
+    Pet:
+      $ref: "./schemas/pet.yaml"
+`
+	pet := `type: object
+properties:
+  name:
+    type: string
+`
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "schemas"), 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(dir, "root.yaml"), []byte(root), 0o644))
+	require.NoError(t, os.WriteFile(filepath.Join(dir, "schemas", "pet.yaml"), []byte(pet), 0o644))
+
+	// Simulate a virtual prefix (like a git ref "rev:") by storing files
+	// under their real paths but loading via a prefixed base path.
+	// Without JoinFunc, path.Dir("myprefix:root.yaml") returns "." which
+	// breaks resolution. With JoinFunc, we split on ":" and resolve correctly.
+	prefix := "myprefix:"
+
+	loader := NewLoader()
+	loader.IsExternalRefsAllowed = true
+	loader.ReadFromURIFunc = func(loader *Loader, location *url.URL) ([]byte, error) {
+		p := location.Path
+		if strings.HasPrefix(p, prefix) {
+			p = p[len(prefix):]
+		}
+		return os.ReadFile(filepath.Join(dir, filepath.FromSlash(p)))
+	}
+	loader.JoinFunc = func(basePath *url.URL, relativePath *url.URL) *url.URL {
+		if basePath == nil {
+			return relativePath
+		}
+		newPath := *basePath
+		base := basePath.Path
+		if i := strings.IndexByte(base, ':'); i >= 0 {
+			pfx := base[:i+1]
+			filePart := base[i+1:]
+			newPath.Path = pfx + path.Join(path.Dir(filePart), relativePath.Path)
+		} else {
+			newPath.Path = path.Join(path.Dir(base), relativePath.Path)
+		}
+		return &newPath
+	}
+
+	rootContent, err := os.ReadFile(filepath.Join(dir, "root.yaml"))
+	require.NoError(t, err)
+
+	doc, err := loader.LoadFromDataWithPath(rootContent, &url.URL{Path: prefix + "root.yaml"})
+	require.NoError(t, err)
+	require.NotNil(t, doc.Components.Schemas["Pet"])
+	require.Equal(t, "string", doc.Components.Schemas["Pet"].Value.Properties["name"].Value.Type.Slice()[0])
+}