RAI Resolution

Overview

RAI resolution is the process of turning an identifier into actionable metadata. The resolver at rai.cifr.org.in accepts an RAI in the URL path and returns either a JSON descriptor or an HTML landing page, depending on what the client asks for.

This is the same content-negotiation pattern used by DOI (via doi.org) and by W3C standards (via their namespace URIs).

Resolution URL

https://rai.cifr.org.in/{prefix}/{suffix}

For example:

https://rai.cifr.org.in/18.cifr/2016.chanda.resiliency-pds

Content negotiation

The resolver inspects the Accept header to decide the response format:

Accept header	Response
application/json	RAI Descriptor (JSON)
text/html	Human-readable landing page
Both present	JSON takes precedence
No Accept header	JSON (default)

JSON resolution

curl -H "Accept: application/json" \
  https://rai.cifr.org.in/18.cifr/2016.chanda.resiliency-pds

Returns the full RAI Descriptor:

{
  "rai": "18.cifr/2016.chanda.resiliency-pds",
  "schema_version": "0.1",
  "identity": {
    "name": "resiliency-pds",
    "version": "2.0.0",
    "version_history": ["2.0.0", "1.0.0"],
    "created_at": "2026-04-10T..."
  },
  "agent": {
    "description": "Composite resiliency of a power distribution system...",
    "inputs": [{"name": "topology", "format": "application/json"}],
    "outputs": [{"name": "resiliency_index", "format": "application/json"}]
  },
  "paper": {
    "title": "Defining and Enabling Resiliency of Electric Distribution Systems...",
    "doi": "10.1109/TSG.2016.2561303",
    "year": 2016
  },
  "trust": {
    "tier": "silver",
    "image_digest": "sha256:abc123..."
  },
  "resolution": {
    "self": "https://rai.cifr.org.in/18.cifr/2016.chanda.resiliency-pds",
    "invoke": "https://api.cifr.org.in/api/agents/.../invoke",
    "landing_page": "https://cifr.org.in/agents/..."
  },
  "status": {
    "visibility": "public",
    "deprecated": false
  }
}

HTML resolution

curl -H "Accept: text/html" \
  https://rai.cifr.org.in/18.cifr/2016.chanda.resiliency-pds

Returns a self-contained HTML landing page showing the agent's identity, paper metadata, trust tier, interface contract, and action links.

Version pinning

Without a version parameter, the resolver returns the latest registered version (highest semver):

https://rai.cifr.org.in/18.cifr/2016.chanda.resiliency-pds
→ returns version 2.0.0 (latest)

With ?version=X.Y.Z, it returns that exact version:

https://rai.cifr.org.in/18.cifr/2016.chanda.resiliency-pds?version=1.0.0
→ returns version 1.0.0

This enables both "follow the latest" (for live composition) and "pin to a specific version" (for reproducibility).

Response codes

Code	Meaning
200 OK	Identifier resolved. Body contains descriptor or HTML.
302 Found	Redirect to canonical URL (e.g., legacy format → v2).
404 Not Found	No agent registered for this RAI, or version not found.
410 Gone	Agent was removed (abuse, DMCA). May include metadata with removal reason.

Response headers

Every resolution response includes:

Header	Example	Purpose
X-RAI-Schema-Version	0.1	Descriptor schema version
X-RAI-Agent-Version	2.0.0	Agent version returned
Link	<https://rai.cifr.org.in/18.cifr/...>; rel="canonical"	Canonical URL

Legacy format support

The older RAI-YYYY-author-slug format is still accepted. Legacy URLs are 302-redirected to their canonical v2 equivalents:

GET /RAI-2016-chanda-resiliency-pds
→ 302 Location: /18.cifr/2016.chanda.resiliency-pds

Resolver metadata

curl https://rai.cifr.org.in/.well-known/rai

{
  "schema_version": "0.1",
  "resolver": "cifr-rai-resolver",
  "supported_prefixes": ["18.cifr"]
}

The /.well-known/rai endpoint lets automated systems discover which prefixes a resolver handles. This is the foundation for federation — multiple resolvers, each handling their own prefixes.