Add URI Scheme Stripping Support (#1091)

- Fixes #1090
## Summary
This PR adds support for stripping URI schemes from reference strings in
ParseReference to improve cross-tool compatibility with Helm, Argo,
Kustomize, and other tools that prefix references with schemes.

## Changes Made
- Strip `oci://`, `http://`, `https://` schemes before parsing
references
  - Add documentation demonstrating usage with `oci://` scheme
  - Add new test cases covering all schemes, forms, and edge cases

---------

Signed-off-by: bupd <bupdprasanth@gmail.com>
Co-authored-by: Terry Howe <terrylhowe@gmail.com>

Author: bupd

registry/example_reference_test.go

@@ -45,3 +45,22 @@ func ExampleParseReference_digest() {
 	// Repository: oras-project/oras-go
 	// Digest: sha256:601d05a48832e7946dab8f49b14953549bebf42e42f4d7973b1a5a287d77ab76
 }
+
+// ExampleParseReference_withScheme demonstrates parsing a reference with
+// a URI scheme and printing its components.
+func ExampleParseReference_withScheme() {
+	rawRef := "oci://ghcr.io/oras-project/oras-go:v3.0.0"
+	ref, err := registry.ParseReference(rawRef)
+	if err != nil {
+		panic(err)
+	}
+
+	fmt.Println("Registry:", ref.Registry)
+	fmt.Println("Repository:", ref.Repository)
+	fmt.Println("Tag:", ref.Reference)
+
+	// Output:
+	// Registry: ghcr.io
+	// Repository: oras-project/oras-go
+	// Tag: v3.0.0
+}

registry/reference.go

@@ -71,6 +71,19 @@ type Reference struct {
 // Note: An "image" is an "artifact", however, an "artifact" is not necessarily
 // an "image".
 //
+// ## URI Schemes
+//
+// ParseReference automatically strips the following URI schemes if present:
+//   - oci://    (used by Helm, Argo, Kustomize)
+//   - http://   (HTTP registry endpoints)
+//   - https://  (HTTPS registry endpoints)
+//
+// Schemes must be lowercase and at the start of the string. Examples:
+//   - "oci://ghcr.io/repo:tag" → parses as "ghcr.io/repo:tag"
+//   - "https://registry.example.com/repo" → parses as "registry.example.com/repo"
+//
+// ## Specification
+//
 // The token `artifact` is composed of other tokens, and those in turn are
 // composed of others.  This definition recursivity requires a notation capable
 // of recursion, thus the following two forms have been adopted:
@@ -117,6 +130,11 @@ type Reference struct {
 // Note: In the case of Valid Form B, TAG is dropped without any validation or
 // further consideration.
 func ParseReference(artifact string) (Reference, error) {
+	// Strip URI schemes if present
+	artifact = strings.TrimPrefix(artifact, "oci://")
+	artifact = strings.TrimPrefix(artifact, "http://")
+	artifact = strings.TrimPrefix(artifact, "https://")
+
 	registry, path := splitRegistry(artifact)
 	if path == "" {
 		return Reference{}, fmt.Errorf("%w: missing registry or repository", errdef.ErrInvalidReference)

registry/reference_test.go

@@ -350,3 +350,176 @@ func TestReference_String(t *testing.T) {
 		})
 	}
 }
+
+func TestParseReferenceWithSchemes(t *testing.T) {
+	tests := []struct {
+		name    string
+		input   string
+		want    Reference
+		wantErr bool
+	}{
+		// oci:// scheme tests
+		{
+			name:  "oci scheme with digest (valid form A)",
+			input: fmt.Sprintf("oci://localhost/hello-world@%s", ValidDigest),
+			want: Reference{
+				Registry:   "localhost",
+				Repository: "hello-world",
+				Reference:  ValidDigest,
+			},
+			wantErr: false,
+		},
+		{
+			name:  "oci scheme with tag (valid form C)",
+			input: "oci://registry.example.com/hello-world:v1",
+			want: Reference{
+				Registry:   "registry.example.com",
+				Repository: "hello-world",
+				Reference:  "v1",
+			},
+			wantErr: false,
+		},
+		{
+			name:  "oci scheme with tag and digest (valid form B)",
+			input: fmt.Sprintf("oci://registry.example.com/hello-world:v2@%s", ValidDigest),
+			want: Reference{
+				Registry:   "registry.example.com",
+				Repository: "hello-world",
+				Reference:  ValidDigest,
+			},
+			wantErr: false,
+		},
+		{
+			name:  "oci scheme basic reference (valid form D)",
+			input: "oci://127.0.0.1:5000/hello-world",
+			want: Reference{
+				Registry:   "127.0.0.1:5000",
+				Repository: "hello-world",
+			},
+			wantErr: false,
+		},
+		{
+			name:  "oci scheme with IPv6 registry",
+			input: "oci://[::1]:5000/hello-world:latest",
+			want: Reference{
+				Registry:   "[::1]:5000",
+				Repository: "hello-world",
+				Reference:  "latest",
+			},
+			wantErr: false,
+		},
+		{
+			name:  "oci scheme with multi-level repository",
+			input: "oci://ghcr.io/oras-project/oras-go:v3.0.0",
+			want: Reference{
+				Registry:   "ghcr.io",
+				Repository: "oras-project/oras-go",
+				Reference:  "v3.0.0",
+			},
+			wantErr: false,
+		},
+
+		// http:// scheme tests
+		{
+			name:  "http scheme with digest",
+			input: fmt.Sprintf("http://localhost/hello-world@%s", ValidDigest),
+			want: Reference{
+				Registry:   "localhost",
+				Repository: "hello-world",
+				Reference:  ValidDigest,
+			},
+			wantErr: false,
+		},
+		{
+			name:  "http scheme with tag",
+			input: "http://registry.example.com:8080/hello-world:v1",
+			want: Reference{
+				Registry:   "registry.example.com:8080",
+				Repository: "hello-world",
+				Reference:  "v1",
+			},
+			wantErr: false,
+		},
+
+		// https:// scheme tests
+		{
+			name:  "https scheme with digest",
+			input: fmt.Sprintf("https://localhost/hello-world@%s", ValidDigest),
+			want: Reference{
+				Registry:   "localhost",
+				Repository: "hello-world",
+				Reference:  ValidDigest,
+			},
+			wantErr: false,
+		},
+		{
+			name:  "https scheme with tag",
+			input: "https://registry.example.com/hello-world:v1",
+			want: Reference{
+				Registry:   "registry.example.com",
+				Repository: "hello-world",
+				Reference:  "v1",
+			},
+			wantErr: false,
+		},
+
+		// Backward compatibility - no scheme
+		{
+			name:  "no scheme (backward compatibility)",
+			input: "localhost/hello-world:v1",
+			want: Reference{
+				Registry:   "localhost",
+				Repository: "hello-world",
+				Reference:  "v1",
+			},
+			wantErr: false,
+		},
+
+		// Edge cases - invalid inputs should still fail validation
+		{
+			name:    "oci scheme but missing repository",
+			input:   "oci://localhost",
+			wantErr: true,
+		},
+		{
+			name:    "oci scheme but invalid registry",
+			input:   "oci://invalid registry/repo",
+			wantErr: true,
+		},
+		{
+			name:    "oci scheme but invalid repository name",
+			input:   "oci://localhost/UPPERCASE",
+			wantErr: true,
+		},
+		{
+			name:    "scheme in wrong position (middle)",
+			input:   "localhost/oci://hello-world",
+			wantErr: true,
+		},
+
+		// Case sensitivity - schemes should be lowercase
+		{
+			name:    "uppercase OCI scheme not stripped",
+			input:   "OCI://localhost/hello-world",
+			wantErr: true, // "OCI:" will be parsed as invalid registry
+		},
+		{
+			name:    "mixed case scheme not stripped",
+			input:   "Oci://localhost/hello-world",
+			wantErr: true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, err := ParseReference(tt.input)
+			if (err != nil) != tt.wantErr {
+				t.Errorf("ParseReference() error = %v, wantErr %v", err, tt.wantErr)
+				return
+			}
+			if !tt.wantErr && !reflect.DeepEqual(got, tt.want) {
+				t.Errorf("ParseReference() = %v, want %v", got, tt.want)
+			}
+		})
+	}
+}