    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.

    Saint-Andre               Best Current Practice                 [Page 1]

    RFC 6963                      Example URNs                      May 2013

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

    Saint-Andre               Best Current Practice                 [Page 2]

    RFC 6963                      Example URNs                      May 2013

    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.

    Saint-Andre               Best Current Practice                 [Page 3]

    RFC 6963                      Example URNs                      May 2013

    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.

    Saint-Andre               Best Current Practice                 [Page 4]

    RFC 6963                      Example URNs                      May 2013

    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.

    Saint-Andre               Best Current Practice                 [Page 5]

    RFC 6963                      Example URNs                      May 2013

    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.

    Saint-Andre               Best Current Practice                 [Page 6]

    RFC 6963                      Example URNs                      May 2013

    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

    Saint-Andre               Best Current Practice                 [Page 7]