URI Scheme: ajson://

Standardized method for uniquely identifying and referencing JSON Agents manifests

Purpose

The ajson:// URI scheme provides a standardized method for uniquely identifying and referencing agent manifests, capabilities, and other JSON Agents resources.

Syntax

ajson-uri = "ajson://" authority path [ "?" query ] [ "#" fragment ]

authority = [ userinfo "@" ] host [ ":" port ]
path      = "/" segment *( "/" segment )
segment   = *pchar

Examples

ajson://jsonagents.org/examples/router-hub
ajson://example.com/agents/summarizer/v2.1.0
ajson://registry.internal/capabilities/routing
ajson://localhost:8080/test/agent#metadata

Identifier Construction

Authority Component

The authority SHOULD represent:

  • DNS domain under publisher's control
  • Well-known registry service
  • localhost for development

Path Component

The path MUST:

  • Begin with forward slash (/)
  • Uniquely identify the resource
  • Use URL-safe characters

MAY include:

  • Organizational hierarchy
  • Version information
  • Resource type indicators

Fragment Component

The fragment MAY reference:

  • Specific manifest sections
  • Individual capabilities
  • Graph nodes
#runtime
#capability/summarization
#node/router

Resolution Mechanism

Implementations SHOULD resolve ajson:// URIs through one of the following methods:

1. HTTPS Transformation (Recommended)

Transform ajson:// to well-known HTTPS path:
ajson://example.com/agents/router
becomes
https://example.com/.well-known/agents/router.agents.json

2. Direct Registry Lookup

Query a configured registry service using the full URI as an identifier.

3. Local Cache

Check local manifest cache before attempting network resolution.

Resolution Algorithm

function resolve(ajsonURI):
  1. Parse URI into components (authority, path, fragment)
  2. Check local cache for authority + path
  3. If cached and not expired, return cached manifest
  4. Transform to HTTPS well-known URI
  5. Perform HTTP GET with Accept: application/agents+json
  6. Validate response against json-agents.json schema
  7. Cache response if valid
  8. If fragment present, extract referenced component
  9. Return resolved manifest or component

Error Handling

ConditionBehavior
Network unavailableUse cached version if available, otherwise fail
404 Not FoundReturn resolution error with original URI
Invalid manifestReturn validation error with details
TimeoutRetry with exponential backoff, max 3 attempts

Registry Service

A conformant registry service MUST:

  • Accept ajson:// URIs as identifiers
  • Store and serve valid JSON Agents manifests
  • Implement versioning for manifest updates
  • Provide discovery endpoints for browsing
  • Support content negotiation (JSON/YAML)

Example Registry API

GET /resolve?uri=ajson://example.com/agents/router
Accept: application/agents+json

Response:
200 OK
Content-Type: application/agents+json
{
  "manifest_version": "1.0",
  ...
}

Versioning and Immutability

URIs MAY encode version information:

Immutable
ajson://example.com/agent/v1.2.3
Exact version
Mutable
ajson://example.com/agent
Latest version
Major
ajson://example.com/agent/v1
Latest v1.x.x

Recommendation: For production deployments, manifests SHOULD reference immutable versioned URIs to ensure reproducibility.

Security Considerations

Transport Security

  • All resolution MUST use TLS 1.2+
  • Certificate validation MUST be performed
  • HTTPS redirects MUST NOT downgrade to HTTP

Manifest Integrity

  • Verify manifest signatures if present
  • Validate Content-Type header
  • Reject manifests with invalid schemas
  • Implement Content Security Policy

URI Validation

  • Validate URI syntax before resolution
  • Reject URIs with embedded credentials
  • Sanitize path components
  • Implement rate limiting

Cache Poisoning Prevention

  • Use cryptographic hashes for cache keys
  • Validate cache-control headers
  • Provide cache invalidation mechanisms
  • Log resolution attempts for audits

IANA Considerations

The ajson:// URI scheme is intended for registration with IANA under the Uniform Resource Identifier (URI) Schemes registry.

Scheme Name:ajson
Status:Provisional
Applications/Protocols:JSON Agents Portable Agent Manifest
Contact:JSON Agents Working Group
Change Controller:JSON Agents Steering Committee

Learn More

Read the complete URI scheme specification in Section 16

View Full Specification

Related Resources

Continue exploring JSON AGENTS

Full Specification

Complete normative specification including URI scheme definition, resolution algorithm, and IANA registration

Implementer's Guide

Learn how to implement ajson:// URI resolution, caching, and registry integration in your runtime

Getting Started

Quick introduction to JSON Agents with examples using ajson:// URIs for agent identification

Schema Reference

Browse the JSON Schema definitions showing how URIs are used in agent manifests and capabilities