idnits 2.17.1 draft-wilde-registries-02.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 separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (April 23, 2019) is 1828 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** Obsolete normative reference: RFC 7500 (Obsoleted by RFC 8720) Summary: 4 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 April 23, 2019 4 Intended status: Informational 5 Expires: October 25, 2019 7 The Use of Registries 8 draft-wilde-registries-02 10 Abstract 12 Registries for Internet and Web protocols fulfill a wide range of 13 tasks, ranging from low-level networking aspects such as packet type 14 identifiers, all the way up to application-level protocols and 15 standards. This document summarizes some of the reasons of why, 16 when, and how to use registries. It serves as an informative 17 reference for specification writers considering whether to create and 18 manage a registry, allowing them to better understand some of the 19 issues associated with certain design and operational decisions. 21 Note to Readers 23 Please discuss this draft on the ART mailing list 24 (). 26 Online access to all versions and files is available on GitHub 27 (). 29 Status of This Memo 31 This Internet-Draft is submitted in full conformance with the 32 provisions of BCP 78 and BCP 79. 34 Internet-Drafts are working documents of the Internet Engineering 35 Task Force (IETF). Note that other groups may also distribute 36 working documents as Internet-Drafts. The list of current Internet- 37 Drafts is at https://datatracker.ietf.org/drafts/current/. 39 Internet-Drafts are draft documents valid for a maximum of six months 40 and may be updated, replaced, or obsoleted by other documents at any 41 time. It is inappropriate to use Internet-Drafts as reference 42 material or to cite them other than as "work in progress." 44 This Internet-Draft will expire on October 25, 2019. 46 Copyright Notice 48 Copyright (c) 2019 IETF Trust and the persons identified as the 49 document authors. All rights reserved. 51 This document is subject to BCP 78 and the IETF Trust's Legal 52 Provisions Relating to IETF Documents 53 (https://trustee.ietf.org/license-info) in effect on the date of 54 publication of this document. Please review these documents 55 carefully, as they describe your rights and restrictions with respect 56 to this document. Code Components extracted from this document must 57 include Simplified BSD License text as described in Section 4.e of 58 the Trust Legal Provisions and are provided without warranty as 59 described in the Simplified BSD License. 61 Table of Contents 63 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 64 2. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 4 65 2.1. TCP/UDP Port Numbers . . . . . . . . . . . . . . . . . . 4 66 2.2. Language Tags . . . . . . . . . . . . . . . . . . . . . . 5 67 2.3. Web Linking . . . . . . . . . . . . . . . . . . . . . . . 5 68 2.4. Domain Name System (DNS) . . . . . . . . . . . . . . . . 6 69 2.5. non-IANA/DNS example . . . . . . . . . . . . . . . . . . 6 70 3. Why use Registries . . . . . . . . . . . . . . . . . . . . . 6 71 3.1. Openness and Extensibility . . . . . . . . . . . . . . . 7 72 3.2. Limited Namespaces . . . . . . . . . . . . . . . . . . . 7 73 3.3. Design/Usage Review . . . . . . . . . . . . . . . . . . . 8 74 3.4. Identifier Design . . . . . . . . . . . . . . . . . . . . 8 75 3.5. Identifier Lifecycle . . . . . . . . . . . . . . . . . . 9 76 3.6. Documentation Requirements . . . . . . . . . . . . . . . 9 77 3.7. Centralized Lookup . . . . . . . . . . . . . . . . . . . 10 78 4. When to use Registries . . . . . . . . . . . . . . . . . . . 10 79 5. Barrier to Entry Issues . . . . . . . . . . . . . . . . . . . 11 80 5.1. Non-Semantic/Reserved Entries . . . . . . . . . . . . . . 11 81 5.2. Entry Levels . . . . . . . . . . . . . . . . . . . . . . 12 82 5.3. Separation by Value Syntax . . . . . . . . . . . . . . . 12 83 6. How to use Registries . . . . . . . . . . . . . . . . . . . . 13 84 6.1. Registry Operations . . . . . . . . . . . . . . . . . . . 14 85 6.2. Registry Creation . . . . . . . . . . . . . . . . . . . . 15 86 6.3. Registry Interaction . . . . . . . . . . . . . . . . . . 15 87 6.4. Implementation Support . . . . . . . . . . . . . . . . . 16 88 6.5. Registry Stability . . . . . . . . . . . . . . . . . . . 16 89 6.6. Registry History . . . . . . . . . . . . . . . . . . . . 16 90 6.7. Registry Access . . . . . . . . . . . . . . . . . . . . . 17 91 6.8. Runtime vs. Design-Time . . . . . . . . . . . . . . . . . 17 92 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18 93 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 18 94 Appendix A. W3C Examples . . . . . . . . . . . . . . . . . . . . 20 95 Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 21 96 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 21 98 1. Introduction 100 Specifications for technologies and standards in computer networking 101 have long used the concept of a "Registry" as a place where well- 102 known information is available and managed. In most case, the main 103 reason to use a registry is to create a specification that has stable 104 parts (the specification itself), as well as some parts of it that 105 are supposed to evolve while the specification itself remains stable 106 and unchanged. 108 In essence, a registry is a pattern of how to separate those two 109 aspects of a specification, allowing the specification to remain 110 stable, while the parts of it managed in the registry can evolve over 111 time by updating the registry contents. For specification writers, 112 this has proven to be a useful and successful pattern. The "Protocol 113 Registries" maintained by the "Internet Assigned Numbers Authority 114 (IANA)" have steadily increased in number. At the time of writing 115 (early 2016), the IANA Protocol Registry [IANA-Protocol-Registry] 116 contains 1903 individual registries. This number indicates that 117 registries as a "protocol specification pattern" are quite popular 118 and successful. 120 Deciding whether a specification should use a registry is not an easy 121 task. It involves identifying those parts that should be kept stable 122 (in the specification itself), and those that should be managed in 123 one or more registries for ongoing management and evolution. Even 124 after identifying this split, it is necessary to define how exactly 125 the registry part(s) should be managed, involving questions such as 126 submission procedures, review processes, revocation/change 127 management, and access to the registry contents for the worldwide 128 developer community. 130 This document is intended to provide an overview to specification 131 developers in terms of why, when, and how to use registries. It is 132 not meant to provide definitive guidance, but mostly intended as a 133 reference to consider the different ways in which the general 134 "registry pattern" can be used, and what the possible side-effects of 135 some of these solutions may be. 137 This document also has to tackle a difficult question: Registries as 138 a pattern can be managed and hosted in a large variety of ways. On 139 the other hand, the IANA Protocol Registry mentioned above provides a 140 simple and hosted place for specifications to run their registries. 141 As all existing platforms, the IANA Protocol Registry comes with 142 certain constraints in terms of how a registry can be defined, 143 managed, and run. This document acknowledges the existence and 144 popularity of the IANA Protocol Registry, but also tries to be open 145 enough so that if specification writer choose to do so for whatever 146 reason, they should also be able to use registries other than one in 147 the IANA Protocol Registry 149 2. Examples 151 The following list of examples is intended to be illustrative of some 152 of the existing registries, what kind of identifiers they are using, 153 and how they are managed. This list is not intended to highlight 154 these registries in any special way other than explaining some of the 155 specifics of the managed namespaces. As mentioned above, the list of 156 IANA-managed registries is long (around 2000 individual registries), 157 and the examples listed here have been selected somewhat randomly 158 just to illustrate certain points. 160 In order to highlight the fact that IANA-managed registries are only 161 one way of how to establish and run a registry, Section 2.4 briefly 162 talks about DNS as an example for the same basic function (providing 163 a managed namespace of identifiers), but one that is based on 164 different constraints and thus results in a different operational 165 model and implementation. 167 2.1. TCP/UDP Port Numbers 169 The registry for TCP/UDP port numbers [RFC6335] is one of the oldest 170 well-known registries on the Internet. Because of its core 171 importance for how the Internet functions, it has been around for a 172 long time, there is a long history about managing and running it, and 173 thus the most up-to-date document about it is relatively new (RFC 174 6335 [RFC6335] from August 2011). 176 The namespace of ports is limited. Port numbers in TCP and UDP are 177 16-bit numbers, yielding a namespace of 65'536 port numbers. The 178 port numbers are subdivided into three ranges of system ports 179 (0-1023), user ports (1024-49151), and dynamic ports (49152-65535). 180 RFC 6335 only treats system and user port numbers as assignable, 181 whereas dynamic port numbers cannot be assigned at all. 183 The TCP/UDP port number registry is a good example for a limited and 184 popular namespace, and thus managing this registry follows a 185 disciplined review process. RFC 6335 [RFC6335] defines specific 186 guidance about assignment, de-assignment, reuse, revocation, and 187 transfer of numbers. This level of detail may not be required for 188 all registries, but it is a good demonstration of what may be 189 necessary in case of constrained and popular namespaces. 191 2.2. Language Tags 193 The ability to identify human languages is important for many 194 scenarios and applications on the Internet, and thus RFC 5646 195 [RFC5646] defines how to do this. The specification uses a registry 196 to manage the actual language identifiers, because this list is 197 constantly evolving and thus better separated from the specification 198 defining the language tag format itself. 200 Apart from the primary language subtag (identifying for example the 201 English language with the identifier "en"), the language tag format 202 supports additional subtags for extended languages, scripts, regions, 203 variants, extensions, and private use. The primary language subtag 204 uses 2- and 3-letter identifiers that are taken from ISO 639 205 [ISO.639.1988]. There is a provision for longer identifiers to exist 206 (and be directly registered with IANA), but the goal is to manage 207 actual registration through ISO 639, and use the namespace and 208 identifiers established by this standard. 210 While the namespace of the primary language subtags is rather 211 restricted (2- and 3-letter identifiers), IANA's registry itself does 212 not need to be directly concerned with its use and management, as 213 this is handled by ISO through their ISO 639 process. 215 Without going into the details of how the other subtag namespaces are 216 defined and registered, it should suffice to mention that one of the 217 main goals of RFC 5646 is to ensure that the language registry of ISO 218 639 (as well as some others, such as the script registry of ISO 219 15924) and language tags as used on the Internet stay in sync. Thus, 220 the management of the namespaces created for language tags by RFC 221 5646 [RFC5646] is mostly delegated to ISO, instead of being managed 222 by IANA itself. 224 Nevertheless, RFC 5646 [RFC5646] does make provisions about the 225 stability of entries in the various namespaces, so that the meaning 226 of language tags remains stable over time. This includes provisions 227 that existing values are not going to be changed, and that even 228 values withdrawn by ISO remain valid and will simply be marked as 229 "deprecated" in the respective IANA registry. 231 2.3. Web Linking 233 Web links can be typed by link relation types, and RFC 8288 [RFC8288] 234 defines a model for how this can be done, and a registry for well- 235 known values. One interesting aspect of the model is that the value 236 space is divided: On the one had there are well-known and registered 237 values identified by strings, and on the other hand it is possible to 238 use URIs, in which case no registration is required. This means that 239 the namespace for the link relation type registry is that of strings, 240 meaning that it is not highly constrained. 242 With a rather large namespace, it is possible to accommodate a larger 243 set of entries. However, it is still required that additions to the 244 registry are done by following a process that requires describing the 245 requested entries, and referring to a document that contains their 246 definition and some context. 248 In addition, RFC 8288 [RFC8288] does define some constraints for how 249 registered link relation types have to be defined. A submission 250 process and reviews by designated experts are used to make sure that 251 these constraints are met when new entries are submitted for 252 inclusion in the registry. 254 2.4. Domain Name System (DNS) 256 The Domain Name System (DNS) specified in RFCs 1034 [RFC1034] and 257 1035 [RFC1035] is a distributed infrastructure for hosting a variety 258 of entry types. In the context of the DNS, the entry types are 259 defined by various Resource Record (RR) types. However, since the 260 DNS is used for specific purposes, it is not a generic key/value 261 store. Instead, the assumption is that the key always is a DNS name, 262 whereas the value then is determined by the RR(s) available for that 263 domain. 265 It could be argued that the DNS is not a typical registry because its 266 design reflects the fact that entries are updated rather frequently, 267 that entries therefore are not stable, and that registry access is a 268 runtime issue Section 6.8. Because of these differences, it may be a 269 bit of a stretch to call the DNS a "registry", but it is a well-know 270 and well-established key/value lookup mechanism for IETF 271 specifications, and therefore deserves mention in this document. 273 2.5. non-IANA/DNS example 275 (( Still looking for an example of a registry that's established/used 276 by an IETF spec and that is neither managed by IANA, nor part of DNS 277 Section 2.4. If you have a suggestion, please let me know. )) 279 3. Why use Registries 281 Establishing and using a registry can be done for a number of 282 reasons. The following sections list some of these reasons, and in 283 many cases, registries are used for at least some of the reasons 284 described here. 286 The list of reasons why to establish a registry may seem long, and in 287 some cases it may feel as if these reasons are valid reasons for 288 managing established long-term values, but that having a registry 289 seems like a potential barrier to entry for short-term 290 experimentation and other not-quite-permanent scenarios. Section 5 291 discusses this issue and how specifications can deal with it. 293 3.1. Openness and Extensibility 295 Registries separate a specification into a stable part that is 296 represented by the specification itself, and a dynamic part that is 297 represented by one or more registries that are established by the 298 specification. This pattern allows a specification to remain stable, 299 while still having well-defined parts that are allowed to evolve over 300 time. 302 In order for this pattern to work well, the specification should 303 clearly state what implementations should do when encountering 304 unknown values in those locations where allowable values are managed 305 in a registry. The two most popular processing models are to either 306 silently ignore such a value and continue as if the value was not 307 present at all, or to raise an error and notify higher layers of the 308 fact that something unknown was encountered. 310 Depending on the way values are managed, it is also possible to 311 distinguish between values that are supposed to be registered, and 312 those that are not supposed to be registered and have to be 313 considered unregistered extensions. The link relation types 314 described in Section 2.3 use such an approach, defining that a link 315 relation is either a string and supposed to be a registered value, or 316 a URI in which case it is not supposed to be a registered value. 317 This strategy works when it is possible to clearly separate the 318 namespace of the place where values are expected into ones that are 319 considered to be registered, and those that are not. This can be 320 done lexically, or by having some kind of flag that indicates whether 321 a value is supposed to be well-known, or an unregistered extension. 323 3.2. Limited Namespaces 325 Historically, registries started managing the limited namespace of 326 identifier fields in protocol packets or other low-level mechanisms 327 such as the port numbers described in Section 2.1, often limited to a 328 small number of bits or bytes. Carefully managing this limited set 329 of available identifiers was important, as was a way to allow new 330 values to be added without having to update the protocol 331 specification itself. 333 The higher the level is on which registries are used, the more likely 334 it is that namespaces at least on the technical level are not overly 335 constrained. For example, the link relation types described in 336 Section 2.3 are using strings as identifiers without imposing a 337 length limitation, meaning that the set of possible identifiers is 338 virtually inexhaustible. However, even in this case, the set of 339 helpful and meaningful identifiers (i.e., names that are human- 340 readable and partly self-describing) is limited, and thus even in 341 this case, the realistically useful namespace is much more limited 342 that the theoretical one. 344 3.3. Design/Usage Review 346 Registries are established in the context of a given specification, 347 and provide a mechanism to make this specification extensible by 348 allowing the registry to evolve over time. However, the context of 349 the specification often has a clear design rationale for why a 350 registry is established for a certain set of values. Any value added 351 or changed in the registry should fit into this context, and having a 352 registry provides an opportunity to have design and usage reviews 353 before the registry gets updated. 355 For design and usage reviews to work well, the most crucial aspect is 356 that the context of the registry is well-defined, and states clearly 357 what kind of expectations the design and usage review will be 358 checking. Often this review process is implemented using a mailing 359 list and designated experts, so that registration requests as well as 360 results of the deign and usage review are done openly and 361 transparently. 363 3.4. Identifier Design 365 Depending on the namespace, managing the registry namespace may 366 follow certain guidelines. For numeric values, there may be certain 367 number ranges that are supposed to be used in certain ways. For 368 string values, there may be some convention or best practices on how 369 to mint identifiers so that the namespace contains values that are 370 following these principles. 372 Note that this is different from the design and usage review 373 Section 3.3. Whereas the design and usage review is about testing 374 whether the meaning associated with a new value follow the 375 constraints defined in the context that established the registry, the 376 identifier design simply checks for how the registered values are 377 chosen. It thus is a lower bar than a design and usage review, but 378 still requires a review process that allows to propose new values, 379 and provides some feedback about whether these values follow the 380 guidelines or not. 382 3.5. Identifier Lifecycle 384 The main reason for registries to exist in contrast to just including 385 a set of predefined values in the underlying specification itself is 386 the ability for these values to change over time. However, 387 registries only make sense if there is some sense of stability to 388 their contents, so that looking at existing registry values at some 389 point in time can be assumed to be a reasonable snapshot for some 390 amount of time. 392 Usually, registry entries are added at a modest pace, and an 393 implementation not supporting the latest additions shouldn't fail, 394 but simply implement some default behavior when encountering 395 unsupported values. This pattern ensures that the namespace can 396 evolve separately from the landscape of implementations. 398 However, adding identifiers is the easiest aspects of registry 399 updates. Things get more complicated when it comes to updating and 400 removing entries. The reason why these things are more complicated 401 is that implementations depending on an identifier having certain 402 semantics will behave incorrectly when the registry has been updated 403 for this identifier with either a change in semantics, or a 404 withdrawal of the entry. 406 For this reason, it often makes sense to include rules in the 407 management of the registry about if/how entries can be updated, or 408 removed. One popular approach is disallow updates with breaking 409 changes, and to allow withdrawal but keep the identifier and mark it 410 as "deprecated". This way it can be ensured that no incompatible 411 entry will be created by somebody using an identifier that was 412 previously used and removed. 414 The exact way how this process is defined depends on the context and 415 purpose of the registry, and also on the namespace size. Tightly 416 constrained namespaces mean that values probably should be managed 417 more carefully, so that the registry does not run out of values. 418 Also, while impossible to predict reliably, it is also important to 419 look at the possible lifetime of implementations (that will use 420 snapshots of the registry at some point in time), and on the long- 421 term effects of having outdated registry snapshots in 422 implementations. 424 3.6. Documentation Requirements 426 Registering a value means that people encountering this value should 427 be able to learn about what it represents. This means that there 428 should be documentation associated with it that can be used to learn 429 more about the value's meaning. Many registries at least require a 430 short explanation to be submitted with a registration request, so 431 that the registry itself can list those texts as helpful 432 explanations. 434 Going further, many registries also require links to more detailed 435 specifications, so that people looking for complete explanations of 436 the meaning of registered values can follow those links and will find 437 specifications or at least explanations. The exact requirement on 438 what such a link must refer to is something that the specification 439 creating the registry has to define. One popular requirement is that 440 it must be publicly available information, so that anybody looking 441 for it can openly access it. 443 3.7. Centralized Lookup 445 With a registry containing all current values (and possibly listing 446 changed/deprecated ones as well) along with some registration 447 metadata, they provide valuable information for anybody looking for 448 information about registered values in the registry namespace. All 449 IANA protocol registries [IANA-Protocol-Registry] are openly 450 accessible on the Web, allowing everybody to lookup the current state 451 of all these registries. 453 Even though centralized lookup is an important aspect of openness and 454 extensibility Section 3.1, the usual usage model of these lookup 455 facilities is to use them at design-time rather than at runtime 456 Section 6.8. This means that the central lookup facilities are meant 457 to be used by developers, and not by the implementations created by 458 those developers. For the latter model a much more scalable 459 infrastructure would be required, and thus it is important to 460 consider the fact if the namespace managed by a registry fits this 461 model of being useful for developer lookup at design-time, and for 462 value lookup at runtime. 464 4. When to use Registries 466 Based on the examples given in Section 2 and the possible reasons 467 described in Section 3, the next question is how for designers to 468 decide when they should establish one or more registries to 469 complement a specification. All the issues describes in Section 3 470 are reasonable motivations, and in many cases it is more than just 471 one of them. 473 For developers using a specification, it is helpful if the 474 specification clearly describes which reasons were most important 475 when deciding to establish one or more registries. This is even more 476 true for developers who are looking to update the registry, because 477 they should be aware of the reasons that were considered when the 478 registry was created. 480 For every registry that is established, it is helpful if a 481 specification explains the following general aspects: 483 What were the main design rationales behind establishing the 484 registry? The reasons described in Section 3 may be a good 485 starting point to pick from. 487 What are the management policies for the registry? Depending on a 488 variety of factors such as namespace size, expected frequency of 489 updated, level of review before acceptance, required level of 490 documentation, and possibly others, management can be rather 491 lightweight or a carefully managed process. 493 What is the size of the namespace and the expected rate of how it 494 will be used and possibly exhausted? 496 Even if it makes sense to establish a registry based on the reasons 497 given in Section 3, and if a specification makes use of this pattern, 498 it is possible that registries are a potential barrier to entry. 499 Section 5 discusses how these issues can be addressed. 501 5. Barrier to Entry Issues 503 For some of the reasons described in Section 3, specification authors 504 may decide to establish one or more registries, as described in 505 Section 4. However, it may be the case that having such a registry 506 can make it harder for developers to experiment with implementations 507 (without violating the specification), and/or that there should be a 508 more "lightweight" way for establishing some identifiers than for 509 others. 511 This section presents some design options for this issue, and 512 discusses how these design options are influenced by the registry's 513 identifier namespace, and the registration policy. 515 5.1. Non-Semantic/Reserved Entries 517 One possible approach is to explicitly reserve parts of the available 518 namespace for "non-semantic" purposes. This means that whenever such 519 a value is encountered, it is impossible to conclude based on this 520 value alone which concept it represents. Instead, the interpretation 521 of the value depends on additional information and/or on context, and 522 usually the exact mechanism is outside of the scope of the 523 specification. 525 One example for this method is the TCP/UDP port example given in 526 Section 2.1. The namespace for port numbers is two bytes and thus 527 numbers from 0 to 65535. However, numbers in the range 49152-65535 528 are considered to be "dynamic ports", and are reserved for uses that 529 are outside of the scope of registered values. 531 5.2. Entry Levels 533 A different pattern to differentiate values is to have different 534 "levels" that values can be registered for. This effectively 535 partitions the registry into different classes, which sometime follow 536 certain naming conventions, sometimes not. In the latter case, when 537 encountering a value, it is necessary to consult the registry to 538 understand which level a value is associated with. 540 The levels often carry differentiations in a variety of factors, such 541 as how established represented concepts are, how well and/or how open 542 they are documented, how the expected stability of the entry is, and 543 what level of scrutiny is applied during the review process when 544 registering a new value. Specifications have a wide latitude 545 defining those levels and specifying what they represent and how they 546 affect value semantics and registration procedures. 548 As one example, media types [RFC6838] establish a "standards tree" 549 and as well as other trees ("vendor" and "personal"). Entries in 550 these trees are distinguished by prefix or lack thereof. The general 551 idea is that the non-standard trees contain entries that are not 552 quite at the same level, significance-wise, as the standards tree. 554 As another example, URI schemes [RFC7595] differentiate registrations 555 into "permanent" and "provisional" schemes. In addition, URI schemes 556 can also be registered as being "historical". A "provisional" 557 registration is intended to be used in cases where URI deployment is 558 likely to happen outside of a private environment, but still 559 controlled by a private party. It is also possible to update a 560 registration from "provisional" to "permanent" once the associated 561 protocol has become stable or more widely deployed. 563 The classification of registry entries into "permanent" and 564 "provisional" is a pattern being followed by some IETF specifications 565 and registries as well, for example by the registration procedures 566 for message header fields [RFC3864]. 568 5.3. Separation by Value Syntax 570 While the examples given in Section 5.2 sometimes use ways to 571 differentiate entry levels by name, this is just a convenience so 572 that it is possible to determine a value's level by value syntax. In 573 this case, the value syntax is enforced by registration policy, 574 meaning that during the registration process it is ensured that when 575 a registration request for a certain level is made, the registered 576 value conforms to the required syntax. However, in this case, all 577 values still need to be registered. 579 A different approach is to separate the value range itself by syntax, 580 and only require registration for partitions of that range. For 581 example, link relation types as described in Section 2.3 allow 582 strings and URIs as values. For strings, it is expected that any 583 used values are registered. For URIs, however, no such registration 584 is required or even possible. This means that "private link relation 585 types" can be safely identified by URI values, and since it is 586 possible to make these dereferencable, it is also possible to make 587 these values self-documenting and/or self-describing by making human- 588 and/or machine-readable information available at that URI. 590 While this separation by value syntax can be useful, it is important 591 to note that by design, any approach that reflects value 592 classification through value syntax automatically means that values 593 cannot moved between categories. Renaming established and deployed 594 values is an expensive thing to do, which means that the approach of 595 separation by value syntax should be carefully considered, in 596 particular in light of the fact that it makes it impossible for 597 values to be moved between categories. This may be acceptable for 598 some scenarios, but may be undesirable in other. RFC 6648 [RFC6648] 599 discusses this problem starting from prefix-based value syntax 600 approaches (the famous "X-" for extension values), but is not limited 601 to discussing this prefix-based approach alone. 603 6. How to use Registries 605 If a specification does introduce registries as part of how the 606 specification divides static and dynamic parts, then it is 607 interesting to look at how those registries will actually be used. 608 As in the previous sections, the list of topics included here is not 609 necessarily mutually exclusive, and it is likely that for any 610 established registry, there is more than one way how the registry is 611 being used. 613 For authors of specifications establishing registries, the following 614 list of possible ways how a registry might be used may be a good 615 starting point to consider the design options for the registry, such 616 as how to design the submission and update process, and how to 617 provide access to registry contents. 619 6.1. Registry Operations 621 A registry is an abstract idea, mostly consisting of a separation of 622 a stable and fixed specifications, and associated registry-based 623 values that can be looked up and which may change over time. How a 624 registry is operated is a different matter. This is true for both 625 the workflows associated with registry operations, and the technical 626 implementation of those workflows. 628 For both the workflows, and their technical implementation, there are 629 a large number of issues to consider, and a large number of possible 630 solutions that satisfy those issues. For an organization like the 631 IETF, with a substantial stream of technical specifications, it makes 632 a lot of sense to establish both a common workflow, and a common 633 implementation, so that specifications can rely on this 634 infrastructure, instead of having to re-invent registry operations 635 every time they want to establish a registry. 637 In the context of IETF specifications, registries are typically 638 maintained by the "Internet Assigned Numbers Authority (IANA)". 639 Since there is a large number of registries, and they should be 640 maintained in a coherent, systematic, and efficient way, there is a 641 set of "Principles for Operation of Internet Assigned Numbers 642 Authority (IANA) Registries" which are described in RFC 7500 643 [RFC7500]. The key principles are defined as follows: 645 Ensure Uniqueness: The same protocol identifier must not be used 646 for more than one purpose. 648 Stable: Protocol identifier assignment must be lasting. 650 Predictable: The process for making assignments must not include 651 unexpected steps. 653 Public: The protocol identifiers must be made available in well- 654 known locations in a manner that makes them freely available to 655 everyone. 657 Open: The process that sets the policy for protocol identifier 658 assignment and registration must be open to all interested 659 parties. 661 Transparent: The protocol registries and their associated policies 662 should be developed in a transparent manner. 664 Accountable: Registry policy development and registry operations 665 need to be accountable to the affected community. 667 The way RFC 7500 currently defines operational principles leaves some 668 possible issues open. For example, the principle of the identifiers 669 being "public" is described as the identifiers being "freely 670 available to everyone without restrictions." This means that it is 671 sufficient to make the identifiers available in human-readable form, 672 as opposed to the more specific ways in which machine-readable access 673 (as discussed in Section 6.7) would have to be enabled and possibly 674 managed. 676 While the exact requirements for a registry can be spelled out in the 677 "IANA Considerations" section of a specification establishing a 678 registry (see Section 6.2), there are hard limitations based on the 679 current implementation which is hosted by IANA. It is possible that 680 a different model may be implemented at a later time, but the current 681 model is biased towards email-based workflows and human-readable 682 registry access. If specification authors feel that IANA's 683 implementation will not fit their needs, then it is (at least 684 theoretically) possible for a specification to define its own 685 registry operations and infrastructure, but that would require a lot 686 of effort for a 688 6.2. Registry Creation 690 If a specification creates one or more registries, then RFC 5226 691 [RFC5226] sets some guidelines for the setup process and the 692 substance of each registry. Without repeating those guidelines here, 693 it should suffice to mention that those revolve around possible 694 status labels for assigned values (private use, experimental, 695 unassigned, reserved), and a number of predefined policies that 696 define how a registry is managed. RFC 5226 also mentions the fact 697 that a registry's management policy can change, in which case a new 698 specification is required that updates the definition of the 699 registry. 701 6.3. Registry Interaction 703 Since registry contents establish a controlled vocabulary, and each 704 registry has some policies around how that vocabulary can be updated, 705 it usually makes sense to have a template or a form that allows 706 applicants to prepare and submit update requests. It is up to the 707 registry to define how detailed this template is, whether applicants 708 are required to use it, and whether submission is implemented based 709 on that template. RFC 5226 [RFC5226] provides guidelines for 710 specification writers how to include any registry interactions in 711 their documents. 713 Following some structure in the interaction process help with keeping 714 a better record of requested and performed updates of a registry, 715 which can be helpful when it comes to maintaining and providing a 716 registry history Section 6.6. 718 6.4. Implementation Support 720 The usual pattern for using registry-based identifiers in 721 implementations is to support some snapshot of the registry, which 722 either can be complete, or just a subset of the registry contents. 723 Implementation support then is based on the semantics associated with 724 registry values at the time of this snapshot. This means that any 725 registry updates changing semantics will affect and possibly break 726 those implementations, unless there is a strong policy to only allow 727 backwards-compatible changes to identifier semantics. 729 6.5. Registry Stability 731 Since implementations often use registries based on snapshots 732 Section 6.4, a key issue for registries is the stability of entries. 733 While it is clear that new entries can be added (this after all is 734 the minimal use case of registries: the ability to add identifiers 735 without the need for updating the specification itself), things get 736 more complicated when it comes to updates of existing entries, or 737 removal of exiting entries. 739 When it comes to updating entries, then often the goal is to avoid 740 breaking changes. This means that entries can only be updated in a 741 way that the updated semantics are backwards-compatible with the old 742 semantics. This way, implementations based on the old semantics can 743 safely use those and will not conflict when encountering data or 744 implementations assuming the updated semantics. 746 In terms of removal, it also is important to consider whether removed 747 entries should remain registered and blocked for future 748 registrations, so that they cannot be re-used (which essentially 749 would be equivalent to making a breaking change to an existing 750 entry). If such a policy is in-place, then technically speaking 751 there is no actual "removal" of a value rom the registry. Instead, a 752 value can be updated to be deprecated, but it remains in the registry 753 so that it is not re-assigned. 755 6.6. Registry History 757 While not strictly necessary for registry usage and management, in 758 terms of openness and transparency it can be helpful to provide a 759 registry history. This way it is possible to recreate all actions 760 that changed the registry, and to reconstruct the state of the 761 registry at any point in time. 763 Some registries have mailing lists associated with them which can be 764 regarded as some sort of history. However, this is a weak form of 765 history since reconstructing the registry history and its state 766 requires to read all the emails, and infer the resulting registry 767 actions. Having access to the actual actions in machine-readable 768 form can make it much easier to access and recreate registry history. 770 Since registry usually are highly structured (often tabular models 771 with small number of columns), they would lend themselves well to 772 representing any updates to the contents in a similarly structured 773 way, along with some metadata about the entry update (such as date, 774 applicant, expert, links to email archives, and similar ways to 775 contextualize the entry update). 777 6.7. Registry Access 779 Depending on the intended use of a registry, an important question is 780 how developers and/or implementations can access the registry. While 781 the current IANA registries can be accessed via HTTP, they are 782 clearly intended and designed to be used as human-readable HTML pages 783 for developers. Alternative or complementary models could provide 784 API-based access, with documented and stable ways how to provide 785 machine-based access to registry contents. 787 However, if an API is considered and provided, then an important 788 question is whether it is intended for accessing registry contents 789 only, or providing full-fledged access to all services of the 790 registry, such as updates Section 6.3 or history access Section 6.6. 791 The former kind of access is easier to accomplish, because the sets 792 of provided is smaller, and the requirements for authentication and 793 authorization are probably simpler. 795 In addition to the question of how the registry API would be 796 designed, a more important question may be how it would be managed. 797 Any Internet-wide registry that provided API access would have to 798 carefully consider the implications of providing such a service, 799 mostly in terms of registry operations. Such as API could easily 800 become overloaded, and then would become a possible point of failure. 801 Also, it could become a point of attack, both in terms of denial or 802 service attacks, or in attempts to use the API to access the registry 803 in unauthorized ways. 805 6.8. Runtime vs. Design-Time 807 Most implementations use registry snapshots (complete or partial) for 808 using a registry's contents Section 6.4. If a registry provides API 809 access, then it would be possible to author implementations that use 810 registry contents at runtime. However, there are two important 811 concerns about this possibility: 813 Having access to registry contents may be of little use other than 814 learning about the existence of new identifiers. In most cases, a 815 registry entry alone will not be sufficient to understand the 816 semantics of a new entry encountered at runtime. If that is the 817 case, then all an implementation can do is to verify that it 818 encountered a new entry that is a valid identifier according to 819 the current registry state, but it cannot implement the behavior 820 associated with that new entry. 822 If the model of the registry allows meaningful implementation 823 behavior by runtime updates, then this can result in this registry 824 becoming overwhelmed by the number of accesses. After all, 825 dynamic implementation behavior then may be preferable over the 826 more traditional snapshot implementation pattern, which then 827 results in the majority of implementations converging to the 828 runtime access model. 830 Because of the second issue in particular, any registry supporting 831 and intended for runtime access should make sure that provisions are 832 in place to control registry access. This is no different from any 833 other service on the Internet or Web that also needs to have 834 mechanisms in place to protect itself against suffering under too 835 much load. 837 7. IANA Considerations 839 This document has no IANA actions. 841 8. References 843 [IANA-Protocol-Registry] 844 "IANA Protocol Registry", . 846 [ISO.639.1988] 847 International Organization for Standardization, "Code for 848 the representation of names of languages, 1st edition", 849 ISO Standard 639, 1988. 851 [RFC1034] Mockapetris, P., "Domain names - concepts and facilities", 852 STD 13, RFC 1034, DOI 10.17487/RFC1034, November 1987, 853 . 855 [RFC1035] Mockapetris, P., "Domain names - implementation and 856 specification", STD 13, RFC 1035, DOI 10.17487/RFC1035, 857 November 1987, . 859 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 860 Procedures for Message Header Fields", BCP 90, RFC 3864, 861 DOI 10.17487/RFC3864, September 2004, 862 . 864 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 865 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 866 DOI 10.17487/RFC5226, May 2008, 867 . 869 [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying 870 Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, 871 September 2009, . 873 [RFC6335] Cotton, M., Eggert, L., Touch, J., Westerlund, M., and S. 874 Cheshire, "Internet Assigned Numbers Authority (IANA) 875 Procedures for the Management of the Service Name and 876 Transport Protocol Port Number Registry", BCP 165, 877 RFC 6335, DOI 10.17487/RFC6335, August 2011, 878 . 880 [RFC6648] Saint-Andre, P., Crocker, D., and M. Nottingham, 881 "Deprecating the "X-" Prefix and Similar Constructs in 882 Application Protocols", BCP 178, RFC 6648, 883 DOI 10.17487/RFC6648, June 2012, 884 . 886 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 887 Specifications and Registration Procedures", BCP 13, 888 RFC 6838, DOI 10.17487/RFC6838, January 2013, 889 . 891 [RFC7500] Housley, R., Ed. and O. Kolkman, Ed., "Principles for 892 Operation of Internet Assigned Numbers Authority (IANA) 893 Registries", RFC 7500, DOI 10.17487/RFC7500, April 2015, 894 . 896 [RFC7595] Thaler, D., Ed., Hansen, T., and T. Hardie, "Guidelines 897 and Registration Procedures for URI Schemes", BCP 35, 898 RFC 7595, DOI 10.17487/RFC7595, June 2015, 899 . 901 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 902 DOI 10.17487/RFC8288, October 2017, 903 . 905 Appendix A. W3C Examples 907 As an example of when registries can be useful, this appendix lists 908 "registries" defined by the World Wide Web Consortium (W3C). The W3C 909 does not currently have a registry model such as IETF's IANA, and 910 thus W3C specification authors have to come up with the own solutions 911 how to define and manage evolving sets of values. 913 The following list is not meant to be complete, but it does highlight 914 that a lack of registry capabilities in larger organizations can lead 915 to the "registry problem" being approached and solved in a variety of 916 ways, each of them requiring their own processes and infrastructure, 917 and each of them having their own side-effects. 919 Over time, various W3C specifications have used managed lists of 920 values. One of these specifications already is a stable 921 specification, it is the "XPointer" specification. XPointer has a 922 scheme registry which is managed as a manually updated Web page, 923 which has a documented registry policy. 925 Of the W3C drafts under development, one common model is to define 926 the values in a separate document, and then to evolve this document. 927 This has the advantage of decoupling the actual specification from 928 the set of managed values. The downside is that value evolution now 929 is based on the process defined for W3C documents, event though 930 that's not primarily the intention and the goal. 932 When following this approach, one set of specifications defines the 933 values in a Working Draft (WD) document. Here are the current W3C 934 specifications following this approach: 936 o Identifiers for WebRTC's Statistics API 938 o UI Events KeyboardEvent code Values 940 o UI Events KeyboardEvent key Values 942 o Basic Card Payment 944 o Payment Method Identifiers 946 A second set of specifications also uses a separately evolved 947 document, but manages this as a Note (NOTE) document. Here are the 948 current W3C specifications following this approach: 950 o Encrypted Media Extensions Stream Format Registry 952 o TTML Media Type Definition and Profile Registry 953 o Media Source Extensions Byte Stream Format Registry 955 o Trace Context Protocols Registry 957 Another approach is to keep the values inside the specification 958 itself. This has the side-effect that any change in the "registered" 959 values requires a change of the complete specification, which usually 960 is one is trying to avoid when identifying a potentially evolving set 961 of values. Here are the current W3C specifications following this 962 approach: 964 o Performance Timeline Level 2: entryType 966 o Permissions: Permission Registry 968 And finally, the last practice seen in W3C specifications is to use a 969 wiki as the managed list of values. Here are the current W3C 970 specifications following this approach: 972 o Web App Manifest Platform Values (wiki is located on GitHub) 974 As can be seen from this list of practices, in larger organizations 975 it can become increasingly useful to support registries as a model of 976 how to define and manage evolving sets of values. Whether or not 977 this results in an organization creating and managing their own 978 registry infrastructure is one question. But apart from that, at 979 least identifying this as an issue that various teams are facing in 980 the organization, and giving them guidance on how to solve it, can 981 already help to better support teams, and avoid a fragmentation of 982 approaches that all create their own side-effects and technical debt 983 in the long run. 985 Appendix B. Acknowledgements 987 Thanks for comments and suggestions provided by John Curran, Doug 988 Ewell, Graham Klyne, and Andrew Malis. 990 Author's Address 992 Erik Wilde 994 Email: erik.wilde@dret.net 995 URI: http://dret.net/netdret/