From 54b09bdec32ddd0f1cce87af6123ae5988de69cd Mon Sep 17 00:00:00 2001 From: sachinsharma3191 Date: Wed, 23 Sep 2026 09:45:27 -0700 Subject: [PATCH] spec: record optional multi-segment in Appendix C (ADR-0007) Appendix C and the term table gave a three-part URN, contradicting ADR-0007 and the spec's own example (urn:air:example.com:weather-server). Also refresh ADR-0007's stale urn:ai: examples to urn:air: (ADR-0009). --- adr/0007-urn-naming-pattern-flexibility.md | 14 +++++++------- spec/ard.md | 4 ++-- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/adr/0007-urn-naming-pattern-flexibility.md b/adr/0007-urn-naming-pattern-flexibility.md index 5f1f853..7516d20 100644 --- a/adr/0007-urn-naming-pattern-flexibility.md +++ b/adr/0007-urn-naming-pattern-flexibility.md @@ -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:::` +`urn:air:::` 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 `` 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 `` 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. diff --git a/spec/ard.md b/spec/ard.md index 29aa39c..030a71d 100644 --- a/spec/ard.md +++ b/spec/ard.md @@ -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:::`); see Appendix C. The JSON-LD `@id` MAY mirror it. | +| identifier | MUST | Globally unique discovery handle. Domain-anchored URN form (`urn:air::[:]`, where `` 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). | @@ -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:::`, where `` 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::[:]`, where `` is a fully qualified domain name. `` 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 `` and the terminal `` 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.