Enola Resource Identifier URIs (ERIs)

Warning

This page needs some updates to fully match the current code.

Introduction

Enola’s CLI (and Web UI) accept an argument which uniquely identifies the Entity to GET, LIST or otherwise act upon.

This is a Uniform Resource Identifier (URI), conceptually somewhat similar to the URL address of this documentation site in your web browser.

Enola originally referred to this concept as an ID, and some of this documentation (and code) currently still does. The intention is to gradually completely remove the ID terminology and exclusively use Enola Entity URI; this page documents both what of this is currently available, and what is planned for the future.

Available

An Enola URI was originally defined as an enola:{ns}.{entity}/path1/path2/... ID; for example: enola:demo.foo/abc/def. The namespace (NS) and entity define the “kind” (type) of the entity and the paths an instance of it. This is further defined in the Proto API doc.

This original {ns}.{entity}/paths... syntax has meanwhile been loosened to permit any unique string.

The enola: URI scheme prefix is often omitted when an URI is not in the full normal form described on this page. Within Enola, the Enola CLI and Web UI accept it, but do not require it; so demo.foo/abc/def is valid, and fully equivalent. (This URI scheme is not currently registered with the IANA.)

Both the enola.dev and enola namespaces are reserved for internal use by models built-in to this project, e.g. enola.entity_kind and enola.schema, and should not be used in user models.

Enola alternatively also accepts a Uniform Resource Name syntax; e.g. urn:enola:demo.foo/abc/def.

Other schemes than enola: or urn:enola are assumed to point to a Resource, and attempted to be fetched and converted to a Thing.

The ?query and #fragment of an URI are not supported, and will be rejected.

The Java classes dev.enola.core.ERI and dev.enola.core.IDs implement this logic, but they are an Enola internal implementation detail, not an API intended for users.

TODO Planned Future Extensions

Some commands accept a --server argument. The plan is to optionally allow to include that server endpoint in this URI, as it’s “authority” component. Endpoints will not be limited to traditional IP address and DNS hostname resolution, only, but could include other protocols to connect to another Enola server, for federation.

Internationalization

The project envisions to eventually fully support Internationalized Resource Identifiers (IRIs), instead of only ASCII URI syntax; more testing to identify and fix any related gaps is required.