Skip to content

spec: record optional multi-segment <namespace> in Appendix C (ADR-0007) #97

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
sachinsharma3191 wants to merge 1 commit into
base: main
Choose a base branch
from
+9 −9
Open

spec: record optional multi-segment <namespace> in Appendix C (ADR-0007) #97

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 7 additions & 7 deletions adr/0007-urn-naming-pattern-flexibility.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,32 +5,32 @@ Accepted

## Context
The Agentic Resource Discovery Naming Guide (`spec/urn-naming-guide.md`) and schema configurations enforce a domain-anchored URN namespace format:
`urn:ai:<publisher>:<namespace>:<agent-name>`
`urn:air:<publisher>:<namespace>:<agent-name>`

In the initial versions of the specification, the validation pattern for this URN format was defined as:
`^urn:ai:[a-zA-Z0-9.-]+:[a-zA-Z0-9.-:]+:[a-zA-Z0-9.-]+$`
`^urn:air:[a-zA-Z0-9.-]+:[a-zA-Z0-9.-:]+:[a-zA-Z0-9.-]+$`

However, feedback from developers and deployment testing revealed three major issues:
1. **Unsafe Character Range**: The bracket syntax `.-:` used inside character classes included an unsafe range (ASCII 46 to 58) which unintentionally matched illegal characters like `/` (ASCII 47) and was prone to pattern compilation errors in Python and standard regex parsers.
2. **Rigid Namespace Structure**: The pattern required exactly three segments after `urn:ai:`. This made it impossible to declare an agent with **no namespace at all** (e.g., `urn:ai:acme.com:assistant`) or with a **multi-segment hierarchy** (e.g., `urn:ai:acme.com:finance:trading:trader`).
3. **Lack of Underscore (`_`) Support**: Many developers and systems use underscores in naming agents or organizing sub-namespaces (e.g., `urn:ai:acme.com:finance:tax_agent`). Forcing standard hyphens created friction with legacy setups.
2. **Rigid Namespace Structure**: The pattern required exactly three segments after `urn:air:`. This made it impossible to declare an agent with **no namespace at all** (e.g., `urn:air:acme.com:assistant`) or with a **multi-segment hierarchy** (e.g., `urn:air:acme.com:finance:trading:trader`).
3. **Lack of Underscore (`_`) Support**: Many developers and systems use underscores in naming agents or organizing sub-namespaces (e.g., `urn:air:acme.com:finance:tax_agent`). Forcing standard hyphens created friction with legacy setups.

## Decision
We refined the URN pattern definition to be fully RFC 8141-compliant, highly flexible, and developer-friendly:

1. **Decoupled Namespace Segments**:
* The pattern was refactored to require a minimum of one publisher domain segment and one terminal agent name segment, allowing intermediate namespace segments to be optional and recursive:
`^urn:ai:[a-zA-Z0-9.-]+(:[a-zA-Z0-9._-]+)+$`
`^urn:air:[a-zA-Z0-9.-]+(:[a-zA-Z0-9._-]+)+$`
2. **Support Underscores (`_`) in Namespace and Agent Name**:
* Added underscore support to all non-domain segments.
3. **Strict FQDN Constraints for Publisher Domain**:
* Kept the `<publisher>` domain segment strictly constrained to `[a-zA-Z0-9.-]` (alphanumeric, dots, and hyphens). Under standard DNS rules (RFC 1123 / RFC 952), public FQDNs do not permit underscores. This maintains strict network-level DNS safety.
4. **Python Conformance Adjustment**:
* Updated the official python conformance checking tool `conformance-test` regex class to safely handle the python regex compiler character ranges (moving the literal dash `-` to the end of character classes):
`r"^urn:ai:([a-zA-Z0-9.-]+)(?::([a-zA-Z0-9._:-]+))?:([a-zA-Z0-9._-]+)$"`
`r"^urn:air:([a-zA-Z0-9.-]+)(?::([a-zA-Z0-9._:-]+))?:([a-zA-Z0-9._-]+)$"`

## Consequences
* **Ergonomics**: Developers can use natural naming styles containing underscores (e.g., `travel_concierge`).
* **Flexibility**: The specification supports URN namespaces of any hierarchical depth (e.g., `urn:ai:acme.com:department:team:service:agent`) or simple non-namespaced entries (e.g., `urn:ai:acme.com:agent`).
* **Flexibility**: The specification supports URN namespaces of any hierarchical depth (e.g., `urn:air:acme.com:department:team:service:agent`) or simple non-namespaced entries (e.g., `urn:air:acme.com:agent`).
* **Security**: Ensures that URN `<publisher>` segments match legitimate resolved domains, preserving the decentralized zero-trust mesh and domain authority matching invariants.
* **Compliance**: Maintains strict compliance with standard URN rules defined in IETF RFC 8141.
4 changes: 2 additions & 2 deletions spec/ard.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -87,7 +87,7 @@ The default namespace supplies definitions for the terms below; ARD determines w

| Term | Requirement | Notes |
| :--- | :--- | :--- |
| identifier | MUST | Globally unique discovery handle. Domain-anchored URN form (`urn:air:<publisher>:<namespace>:<agent-name>`); see Appendix C. The JSON-LD `@id` MAY mirror it. |
| identifier | MUST | Globally unique discovery handle. Domain-anchored URN form (`urn:air:<publisher>:[<namespace>:]<agent-name>`, where `<namespace>` is optional and MAY span several segments); see Appendix C. The JSON-LD `@id` MAY mirror it. |
| displayName | MUST | Human-readable name. |
| type | MUST | Artifact type as an IANA Media Type (§3.3). |
| url _or_ data | MUST (exactly one) | Value-or-reference (§4.3). |
Expand Down Expand Up @@ -505,7 +505,7 @@ Logical AND is used across different parameters; OR is used within a single para

## Appendix C: Agent Naming URN Format {#appendix-c:-agent-naming-urn-format}

The discovery identifier uses a domain-anchored URN form, `urn:air:<publisher>:<namespace>:<agent-name>`, where `<publisher>` is a fully qualified domain name. Restricting the discovery identifier to this form, rather than allowing arbitrary URIs, provides fundamental architectural benefits for federated discovery:
The discovery identifier uses a domain-anchored URN form, `urn:air:<publisher>:[<namespace>:]<agent-name>`, where `<publisher>` is a fully qualified domain name. `<namespace>` is optional and MAY contain more than one colon-separated segment, so `urn:air:example.com:weather-server` and `urn:air:example.com:finance:trading:trader` are both valid; only `<publisher>` and the terminal `<agent-name>` are required (ADR-0007). Restricting the discovery identifier to this form, rather than allowing arbitrary URIs, provides fundamental architectural benefits for federated discovery:

1. **Nomenclature Stability (Immutable Noun vs. Mutable Location)**: Arbitrary URIs, particularly HTTP URLs, conflate the logical identity of a capability with its physical network location. The `urn:air:` identifier acts as an abstract, permanent contract; physical distribution and transport bindings are decoupled into the `url` or `data` term, allowing infrastructure to evolve without breaking client discovery, indexing, or orchestration code.
2. **Strict Separation of Concerns**: Federated registries require a stable primary key to index capabilities; zero-trust runtimes require dynamic cryptographic tokens (SPIFFE IDs, DIDs, X.509 certificates) to authenticate workloads. The `urn:air:` form cleanly decouples the searchable discovery handle from the security principal, allowing the discovery index and the security mesh to operate independently.
Expand Down