fix: handle git ref paths in join() for $ref resolution

When resolving relative $ref paths against a base path that uses git ref
syntax (e.g. "origin/main:openapi.yaml"), path.Dir() treats the colon as
a regular character and returns "origin" instead of recognizing it as the
git ref separator.

This causes $ref resolution to produce invalid paths like
"origin/schemas/pet.yaml" instead of "origin/main:schemas/pet.yaml",
breaking multi-file OpenAPI specs loaded via git refs.

The fix detects the colon separator and applies path.Dir/path.Join only
to the file path portion after the colon, preserving the git ref prefix.

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

Author: reuvenharrison

openapi3/loader.go

@@ -278,7 +278,16 @@ func join(basePath *url.URL, relativePath *url.URL) *url.URL {
 		return relativePath
 	}
 	newPath := *basePath
-	newPath.Path = path.Join(path.Dir(newPath.Path), relativePath.Path)
+	// 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)
+	}
 	return &newPath
 }
 

openapi3/loader_test.go

@@ -672,3 +672,57 @@ func TestReadFromIoReader_Nil(t *testing.T) {
 	_, err := loader.LoadFromIoReader(nil)
 	require.EqualError(t, err, "invalid reader: <nil>")
 }
+
+func TestJoinGitRefPath(t *testing.T) {
+	tests := []struct {
+		name     string
+		base     string
+		rel      string
+		expected string
+	}{
+		{
+			name:     "git ref with relative path",
+			base:     "origin/main:openapi.yaml",
+			rel:      "schemas/pet.yaml",
+			expected: "origin/main:schemas/pet.yaml",
+		},
+		{
+			name:     "git ref with dot-slash relative path",
+			base:     "origin/main:openapi.yaml",
+			rel:      "./schemas/pet.yaml",
+			expected: "origin/main:schemas/pet.yaml",
+		},
+		{
+			name:     "git ref with nested base path",
+			base:     "origin/main: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",
+		},
+		{
+			name:     "nil base returns relative",
+			base:     "",
+			rel:      "schemas/pet.yaml",
+			expected: "schemas/pet.yaml",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			rel := &url.URL{Path: tt.rel}
+			if tt.base == "" {
+				result := join(nil, rel)
+				require.Equal(t, tt.expected, result.Path)
+				return
+			}
+			base := &url.URL{Path: tt.base}
+			result := join(base, rel)
+			require.Equal(t, tt.expected, result.Path)
+		})
+	}
+}