2. URN Syntax
As discussed above, the syntax for URNs in this specification allows significantly more functionality than was the case in the earlier specifications, most recently [RFC2141]. It is also harmonized with the general URI syntax [RFC3986] (which, it must be noted, was completed after the earlier URN specifications).
However, this specification does not extend the URN syntax to allow direct use of characters outside the ASCII range [RFC20]. That restriction implies that any such characters need to be percent-encoded as described in Section 2.1 of the URI specification [RFC3986].
The basic syntax for a URN is defined using the Augmented Backus-Naur Form (ABNF) as specified in [RFC5234]. Rules not defined here (specifically: alphanum, fragment, and pchar) are defined as part of the URI syntax [RFC3986] and used here to point out the syntactic relationship with the terms used there. The definitions of some of the terms used below are not comprehensive; additional restrictions are imposed by the prose that can be found in sections of this document that are specific to those terms (especially r-component in Section 2.3.1 and q-component in Section 2.3.2).
namestring = assigned-name
[ rq-components ]
[ "#" f-component ]
assigned-name = "urn" ":" NID ":" NSS
NID = (alphanum) 0*30(ldh) (alphanum)
ldh = alphanum / "-"
NSS = pchar *(pchar / "/")
rq-components = [ "?+" r-component ]
[ "?=" q-component ]
r-component = pchar *( pchar / "/" / "?" )
q-component = pchar *( pchar / "/" / "?" )
f-component = fragment
The question mark character "?" can be used without percent-encoding inside r-components, q-components, and f-components. Other than inside those components, a "?" that is not immediately followed by "=" or "+" is not defined for URNs and SHOULD be treated as a syntax error by URN-specific parsers and other processors.
The following sections provide additional information about the syntactic elements of URNs.
2.1. Namespace Identifier (NID)
NIDs are case insensitive (e.g., "ISBN" and "isbn" are equivalent).
Characters outside the ASCII range [RFC20] are not permitted in NIDs, and no encoding mechanism for such characters is supported.
Sections 5.1 and 5.2 impose additional constraints on the strings that can be used as NIDs, i.e., the syntax shown above is not comprehensive.
2.2. Namespace Specific String (NSS)
The NSS is a string, unique within a URN namespace, that is assigned and managed in a consistent way and that conforms to the definition of the relevant URN namespace. The combination of the NID (unique across the entire "urn" scheme) and the NSS (unique within the URN namespace) ensures that the resulting URN is globally unique.
The NSS as specified in this document allows several characters not permitted by earlier specifications (see Appendix B). In particular, the "/" character, which is now allowed, effectively makes it possible to encapsulate hierarchical names from non-URN identifier systems. For instance, consider the hypothetical example of a hierarchical identifier system in which the names take the form of a sequence of numbers separated by the "/" character, such as "1/406/47452/2". If the authority for such names were to use URNs, it would be natural to place the existing name in the NSS, resulting in URNs such as "urn:example:1/406/47452/2".
Those changes to the syntax for the NSS do not modify the encoding rules for URN namespaces that were defined in accordance with [RFC2141]. If any such URN namespace whose names are used outside of the URN context (i.e., in a non-URN identifier system) also allows the use of "/", "~", or "&" in the native form within that identifier system, then the encoding rules for that URN namespace are not changed by this specification.
Depending on the rules governing a non-URN identifier system and its associated URN namespace, names that are valid in that identifier system might contain characters that are not allowed by the "pchar" production referenced above (e.g., characters outside the ASCII range or, consistent with the restrictions in RFC 3986, the characters "/", "?", "#", "[", and "]"). While such a name might be valid within the non-URN identifier system, it is not a valid URN until it has been translated into an NSS that conforms to the rules of that particular URN namespace. In the case of URNs that are formed from names that exist separately in a non-URN identifier system, translation of a name from its "native" format to a URN format is accomplished by using the canonicalization and encoding methods defined for URNs in general or specific rules for that URN namespace. Software that is not aware of namespace-specific canonicalization and encoding rules MUST NOT construct URNs from the name in the non-URN identifier system.
In particular, with regard to characters outside the ASCII range, URNs that appear in protocols or that are passed between systems MUST use only Unicode characters encoded in UTF-8 and further encoded as required by RFC 3986. To the extent feasible and consistent with the requirements of names defined and standardized elsewhere, as well as the principles discussed in Section 1.2, the characters used to represent names SHOULD be restricted to either ASCII letters and digits or to the characters and syntax of some widely used models such as those of Internationalizing Domain Names in Applications (IDNA) [RFC5890], Preparation, Enforcement, and Comparison of Internationalized Strings (PRECIS) [RFC7613], or the Unicode Identifier and Pattern Syntax specification [UAX31].
In order to make URNs as stable and persistent as possible when protocols evolve and the environment around them changes, URN namespaces SHOULD NOT allow characters outside the ASCII range [RFC20] unless the nature of the particular URN namespace makes such characters necessary.
2.3. Optional Components
This specification includes three optional components in the URN syntax. They are known as r-component, q-component, and f-component and are described in more detail below. Because this specification focuses almost exclusively on URN syntax, it does not define detailed semantics of these components for URNs in general. However, each of these components has a distinct role that is independent of any given URN and its URN namespace. It is intended that clients will be able to handle these components uniformly for all URNs. These components MAY be used with URNs from existing URN namespaces, whether or not a URN namespace explicitly supports them. However, consistent with the approach taken in RFC 3986, the behavior of a URN that contains components that are undefined or meaningless for a particular URN namespace or resource is not defined. The following sections describe these optional components and their interpretation in greater detail.
2.3.1. r-component
The r-component is intended for passing parameters to URN resolution services (taken broadly, see Section 1.2) and interpreted by those services. (By contrast, passing parameters to the resources identified by a URN, or to applications that manage such resources, is handled by q-components as described in the next section.)
The URN r-component has no syntactic counterpart in any other known URI scheme.
The sequence "?+" introduces the r-component. The r-component ends with a "?=" sequence (which begins a q-component) or a "#" character (number sign, which begins an f-component). If neither of those appear, the r-component continues to the end of the URN. Note that characters outside the ASCII range [RFC20] MUST be percent-encoded using the method defined in Section 2.1 of the generic URI specification [RFC3986].
As described in Section 3, the r-component SHALL NOT be taken into account when determining URN-equivalence. However, the r-component SHALL be supplied along with the URN when presenting a request to a URN resolution service.
This document defines only the syntax of the r-component and reserves it for future use. The exact semantics of the r-component and its use in URN resolution protocols are a matter for potential standardization in separate specifications, presumably including specifications that define conventions and a registry for resolution service identifiers.
Consider the hypothetical example of passing parameters to a resolution service (say, an ISO alpha-2 country code [ISO.3166-1] in order to select the preferred country in which to search for a physical copy of a book). This could perhaps be accomplished by specifying the country code in the r-component, resulting in URNs such as:
urn:example:foo-bar-baz-qux?+CCResolve:cc=uk
While the above should serve as a general explanation and illustration of the intent for r-components, there are many open issues with them, including their relationship to resolution mechanisms associated with the particular URN namespace at registration time. Thus, r-components SHOULD NOT be used for URNs before their semantics have been standardized.
2.3.2. q-component
The q-component is intended for passing parameters to either the named resource or a system that can supply the requested service, for interpretation by that resource or system. (By contrast, passing parameters to URN resolution services is handled by r-components as described in the previous section.)
The URN q-component has the same syntax as the URI query component but is introduced by "?=", not "?" alone. For a URN that may be resolved to a URI that is a locator, the semantics of the q-component are identical to those for the query component of that URI. Thus, URN resolvers returning a URI that is a locator for a URN with a q-component do this by copying the q-component from the URN to the query component of the URI. An example of the copying operation appears below.
This specification does not specify a required behavior in the case of URN resolution to a URI that is a locator when the original URN has a q-component and the URI has a query string. Different circumstances may require different approaches. Resolvers SHOULD document their strategy in such cases.
If the URN does not resolve to a URI that is a locator, the interpretation of the q-component is undefined by this specification. For URNs that may be resolved to a URI that is a locator, the semantics of the q-component are identical to those for queries to the resource located via that URI.
For the sake of consistency with RFC 3986, the general syntax and the semantics of q-components are not defined by, or dependent on, the URN namespace of the URN. In parallel with RFC 3986, specifics of syntax and semantics, e.g., which keywords or terms are meaningful, of course may depend on a particular URN namespace or even a particular resource.
The sequence "?=" introduces the q-component. The q-component ends with a "#" character (number sign, which begins an f-component). If that character does not appear, the q-component continues to the end of the URN. The characters slash ("/") and question mark ("?") may represent data within the q-component. Note that characters outside the ASCII range [RFC20] MUST be percent-encoded using the method defined in Section 2.1 of the generic URI specification [RFC3986].
As described in Section 3, the q-component SHALL NOT be taken into account when determining URN-equivalence.
URN namespaces and associated information placement in syntax SHOULD be designed to avoid any need for a resolution service to consider the q-component. Namespace-specific and more generic resolution systems MUST NOT require that q-component information be passed to them for processing.
Consider the hypothetical example of passing parameters to an application that returns weather reports from different regions or for different time periods. This could perhaps be accomplished by specifying latitude and longitude coordinates and datetimes in the URN's q-component, resulting in URNs such as the following.
urn:example:weather?=op=map&lat=39.56
&lon=-104.85&datetime=1969-07-21T02:56:15Z
If this example resolved to an HTTP URI, the result might look like:
https://weatherapp.example?op=map&lat=39.56
&lon=-104.85&datetime=1969-07-21T02:56:15Z
2.3.3. f-component
The f-component is intended to be interpreted by the client as a specification for a location within, or region of, the named resource. It distinguishes the constituent parts of a resource named by a URN. For a URN that resolves to one or more locators that can be dereferenced to a representation, or where the URN resolver directly returns a representation of the resource, the semantics of an f-component are defined by the media type of the representation.
The URN f-component has the same syntax as the URI fragment component. If a URN containing an f-component resolves to a single URI that is a locator associated with the named resource, the f-component from the URN can be applied (usually by the client) as the fragment of that URI. If the URN does not resolve to a URI that is a locator, the interpretation of the f-component is undefined by this specification. Thus, for URNs that may be resolved to a URI that is a locator, the semantics of f-components are identical to those of fragments for that resource.
For the sake of consistency with RFC 3986, neither the general syntax nor the semantics of f-components are defined by, or dependent on, the URN namespace of the URN. In parallel with RFC 3986, specifics of syntax and semantics, e.g., which keywords or terms are meaningful, of course may depend on a particular URN namespace or even a particular resource.
The f-component is introduced by the number sign ("#") character and terminated by the end of the URI. Any characters outside the ASCII range [RFC20] that appear in the f-component MUST be percent-encoded using the method defined in Section 2.1 of the generic URI specification [RFC3986].
As described in Section 3, the f-component SHALL NOT be taken into account when determining URN-equivalence.
Clients SHOULD NOT pass f-components to resolution services unless those services also perform object retrieval and interpretation functions.
Consider the hypothetical example of obtaining resources that are part of a larger entity (say, the chapters of a book). Each part could be specified in the f-component, resulting in URNs such as:
urn:example:foo-bar-baz-qux#somepart