A Uniform Resource Name (URN) Namespace for Examples
Cisco Systems, Inc.
1899 Wynkoop Street, Suite 600
Denver
CO
80202
USA
psaintan@cisco.com
APP
Internet-Draft
URN
examples
documentation
This document defines a Uniform Resource Name (URN) namespace identifier enabling generation of URNs that are appropriate for use in documentation and in URN-related testing and experimentation.
The Uniform Resource Name (URN) technology provides a way to generate persistent, location-independent, resource identifiers. The primary "scope" of a URN is provided by its namespace identifier (NID). As specified in , there are three kinds of NID: formal, informal, and experimental. Most of the NIDs registered to date are formal: as far as is known the few informal namespaces have not been widely used, and the experimental namespaces are by definition unregistered.
The experimental namespaces take the form "X-NID" (where "NID" is the desired namespace identifier). Because the "x-" convention has been deprecated in general , it seems sensible to achieve the same objective in a different way. Therefore this document registers a formal namespace identifier of "example", similar to "example.com" and other domain names . Under the "example" NID, specification authors and code developers can mint URNs for use in documentation and in URN-related testing and experimentation by assigning their own unique namespace-specific strings, without fear of conflicts with current or future actual URNs. Such URNs are intended for use as examples in documentation, testing of code for URN and URI processing, URN-related experimentation, invalid URNs, and other similar uses. They are not intended for testing non-URI code or for building higher-level applications for use over the Internet or private networks (e.g., as XML namespace names), since it relatively easy to mint URIs whose authority component is a domain name controlled by the person or organization that wishes to engage in such testing and experimentation.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in .
The Namespace ID "example" is requested.
Version 1
Date: [to be assigned]
Registering organization: IETF
Designated contact: IESG, iesg@ietf.org
URNs that use the "example" NID shall have the following structure:
urn:example:{NSS}
The Namespace Specific String (NSS) is a mandatory string of ASCII characters that conforms to the URN syntax requirements and that provides a name that is useful within the relevant documentation example, test suite, or other application.
See for information about deprecation of the "x-" convention in protocol parameters and identifiers.
Those who mint example URNs ought to strive for uniqueness in the namespace specific string portion of the URN. However, such uniqueness cannot be guaranteed through the assignment process. Therefore it is NOT RECOMMENDED for implementers to use example URNs for any purposes other than documentation, private testing, and truly experimental contexts.
Once minted, an example URN is immutable. However, it is simply a string and there is no guarantee that the documentation, test suite, or other application using the URN is immutable.
Assignment is completely open, since anyone can mint example URNs for use in documentation, private testing, and other experimental contexts.
Example URNs are not intended to be resolved, and the namespace will probably never be registered with a Resolution Discovery System (unless to simply inform requesters that such URNs are merely examples).
No special considerations; the rules for lexical equivalence specified in apply.
No special considerations
The scope of an example URN is limited to the documentation in which it is found, the test in which it is used, the experiment in which it appears, etc. Example URNs have no meaning outside such strictly-limited contexts.
No existing formal namespace enables entities to generate URNs that are appropriate for use as examples in documentation and in URN-related testing and experimentation. It could be argued that no such formal namespace is needed, given that experimental namespaces can be minted at will. However, experimental namespaces run afoul of the trend away from using the "x-" convention in the names of protocol parameters and identifiers . Additionally, in practice specification authors often mint examples using fake NIDs that go unregistered because they are never intended to be used. To minimize the possibility of confusion, use of this dedicated example namespace is recommended for generating example URNs.
The "example" NID is intended to provide a clean, easily-recognizable space for minting examples to be used in documentation and in URN-related testing and experimentation. The Namespace Specific String (NSS) is best as a unique string, generated by the person, organization, or other entity that creates the documentation, test suite, or other application. There is no issuing authority for example URNs and it is not intended that they can be resolved in any meaningful way.
The "example" NID does not obviate the need to coordinate with issuing authorities for existing namespaces (e.g., minting "urn:example:xmpp:foo" instead of requesting issuance of "urn:xmpp:foo"), to register new namespace identifiers if existing namespaces do not match one's desired functionality (e.g., minting "urn:example:sha-1:29ead03e784b2f636a23ffff95ed12b56e2f2637" instead of registering the "sha-1" NID), or to respect the basic spirit of URN NID assignment (e.g., setting up shadow NIDs such as "urn:example:MyCompany:*" instead of using, say, HTTP URIs).
This document introduces no additional security considerations beyond those associated with the use and resolution of URNs in general.
This document defines a URN NID registration of "example", to be added to the Uniform Resource Names (URN) Formal Namespaces registry. The completed registration template can be found in under .
ASCII format for network interchange
University California Los Angeles (UCLA)
For concreteness, we suggest the use of standard 7-bit ASCII embedded in an 8 bit byte whose high order bit is always 0.
Key words for use in RFCs to Indicate Requirement Levels
Harvard University
1350 Mass. Ave.
Cambridge
MA 02138
- +1 617 495 3864
sob@harvard.edu
General
keyword
In many standards track documents several words are used to signify
the requirements in the specification. These words are often
capitalized. This document defines these words as they should be
interpreted in IETF documents. Authors who follow these guidelines
should incorporate this phrase near the beginning of their document:
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in
RFC 2119.
Note that the force of these words is modified by the requirement
level of the document in which they are used.
URN Syntax
AT&T
15621 Drexel Circle
Omaha
NE 68135-2358
USA
+1 402 894-9456
jayhawk@ds.internic.net
Applications
URN
uniform resource
Uniform Resource Names (URNs) are intended to serve as persistent,
location-independent, resource identifiers. This document sets
forward the canonical syntax for URNs. A discussion of both existing
legacy and new namespaces and requirements for URN presentation and
transmission are presented. Finally, there is a discussion of URN
equivalence and how to determine it.
Uniform Resource Names (URN) Namespace Definition Mechanisms
<p>This document lays out general definitions of and mechanisms for establishing Uniform Resource Names (URN) "namespaces". The URN WG has defined a syntax for URNs in RFC 2141, as well as some proposed mechanisms for their resolution and use in Internet applications in RFC 3401 and RFC 3405. The whole rests on the concept of individual "namespaces" within the URN structure. Apart from proof-of-concept namespaces, the use of existing identifiers in URNs has been discussed in RFC 2288. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. </p>
Reserved Top Level DNS Names
IBM
65 Shindegan Hill Road
RR #1
Carmel
NY
10512
US
+1 914 276 1668
+1 914 784 3833
dee3@us.ibm.com
500 Stamford Dr. No. 310
Newark
DE
19711
US
+1 302 738 1554
buglady@fuschia.net
To reduce the likelihood of conflict and confusion, a few top level domain names are reserved for use in private testing, as examples in documentation, and the like. In addition, a few second level domain names reserved for use as examples are documented.
Deprecating the "X-" Prefix and Similar Constructs in Application Protocols
Historically, designers and implementers of application protocols have often distinguished between standardized and unstandardized parameters by prefixing the names of unstandardized parameters with the string "X-" or similar constructs. In practice, that convention causes more problems than it solves. Therefore, this document deprecates the convention for newly defined parameters with textual (as opposed to numerical) names in application protocols. This memo documents an Internet Best Current Practice.
Thanks to Martin Duerst, Barry Leiba, and Jim Schaad for their feedback, to Christer Holmberg for his Gen-ART review, and to Benoit Claise, Adrian Farrel, and Stephen Farrell for their helpful input during IESG review. Julian Reschke inspired the work on this document, provided valuable suggestions, and shepherded the document.