Skip to content

Resource Identifier Spec (Core42 AI Cloud)

Status

Accepted baseline for MVP and forward-compatible expansion.

Purpose

Define one canonical, machine-readable resource identifier format that can be used consistently across: - API responses, - audit logs, - domain events, - policy evaluation inputs, - runbooks and incident tooling.

This avoids fragmented identifier formats and enables deterministic routing and authorization matching across services.

Canonical Format

core42:aicloud:{region}:{tenant_id}:{project_id}:{resource_type}:{resource_id}

Example: 

core42:aicloud:region-1:2babaf31-19cb-4af7-8065-e676f9e9f6d3:50ab9f5e-cf0c-4d5c-9f78-67dc91b0c8c0:gpuaas/allocation:3a1cae68-3ca7-41e5-99c9-e6d391e84bc5

Segment Semantics

  1. core42: organization namespace.
  2. aicloud: platform namespace.
  3. region: control-plane region code (region-1, us-east-1, etc.).
  4. tenant_id: ownership boundary (maps to organizations.id).
  5. project_id: resource scope boundary (maps to projects.id).
  6. resource_type: service-qualified type (gpuaas/allocation, gpuaas/node, storage/object, iam/service-account, etc.).
  7. resource_id: stable resource identifier in that type domain (typically UUID).

Grammar

resource_name  = namespace ":" platform ":" region ":" tenant ":" project ":" rtype ":" rid
namespace      = "core42"
platform       = "aicloud"
region         = 1*(ALPHA / DIGIT / "-" / "_")
tenant         = uuid
project        = uuid
rtype          = service "/" kind
service        = 1*(ALPHA / DIGIT / "-" / "_")
kind           = 1*(ALPHA / DIGIT / "-" / "_")
rid            = 1*(ALPHA / DIGIT / "-" / "_" / "." / "~" / "%")

Encoding Rules

  • resource_id must be ASCII-safe and deterministic.
  • If a native ID can contain reserved separators (: or /), encode before insertion (percent-encoding preferred for MVP).
  • Identifiers are case-sensitive except fixed namespace/platform constants.

Ownership Rules

  • For tenant-owned, project-scoped resources, tenant_id and project_id are always required.
  • Platform-scoped resources (rare) are out of this baseline and must use a dedicated documented pattern; do not overload this format with null segments.

Operational Rules

  • Resource names are immutable for the lifetime of a resource.
  • Resource names are external-facing references, not primary database keys.
  • Services should store native IDs and synthesize resource names at boundaries (API/event/audit), with optional caching.

Initial Resource Type Registry (MVP)

  • gpuaas/allocation
  • gpuaas/node
  • storage/object
  • iam/service-account
  • iam/service-account-credential

Policy Integration

Policy engines must receive both: - structured fields (tenant_id, project_id, resource_type, resource_id) - canonical resource_name

This enables exact-match and prefix/scope matching without re-deriving context.

Error Handling

  • Parsing failures return invalid_request with details indicating segment mismatch.
  • Unknown resource_type returns validation_error where endpoint requires registry-constrained values.

Adoption Plan

  1. Publish this spec and ADR.
  2. Add shared parser/formatter helper in code.
  3. Emit resource_name in core API responses and domain events.
  4. Include resource_name in audit logs and operational runbooks.