resourceref

README

resourceref

Universal resource references and a data-driven engine for owned URI schemes, for Go.

The idea

A resource reference is a URI. Prefer the resource owner's canonical URI when one exists — an AWS ARN, a SPIFFE ID, a GitHub URL — and mint an owned URI only when one does not. Owner-canonical URIs pass through this module untouched; there is no translation layer for external resources.

arn:aws:s3:::customer-data                  (AWS's own reference — pass through)
spiffe://prod.example.com/ns/api/sa/default  (SPIFFE's own reference — pass through)
https://github.com/acme/billing-service      (GitHub's own reference — pass through)
prn://acme/billing/org_7f3/invoice/inv_9c3@prod   (an owned reference)

Once independently developed systems agree on this one reference format, they can exchange references — in JSON IRs, policy documents, lineage graphs, audit events — without understanding one another's internal schemas. The reference becomes the join key.

What's in this module

• ResourceRef — a parsed, canonicalized, comparable resource reference. Parse, String, Equal, JSON/text marshaling as a plain string.
• scheme — the engine for defining owned URI schemes as data: a Profile describes a SPIFFE-strict URI subset, an authority (namespace owner) registry, per-authority path shapes, resource-type registries, and version/alias suffix grammar (@prod, @14). Load parses and structurally validates a profile document; Profile.Validate and Profile.Split check a ResourceRef against it and, for Split, return its typed decomposition (Parts). Namespace owners publish their own profile — this module ships none, only a reference test fixture.
• schema — the generated JSON Schema for the Profile format and a ready-to-embed fragment for a ResourceRef-typed field, for external tooling and other IRs' schemas.

See docs/embedding.md for how to add a reference field to your own IR — Go type, JSON Schema, and the logical-vs-instance identity pitfall to avoid.

What this module deliberately does not do

• No resolution. Identifier is not locator; turning a reference into an endpoint is a resolver's job, not this module's.
• No specific scheme. This module ships the mechanism only — a reference test fixture, not a real scheme. Defining your own owned scheme (its authorities, path shapes, resource types) is entirely up to whoever adopts it; see docs/embedding.md.
• No invocation or authorization. Calling, authorizing, or executing against a reference is the concern of a layer built on top of this module, not this module's own.

Design basis

RFC 3986 (URI generic syntax) for the wire form, RFC 8141 (URN persistence semantics) for the identifier-not-locator discipline, and the SPIFFE ID specification for strict URI-subset validation. AWS ARN and Kubernetes resource references inform the cross-referencing and typed-identity lessons without adopting their service-specific syntax.

Status

Early development. See docs/specs/initiatives/INIT-RESOURCEREF-001 for the current PRD/TRD/PLAN/ROADMAP.

License

Apache License 2.0. See LICENSE.

Documentation

Overview

Package resourceref provides a universal resource-reference type and a data-driven engine for defining owned URI schemes.

The governing rule is simple: a resource reference is a URI. Prefer the resource owner's canonical URI when one exists — an AWS ARN, a SPIFFE ID, a GitHub URL — and mint an owned URI only when one does not. Owner-canonical URIs pass through this package untouched; there is no translation layer for external resources.

Two layers

ResourceRef is the universal type: any RFC 3986 URI, canonicalized and comparable, usable as a graph node ID, a lineage edge, or a field in any JSON IR.

The scheme subpackage defines owned URI schemes as data (a Profile), not code: a SPIFFE-strict URI subset, an authority (namespace owner) registry, per-authority path shapes, resource-type registries, and version/alias suffix grammar. Namespace owners define their own profiles; this package supplies only the mechanism, not any specific scheme instance.

What this package deliberately does not do

It does not resolve references to locations — identifier is not locator. It does not authorize, invoke, or execute anything against a reference. It does not define any specific scheme instance. Those concerns belong to resolvers, invocation contracts, and whatever adopts this module.

Index

• Variables
• type ResourceRef
  • func MustParse(s string) ResourceRef
  • func Parse(s string) (ResourceRef, error)
  • func (r ResourceRef) Equal(o ResourceRef) bool
  • func (r ResourceRef) IsZero() bool
  • func (r ResourceRef) MarshalText() ([]byte, error)
  • func (r ResourceRef) Scheme() string
  • func (r ResourceRef) String() string
  • func (r *ResourceRef) UnmarshalText(text []byte) error

Variables

var ErrNoScheme = errors.New("resourceref: missing URI scheme")

ErrNoScheme is returned by Parse when the input has no URI scheme. A ResourceRef must be an absolute URI reference — relative references are not resource references.

Types

type ResourceRef

type ResourceRef struct {
	// contains filtered or unexported fields
}

A ResourceRef is a parsed, canonicalized resource reference.

Construct one with Parse or MustParse; the zero value is not a valid reference (its String method returns "").

func MustParse

func MustParse(s string) ResourceRef

MustParse is like Parse but panics if s cannot be parsed. It is intended for tests and package-level initialization from known-good literals, not for parsing untrusted input.

func Parse

func Parse(s string) (ResourceRef, error)

Parse parses s as an absolute URI reference (RFC 3986) and returns its canonical ResourceRef form.

Canonicalization is conservative and never semantically reinterprets a reference's components:

• the scheme, and the host of a hierarchical reference, are lowercased;
• percent-encoding is normalized per RFC 3986 §6.2.2.2 — an encoded octet is decoded only when it corresponds to an unreserved character (ALPHA / DIGIT / "-" / "." / "_" / "~"), and any encoding that remains has its hex digits uppercased;
• dot segments are removed from hierarchical paths per RFC 3986 §5.2.4;
• no scheme-specific default (e.g. treating :443 as implied by https) is ever stripped or assumed.

Owner-canonical external references — an AWS ARN, a SPIFFE ID, a URN — pass through with their opaque or authority structure intact.

func (ResourceRef) Equal

func (r ResourceRef) Equal(o ResourceRef) bool

Equal reports whether r and o refer to the same canonical reference.

func (ResourceRef) IsZero

func (r ResourceRef) IsZero() bool

IsZero reports whether r is the zero ResourceRef.

func (ResourceRef) MarshalText

func (r ResourceRef) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler, encoding the reference as its canonical string form. json.Marshal uses this automatically for any struct field of type ResourceRef, so it encodes as a plain JSON string.

Marshaling the zero value is an error: a ResourceRef field is either a real reference or should be represented as *ResourceRef (nil, with omitempty) — never as a silent empty string.

func (ResourceRef) Scheme

func (r ResourceRef) Scheme() string

Scheme returns the reference's URI scheme, already lowercased by Parse.

func (ResourceRef) String

func (r ResourceRef) String() string

String returns the reference's canonical form, or "" for the zero value.

func (*ResourceRef) UnmarshalText

func (r *ResourceRef) UnmarshalText(text []byte) error

UnmarshalText implements encoding.TextUnmarshaler by parsing text with Parse.