A Uniform Resource Name (URN) Namespace for Examples
draft-saintandre-urn-example-01

Abstract

This document defines a Uniform Resource Name (URN) namespace identifier enabling generation of URNs that are appropriate for use in documentation, private testing, and the like.

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http:/⁠/⁠datatracker.ietf.org/⁠drafts/⁠current/⁠.

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."

This Internet-Draft will expire on July 12, 2013.

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. Specification Template
• 2.1. Namespace ID
• 2.2. Registration Information
• 2.3. Declared Registrant of the Namespace
• 2.4. Declaration of Syntactic Structure
• 2.5. Relevant Ancillary Documentation
• 2.6. Identifier Uniqueness Considerations
• 2.7. Identifier Persistence Considerations
• 2.8. Process for Identifier Resolution
• 2.9. Rules for Lexical Equivalence
• 2.10. Conformance with URN Syntax
• 2.11. Validation Mechanism
• 2.12. Scope
• 3. Namespace Considerations
• 4. Community Considerations
• 5. Security Considerations
• 6. IANA Considerations
• 7. References
• 7.1. Normative References
• 7.2. Informative References
• Appendix A. Acknowledgements
• Author's Address

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) [RFC3406]. 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 [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 private testing by assigning their own unique namespace-specific strings.

2. Specification Template

2.1. Namespace ID

The Namespace ID "example" is requested.

2.2. Registration Information

Version 1

Date: [to be assigned]

2.3. Declared Registrant of the Namespace

Registering organization: IETF

Designated contact: IESG, iesg@ietf.org

2.4. Declaration of Syntactic Structure

The Namespace Specific String (NSS) of all URNs that use the "example" NID shall have the following structure:

urn:example:{NSS}

The NSS is a mandatory string of ASCII characters [RFC20] that conforms to the URN syntax requirements [RFC2141] and that provides a name that is useful within the relevant documentation example, test suite, or other application.

2.5. Relevant Ancillary Documentation

See [RFC6648] for information about deprecation of the "x-" convention in protocol parameters and identifiers.

2.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. As a result, implementers are counselled against using example URNs for any purposes other than documentation, private testing, and truly experimental contexts.

2.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.

2.8. Process for Identifier Resolution

Example URNs are not intended to be resolved, and the namespace is not and probably never will be registered with a Resolution Discovery System.

2.9. Rules for Lexical Equivalence

No special considerations; the rules for lexical equivalence specified in [RFC2141] apply.

2.10. Conformance with URN Syntax

No special considerations

2.11. Validation Mechanism

None

2.12. Scope

Global

3. Namespace Considerations

No existing formal namespace enables entities to generate URNs that are appropriate for use as examples in documentation, in private testing, and the like. It could be argue 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, it seems preferable to create a dedicated namespace that can be used to generate example URNs.

4. Community Considerations

The "example" NID is intended to provide a clean, easily-recognizable space for minting examples to be used in documentation, in private testing, and the like. The Namespace Specific String (NSS) needs to be 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 they cannot be resolved in any 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 "urn:sha-1" namespace), 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).

5. Security Considerations

This document introduces no additional security considerations beyond those associated with the use and resolution of URNs in general.

6. IANA Considerations

This document defines a URN NID registration of "example", to be added to the formal namespace registration; the completed registration template can be found under Section 2.

7. References

7.1. Normative References

7.2. Informative References

Appendix A. Acknowledgements

Thanks to Jim Schaad for his feedback.

Author's Address