CRI Format

Overview

A CRI (Kinotic Resource Identifier) is used by Kinotic to route requests to the appropriate service, method, or event stream. It is a URI-like format with parts named for clarity within the Kinotic platform.

Format

scheme://[scope@][zone~]resourceName[/path][#version]

Everything in brackets ([]) is optional.

Case

Every part keeps the case it was written with, and addresses match by exact string comparison — OrderService and OrderService are two different addresses. Service names carry the case of the class that published them, so a typical address looks like:

srv://management-api~org.kinotic.management.api.services.ProjectService/findByRepoFullName

Components

Scheme

Identifies the type of resource being addressed.

Scope

An optional qualifier that narrows the CRI to a specific context, such as a tenant ID, user ID, or device ID. When present, it appears before the @ symbol.

If a scope needs sub-scopes, use the format scope:sub-scope.

srv://tenant-123@app.acme-org.orders-app~OrderService
stream://device-42@app.acme-org.orders-app~temperature/sensor-1

Zone

The optional zone places the resource in the isolation boundary the gateway validates on every send and subscribe. It precedes the resourceName, separated by ~. A zone is one or more dot-separated labels of lowercase letters, digits, and interior dashes.

Organization and application ids become zone labels, but only ever after the app prefix, so they cannot collide with the platform's own zones. The one exception is guarded explicitly: creating an organization or application whose name slugifies to system-api is rejected.

Which zones a connection may address is determined by the authenticated participant. A participant may also address any sub-zone of a zone it is allowed, so app.acme-org.orders-app.billing is reachable by whoever may reach app.acme-org.orders-app. An address without a ~ carries no zone at all and is only reachable by system participants.

Resource Name

The name of the resource being addressed, excluding the zone. For services, this is the fully qualified service name. For streams, this is the event type name.

srv://management-api~com.example.UserService
stream://app.acme-org.orders-app~temperature

Path

An optional path that identifies a specific part of the resource, such as a method name on a service. The path's case is preserved.

srv://management-api~com.example.UserService/findById
stream://app.acme-org.orders-app~temperature/sensor-1

Version

An optional semantic version for the resource. Enables versioned service routing so multiple versions of a service can coexist.

srv://management-api~com.example.UserService/findById#1.0.0
srv://management-api~com.example.UserService#2.0.0

Factory Function

The createCRI function provides several overloads for constructing CRI instances:

import { createCRI } from '@kinotic-ai/core'

// From a raw string
const cri1 = createCRI('srv://management-api~com.example.UserService/findById#1.0.0')

// From scheme and resource name (which may carry a zone)
const cri2 = createCRI('srv', 'management-api~com.example.UserService')

// From scheme, scope, and resource name
const cri3 = createCRI('stream', 'tenant-123', 'app.acme-org.orders-app~orders')

// From all components
const cri4 = createCRI('srv', null, 'management-api~com.example.UserService', 'findById', '1.0.0')

CRI Interface

The CRI interface provides methods to access each component:

const cri = createCRI('srv://tenant-123@app.acme-org.orders-app~OrderService/placeOrder#2.0.0')

cri.scheme()        // 'srv'
cri.scope()         // 'tenant-123'
cri.hasScope()      // true
cri.zone()          // 'app.acme-org.orders-app'
cri.hasZone()       // true
cri.resourceName()  // 'OrderService'
cri.path()          // 'placeOrder'
cri.hasPath()       // true
cri.version()       // '2.0.0'
cri.hasVersion()    // true
cri.baseResource()  // 'srv://tenant-123@app.acme-org.orders-app~OrderService'
cri.raw()           // 'srv://tenant-123@app.acme-org.orders-app~OrderService/placeOrder#2.0.0'

Examples