idnits 2.17.1 draft-loffredo-regext-rdap-jcard-deprecation-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 : ---------------------------------------------------------------------------- ** There is 1 instance of too long lines in the document, the longest one being 15 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (May 28, 2020) is 1422 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 7482 (Obsoleted by RFC 9082) ** Obsolete normative reference: RFC 7483 (Obsoleted by RFC 9083) Summary: 3 errors (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Registration Protocols Extensions M. Loffredo 3 Internet-Draft IIT-CNR/Registro.it 4 Intended status: Standards Track G. Brown 5 Expires: November 29, 2020 CentralNic Group plc 6 May 28, 2020 8 Using JSContact in Registration Data Access Protocol (RDAP) JSON 9 Responses 10 draft-loffredo-regext-rdap-jcard-deprecation-02 12 Abstract 14 This document describes an RDAP extension which represents entity 15 contact information in JSON responses using JSContact. 17 Status of This Memo 19 This Internet-Draft is submitted in full conformance with the 20 provisions of BCP 78 and BCP 79. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF). Note that other groups may also distribute 24 working documents as Internet-Drafts. The list of current Internet- 25 Drafts is at https://datatracker.ietf.org/drafts/current/. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 This Internet-Draft will expire on November 29, 2020. 34 Copyright Notice 36 Copyright (c) 2020 IETF Trust and the persons identified as the 37 document authors. All rights reserved. 39 This document is subject to BCP 78 and the IETF Trust's Legal 40 Provisions Relating to IETF Documents 41 (https://trustee.ietf.org/license-info) in effect on the date of 42 publication of this document. Please review these documents 43 carefully, as they describe your rights and restrictions with respect 44 to this document. Code Components extracted from this document must 45 include Simplified BSD License text as described in Section 4.e of 46 the Trust Legal Provisions and are provided without warranty as 47 described in the Simplified BSD License. 49 Table of Contents 51 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 52 1.1. Rationale . . . . . . . . . . . . . . . . . . . . . . . . 2 53 1.2. Conventions Used in This Document . . . . . . . . . . . . 3 54 2. JSContact . . . . . . . . . . . . . . . . . . . . . . . . . . 3 55 3. Using JSCard objects in RDAP Responses . . . . . . . . . . . 4 56 3.1. RDAP Query Parameters . . . . . . . . . . . . . . . . . . 6 57 4. Transition Considerations . . . . . . . . . . . . . . . . . . 7 58 4.1. RDAP Features Supporting a Transition Process . . . . . . 7 59 4.1.1. Notices and Link Relationships . . . . . . . . . . . 7 60 4.1.2. rdapConformance Property . . . . . . . . . . . . . . 7 61 4.1.3. Query Parameters . . . . . . . . . . . . . . . . . . 7 62 4.2. Transition Procedure . . . . . . . . . . . . . . . . . . 7 63 4.2.1. Transition Stages . . . . . . . . . . . . . . . . . . 7 64 4.2.1.1. Stage 1: only jCard provided . . . . . . . . . . 8 65 4.2.1.2. Stage 2: jCard sunset . . . . . . . . . . . . . . 8 66 4.2.1.3. Stage 3: jCard deprecation . . . . . . . . . . . 9 67 4.2.1.4. Stage 4: jCard deprecated . . . . . . . . . . . . 11 68 4.2.1.5. Length . . . . . . . . . . . . . . . . . . . . . 11 69 4.2.1.6. Goals . . . . . . . . . . . . . . . . . . . . . . 11 70 5. Implementation Status . . . . . . . . . . . . . . . . . . . . 11 71 5.1. IIT-CNR/Registro.it . . . . . . . . . . . . . . . . . . . 12 72 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 73 7. Security Considerations . . . . . . . . . . . . . . . . . . . 13 74 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 13 75 8.1. Normative References . . . . . . . . . . . . . . . . . . 13 76 8.2. Informative References . . . . . . . . . . . . . . . . . 14 77 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 14 78 A.1. Change from 00 to 01 . . . . . . . . . . . . . . . . . . 14 79 A.2. Change from 01 to 02 . . . . . . . . . . . . . . . . . . 15 80 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 15 82 1. Introduction 84 This document specifies an extension to the Registration Data Access 85 Protocol (RDAP) that allows RDAP servers to use JSContact 86 ([draft-ietf-jmap-jscontact]) to represent the contact information 87 associated with entities in RDAP responses, instead of jCard 88 ([RFC7095]). It also describes the process by which an RDAP server 89 can transition from jCard to JSContact. RDAP query and response 90 extensions are defined to facilitate the transition process. 92 1.1. Rationale 94 According to the feedback from RDAP Pilot Working Group 95 ([RDAP-PILOT-WG], a group of RDAP server implementers representing 96 registries and registrars of generic TLDs), the most commonly raised 97 implementation concern, for both servers and client implementers, 98 related to the use of jCard ([RFC7095]) to represent the contact 99 information associated with entities. Working Group members reported 100 jCard to be unintuitive, complicated to implement for both clients 101 and servers, and incompatible with best practices for RESTful APIs. 103 JSContact ([draft-ietf-jmap-jscontact]) provides a simpler and more 104 efficient representation for contact information. In addition, 105 similarly to jCard, it provides a means to represent 106 internationalised and unstructured contact information. Support for 107 internationalised contact information has been recognised being 108 necessary to facilitate the future internationalisation of 109 registration data directory services. 111 1.2. Conventions Used in This Document 113 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 114 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 115 document are to be interpreted as described in [RFC2119]. 117 2. JSContact 119 The JSContact specification defines a data model and JSON 120 representation of contact information that can be used for data 121 storage and exchange in address book or directory applications. It 122 aims to be an alternative to the vCard data format ([RFC6350]) and to 123 be unambiguous, extendable and simple to process. In contrast with 124 jCard, it is not a direct mapping from the vCard data model and 125 expands semantics where appropriate. 127 The JSContact specification declares two main object types: "JSCard", 128 which represents a single contact "card", and "JSCardGroup" which 129 represents a collection of JSCard objects. For the purpose of this 130 document, only JSCard objects are considered. 132 JSCard differs from jCard in that it: 134 o follows an object-oriented rather than array-oriented approach; 136 o is simple to process; 138 o requires no extra work in serialization/deserialization from/to a 139 data model; 141 o includes no "jagged" arrays; 143 o prefers maps rather than arrays to implement collections; 144 o is able to represent redacted contacts (both "name" and"fullName" 145 properties are optional). 147 [draft-loffredo-jmap-jscontact-vcard] provides informational guidance 148 on the conversion of jCard objects into JSCard objects, and vice 149 versa. 151 3. Using JSCard objects in RDAP Responses 153 Entity objects in RDAP responses MAY include a "jscard" property 154 whose value is a JSCard object instead of the "vCardArray" property 155 defined in [RFC7483]. 157 Servers returning the "jscard" property in their response MUST 158 include "jscard" in the "rdapConformance" array. 160 An example of an RDAP response containing a "jscard" property is 161 shown in Figure 1. The "jscard" object in this example has been 162 converted from the example included in section 5.1 of [RFC7483]. 164 { 165 "rdapConformance": [ 166 "rdap_level_0", 167 "jscard" 168 ], 169 "objectClassName" : "entity", 170 "handle":"XXXX", 171 "jscard":{ 172 "uid": "XXXX", 173 "fullName": { "value": "Joe User" }, 174 "kind": "individual", 175 "preferredContactLanguages": { 176 "fr": { "preference": 1 }, 177 "en": { "preference": 2 } 178 }, 179 "organization": [ { "value": "Example" } ], 180 "jobTitle": [ { "value": "Research Scientist" } ], 181 "role": [ { "value": "Project Lead" } ], 182 "addresses": [ 183 { 184 "context": "work", 185 "extension": "Suite 1234", 186 "street": "4321 Rue Somewhere", 187 "locality": "Quebec", 188 "region": "QC", 189 "postcode": "G1V 2M2", 190 "country": "Canada", 191 "coordinates": "geo:46.772673,-71.282945", 192 "timeZone": "Canada/Eastern" 193 }, 194 { 195 "context": "private", 196 "fullAddress": { 197 "value": "123 Maple Ave\nSuite 90001\nVancouver\nBC\n1239\n" 198 } 199 } 200 ], 201 "phones": [ 202 { 203 "context": "work", 204 "type": "voice", 205 "labels": { 206 "cell": true, 207 "video": true, 208 "text": true 209 }, 210 "isPreferred": true, 211 "value": "tel:+1-555-555-1234;ext=102" 212 } 213 ], 214 "emails": [ 215 { 216 "context": "work", 217 "value": "joe.user@example.com" 218 } 219 ], 220 "online": [ 221 { 222 "context": "work", 223 "type": "uri", 224 "labels": { "key": true }, 225 "value": "http://www.example.com/joe.user/joe.asc" 226 }, 227 { 228 "context": "private", 229 "type": "uri", 230 "labels": { "url": true }, 231 "value": "http://example.org" 232 } 233 ] 234 } 235 "roles":[ "registrar" ], 236 "publicIds":[ 237 { 238 "type":"IANA Registrar ID", 239 "identifier":"1" 241 } 242 ], 243 "remarks":[ 244 { 245 "description":[ 246 "She sells sea shells down by the sea shore.", 247 "Originally written by Terry Sullivan." 248 ] 249 } 250 ], 251 "links":[ 252 { 253 "value":"http://example.com/entity/XXXX", 254 "rel":"self", 255 "href":"http://example.com/entity/XXXX", 256 "type" : "application/rdap+json" 257 } 258 ], 259 "events":[ 260 { 261 "eventAction":"registration", 262 "eventDate":"1990-12-31T23:59:59Z" 263 } 264 ], 265 "asEventActor":[ 266 { 267 "eventAction":"last changed", 268 "eventDate":"1991-12-31T23:59:59Z" 269 } 270 ] 271 } 273 Figure 1: Example of "jscard" in RDAP response 275 3.1. RDAP Query Parameters 277 Two new query parameters are defined for the purpose of this 278 document. 280 The query parameters are OPTIONAL extensions of path segments defined 281 in [RFC7482]. They are as follows: 283 o "jscard": a boolean value that allows a client to request the 284 "jscard" property in the RDAP response; 286 o "jcard": a boolean value that allows a client to request the 287 "vcardArray" property in the RDAP response. 289 These parameters are furtherly explained in Section 4. 291 4. Transition Considerations 293 4.1. RDAP Features Supporting a Transition Process 295 4.1.1. Notices and Link Relationships 297 RDAP allows servers to communicate service information to clients 298 through notices. An RDAP response may contain one or more notice 299 objects ([RFC7483], Section 4.3), each of which may include a set of 300 link objects, which can be used to provide clients with references 301 and documentation. These link objects may have a "rel" property 302 which defines the relationship type, as described in [RFC8288], 303 Section 4. The transition process outlined in this document uses two 304 types of link relation: 306 o "deprecation", as described in [draft-dalal-deprecation-header]; 308 o "alternate", as described in [RFC8288]. 310 4.1.2. rdapConformance Property 312 The information about the specifications used in the construction of 313 the response is also described by the strings which appear in the 314 "rdapConformance" property of the RDAP response. 316 4.1.3. Query Parameters 318 Clients are able to ask servers to use specific RDAP features by 319 using appropriate query parameters as described in [RFC7482]. 321 4.2. Transition Procedure 323 The procedure for jCard to JSCard transition consists of four 324 contiguous stages. During the procedure, the presence of "jscard" 325 tag in the rdapConformance array indicates that JSCard is returned 326 instead of jCard. The time format used to notify clients about this 327 procedure is defined in [RFC3339]. 329 Some elements of the following procedure are based on the best 330 practices in [API-DEPRECATION]. 332 4.2.1. Transition Stages 333 4.2.1.1. Stage 1: only jCard provided 335 This stage corresponds to providing jCard as default contact card 336 ([RFC7483]). The RDAP server is not able to provide an alternate 337 contact card. The rdapConformance array MUST NOT contain the 338 "jscard" tag. 340 4.2.1.2. Stage 2: jCard sunset 342 During this stage, the server uses jCard by default, but the RDAP 343 server will return JSCard if the client sets the query parameter 344 "jscard" to a true value. The rdapConformance array MUST contain the 345 "jscard" tag if JSCard is requested. 347 The RDAP server SHOULD include a notice titled "jCard sunset end". 348 Such a notice should include a description reporting the jCard sunset 349 end time and two links: 351 o "deprecation": a link to a URI-identified resource documenting the 352 jCard deprecation; 354 o "alternate": if JSCard is not requested, a link to the JSCard 355 version of same resource as identified by the current query string 356 plus the parameter "jscard" set to a true value (Figure 2); 357 otherwise, only the "deprecation" link is provided (Figure 3). 359 "notices": [ 360 { 361 "title": "jCard sunset end", 362 "description": ["2020-07-01T00:00:00Z"], 363 "links": [{ 364 "value": "http://example.net/entity/XXXX", 365 "rel": "deprecation", 366 "type": "text/html", 367 "href": "http://www.example.com/jcard_deprecation.html" 368 }, 369 { 370 "value": "http://example.net/entity/XXXX", 371 "rel": "alternate", 372 "type": "application/rdap+json", 373 "href": " http://example.net/entity/XXXX?jscard=1" 374 } 375 ] 376 } 377 ] 379 Figure 2: jCard sunset - JSCard not requested 381 "notices": [ 382 { 383 "title": "jCard sunset end", 384 "description": ["2020-07-01T00:00:00Z"], 385 "links": [ 386 { 387 "value": "http://example.net/entity/XXXX?jscard=1", 388 "rel": "deprecation", 389 "type": "text/html", 390 "href": "http://www.example.com/jcard_deprecation.html" 391 } 392 ] 393 } 394 ] 396 Figure 3: jCard sunset - JSCard requested 398 4.2.1.3. Stage 3: jCard deprecation 400 This stage corresponds to the provisioning of JSCard by default, but 401 the RDAP will return jCard if the client sets the query parameter 402 "jcard" to a true value. The rdapConformance array contains the 403 "jscard" tag unless jCard is requested. The "jscard" query parameter 404 is ignored. 406 The RDAP server SHOULD to return a notice titled "jCard deprecation 407 end". Such a notice should include a description reporting the jCard 408 deprecation end time and two links: 410 o "deprecation": a link to a URI-identified resource documenting the 411 jCard deprecation; 413 o "alternate": if jCard is not requested, a link to the jCard 414 version of the same resource as identified by the current query 415 string plus the parameter "jcard" set to 1/true/yes (Figure 4); 416 otherwise, a link to the JSCard version of the same resource as 417 identified by the current query string without the parameter 418 "jcard" (Figure 5). 420 "notices": [ 421 { 422 "title": "jCard deprecation end", 423 "description": ["2020-12-31T23:59:59Z"], 424 "links": [ 425 { 426 "value": "http://example.net/entity/XXXX", 427 "rel": "deprecation", 428 "type": "text/html", 429 "href": "http://www.example.com/jcard_deprecation.html" 430 }, 431 { 432 "value": "http://example.net/entity/XXXX", 433 "rel": "alternate", 434 "type": "application/rdap+json", 435 "href": " http://example.net/entity/XXXX?jcard=1" 436 } 437 ] 438 } 439 ] 441 Figure 4: jCard deprecation - jCard not requested 443 "notices": [ 444 { 445 "title": "jCard deprecation end", 446 "description": ["2020-12-31T23:59:59Z"], 447 "links": [ 448 { 449 "value": "http://example.net/entity/XXXX?jcard=1", 450 "rel": "deprecation", 451 "type": "text/html", 452 "href": "http://www.example.com/jcard_deprecation.html" 453 }, 454 { 455 "value": "http://example.net/entity/XXXX?jcard=1", 456 "rel": "alternate", 457 "type": "application/rdap+json", 458 "href": " http://example.net/entity/XXXX" 459 } 460 ] 461 } 462 ] 464 Figure 5: jCard deprecation - jCard requested 466 4.2.1.4. Stage 4: jCard deprecated 468 This stage corresponds to providing JSCard as default contact card. 469 The RDAP server is not able to provide an alternate contact card. 470 The rdapConformance array always contains "jscard" tag. The RDAP 471 server doesn't include any notice about the jCard deprecation 472 process. Both "jscard" and "jcard" query parameters are ignored. 474 4.2.1.5. Length 476 The length of both jCard sunset and jCard deprecation periods are not 477 fixed by this specification. Best practices in REST API deprecation 478 suggest that, depending on the deprecated API's reach, user base and 479 service offering, a convenient time could be anywhere between 3 - 8 480 months. Anyway, RDAP providers are recommended to monitor the server 481 log to figure out whether declared times need to be changed to meet 482 client requirements. 484 4.2.1.6. Goals 486 The procedure described in this document achieves the following 487 goals: 489 o only one contact representation would be included in the response; 491 o the response would always be compliant to [RFC7483]; 493 o clients would be informed about the transition timeline; 495 o the backward compatibility would be guaranteed throughout the 496 transition; 498 o servers and clients could execute their transitions independently. 500 5. Implementation Status 502 NOTE: Please remove this section and the reference to RFC 7942 prior 503 to publication as an RFC. 505 This section records the status of known implementations of the 506 protocol defined by this specification at the time of posting of this 507 Internet-Draft, and is based on a proposal described in RFC 7942 508 [RFC7942]. The description of implementations in this section is 509 intended to assist the IETF in its decision processes in progressing 510 drafts to RFCs. Please note that the listing of any individual 511 implementation here does not imply endorsement by the IETF. 512 Furthermore, no effort has been spent to verify the information 513 presented here that was supplied by IETF contributors. This is not 514 intended as, and must not be construed to be, a catalog of available 515 implementations or their features. Readers are advised to note that 516 other implementations may exist. 518 According to RFC 7942, "this will allow reviewers and working groups 519 to assign due consideration to documents that have the benefit of 520 running code, which may serve as evidence of valuable experimentation 521 and feedback that have made the implemented protocols more mature. 522 It is up to the individual working groups to use this information as 523 they see fit". 525 5.1. IIT-CNR/Registro.it 527 Responsible Organization: Institute of Informatics and Telematics 528 of National Research Council (IIT-CNR)/Registro.it 530 Location: https://rdap.pubtest.nic.it/ 532 Description: This implementation includes support for RDAP queries 533 using data from the public test environment of .it ccTLD. 535 Level of Maturity: This is a "proof of concept" research 536 implementation. 538 Coverage: This implementation includes all of the features 539 described in this specification. 541 Contact Information: Mario Loffredo, mario.loffredo@iit.cnr.it 543 6. IANA Considerations 545 IANA is requested to register the following values in the RDAP 546 Extensions Registry: 548 Extension identifier: jscard 550 Registry operator: Any 552 Published specification: This document. 554 Contact: IESG 556 Intended usage: This extension represents a contact card provided 557 in an RDAP response according to the JSContact specification 558 ([draft-ietf-jmap-jscontact]). 560 7. Security Considerations 562 Unlike jCard, the formatted name as well as any other personally 563 identifiable information is not required in JSCard. The only 564 mandatory property, namely "uid", is usually an opaque string. 565 Therefore, redacted properties can be merely excluded without using 566 placeholder values. 568 8. References 570 8.1. Normative References 572 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 573 Requirement Levels", BCP 14, RFC 2119, 574 DOI 10.17487/RFC2119, March 1997, 575 . 577 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 578 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 579 . 581 [RFC6350] Perreault, S., "vCard Format Specification", RFC 6350, 582 DOI 10.17487/RFC6350, August 2011, 583 . 585 [RFC7095] Kewisch, P., "jCard: The JSON Format for vCard", RFC 7095, 586 DOI 10.17487/RFC7095, January 2014, 587 . 589 [RFC7482] Newton, A. and S. Hollenbeck, "Registration Data Access 590 Protocol (RDAP) Query Format", RFC 7482, 591 DOI 10.17487/RFC7482, March 2015, 592 . 594 [RFC7483] Newton, A. and S. Hollenbeck, "JSON Responses for the 595 Registration Data Access Protocol (RDAP)", RFC 7483, 596 DOI 10.17487/RFC7483, March 2015, 597 . 599 [RFC7942] Sheffer, Y. and A. Farrel, "Improving Awareness of Running 600 Code: The Implementation Status Section", BCP 205, 601 RFC 7942, DOI 10.17487/RFC7942, July 2016, 602 . 604 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 605 DOI 10.17487/RFC8288, October 2017, 606 . 608 8.2. Informative References 610 [API-DEPRECATION] 611 Sandoval, K., "How to Smartly Sunset and Deprecate APIs", 612 August 2019, . 616 [draft-dalal-deprecation-header] 617 Dalal, S. and E. Wilde, "The Deprecation HTTP Header 618 Field", . 621 [draft-ietf-jmap-jscontact] 622 Stepanek, R. and M. Loffredo, "JSContact: A JSON 623 representation of contact data", 624 . 627 [draft-loffredo-jmap-jscontact-vcard] 628 Loffredo, M. and R. Stepanek, "JSContact: Converting from 629 and to vCard", . 632 [RDAP-PILOT-WG] 633 ICANN RDAP Pilot WG, "RDAP Pilot Report", April 2019, 634 . 637 Appendix A. Change Log 639 A.1. Change from 00 to 01 641 1. Changed category from "Best Current Practice" to "Standards 642 Track" 644 2. Replaced the example of Figure 1 646 3. Changed the title of the "Migration from JCard to JSCard" 647 section to "Transition Considerations" 649 4. Added Section 3.1 651 5. Updated Section 6 653 6. Updated Section 7 655 7. Rearranged the description of stage 1 in Section 4.2.1 656 8. Changed the names of the transition stages 1 and 2 658 9. Corrected Figure 2, Figure 4, Figure 5 660 10. Changed the rdapConformance tag "jscard_level_0" to "jscard" 662 11. Removed the "Best Practices for deprecating a REST API features" 663 section, but added a useful reference. 665 A.2. Change from 01 to 02 667 1. Removed the sentence "which cannot be represented using jCard" in 668 Section 1.1. 670 Authors' Addresses 672 Mario Loffredo 673 IIT-CNR/Registro.it 674 Via Moruzzi,1 675 Pisa 56124 676 IT 678 Email: mario.loffredo@iit.cnr.it 679 URI: http://www.iit.cnr.it 681 Gavin Brown 682 CentralNic Group plc 683 Saddlers House, 44 Gutter Lane 684 London, England EC2V 6BR 685 GB 687 Phone: +44 20 33 88 0600 688 Email: gavin.brown@centralnic.com 689 URI: https://www.centralnic.com