Example URNs: A Uniform Resource Name (URN) Namespace for Examples
A reserved 'example' prefix so documents and tests can use URNs that will never collide with real ones.
Saint-Andre, P., "A Uniform Resource Name (URN) Namespace for Examples", BCP 183, RFC 6963, DOI 10.17487/RFC6963, May 2013, <https://www.rfc-editor.org/info/rfc6963>.
@misc{rfc6963,
series = {Request for Comments},
number = 6963,
howpublished = {RFC 6963},
publisher = {RFC Editor},
doi = {10.17487/RFC6963},
url = {https://www.rfc-editor.org/info/rfc6963},
author = {P. Saint-Andre},
title = {{A Uniform Resource Name (URN) Namespace for Examples}},
pagetotal = 7,
year = 2013,
month = may,
} RFC text
Contents
Internet Engineering Task Force (IETF) P. Saint-Andre
Request for Comments: 6963 Cisco Systems, Inc.
BCP: 183 May 2013
Category: Best Current Practice
ISSN: 2070-1721
A Uniform Resource Name (URN) Namespace for Examples
Abstract
This document defines a Uniform Resource Name (URN) namespace
identifier enabling the generation of URNs that are appropriate for
use in documentation and in URN-related testing and experimentation.
Status of This Memo
This memo documents an Internet Best Current Practice.
This document is a product of the Internet Engineering Task Force
(IETF). It represents the consensus of the IETF community. It has
received public review and has been approved for publication by the
Internet Engineering Steering Group (IESG). Further information on
BCPs is available in Section 2 of RFC 5741.
Information about the current status of this document, any errata,
and how to provide feedback on it may be obtained at
http://www.rfc-editor.org/info/rfc6963.
Copyright Notice
Copyright (c) 2013 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Table of Contents
1. Introduction ....................................................2
2. Terminology .....................................................2
3. Completed Namespace Definition Template .........................3
4. Namespace Considerations ........................................4
5. Community Considerations ........................................5
6. Security Considerations .........................................5
7. IANA Considerations .............................................5
8. References ......................................................6
Appendix A. Acknowledgements .......................................7
1. Introduction
The Uniform Resource Name (URN) technology [RFC2141] 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 [RFC3406], there are three kinds of NIDs:
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 [RFC6648], 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 [RFC2606]. 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 is
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.
2. Terminology
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
[RFC2119].
3. Completed Namespace Definition Template
3.1. Namespace ID
The Namespace ID "example" has been assigned.
3.2. Registration Information
Version 1
Date: 2013-04-24
3.3. Declared Registrant of the Namespace
Registering organization: IETF
Designated contact: IESG, iesg@ietf.org
3.4. Declaration of Syntactic Structure
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 [RFC20] that conforms to the URN syntax requirements
[RFC2141] and provides a name that is useful within the relevant
documentation example, test suite, or other application.
3.5. Relevant Ancillary Documentation
See [RFC6648] for information about deprecation of the "X-"
convention in protocol parameters and identifiers.
3.6. Identifier Uniqueness Considerations
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.
3.7. Identifier Persistence Considerations
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.
3.8. Process of Identifier Assignment
Assignment is completely open, since anyone can mint example URNs for
use in documentation, private testing, and other experimental
contexts.
3.9. Process for Identifier Resolution
Example URNs are not intended to be resolved, and the namespace will
probably never be registered with a Resolution Discovery System
(except to simply inform requesters that such URNs are merely
examples).
3.10. Rules for Lexical Equivalence
No special considerations; the rules for lexical equivalence
specified in [RFC2141] apply.
3.11. Conformance with URN Syntax
No special considerations
3.12. Validation Mechanism
None
3.13. Scope
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.
4. Namespace Considerations
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 [RFC6648]. 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.
5. Community Considerations
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 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).
6. Security Considerations
This document introduces no additional security considerations beyond
those associated with the use and resolution of URNs in general.
7. IANA Considerations
This document defines a URN NID registration of "example", which IANA
has added to the "Formal URN Namespaces" registry. The completed
registration template can be found in Section 3.
8. References
8.1. Normative References
[RFC20] Cerf, V., "ASCII format for network interchange", RFC 20,
October 1969.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2141] Moats, R., "URN Syntax", RFC 2141, May 1997.
[RFC3406] Daigle, L., van Gulik, D., Iannella, R., and P. Faltstrom,
"Uniform Resource Names (URN) Namespace Definition
Mechanisms", BCP 66, RFC 3406, October 2002.
8.2. Informative References
[RFC2606] Eastlake, D. and A. Panitz, "Reserved Top Level DNS
Names", BCP 32, RFC 2606, June 1999.
[RFC6648] Saint-Andre, P., Crocker, D., and M. Nottingham,
"Deprecating the "X-" Prefix and Similar Constructs in
Application Protocols", BCP 178, RFC 6648, June 2012.
Appendix A. Acknowledgements
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.
Author's Address
Peter Saint-Andre
Cisco Systems, Inc.
1899 Wynkoop Street, Suite 600
Denver, CO 80202
USA
EMail: psaintan@cisco.com
ISO Plain Language
On this page
§1Why an Example Namespace
The Uniform Resource Name (URN) technology provides a way to generate persistent, location-independent resource identifiers. The scope of a URN comes from its namespace identifier, the short code that appears after urn:. As specified in RFC 3406, there are three kinds of namespace identifier: formal, informal and experimental. Most of the identifiers registered to date are formal.
The experimental kind takes the form X-NID. Because the X- convention has been deprecated in general, this document takes a different route and registers a formal namespace identifier of example, similar to example.com and other reserved domain names.
Under this namespace, specification authors and code developers can mint URNs for documentation, for testing of URN and URI processing, and for URN-related experimentation, by assigning their own unique namespace specific strings, without fear of conflicts with current or future actual URNs.
This RFC sets aside one word, 'example', for names that only appear in documents and tests. A sample name can then look like a real URN without ever being one, and no registration is needed to use it.
- URN namespace identifiers three kinds, per RFC 3406
- formal most registered identifiers
- example registered by this RFC
- informal not widely used
- experimental X-NID, unregistered
- formal most registered identifiers
§2Requirement Words
The document states that the key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, NOT RECOMMENDED, MAY and OPTIONAL are to be interpreted as described in RFC 2119. Those capitalised words set how strongly each rule in the document applies.
The document uses the standard capitalised words for rules, such as MUST and SHOULD, so a reader can tell which parts are mandatory and which are advice.
§3The Namespace Definition Template
The namespace identifier example is assigned, with registration information of version 1, dated 2013-04-24, and the IETF as the registering organisation, with the IESG as designated contact.
The declared syntactic structure is urn:example:{NSS}. The namespace specific string, abbreviated NSS, is a mandatory string of ASCII characters that conforms to the URN syntax requirements and provides a name that is useful within the relevant documentation example, test suite or other application.
The template settles the remaining questions. Those who mint example URNs ought to strive for uniqueness in the NSS, but such uniqueness cannot be guaranteed through the assignment process, so it is NOT RECOMMENDED to use example URNs for any purpose other than documentation, private testing and truly experimental contexts. Once minted, an example URN is immutable, although the document or test suite that uses it need not be. Assignment is completely open, since anyone can mint example URNs. Example URNs are not intended to be resolved, and the namespace will probably never be registered with a Resolution Discovery System, except to inform requesters that the URNs are merely examples. The rules for lexical equivalence specified in RFC 2141 apply, there is no validation mechanism, and the scope of an example URN is limited to the documentation, test or experiment in which it is found.
The name always has the same shape: urn:example: followed by a string the author invents. You are asked to make that string unique, but nothing checks it, so these names stay inside the document or test that uses them and are never resolved.
urn:example:{NSS}
urn:example:xmpp:foo
urn:example:sha-1:29ead03e784b2f636a23ffff95ed12b56e2f2637
urn:example:MyCompany:*§4Why a Formal Namespace Was Needed
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.
In practice, specification authors often mint examples using fake namespace identifiers that go unregistered because they were never intended to be used. To minimise the possibility of confusion, use of this dedicated example namespace is recommended for generating example URNs.
Authors used to write fake namespace codes such as X-whatever, but that convention has been retired. Giving one reserved word to examples removes the guesswork and keeps sample names from being mistaken for real ones.
- DocumentationSample names in specifications, manuals and articles.
- TestingTest suites for code that handles URNs and URIs.
- ExperimentationTrying out URN-related ideas without registering anything.
- Never resolvedExample URNs are not meant to be looked up, and the namespace will probably never be registered with a resolver.
§5How Example URNs Are Minted
The example namespace identifier is intended to provide a clean, easily recognisable space for minting examples to be used in documentation and in URN-related testing and experimentation. The NSS is best as a unique string, generated by the person, organisation 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 namespace does not remove the need to coordinate with issuing authorities for existing namespaces. Minting urn:example:xmpp:foo instead of requesting issuance of urn:xmpp:foo is still the right move, new namespace identifiers must still be registered when existing namespaces do not match the desired functionality, and the basic spirit of namespace identifier assignment still applies, such as setting up shadow identifiers like urn:example:MyCompany:* instead of using HTTP URIs.
You make up the rest of the name yourself; no authority issues it. But a real namespace identifier is still needed for anything that must work in production, so example names stay for examples.
§6Security Considerations
The document introduces no additional security considerations beyond those associated with the use and resolution of URNs in general.
The document adds no security rules of its own. The usual care around URNs applies.
§7The IANA Registration
The document defines a URN namespace identifier registration of example, which IANA has added to the Formal URN Namespaces registry. The completed registration template can be found in Section 3 of the document.
The word 'example' is now on IANA's list of formal URN namespaces, so any tool can recognise it.