idnits 2.17.1 draft-loffredo-regext-rdap-jcard-deprecation-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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (March 23, 2020) is 1495 days in the past. Is this intentional? Checking references for intended status: Best Current Practice ---------------------------------------------------------------------------- (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: 2 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: Best Current Practice G. Brown 5 Expires: September 24, 2020 CentralNic Group plc 6 March 23, 2020 8 Using JSContact in Registration Data Access Protocol (RDAP) JSON 9 Responses 10 draft-loffredo-regext-rdap-jcard-deprecation-00 12 Abstract 14 This document describes how RDAP servers can represent entity contact 15 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 September 24, 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 4. Migration from JCard to JSCard . . . . . . . . . . . . . . . 4 57 4.1. Best Practices for deprecating a REST API features . . . 5 58 4.2. RDAP Features Supporting a Deprecation Process . . . . . 5 59 4.3. jCard Deprecation Procedure . . . . . . . . . . . . . . . 6 60 4.3.1. Stages . . . . . . . . . . . . . . . . . . . . . . . 6 61 4.3.2. Length . . . . . . . . . . . . . . . . . . . . . . . 9 62 4.3.3. Goals . . . . . . . . . . . . . . . . . . . . . . . . 9 63 5. Implementation Status . . . . . . . . . . . . . . . . . . . . 10 64 5.1. IIT-CNR/Registro.it . . . . . . . . . . . . . . . . . . . 10 65 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 66 7. Security Considerations . . . . . . . . . . . . . . . . . . . 11 67 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 11 68 8.1. Normative References . . . . . . . . . . . . . . . . . . 11 69 8.2. Informative References . . . . . . . . . . . . . . . . . 12 70 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 12 72 1. Introduction 74 This document specifies how RDAP servers can use JSContact 75 ([draft-ietf-jmap-jscontact]) to represent the contact information 76 associated with entities in RDAP responses, instead of jCard 77 ([RFC7095]). It also describes the process by which an RDAP server 78 can migrate from jCard to JSContact. 80 1.1. Rationale 82 According to the feedback from RDAP Pilot Working Group 83 ([RDAP-PILOT-WG], a group of RDAP server implementers representing 84 registries and registrars of generic TLDs), the most commonly raised 85 implementation concern, for both servers and clients related to the 86 use of jCard ([RFC7095]) to represent the contact information 87 associated with entities. Working Group members reported jCard to be 88 unintuitive, complicated to implement for both clients and servers, 89 and incompatible with best practices for RESTful APIs. 91 JSContact ([draft-ietf-jmap-jscontact]) provides a simpler and more 92 efficient representation for contact information. In addition, it 93 provides a means to represent internationalised and unstructured 94 contact information which cannot currently be represented using 95 jCard. Support for internationalised contact information has been 96 recognised being necessary to facilitate the future 97 internationalisation of registration data directory services. 99 1.2. Conventions Used in This Document 101 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 102 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 103 document are to be interpreted as described in [RFC2119]. 105 2. JSContact 107 The JSContact specification defines a data model and JSON 108 representation of contact information that can be used for data 109 storage and exchange in address book or directory applications. It 110 aims to be an alternative to the vCard data format ([RFC6350]) and to 111 be unambiguous, extendable and simple to process. In contrast with 112 jCard, it is not a direct mapping from the vCard data model and 113 expands semantics where appropriate. 115 The JSContact specification declares two main object types: "JSCard", 116 which represents a single contact "card", and "JSCardGroup" which 117 represents a collection of JSCard objects. For the purpose of this 118 document, only JSCard obejcts are considered. 120 JSCard differs from jCard in that it: 122 o follows an object-oriented rather than array-oriented approach; 124 o is simple to process; 126 o requires no extra work in serialization/deserialization from/to a 127 data model; 129 o includes no "jagged" arrays; 131 o prefers maps rather than arrays to implement collections; 133 o is able to represent redacted contacts (both "name" and "fullName" 134 properties are optional). 136 [draft-loffredo-jmap-jscontact-vcard] provides informational guidance 137 on the conversion of jCard objects into JSCard objects, and vice 138 versa. 140 3. Using JSCard objects in RDAP Responses 142 Entity objects in RDAP responses MAY include a "jscard" property 143 whose value is a JSCard object, in addition, or instead of, the 144 "vCardArray" property defined in RFC 7483. 146 Example of an entity object containing a "jscard" property: 148 { 149 "objectClassName": "entity", 150 "handle": "entity-12345", 151 "roles": ["registrant"], 152 "status": ["validated"], 153 "jscard": { 154 "uid": "entity-12345", 155 "fullName": "John Doe", 156 "organization": [ 157 { 158 "value": "Example Inc" 159 } 160 ], 161 "addresses": [ 162 { 163 "street": "123 Example Street", 164 "locality": "Exampleton", 165 "region": "Exampleshire", 166 "postcode": "EX1 2AM", 167 "country": "Exampletania" 168 } 169 ], 170 "phones": [ 171 { 172 "value": "tel:+12.3456789" 173 } 174 ], 175 "emails": [ 176 { 177 "value": "jdoe@example.com" 178 } 179 ] 180 } 181 } 183 4. Migration from JCard to JSCard 184 4.1. Best Practices for deprecating a REST API features 186 Deprecation of a REST API feature is a process that should be 187 executed as smartly as possible. Before introducing the basic 188 principles guiding a deprecation process, it could be useful to 189 clarify about the terms deprecation and sunsetting: 191 o Deprecating an API means it is not usable in its current form for 192 the purpose intended. This usually means that a new version has 193 been created, or the API provider no longer intends to support it. 195 o Sunsetting is merely a period of time leading up to a deprecation. 196 It is a period of limited support, while deprecation is the period 197 in which support officially ends. In the meantime, the support 198 for an alternate feature replacing the old one might be provided. 199 A sunsetting plan can be set up months or even years in advance of 200 the deprecation announcement. 202 That being said, here are a few guidelines to deprecate a REST API 203 feature: 205 o "Communicating": REST API providers should announce the intended 206 deprecation communicating the timeline and any other helpful 207 information. 209 o "Planning a long enough sunset period": a good sunset period is 210 important as it gives API consumers time to work on their clients. 211 Such a period could consist of API updates to fit the future 212 version. 214 o "Providing alternatives": when entering the sunset period, there 215 may be a provision for elements like redirect URIs, migration 216 endpoints, etc., but, at the same time, the API might still 217 respond to old fashioned requests in order to guarantee backward 218 compatibility for a limited period. 220 4.2. RDAP Features Supporting a Deprecation Process 222 RDAP enables servers to communicate service information to clients 223 through notices. A notice can include a set of links which can be 224 used to provide clients with references and documentation. For the 225 purpose of this document, two link relation types are used: 227 o "deprecation" as described in [draft-dalal-deprecation-header]; 229 o "alternate" as described in [RFC8288]. 231 The information about the specifications used in the construction of 232 the response is also described by the "rdapConformance" tags. 234 Clients are able to ask servers for RDAP features by using 235 appropriate query parameters as described in [RFC7482]. 237 4.3. jCard Deprecation Procedure 239 The procedure for jCard to JSCard migration consists of four 240 contiguous stages, each one corresponding to as many alternatives in 241 providing the contact card. During the procedure, the presence of 242 "jscard_level_0" tag in the rdapConformance array means that JSCard 243 is returned instead of jCard. The time format used in notifying 244 clients about this procedure is defined in [RFC3339]. 246 4.3.1. Stages 248 Here in the following the four stages are reported in detail: 250 Stage 1 - JSCard unimplemented 252 This stage corresponds to providing jCard as default contact card 253 ([RFC7483]). The RDAP server is not able to provide an alternate 254 contact card. The rdapConformance array contains only the 255 "rdap_level_0" tag. 257 Stage 2 - JSCard sunset 259 This stage corresponds to providing jCard as default contact card 260 but the RDAP server is able to alternatively return JSCard if the 261 client sets the query parameter "jscard" to 1/true/yes. The 262 rdapConformance array contains the "rdap_level_0" tag but also the 263 "jscard_level_0" tag if JSCard is requested. 265 The RDAP server is recommended to return a notice titled "JSCard 266 sunset end". Such a notice should include a description reporting 267 the JSCard sunset end time and two links: 269 * "deprecation": a link to a URI-identified resource documenting 270 the jCard deprecation; 272 * "alternate": if JSCard is not requested, a link to the JSCard 273 version of same resource as identified by the current query 274 string plus the parameter "jscard" set to 1/true/yes 275 (Figure 1); otherwise, only the "deprecation" link is provided 276 (Figure 2). 278 "notices": [ 279 { 280 "title": "JSCard sunset end", 281 "description": ["2020-07-01T00:00:00Z"], 282 "links": [{ 283 "value": "http://example.net/entity/XXXX", 284 "rel": "deprecation", 285 "type": "text/html", 286 "href": "http://www.example.com/jcard_deprecation.html" 287 }, 288 { 289 "value": "http://example.net/entity/XXXX", 290 "rel": "alternate", 291 "type": "text/html", 292 "href": " http://example.net/entity/XXXX?jscard=1" 293 } 294 ] 295 } 296 ] 298 Figure 1: JSCard sunset - JSCard not requested 300 "notices": [ 301 { 302 "title": "JSCard sunset end", 303 "description": ["2020-07-01T00:00:00Z"], 304 "links": [ 305 { 306 "value": "http://example.net/entity/XXXX?jscard=1", 307 "rel": "deprecation", 308 "type": "text/html", 309 "href": "http://www.example.com/jcard_deprecation.html" 310 } 311 ] 312 } 313 ] 315 Figure 2: JSCard sunset - JSCard requested 317 Stage 3 - jCard deprecation 319 This stage corresponds to the provisioning of JSCard as default 320 contact card but the RDAP server is able to alternatively return 321 jCard if the client sets the query parameter "jcard" to 1/true/ 322 yes. The rdapConformance array contains both "rdap_level_0" and 323 "jscard_level_0" tags unless jCard is requested. The "jscard" 324 query parameter is ignored. 326 The RDAP server is recommended to return a notice titled "jCard 327 deprecation end". Such a notice should include a description 328 reporting the jCard deprecation end time and two links: 330 * "deprecation": a link to a URI-identified resource documenting 331 the jCard deprecation; 333 * "alternate": if jCard is not requested, a link to the jCard 334 version of the same resource as identified by the current query 335 string plus the parameter "jcard" set to 1/true/yes (Figure 3); 336 otherwise, a link to the JSCard version of the same resource as 337 identified by the current query string without the parameter 338 "jcard" (Figure 4). 340 "notices": [ 341 { 342 "title": "jCard deprecation end", 343 "description": ["2020-12-31T23:59:59Z"], 344 "links": [ 345 { 346 "value": "http://example.net/entity/XXXX", 347 "rel": "deprecation", 348 "type": "text/html", 349 "href": "http://www.example.com/jcard_deprecation.html" 350 }, 351 { 352 "value": "http://example.net/entity/XXXX", 353 "rel": "alternate", 354 "type": "text/html", 355 "href": " http://example.net/entity/XXXX?jcard=1" 356 } 357 ] 358 } 359 ] 361 Figure 3: jCard deprecation - jCard not requested 363 "notices": [ 364 { 365 "title": "jCard deprecation end", 366 "description": ["2020-12-31T23:59:59Z"], 367 "links": [ 368 { 369 "value": "http://example.net/entity/XXXX?jcard=1", 370 "rel": "deprecation", 371 "type": "text/html", 372 "href": "http://www.example.com/jcard_deprecation.html" 373 }, 374 { 375 "value": "http://example.net/entity/XXXX?jcard=1", 376 "rel": "alternate", 377 "type": "text/html", 378 "href": " http://example.net/entity/XXXX" 379 } 380 ] 381 } 382 ] 384 Figure 4: jCard deprecation - jCard requested 386 Stage 4 - jCard deprecated 388 This stage corresponds to providing JSCard as default contact 389 card. The RDAP server is not able to provide an alternate contact 390 card. The rdapConformance array always contains both 391 "rdap_level_0" and "jscard_level_0" tags. The RDAP server doesn't 392 include any notice about the jCard deprecation process. Both 393 "jscard" and "jcard" query parameters are ignored. 395 4.3.2. Length 397 The length of both JSCard sunset and jCard deprecation periods are 398 not fixed by this specification. Best practices in REST API 399 deprecation suggest that, depending on the deprecated API's reach, 400 user base and service offering, a convenient time could be anywhere 401 between 3 - 8 months. Anyway, RDAP providers are recommended to 402 monitor the server log to figure out whether declared times need to 403 be changed to meet client requirements. 405 4.3.3. Goals 407 The procedure described in this document achieves the following 408 goals: 410 o only one contact representation would be included in the response; 411 o the response would always be compliant to RFC7483; 413 o clients would be informed about the transition timeline; 415 o the backward compatibility would be guaranteed throughout the 416 transition; 418 o servers and clients could execute their transitions independently. 420 5. Implementation Status 422 NOTE: Please remove this section and the reference to RFC 7942 prior 423 to publication as an RFC. 425 This section records the status of known implementations of the 426 protocol defined by this specification at the time of posting of this 427 Internet-Draft, and is based on a proposal described in RFC 7942 428 [RFC7942]. The description of implementations in this section is 429 intended to assist the IETF in its decision processes in progressing 430 drafts to RFCs. Please note that the listing of any individual 431 implementation here does not imply endorsement by the IETF. 432 Furthermore, no effort has been spent to verify the information 433 presented here that was supplied by IETF contributors. This is not 434 intended as, and must not be construed to be, a catalog of available 435 implementations or their features. Readers are advised to note that 436 other implementations may exist. 438 According to RFC 7942, "this will allow reviewers and working groups 439 to assign due consideration to documents that have the benefit of 440 running code, which may serve as evidence of valuable experimentation 441 and feedback that have made the implemented protocols more mature. 442 It is up to the individual working groups to use this information as 443 they see fit". 445 5.1. IIT-CNR/Registro.it 447 Responsible Organization: Institute of Informatics and Telematics 448 of National Research Council (IIT-CNR)/Registro.it 450 Location: https://rdap.pubtest.nic.it/ 452 Description: This implementation includes support for RDAP queries 453 using data from the public test environment of .it ccTLD. 455 Level of Maturity: This is a "proof of concept" research 456 implementation. 458 Coverage: This implementation includes all of the features 459 described in this specification. 461 Contact Information: Mario Loffredo, mario.loffredo@iit.cnr.it 463 6. IANA Considerations 465 This document has no actions for IANA. 467 7. Security Considerations 469 This document doesn't report any security consideration. 471 8. References 473 8.1. Normative References 475 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 476 Requirement Levels", BCP 14, RFC 2119, 477 DOI 10.17487/RFC2119, March 1997, 478 . 480 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 481 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 482 . 484 [RFC6350] Perreault, S., "vCard Format Specification", RFC 6350, 485 DOI 10.17487/RFC6350, August 2011, 486 . 488 [RFC7095] Kewisch, P., "jCard: The JSON Format for vCard", RFC 7095, 489 DOI 10.17487/RFC7095, January 2014, 490 . 492 [RFC7482] Newton, A. and S. Hollenbeck, "Registration Data Access 493 Protocol (RDAP) Query Format", RFC 7482, 494 DOI 10.17487/RFC7482, March 2015, 495 . 497 [RFC7483] Newton, A. and S. Hollenbeck, "JSON Responses for the 498 Registration Data Access Protocol (RDAP)", RFC 7483, 499 DOI 10.17487/RFC7483, March 2015, 500 . 502 [RFC7942] Sheffer, Y. and A. Farrel, "Improving Awareness of Running 503 Code: The Implementation Status Section", BCP 205, 504 RFC 7942, DOI 10.17487/RFC7942, July 2016, 505 . 507 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 508 DOI 10.17487/RFC8288, October 2017, 509 . 511 8.2. Informative References 513 [draft-dalal-deprecation-header] 514 Dalal, S. and E. Wilde, "The Deprecation HTTP Header 515 Field", . 518 [draft-ietf-jmap-jscontact] 519 Stepanek, R. and M. Loffredo, "JSContact: A JSON 520 representation of contact data", 521 . 524 [draft-loffredo-jmap-jscontact-vcard] 525 Loffredo, M. and R. Stepanek, "JSContact: Converting from 526 and to vCard", . 529 [RDAP-PILOT-WG] 530 ICANN RDAP Pilot WG, "RDAP Pilot Report", April 2019, 531 . 534 Authors' Addresses 536 Mario Loffredo 537 IIT-CNR/Registro.it 538 Via Moruzzi,1 539 Pisa 56124 540 IT 542 Email: mario.loffredo@iit.cnr.it 543 URI: http://www.iit.cnr.it 545 Gavin Brown 546 CentralNic Group plc 547 Saddlers House, 44 Gutter Lane 548 London, England EC2V 6BR 549 GB 551 Phone: +44 20 33 88 0600 552 Email: gavin.brown@centralnic.com 553 URI: https://www.centralnic.com