idnits 2.17.1 draft-wilde-registries-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack a Security Considerations section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** The abstract seems to contain references ([2], [1]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (February 1, 2016) is 3006 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 4646 (ref. '1') (Obsoleted by RFC 5646) ** Obsolete normative reference: RFC 5988 (ref. '2') (Obsoleted by RFC 8288) Summary: 6 errors (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group E. Wilde 3 Internet-Draft February 1, 2016 4 Intended status: Informational 5 Expires: August 4, 2016 7 The Use of Registries 8 draft-wilde-registries-00 10 Abstract 12 Registries on the Internet and the Web fulfill a wide range of tasks, 13 ranging from low-level networking aspects such as packet type 14 identifiers, all the way to application-level protocols and 15 standards. This document summarizes some of the reasons of why and 16 how to use registries, and how some of them are operated. It serves 17 as a informative reference for specification writers considering 18 whether to create and manage a registry, allowing them to better 19 understand some of the issues associated with certain design 20 discussions. 22 Note to Readers 24 Please discuss this draft on the apps-discuss mailing list [1]. 26 Online access to all versions and files is available on GitHub [2]. 28 Status of This Memo 30 This Internet-Draft is submitted in full conformance with the 31 provisions of BCP 78 and BCP 79. 33 Internet-Drafts are working documents of the Internet Engineering 34 Task Force (IETF). Note that other groups may also distribute 35 working documents as Internet-Drafts. The list of current Internet- 36 Drafts is at http://datatracker.ietf.org/drafts/current/. 38 Internet-Drafts are draft documents valid for a maximum of six months 39 and may be updated, replaced, or obsoleted by other documents at any 40 time. It is inappropriate to use Internet-Drafts as reference 41 material or to cite them other than as "work in progress." 43 This Internet-Draft will expire on August 4, 2016. 45 Copyright Notice 47 Copyright (c) 2016 IETF Trust and the persons identified as the 48 document authors. All rights reserved. 50 This document is subject to BCP 78 and the IETF Trust's Legal 51 Provisions Relating to IETF Documents 52 (http://trustee.ietf.org/license-info) in effect on the date of 53 publication of this document. Please review these documents 54 carefully, as they describe your rights and restrictions with respect 55 to this document. Code Components extracted from this document must 56 include Simplified BSD License text as described in Section 4.e of 57 the Trust Legal Provisions and are provided without warranty as 58 described in the Simplified BSD License. 60 Table of Contents 62 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 63 2. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 3 64 2.1. TCP/UDP Port Numbers . . . . . . . . . . . . . . . . . . 4 65 2.2. Language Tags . . . . . . . . . . . . . . . . . . . . . . 4 66 2.3. Web Linking . . . . . . . . . . . . . . . . . . . . . . . 5 67 3. Why to use Registries . . . . . . . . . . . . . . . . . . . . 5 68 3.1. Openness and Extensibility . . . . . . . . . . . . . . . 6 69 3.2. Limited Namespaces . . . . . . . . . . . . . . . . . . . 6 70 3.3. Design/Usage Review . . . . . . . . . . . . . . . . . . . 7 71 3.4. Identifier Design . . . . . . . . . . . . . . . . . . . . 7 72 3.5. Identifier Lifecycle . . . . . . . . . . . . . . . . . . 7 73 3.6. Documentation Requirements . . . . . . . . . . . . . . . 8 74 3.7. Centralized Lookup . . . . . . . . . . . . . . . . . . . 9 75 4. When to use Registries . . . . . . . . . . . . . . . . . . . 9 76 5. How to use Registries . . . . . . . . . . . . . . . . . . . . 10 77 5.1. Implementation Support . . . . . . . . . . . . . . . . . 10 78 5.2. Registry Application . . . . . . . . . . . . . . . . . . 10 79 5.3. Registry Stability . . . . . . . . . . . . . . . . . . . 10 80 5.4. Registry History . . . . . . . . . . . . . . . . . . . . 10 81 5.5. Runtime vs. Design-Time . . . . . . . . . . . . . . . . . 10 82 5.6. Registry Access . . . . . . . . . . . . . . . . . . . . . 10 83 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 84 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 11 85 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 11 87 1. Introduction 89 Technologies and standards in computer networking have long used the 90 concept of a "Registry" as a place where well-known information is 91 available and managed. In most case, the main reason to use a 92 registry is to create a technology or standard that has stable parts 93 (the technology/standard itself), as well as some parts that are 94 supposed to evolve while the technology/standard itself remains 95 stable and unchanged. 97 A registry essentially is a pattern of how to separate those two 98 aspects of a technology/standard, allowing the technology/standard to 99 remain stable, while the parts of it referencing the registry can 100 evolve over time by changing the registry contents. For 101 specification writers, this has proven to be a useful and successful 102 pattern. The "Protocol Registries" maintained by the "Internet 103 Assigned Numbers Authority (IANA)" have steadily increased in number. 104 At the time of writing (early 2016), the IANA Protocol Registry [5] 105 contains 1903 individual registries. This number indicates that 106 registries as a "protocol specification pattern" are quite popular 107 and successful. 109 Deciding if a specification should use a registry is not an easy 110 task. It involves identifying those parts that should be kept stable 111 (in the specification itself), and those that should be managed in 112 one or more registries for ongoing management and evolution. Even 113 after identifying this split, it is necessary to define how exactly 114 the registry part(s) should be managed, involving questions such as 115 submission procedures, review processes, revocation/change 116 management, and access to the registry contents for the worldwide 117 developer community. 119 This document is intended to provide an overview to specification 120 developers in terms of why, when, and how to use registries. It is 121 not meant to provide definitive guidance, but mostly intended as a 122 reference to consider the different ways in which the general 123 "registry pattern" can be used, and what the possible side-effects on 124 some of these solutions may be. 126 2. Examples 128 The following list of examples is intended to be illustrative of some 129 of the existing registries, what kind of identifiers they are using, 130 and how they are managed. This list is not intended to highlight 131 these registries in any special way other than explaining some of the 132 specifics of the managed namespaces. As mentioned above, the list of 133 IANA-managed registries is long (around 2000 individual registries), 134 and the examples listed here have been selected somewhat randomly to 135 illustrate certain points. 137 2.1. TCP/UDP Port Numbers 139 The registry for TCP/UDP port numbers [3] is one of the oldest well- 140 known registries on the Internet. Because of its core importance for 141 how the Internet functions, it has been around for a long time, there 142 is a long history about managing and running it, and thus the most 143 up-to-date document about it is relatively new (RFC 6335 [3] from 144 August 2011). 146 The namespace of ports is a very limited one. Port numbers in TCP 147 and UDP are 16-bit numbers, yielding a namespace of 65'536 port 148 numbers. The port numbers are subdivided into three ranges of system 149 ports (0-1023), user ports (1024-49151), and dynamic ports 150 (49152-65535). IANA only treats system and user port numbers as 151 assignable, whereas dynamic port numbers cannot be assigned at all. 153 The TCP/UDP port number registry is a good example for a very limited 154 and very popular namespace, and thus managing this registry follows a 155 very disciplined review process. RFC 6335 [3] specifies very 156 specific guidance about assignment, de-assignment, reuse, revocation, 157 and transfer of numbers. This level of detail may not be required 158 for all registries, but it is a good demonstration of what may be 159 necessary in case of constrained and popular namespaces. 161 2.2. Language Tags 163 The ability to identify human languages is important for many 164 scenarios and applications on the Internet, and thus RFC 4646 [1] 165 defines how to do this. The specification uses a registry to manage 166 the actual language identifiers, because this list is constantly 167 evolving and thus better separated from the standard defining the 168 language tag format itself. 170 Apart from the primary language subtag (identifying for example the 171 English language with the identifier "en"), the language tag format 172 supports additional subtags for extended languages, scripts, regions, 173 variants, extensions, and private use. The primary language subtag 174 uses 2- and 3-letter identifiers that are taken from ISO 639 [4]. 175 There is a provision for longer identifiers to exist (and be directly 176 registered with IANA), but the goal is to manage actual registration 177 through ISO 639, and use the namespace and identifiers established by 178 this standard. 180 While the namespace of the primary language subtags is rather 181 restricted (2- and 3-letter identifiers), IANA's registry itself does 182 not need to be directly concerned with its use and management, as 183 this is handled by ISO through their ISO 639 process. 185 Without going into the details of how all the other subtags 186 namespaces are defined and registered, it should suffice to mention 187 that one of the main goals of RFC 4646 [1] is to ensure that the 188 language registry of ISO 639 (as well as some others, such as the 189 script registry of ISO 15924) and language tags as used on the 190 Internet stay in sync. Thus, the management of the namespaces 191 created for language tags by RFC 4646 [1] is mostly delegated to ISO, 192 instead of being managed by IANA itself. 194 Nevertheless, RFC 4646 [1] does make provisions about the stability 195 of entries in the various namespaces, so that the meaning of language 196 tags remains stable over time. This includes provisions that 197 existing values are not going to be changed, and that even values 198 withdrawn by ISO remain valid and will simply be marked as 199 "deprecated" in the respective IANA registry. 201 2.3. Web Linking 203 Web links can be typed by link relation types, and RFC 5988 [2] 204 defines a model for how this can be done, and a registry for well- 205 known values. One interesting aspect of the model is that the value 206 space is divided: On the one had there are well-known and registered 207 values identified by strings, and on the other hand it is possible to 208 use URIs, in which case no registration is required. This means that 209 the namespace for the link relation type registry is that of strings, 210 meaning that it is not highly constrained. 212 With a rather large namespace, it is possible to accommodate a larger 213 set of entries. However, it is still required that additions to the 214 registry are done by following a process that requires describing the 215 requested entries, and referring to a document that contains their 216 definition and some context. 218 In addition, RFC 5988 [2] does define some constraints for how 219 registered link relation types have to be defined. A submission 220 process and reviews by designated experts are used to make sure that 221 these constraints are met when new entries are submitted for 222 inclusion in the registry. 224 3. Why to use Registries 226 Establishing and using a registry can be done for a number of 227 reasons. The following sections list some of these reasons, and in 228 many cases, registries are used for at least some of the reasons 229 described here. 231 3.1. Openness and Extensibility 233 Registries separate a specification into a stable part that is 234 represented by the specification itself, and a dynamic part that is 235 represented by one or more registries that are established by the 236 specification. This pattern allows a specification to remain stable, 237 while still having well-defined parts that are allowed to evolve over 238 time. 240 In order for this pattern to work well, the specification should 241 clearly state what implementations should do when encountering 242 unknown values in those locations where allowable values are managed 243 in a registry. The two most popular processing models are to either 244 silently ignore such a value and continue as if the value was not 245 present at all, or to raise an error and notify higher layers of the 246 fact that something unknown was encountered. 248 Depending on the way values are managed, it is also possible to 249 distinguish between values that are supposed to be registered, and 250 those that are not supposed to be registered and have to be 251 considered unregistered extensions. The link relation types 252 described in Section 2.3 use such an approach, defining that a link 253 relation is either a string and supposed to be a registered value, or 254 a URI in which case it is not supposed to be a registered value. 255 This strategy works when it is possible to clearly separate the 256 namespace of the place where values are expected into ones that are 257 considered to be registered, and those that are not. 259 3.2. Limited Namespaces 261 Historically, registries started managing the very limited namespace 262 of identifier fields in protocol packets or other low-level 263 mechanisms such as the port numbers described in Section 2.1, often 264 limited to a small number of bits or bytes. Carefully managing this 265 very limited set of available identifiers was important, as was a way 266 to allow new values to be added without having to update the protocol 267 specification itself. 269 The higher the level is on which registries are used, the more likely 270 it is that namespaces at least on the technical level are not very 271 constrained. For example, the link relation types described in 272 Section 2.3 are using strings as identifiers without imposing a 273 length limitations, meaning that the set of possible identifiers is 274 virtually inexhaustible. However, even in this case, the set of 275 helpful and meaningful identifiers (i.e., names that are human- 276 readable and partly self-describing) is limited, and thus even in 277 this case, the realistically useful namespace is much more limited 278 that the theoretical one. 280 3.3. Design/Usage Review 282 Registries are established in the context of a given specification, 283 and provide a mechanism to make this specification extensible by 284 allowing the registry to evolve over time. However, the context of 285 the specification very often has a clear design rationale for why a 286 registry is established for a certain set of values. Any value added 287 or changed in the registry should fit into this context, and having a 288 registry provides an opportunity to have design and usage reviews 289 before the registry gets updated. 291 For design and usage reviews to work well, the most crucial aspect is 292 that the context of the registry is well-defined, and states clearly 293 what kind of expectations the design and usage review will be 294 checking. Often this review process is implemented using a mailing 295 list and designated experts, so that registration requests as well as 296 results of the deign and usage review are done openly and 297 transparently. 299 3.4. Identifier Design 301 Depending on the namespace, managing the registry namespace may 302 follow certain guidelines. For numeric values, there may be certain 303 number ranges that are supposed to be used in certain ways. For 304 string values, there may be some convention or best practices on how 305 to mint identifiers so that the namespace contains values that are 306 following these principles. 308 Note that this is different from the design and usage review 309 Section 3.3. Whereas the design and usage review is about testing 310 whether the meaning associated with a new value follow the 311 constraints defined in the context that established the registry, the 312 identifier design simply checks for how the registered values are 313 chosen. It thus is a lower bar than a design and usage review, but 314 still requires a review process that allows to propose new values, 315 and provides some feedback about whether these values follow the 316 guidelines or not. 318 3.5. Identifier Lifecycle 320 The main reason for registries to exist in contrast to just including 321 a set of predefined values in the underlying technology/standard 322 itself is the ability for these values to change over time. However, 323 registries only make sense if there is some sense of stability to 324 their contents, so that looking at existing registry values at some 325 point in time can be assumed to be a reasonable snapshot for some 326 amount of time. 328 Usually, registry entries are added at a modest pace, and an 329 implementation not supporting the latest additions shouldn't fail, 330 but simply implement some default behavior when encountering 331 unsupported values. This pattern ensures that the namespace can 332 evolve separately from the landscape of implementations. 334 However, adding identifiers is the easiest aspects of registry 335 updates. Things get more complicated when it comes to updating and 336 removing entries. The reason why these things are more complicated 337 is that implementations depending on an identifier having certain 338 semantics will behave incorrectly when the registry has been updated 339 for this identifier with either a change in semantics, or a 340 withdrawal of the entry. 342 For this reason, it often makes sense to include rules in the 343 management of the registry about if/how entries can be updated, or 344 removed. One popular approach is disallow updates with breaking 345 changes, and to allow withdrawal but keep the identifier and mark it 346 as "deprecated". This way it can be ensured that no incompatible 347 entry will be created by somebody using an identifier that was 348 previously used and removed. 350 The exact way how this process is defined depends on the context and 351 purpose of the registry, and also on the namespace size. Tightly 352 constrained namespaces mean that values probably should be managed 353 more carefully, so that the registry does not run out of values. 354 Also, while impossible to predict reliably, it is also important to 355 look at the possible lifetime of implementations (that will use 356 snapshots of the registry at some point in time), and on the long- 357 term effects of having outdated registry snapshots in 358 implementations. 360 3.6. Documentation Requirements 362 Registering a value means that people encountering this value should 363 be able to learn about what it represents. This means that there 364 should be documentation associated with it that can be used to learn 365 more about the value's meaning. Many registries at the very least 366 require a very short explanation to be submitted with a registration 367 request, so that the registry itself can list those texts as helpful 368 explanations. 370 Going further, many registries also require links to more detailed 371 specifications, so that people looking for complete explanations of 372 the meaning of registered values can follow those links and will find 373 specifications or at least explanations. The exact requirement on 374 what such a link must refer to is something that the specification 375 creating the registry has to define. One popular requirement is that 376 it must be publicly available information, so that anybody looking 377 for it can openly access it. 379 3.7. Centralized Lookup 381 With a registry containing all current values (and possibly listing 382 changed/deprecated ones as well) along with some registration 383 metadata, they provide valuable information for anybody looking for 384 information about registered values in the registry namespace. All 385 IANA protocol registries [5] are openly accessible on the Web, 386 allowing everybody to lookup the current state of all these 387 registries. 389 Even though centralized lookup is an important aspect of openness and 390 extensibility Section 3.1, the usual usage model of these lookup 391 facilities is to use them at design-time rather than at runtime 392 Section 5.5. This means that the central lookup facilities are meant 393 to be used by developers, and not by the implementations created by 394 those developers. For the latter model a much more scalable 395 infrastructure would be required, and thus it is important to 396 consider the fact if the namespace managed by a registry fits this 397 model of being useful for developer lookup at design-time, and for 398 value lookup at runtime. 400 4. When to use Registries 402 Based on the examples given in Section 2 and the possible reasons 403 described in Section 3, the next question is how for designers to 404 decide when they should establish one or more registries to 405 complement a technology/standard. All the issues describes in 406 Section 3 are reasonable motivations, and in many cases it is more 407 than just one of them. 409 For users of a technology/standard, it is helpful if the 410 specification clearly describes which reasons were most important 411 when deciding to establish one or more registries. This is even more 412 true for users who are looking to update the registry, because they 413 should be aware of the reasons that were considered when the registry 414 was created. 416 For every registry that is established, it is helpful if a 417 specification explains the following general aspects: 419 What were the main design rationales behind establishing the 420 registry? The reasons described in Section 3 may be a good 421 starting point to pick from. 423 What are the management policies for the registry? Depending on a 424 variety of factors such as namespace size, expected frequency of 425 updated, level of review before acceptance, required level of 426 documentation, and possibly others, management can be rather 427 lightweight or a carefully managed process. 429 What is the size of the namespace and the expected rate of how it 430 will be used and possibly exhausted? 432 5. How to use Registries 434 ... 436 5.1. Implementation Support 438 ... implement a snapshot, fail over in a controlled way ... 440 5.2. Registry Application 442 ... template ... 444 5.3. Registry Stability 446 ... changes beyond editorial ones ... 448 ... removal of a registry entry ... 450 5.4. Registry History 452 ... history of all registry updates ... 454 5.5. Runtime vs. Design-Time 456 ... snapshot ... 458 5.6. Registry Access 460 ... API ... 462 6. References 464 [1] Phillips, A. and M. Davis, "Tags for Identifying 465 Languages", RFC 4646, DOI 10.17487/RFC4646, September 466 2006, . 468 [2] Nottingham, M., "Web Linking", RFC 5988, 469 DOI 10.17487/RFC5988, October 2010, 470 . 472 [3] Cotton, M., Eggert, L., Touch, J., Westerlund, M., and S. 473 Cheshire, "Internet Assigned Numbers Authority (IANA) 474 Procedures for the Management of the Service Name and 475 Transport Protocol Port Number Registry", BCP 165, 476 RFC 6335, DOI 10.17487/RFC6335, August 2011, 477 . 479 [4] International Organization for Standardization, "Code for 480 the representation of names of languages, 1st edition", 481 ISO Standard 639, 1988. 483 [5] "IANA Protocol Registry", . 485 Appendix A. Acknowledgements 487 Thanks for comments and suggestions provided by ... 489 Author's Address 491 Erik Wilde 493 Email: erik.wilde@dret.net 494 URI: http://dret.net/netdret/