urn

package module
v0.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 3, 2026 License: MIT Imports: 3 Imported by: 0

README

urn

The grammar of the estate's URN identifiers for schemas and scopes, and their parsers

Go Reference Pipeline Coverage phpboyscout Go toolkit

Part of the phpboyscout Go toolkit — small, framework-free Go modules. Docs: urn.go.phpboyscout.uk

go get gitlab.com/phpboyscout/go/urn
urn:phpboyscout:schema:orders.created:3
urn:phpboyscout:scope:continuity:01JQ8Z3F7K2M4N6P8R0T2V4W6X
s, err := urn.ParseSchema("urn:phpboyscout:schema:orders.created:3")
// s.Name == "orders.created", s.Version == 3, s.String() returns the input

sc, err := urn.ParseScope("urn:phpboyscout:scope:continuity:01JQ8Z3F7K2M4N6P8R0T2V4W6X")
// sc.Kind == "continuity"

A schema URN is what an event's dataschema attribute carries, and what go/schema resolves. A scope URN is the estate's tenancy attribute. The module depends on nothing but go/errors, so reading an identifier brings nothing else with it.

Moving from go/cloudevents/urn

This was gitlab.com/phpboyscout/go/cloudevents/urn. Change the import path; nothing else changed. The move is spec 0014's OQ6 in go/messaging.

Licence

MIT. See LICENSE.

Documentation

Overview

Package urn carries the grammar of the estate's URN identifiers.

Two kinds exist, and both are written down here because a format agreed in conversation is not written down at all:

urn:phpboyscout:schema:orders.created:3
urn:phpboyscout:scope:continuity:01JQ8Z3F7K2M4N6P8R0T2V4W6X

A schema URN is what a CloudEvent's dataschema attribute carries, and what go/schema resolves. A scope URN is the estate's tenancy attribute.

This module depends on nothing but go/errors, so a consumer that only needs to read an identifier takes nothing else to do it. It is the one place the grammar is defined and the one place it is tested; go/schema cites it rather than restating it, because two copies with two test suites drift while both stay green.

Why a URN and not an HTTPS URL

A dataschema outlives the infrastructure that served it. Once a message carries one it is in logs and object stores for years, long after a registry has been renamed, moved or replaced, and every one of those historical messages would then point at a dead host. A URN separates identity from location, which is what the CloudEvents specification's own wording asks for. Resolution becomes configuration: embedded, cached, or over the network.

The cost is that it is not dereferenceable. Somebody outside the estate holding one of our messages cannot fetch the schema without knowing our resolver. That is acceptable for internal traffic and would not be if we published events externally.

Index

Examples

Constants

View Source
const (
	NamespaceSchema = "schema"
	NamespaceScope  = "scope"
)

The namespaces defined so far. A namespace is the third colon-separated part and says what kind of thing the rest of the identifier names.

View Source
const Prefix = "urn:" + estate

Prefix is what every identifier in this grammar starts with.

Parsing matches it case-insensitively, per RFC 8141 §3; rendering always produces this exact lower-case form, so Schema.String and Scope.String emit one canonical spelling.

Variables

View Source
var (
	// ErrNotAURN is returned when a string is not one of this estate's URNs at
	// all — a bare name, an HTTPS URL, or a URN in somebody else's namespace.
	//
	// Separate from the shape errors below because it is the case a caller most
	// often wants to handle rather than report: a dataschema that is a wiki link
	// today and a registry URN tomorrow is a migration, not a defect.
	ErrNotAURN = errors.NewSentinel("urn.not_a_urn",
		"urn: not a urn:phpboyscout identifier")

	// ErrMalformed is returned when a string is one of ours and its shape is
	// wrong: the wrong number of colon-separated parts, or an empty one.
	ErrMalformed = errors.NewSentinel("urn.malformed",
		"urn: identifier does not have the expected shape")

	// ErrInvalidName is returned when a schema name breaks the grammar.
	//
	// The grammar is narrow on purpose. A schema name appears in log lines, in
	// metric labels and in directory paths, and every character class allowed
	// here is one somebody downstream has to escape.
	ErrInvalidName = errors.NewSentinel("urn.invalid_name",
		"urn: schema name must be dot-separated lower-case segments")

	// ErrInvalidVersion is returned when a schema version is not a positive
	// integer written without a leading zero.
	//
	// Spec 0001 D9. An integer is unambiguous, orders trivially and claims
	// nothing; a semantic version would imply a compatibility promise nothing
	// checks, and a date encodes when rather than what.
	ErrInvalidVersion = errors.NewSentinel("urn.invalid_version",
		"urn: schema version must be a positive integer")

	// ErrInvalidKind is returned when a scope kind breaks the grammar.
	ErrInvalidKind = errors.NewSentinel("urn.invalid_kind",
		"urn: scope kind must be a lower-case identifier")

	// ErrInvalidID is returned when a scope identifier breaks the grammar.
	//
	// Scope identifiers must be opaque — an account name or a guild name in one
	// would put a person's chosen string into every header of every message,
	// where nothing redacts it. Spec 0001 D7.
	ErrInvalidID = errors.NewSentinel("urn.invalid_id",
		"urn: scope identifier must be an opaque token")
)

Parse failures, as sentinels so a caller can tell a malformed identifier from one that is well-formed but names something unknown.

Functions

This section is empty.

Types

type Schema

type Schema struct {
	Name    string
	Version int
}

Schema identifies one version of one schema.

urn:phpboyscout:schema:orders.created:3

The version is part of identity because the CloudEvents specification requires that an incompatible change to a schema gets a different URI. It carries no compatibility meaning beyond that — see go/schema spec 0001 D8 and D9: D9 settles the form, D8 the consequence.

func ParseSchema

func ParseSchema(s string) (Schema, error)

ParseSchema reads a schema URN.

It returns ErrNotAURN for anything outside this estate's namespace, which is the case a caller most often wants to distinguish: a dataschema pointing at a wiki page is not yet a registry URN, and that is a migration rather than a defect.

Example

ExampleParseSchema reads a dataschema URN. ErrNotAURN is separated from the shape errors because it is the one a caller handles rather than reports.

package main

import (
	"fmt"

	"gitlab.com/phpboyscout/go/errors"

	"gitlab.com/phpboyscout/go/urn"
)

func main() {
	s, err := urn.ParseSchema("urn:phpboyscout:schema:orders.created:3")
	if err != nil {
		fmt.Println("parse:", err)

		return
	}

	fmt.Println(s.Name, s.Version)

	_, err = urn.ParseSchema("https://example.com/schemas/orders.json")
	fmt.Println("a url is not one of ours:", errors.Is(err, urn.ErrNotAURN))

}
Output:
orders.created 3
a url is not one of ours: true

func (Schema) String

func (s Schema) String() string

String renders the identifier. It is the exact inverse of ParseSchema for any Schema that parsing produced.

type Scope

type Scope struct {
	Kind string
	ID   string
}

Scope identifies a tenancy boundary a message claims to belong to.

urn:phpboyscout:scope:continuity:01JQ8Z3F7K2M4N6P8R0T2V4W6X

The kind is explicit because there is no single boundary to name. In scoutdm, commerce is scoped by account, play by continuity, and reference content by neither. A single unqualified attribute would assert that every service has one boundary and that all of them mean the same thing by it.

A scope is ADVISORY, AND NEVER THE AUTHORITY. It is a claim in a message, for routing, filtering and legibility. Enforcement is NATS accounts with subject-scoped credentials, and a filter on this value has isolated nothing.

func ParseScope

func ParseScope(s string) (Scope, error)

ParseScope reads a scope URN.

Example

ExampleParseScope reads a tenancy claim. The kind is part of the identifier because there is no single boundary to name.

package main

import (
	"fmt"

	"gitlab.com/phpboyscout/go/urn"
)

func main() {
	s, err := urn.ParseScope("urn:phpboyscout:scope:continuity:01JQ8Z3F7K2M4N6P8R0T2V4W6X")
	if err != nil {
		fmt.Println("parse:", err)

		return
	}

	fmt.Println(s.Kind, s.ID)

}
Output:
continuity 01JQ8Z3F7K2M4N6P8R0T2V4W6X

func (Scope) String

func (s Scope) String() string

String renders the identifier. It is the exact inverse of ParseScope for any Scope that parsing produced.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL