URIs

An XDB URI identifies a namespace, schema, record, or attribute. It uses the xdb scheme and the syntax defined by RFC 3986. A record path identifies a tuple set; an attribute fragment (#attr) selects one tuple.

A URI is an immutable value type. Construct one with NewURI, ParseURI, or ParsePath.

Format

xdb://NS[/SCHEMA][/ID][#ATTRIBUTE]

xdb://com.example/posts/123-456-789#author.id
└─┬──┘└────┬────┘└──┬─┘└─────┬─────┘└─────┬─────┘
scheme     NS    SCHEMA      ID        ATTRIBUTE
           └───────────┬───────────┘
                     path

Component	Required	Description
Scheme	Yes	Always xdb://
NS	Yes	Namespace identifier
Schema	No	Schema name
ID	No	Record identifier
Attribute	No	Tuple attribute (fragment)

URI Levels

Each level of the URI identifies a different resource type:

# Namespace — groups schemas
xdb://com.example

# Schema — groups records
xdb://com.example/posts

# Record — a single entity
xdb://com.example/posts/123-456-789

# Attribute — a single value in a record
xdb://com.example/posts/123-456-789#title

The more components a URI has, the more specific the reference is. The Depth() method reports this specificity: 1 for a namespace, 2 for a schema, and 3 for a record. The attribute fragment does not change the depth.

URIs in the CLI

The URI is the noun of the CLI grammar. Resource commands use the form xdb <resource> <action> <URI> [flags]. The URI depth selects the resource. The action set is not the same for every resource:

• Records support get, list, create, update, upsert, and delete.

• Schemas support get, list, create, update, and delete.

• Namespaces support only list and get.

xdb watch <uri> is a top-level command, not a resource action. Run xdb describe --actions for the live matrix of actions and resources.

The shorthand commands xdb get, xdb ls, and xdb rm also select the resource from the URI depth. For example, xdb get xdb://com.example/posts/123 is the same as xdb records get xdb://com.example/posts/123.

Paths

A path is the URI without the xdb:// scheme:

com.example/posts/123-456-789

Paths are used internally for storage keys and as arguments to NewTuple and ParsePath.

// Parse a full URI (scheme required)
uri, err := core.ParseURI("xdb://com.example/posts/123")

// Parse a path (no scheme)
uri, err := core.ParsePath("com.example/posts/123")

Component Access

Accessors return plain strings. An absent component is the empty string.

uri.NS()         // string — namespace
uri.Schema()     // string — schema ("" for a namespace URI)
uri.ID()         // string — record ID ("" for a namespace or schema URI)
uri.Attr()       // string — attribute ("" if there is no fragment)
uri.Depth()      // int    — 1 (namespace), 2 (schema), or 3 (record)
uri.Path()       // string — path without the scheme
uri.String()     // string — full URI with the scheme
uri.SchemaURI()  // *URI   — URI with only NS + Schema
uri.RecordURI()  // *URI   — URI with NS + Schema + ID (attribute dropped)
uri.RecordPath() // string — the ns/schema/id record key (attribute dropped)

Constructing URIs

NewURI

NewURI(ns, parts...) builds a namespace, schema, or record URI from its parts. The first part is the schema and the second part is the ID. Both parts are optional:

nsURI, err := core.NewURI("com.example")                     // xdb://com.example
schemaURI, err := core.NewURI("com.example", "posts")        // xdb://com.example/posts
recordURI, err := core.NewURI("com.example", "posts", "123") // xdb://com.example/posts/123
uri := core.MustNewURI("com.example", "posts", "123")        // panics on invalid input

Parsing

uri, err := core.ParseURI("xdb://com.example/posts/123#title")
uri := core.MustParseURI("xdb://com.example/posts/123#title")

NS, Schema, and Attribute cannot contain /. An ID can contain /. Trailing path segments join into the ID. Every valid URI round-trips: ParseURI(u.String()) equals u.

Equality

URIs are comparable value types. == on the dereferenced pointers compares the components:

a := core.MustParseURI("xdb://com.example/posts/123")
b := core.MustParseURI("xdb://com.example/posts/123")
*a == *b // true

JSON Serialization

A URI serializes to JSON as a quoted string, and parses back from one:

"xdb://com.example/posts/123"

Related Concepts

• Namespaces: The NS component

• Schemas: The Schema component

• Records: The ID component

• Tuples: The Attribute fragment