idnits 2.17.1 draft-ietf-regext-rdap-jscontact-12.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: ---------------------------------------------------------------------------- == There are 5 instances of lines with non-ascii characters in the document. 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 6 characters in excess of 72. == There are 1 instance of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (2 May 2022) is 725 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) -- Looks like a reference, but probably isn't: '1' on line 961 -- Looks like a reference, but probably isn't: '0' on line 961 -- Looks like a reference, but probably isn't: '3' on line 954 -- Looks like a reference, but probably isn't: '2' on line 926 -- Looks like a reference, but probably isn't: '4' on line 940 -- Looks like a reference, but probably isn't: '5' on line 947 -- Looks like a reference, but probably isn't: '6' on line 954 == Outdated reference: A later version (-17) exists of draft-ietf-calext-jscontact-00 == Outdated reference: A later version (-15) exists of draft-ietf-calext-jscontact-vcard-00 ** Downref: Normative reference to an Informational RFC: RFC 8605 == Outdated reference: A later version (-21) exists of draft-ietf-jsonpath-base-03 == Outdated reference: A later version (-16) exists of draft-ietf-regext-rdap-redacted-02 Summary: 2 errors (**), 0 flaws (~~), 7 warnings (==), 8 comments (--). 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: 3 November 2022 CentralNic Group plc 6 2 May 2022 8 Using JSContact in Registration Data Access Protocol (RDAP) JSON 9 Responses 10 draft-ietf-regext-rdap-jscontact-12 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 3 November 2022. 34 Copyright Notice 36 Copyright (c) 2022 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 (https://trustee.ietf.org/ 41 license-info) in effect on the date of publication of this document. 42 Please review these documents carefully, as they describe your rights 43 and restrictions with respect to this document. Code Components 44 extracted from this document must include Revised BSD License text as 45 described in Section 4.e of the Trust Legal Provisions and are 46 provided without warranty as described in the Revised BSD License. 48 Table of Contents 50 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 51 1.1. Rationale . . . . . . . . . . . . . . . . . . . . . . . . 3 52 1.2. Conventions Used in This Document . . . . . . . . . . . . 3 53 2. JSContact . . . . . . . . . . . . . . . . . . . . . . . . . . 4 54 3. Using JSCard objects in RDAP Responses . . . . . . . . . . . 4 55 3.1. RDAP Query Parameters . . . . . . . . . . . . . . . . . . 10 56 4. Transition Considerations . . . . . . . . . . . . . . . . . . 10 57 4.1. RDAP Features Supporting a Transition Process . . . . . . 10 58 4.1.1. Notices and Link Relationships . . . . . . . . . . . 10 59 4.1.2. rdapConformance Property . . . . . . . . . . . . . . 11 60 4.1.3. Query Parameters . . . . . . . . . . . . . . . . . . 11 61 4.2. Transition Procedure . . . . . . . . . . . . . . . . . . 11 62 4.2.1. Goals . . . . . . . . . . . . . . . . . . . . . . . . 11 63 4.2.2. Transition Stages . . . . . . . . . . . . . . . . . . 11 64 4.2.2.1. Stage 1: only jCard provided . . . . . . . . . . 12 65 4.2.2.2. Stage 2: jCard sunset . . . . . . . . . . . . . . 12 66 4.2.2.3. Stage 3: jCard deprecation . . . . . . . . . . . 13 67 4.2.2.4. Stage 4: jCard deprecated . . . . . . . . . . . . 15 68 4.2.2.5. Length . . . . . . . . . . . . . . . . . . . . . 15 69 5. Implementation Status . . . . . . . . . . . . . . . . . . . . 15 70 5.1. IIT-CNR/Registro.it RDAP Server . . . . . . . . . . . . . 15 71 5.2. IIT-CNR/Registro.it RDAP Client . . . . . . . . . . . . . 16 72 5.3. client.rdap.org . . . . . . . . . . . . . . . . . . . . . 16 73 5.4. CentralNic Registry . . . . . . . . . . . . . . . . . . . 16 74 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 75 7. Security Considerations . . . . . . . . . . . . . . . . . . . 17 76 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 17 77 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 17 78 9.1. Normative References . . . . . . . . . . . . . . . . . . 17 79 9.2. Informative References . . . . . . . . . . . . . . . . . 19 80 Appendix A. jCard-JSContact Mapping . . . . . . . . . . . . . . 19 81 Appendix B. Change Log . . . . . . . . . . . . . . . . . . . . . 21 82 B.1. Change from 00 to 01 . . . . . . . . . . . . . . . . . . 21 83 B.2. Change from 01 to 02 . . . . . . . . . . . . . . . . . . 21 84 B.3. Change from 02 to 03 . . . . . . . . . . . . . . . . . . 22 85 B.4. Change from 03 to 04 . . . . . . . . . . . . . . . . . . 22 86 B.5. Initial WG version . . . . . . . . . . . . . . . . . . . 22 87 B.6. Change from 00 to 01 . . . . . . . . . . . . . . . . . . 22 88 B.7. Change from 01 to 02 . . . . . . . . . . . . . . . . . . 22 89 B.8. Change from 02 to 03 . . . . . . . . . . . . . . . . . . 22 90 B.9. Change from 03 to 04 . . . . . . . . . . . . . . . . . . 22 91 B.10. Change from 04 to 05 . . . . . . . . . . . . . . . . . . 23 92 B.11. Change from 05 to 06 . . . . . . . . . . . . . . . . . . 23 93 B.12. Change from 06 to 07 . . . . . . . . . . . . . . . . . . 23 94 B.13. Change from 07 to 08 . . . . . . . . . . . . . . . . . . 23 95 B.14. Change from 08 to 09 . . . . . . . . . . . . . . . . . . 23 96 B.15. Change from 09 to 10 . . . . . . . . . . . . . . . . . . 23 97 B.16. Change from 10 to 11 . . . . . . . . . . . . . . . . . . 23 98 B.17. Change from 11 to 12 . . . . . . . . . . . . . . . . . . 23 99 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 23 101 1. Introduction 103 This document specifies an extension to the Registration Data Access 104 Protocol (RDAP) that allows RDAP servers to use JSContact 105 [I-D.ietf-calext-jscontact] to represent the contact information 106 associated with entities in RDAP responses, instead of jCard 107 [RFC7095]. It also describes the process by which an RDAP server can 108 transition from jCard to JSContact. RDAP query and response 109 extensions are defined to facilitate the transition process. 111 1.1. Rationale 113 According to the feedback from RDAP Pilot Working Group 114 [RDAP-PILOT-WG], a group of RDAP server implementers representing 115 registries and registrars of generic TLDs, the most commonly raised 116 implementation concern, for both servers and client implementers, 117 related to the use of jCard [RFC7095] to represent the contact 118 information associated with entities. Working Group members reported 119 jCard to be unintuitive, complicated to implement for both clients 120 and servers, and incompatible with best practices for RESTful APIs. 122 JSContact [I-D.ietf-calext-jscontact] provides a simpler and more 123 efficient representation for contact information with regard to time 124 and effort saved in processing it. In addition, similarly to jCard, 125 it provides a means to represent internationalised and unstructured 126 contact information. Support for internationalised contact 127 information has been recognised being necessary to facilitate the 128 future internationalisation of registration data directory services. 130 1.2. Conventions Used in This Document 132 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 133 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 134 "OPTIONAL" in this document are to be interpreted as described in BCP 135 14 [RFC2119] [RFC8174] when, and only when, they appear in all 136 capitals, as shown here. 138 2. JSContact 140 The JSContact specification defines a data model and JSON 141 representation of contact information that can be used for data 142 storage and exchange in address book or directory applications. It 143 aims to be an alternative to the vCard data format [RFC6350] and to 144 be unambiguous, extendable and simple to process. In contrast with 145 jCard, it is not a direct mapping from the vCard data model and 146 expands semantics where appropriate. 148 The JSContact specification declares two main object types: "Card", 149 which represents a single contact card, and "CardGroup" which 150 represents a collection of Card objects. For the purpose of this 151 document, only Card objects are considered. To avoid confusion, in 152 the following of this document, the term "JSCard" is used to refer to 153 "JSContact Card". 155 JSCard differs from jCard in that it: 157 * follows an object-oriented rather than array-oriented approach; 158 * is simple to process; 159 * requires no extra work in serialization/deserialization from/to a 160 data model; 161 * includes no "jagged" arrays; 162 * prefers maps rather than arrays to implement collections. 164 [I-D.ietf-calext-jscontact-vcard] provides informational guidance on 165 the conversion of jCard into JSCard, and vice versa. Appendix A 166 shows JSContact counterparts for the most commonly used jCard 167 properties in an RDAP response. 169 3. Using JSCard objects in RDAP Responses 171 Entity objects in RDAP responses MAY include a "jscard_0" property 172 whose value is a JSCard object instead of the "vCardArray" property 173 defined in [RFC9083]. 175 Servers returning the "jscard_0" property in their response MUST 176 include "jscard_0" in the "rdapConformance" array. 178 The JSCard "uid" property SHOULD contain the same value as the RDAP 179 "handle" property. 181 Since most of the JSCard collections are represented as maps, map 182 keys must be defined. To aid interoperability, RDAP providers are 183 RECOMMENDED to use as map keys the following string values and labels 184 defined in [RFC5733]: 186 * "org" in the "organizations" map when there is a single 187 element. If both internationalised and localized 188 forms exist, the key MUST be used for the internationalised form; 189 * "addr" in the "addresses" map when there is a single 190 element. If both internationalised and localized 191 forms exist, the key MUST be used for the internationalised form; 192 * "email" in the "emails" map for the element; 193 * "voice" in the "phones" map for the element; 194 * "fax" in the "phones" map for the element. 196 If present, the localized versions of name, organization and postal 197 address MUST be inserted into the "localizations" map. The following 198 is an elided example of an RDAP entity lookup response including a 199 JSCard object that presents the "localizations" map (See PDF for non- 200 ASCII character string). 202 ... 203 "jscard_0": { 204 "@type" : "Card", 205 "uid" : "7e0636f5-e48f-4a32-ab96-b57e9c07c7aa", 206 "fullName" : "Vasya Pupkin", 207 "organizations" : { 208 "org" : { 209 "@type" : "Organization", 210 "name" : "My Company" 211 } 212 }, 213 "addresses" : { 214 "addr" : { 215 "@type" : "Address", 216 "street" : [ { 217 "@type" : "StreetComponent", 218 "type" : "name", 219 "value" : "1 Street" 220 }, { 221 "@type" : "StreetComponent", 222 "type" : "postOfficeBox", 223 "value" : "01001" 224 } ], 225 "locality" : "Kyiv", 226 "countryCode" : "UA" 227 } 228 }, 229 "localizations" : { 230 "ua" : { 231 "/jscard_0/addresses/addr" : { 232 "@type" : "Address", 233 "street" : [ { 234 "@type" : "StreetComponent", 235 "type" : "name", 236 "value" : "1, Улица" 237 }, { 238 "@type" : "StreetComponent", 239 "type" : "postOfficeBox", 240 "value" : "01001" 241 } ], 242 "locality" : "Киев", 243 "countryCode" : "UA" 244 }, 245 "/jscard_0/fullName" : "Вася Пупкин", 246 "/jscard_0/organizations/org" : { 247 "@type" : "Organization", 248 "name" : "Моя Компания" 249 } 250 } 251 } 252 } 253 ... 255 Figure 1: Example of handling localizations in JSContact 257 Implementers MAY use different mapping schemes to define keys for 258 additional entries of the aforementioned maps or others. For 259 example, a mapping scheme may consist in using a trivial sequential 260 number (e.g. "url-1", "url-2", etc.) 262 The following is an example of an RDAP entity including a JSCard 263 object that has been converted from the example in section 5.1 of 264 [RFC9083]. 266 { 267 "rdapConformance": [ 268 "rdap_level_0", 269 "jscard_0" 270 ], 271 "objectClassName" : "entity", 272 "handle":"XXXX", 273 "jscard_0":{ 274 "@type": "Card", 275 "uid": "XXXX", 276 "fullName": "Joe User" , 277 "name": { 278 "@type": "Name", 279 "components": [ 280 { 281 "@type": "NameComponent", 282 "type": "surname", 283 "value": "User" 284 }, 285 { 286 "@type": "NameComponent", 287 "type": "personal", 288 "value": "Joe" 289 }, 290 { 291 "@type": "NameComponent", 292 "type": "suffix", 293 "value": "ing. jr" 294 }, 295 { 296 "@type": "NameComponent", 297 "type": "suffix", 298 "value": "M.Sc." 299 } 300 ] 301 }, 302 "kind": "individual", 303 "preferredContactLanguages": { 304 "fr": { 305 "@type": "ContactLanguage", 306 "pref": 1 307 }, 308 "en": { 309 "@type": "ContactLanguage", 310 "pref": 2 311 } 312 }, 313 "organizations": { 314 "org": { 315 "@type": "Organization", 316 "name": "Example" 317 } 318 }, 319 "titles": { 320 "title": { 321 "@type": "Title", 322 "title": "Research Scientist" 323 }, 324 "role": { 325 "@type": "Title", 326 "title": "Project Lead" 327 } 328 }, 329 "addresses": { 330 "addr": { 331 "@type": "Address", 332 "contexts": { 333 "work": true 334 }, 335 "street": [ 336 { 337 "@type": "StreetComponent", 338 "type": "name", 339 "value": "4321 Rue Somewhere" 340 }, 341 { 342 "@type": "StreetComponent", 343 "type": "extension", 344 "value": "Suite 1234" 345 } 346 ], 347 "locality": "Quebec", 348 "region": "QC", 349 "postcode": "G1V 2M2", 350 "country": "Canada", 351 "countryCode": "CA", 352 "coordinates": "geo:46.772673,-71.282945", 353 "timeZone": "Etc/GMT+5" 354 }, 355 "home": { 356 "@type": "Address", 357 "contexts": { 358 "private": true 359 }, 360 "fullAddress": "123 Maple Ave\nSuite 90001\nVancouver\nBC\n1239\n" 361 } 362 }, 363 "phones": { 364 "voice" : { 365 "@type": "Phone", 366 "contexts": { 367 "work": true 368 }, 369 "features": { 370 "voice": true, 371 "cell": true, 372 "video": true, 373 "text": true 374 }, 375 "pref": 1, 376 "phone": "tel:+1-555-555-1234;ext=102" 377 } 379 }, 380 "emails": { 381 "email": { 382 "@type": "EmailAddress", 383 "contexts": { 384 "work": true 385 }, 386 "email": "joe.user@example.com" 387 } 388 }, 389 "online": { 390 "key": { 391 "@type" : "Resource", 392 "contexts": { 393 "work": true 394 }, 395 "type": "publicKey", 396 "resource": "http://www.example.com/joe.user/joe.asc" 397 }, 398 "url": { 399 "@type" : "Resource", 400 "contexts": { 401 "private": true 402 }, 403 "type": "uri", 404 "resource": "http://example.org" 405 } 406 } 407 }, 408 "roles":[ "registrar" ], 409 "publicIds":[ 410 { 411 "type":"IANA Registrar ID", 412 "identifier":"1" 413 } 414 ], 415 "remarks":[ 416 { 417 "description":[ 418 "She sells sea shells down by the sea shore.", 419 "Originally written by Terry Sullivan." 420 ] 421 } 422 ], 423 "links":[ 424 { 425 "value":"http://example.com/entity/XXXX", 426 "rel":"self", 427 "href":"http://example.com/entity/XXXX", 428 "type" : "application/rdap+json" 429 } 430 ], 431 "events":[ 432 { 433 "eventAction":"registration", 434 "eventDate":"1990-12-31T23:59:59Z" 435 } 436 ], 437 "asEventActor":[ 438 { 439 "eventAction":"last changed", 440 "eventDate":"1991-12-31T23:59:59Z" 441 } 442 ] 443 } 445 Figure 2: Example of using JSContact in RDAP response 447 3.1. RDAP Query Parameters 449 Two new query parameters are defined for the purpose of this 450 document. 452 The query parameters are OPTIONAL extensions of path segments defined 453 in [RFC9082]. They are as follows: 455 * "jscard": a boolean value that allows a client to request the 456 "jscard_0" property in the RDAP response; 457 * "jcard": a boolean value that allows a client to request the 458 "vcardArray" property in the RDAP response. 460 These parameters are furtherly explained in Section 4. 462 4. Transition Considerations 464 4.1. RDAP Features Supporting a Transition Process 466 4.1.1. Notices and Link Relationships 468 RDAP allows servers to communicate service information to clients 469 through notices. According to Section 4.3 of [RFC9083], an RDAP 470 response may contain one or more notice objects. Each notice may 471 include a set of link objects, which can be used to provide clients 472 with references and documentation. These link objects may have a 473 "rel" property which defines the relationship type, as described in 474 [RFC8288], Section 4. The transition process outlined in this 475 document uses two link relation types, namely "related" and 476 "alternate", described in [RFC8288]. 478 4.1.2. rdapConformance Property 480 The information about the specifications used in the construction of 481 the response is also described by the strings which appear in the 482 "rdapConformance" property of the RDAP response. 484 4.1.3. Query Parameters 486 Clients can ask servers to use the query parameters defined in 487 Section 3.1 in accordance with [RFC9082]. 489 4.2. Transition Procedure 491 The principles of the procedure for jCard to JSCard transition are 492 based on the best practices in [API-DEPRECATION]. 494 The procedure consists of four contiguous stages. During the 495 procedure, the presence of "jscard_0" tag in the rdapConformance 496 array indicates that JSCard is returned instead of jCard. The date 497 and time format used to notify clients about the stages of this 498 procedure is defined in [RFC3339]. 500 4.2.1. Goals 502 The procedure described in this document aims to achieve the 503 following goals: 505 * only one contact representation would be included in the response; 506 * the response would always be compliant to [RFC9083] because: 507 - being the "jscard_0" property a response extension, its 508 presence would be signaled by the "jscard_0" conformance tag; 509 - being "vcardArray" property optional in a response, its absence 510 would be allowed; 511 * clients would be informed about the transition timeline; 512 * the backward compatibility would be guaranteed throughout the 513 transition; 514 * servers and clients could execute their transitions independently. 516 4.2.2. Transition Stages 517 4.2.2.1. Stage 1: only jCard provided 519 This stage corresponds to providing jCard as the default contact card 520 [RFC9083]. The RDAP server is not able to provide an alternate 521 contact card. The rdapConformance array MUST NOT contain the 522 "jscard_0" tag. 524 4.2.2.2. Stage 2: jCard sunset 526 During this stage, the server uses jCard by default, but the RDAP 527 server will return JSCard if the client sets the query parameter 528 "jscard" to 1/true/yes. The rdapConformance array MUST contain the 529 "jscard_0" tag if JSCard is returned. 531 From this stage on, the RDAP server MUST include the "jscard_0" tag 532 in the rdapConformance array of the help response to signal clients 533 that JSCard can be returned instead of jCard. 535 The RDAP server SHOULD include a notice titled "jCard sunset end". 536 Such a notice includes a description reporting the jCard sunset end 537 date and time and two OPTIONAL links: 539 * "related": a link to a URI-identified resource documenting the 540 transition procedure; 541 * "alternate": if JSCard is not requested, a link to an alternate 542 result view identified by the current query string plus the 543 parameter "jscard" set to 1/true/yes (Figure 3); otherwise, only 544 the "related" link can be provided (Figure 4). 546 "notices": [ 547 { 548 "title": "jCard sunset end", 549 "description": ["2022-07-01T00:00:00Z"], 550 "links": [{ 551 "value": "http://example.net/entity/XXXX", 552 "rel": "related", 553 "type": "text/html", 554 "href": "http://www.example.com/jcard_deprecation.html" 555 }, 556 { 557 "value": "http://example.net/entity/XXXX", 558 "rel": "alternate", 559 "type": "application/rdap+json", 560 "href": " http://example.net/entity/XXXX?jscard=1" 561 } 562 ] 563 } 564 ] 565 Figure 3: jCard sunset - JSCard not requested 567 "notices": [ 568 { 569 "title": "jCard sunset end", 570 "description": ["2022-07-01T00:00:00Z"], 571 "links": [ 572 { 573 "value": "http://example.net/entity/XXXX?jscard=1", 574 "rel": "related", 575 "type": "text/html", 576 "href": "http://www.example.com/jcard_deprecation.html" 577 } 578 ] 579 } 580 ] 582 Figure 4: jCard sunset - JSCard requested 584 4.2.2.3. Stage 3: jCard deprecation 586 This stage corresponds to the provisioning of JSCard by default, but 587 the RDAP will return jCard if the client sets the query parameter 588 "jcard" to 1/true/yes. The rdapConformance array contains the 589 "jscard_0" tag unless jCard is returned. The "jscard" query 590 parameter MUST be ignored. 592 The RDAP server SHOULD return a notice titled "jCard deprecation 593 end". Such a notice includes a description reporting the jCard 594 deprecation end date and time and two OPTIONAL links: 596 * "related": a link to a URI-identified resource documenting the 597 transition procedure; 598 * "alternate": if jCard is not requested, a link to an alternate 599 result view identified by the current query string plus the 600 parameter "jcard" set to 1/true/yes (Figure 5); otherwise, a link 601 to the result view identified by the current query string without 602 the parameter "jcard" (Figure 6). 604 "notices": [ 605 { 606 "title": "jCard deprecation end", 607 "description": ["2022-12-31T23:59:59Z"], 608 "links": [ 609 { 610 "value": "http://example.net/entity/XXXX", 611 "rel": "related", 612 "type": "text/html", 613 "href": "http://www.example.com/jcard_deprecation.html" 614 }, 615 { 616 "value": "http://example.net/entity/XXXX", 617 "rel": "alternate", 618 "type": "application/rdap+json", 619 "href": " http://example.net/entity/XXXX?jcard=1" 620 } 621 ] 622 } 623 ] 625 Figure 5: jCard deprecation - jCard not requested 627 "notices": [ 628 { 629 "title": "jCard deprecation end", 630 "description": ["2022-12-31T23:59:59Z"], 631 "links": [ 632 { 633 "value": "http://example.net/entity/XXXX?jcard=1", 634 "rel": "related", 635 "type": "text/html", 636 "href": "http://www.example.com/jcard_deprecation.html" 637 }, 638 { 639 "value": "http://example.net/entity/XXXX?jcard=1", 640 "rel": "alternate", 641 "type": "application/rdap+json", 642 "href": " http://example.net/entity/XXXX" 643 } 644 ] 645 } 646 ] 648 Figure 6: jCard deprecation - jCard requested 650 4.2.2.4. Stage 4: jCard deprecated 652 This stage corresponds to providing JSCard as default contact card. 653 The RDAP server is not able to provide an alternate contact card. 654 The rdapConformance array always contains "jscard_0" tag. The RDAP 655 server doesn't include any notice about the jCard deprecation 656 process. Both "jscard" and "jcard" query parameters MUST be ignored. 658 4.2.2.5. Length 660 The length of both jCard sunset and jCard deprecation periods are not 661 fixed by this specification. Best practices in REST API deprecation 662 suggest that, depending on the deprecated API's reach, user base and 663 service offering, a convenient time could be anywhere between 3 - 8 664 months. Anyway, RDAP providers are RECOMMENDED to monitor the server 665 log to figure out whether declared times need to be changed to meet 666 client requirements. 668 5. Implementation Status 670 NOTE: Please remove this section and the reference to RFC 7942 prior 671 to publication as an RFC. 673 This section records the status of known implementations of the 674 protocol defined by this specification at the time of posting of this 675 Internet-Draft, and is based on a proposal described in RFC 7942 676 [RFC7942]. The description of implementations in this section is 677 intended to assist the IETF in its decision processes in progressing 678 drafts to RFCs. Please note that the listing of any individual 679 implementation here does not imply endorsement by the IETF. 680 Furthermore, no effort has been spent to verify the information 681 presented here that was supplied by IETF contributors. This is not 682 intended as, and must not be construed to be, a catalog of available 683 implementations or their features. Readers are advised to note that 684 other implementations may exist. 686 According to RFC 7942, "this will allow reviewers and working groups 687 to assign due consideration to documents that have the benefit of 688 running code, which may serve as evidence of valuable experimentation 689 and feedback that have made the implemented protocols more mature. 690 It is up to the individual working groups to use this information as 691 they see fit". 693 5.1. IIT-CNR/Registro.it RDAP Server 695 * Responsible Organization: Institute of Informatics and Telematics 696 of National Research Council (IIT-CNR)/Registro.it 697 * Location: https://rdap.pubtest.nic.it/ 698 * Description: This implementation includes support for RDAP queries 699 using data from the public test environment of .it ccTLD. 700 * Level of Maturity: This is an "alpha" test implementation. 701 * Coverage: This implementation includes all of the features 702 described in this specification. 703 * Contact Information: Mario Loffredo, mario.loffredo@iit.cnr.it 705 5.2. IIT-CNR/Registro.it RDAP Client 707 * Responsible Organization: Institute of Informatics and Telematics 708 of National Research Council (IIT-CNR)/Registro.it 709 * Location: https://web-rdap.pubtest.nic.it/ 710 * Description: This is a Javascript web-based RDAP client. RDAP 711 responses are retrieved from RDAP servers by the browser, parsed 712 into an HTML representation, and displayed in a format improving 713 the user experience. RDAP responses containing JSCard objects are 714 handled identically to those containing jCard objects. Raw 715 versions of RDAP responses including either jCard or JSCard 716 objects are provided. 717 * Level of Maturity: This is an "alpha" test implementation. 718 * Coverage: This implementation includes all of the features 719 described in this specification. 720 * Contact Information: Francesco Donini, francesco.donini@iit.cnr.it 722 5.3. client.rdap.org 724 * Location: https://client.rdap.org/ 725 * Description: This is a web-based "single page" RDAP client. RDAP 726 responses are retrieved from RDAP servers by the browser, and 727 parsed into an HTML representation. RDAP responses containing 728 JSCard objects are handled identically to those containing jCard 729 objects. 730 * Level of Maturity: This is an "alpha" test implementation. 731 * Coverage: This implementation implements client support for 732 parsing JSCard objects in RDAP responses. 733 * Contact Information: Gavin Brown, feedback@rdap.org 735 5.4. CentralNic Registry 737 * Responsible Organization: CentralNic Group PLC 738 * Location: https://rdap.centralnic.com/{tld} 739 * Description: This server is the product RDAP service for all top- 740 level domains on the CentralNic registry platform. 741 * Level of Maturity: Production quality. 742 * Coverage: This implementation includes all of the features 743 described in this specification. 744 * Contact Information: support@centralnic.com 746 6. IANA Considerations 748 IANA is requested to register the following values in the RDAP 749 Extensions Registry: 751 * Extension identifier: jscard_0 752 * Registry operator: Any 753 * Published specification: This document. 754 * Contact: IETF 755 * Intended usage: This extension represents a contact card provided 756 in an RDAP response according to the JSContact specification 757 [I-D.ietf-calext-jscontact]. 759 7. Security Considerations 761 Unlike jCard, the formatted name as well as any other personally 762 identifiable information is not required in JSCard. The only 763 mandatory property, namely "uid", is not a sensitive information as 764 it happens, instead, for the "fn" property in jCard. Therefore, 765 redacted properties can be merely excluded without using placeholder 766 values. This means that, with reference to what is described in 767 [I-D.ietf-regext-rdap-redacted], only the "Removal" method can be 768 used for redacting JSContact properties whereas the "Empty Value" is 769 also used for redacting jCard. 771 8. Acknowledgements 773 The authors would like to acknowledge the following individuals for 774 their contributions to this document: Jasdip Singh and Francesco 775 Donini. 777 9. References 779 9.1. Normative References 781 [I-D.ietf-calext-jscontact] 782 Stepanek, R. and M. Loffredo, "JSContact: A JSON 783 representation of contact data", Work in Progress, 784 Internet-Draft, draft-ietf-calext-jscontact-00, 17 January 785 2020, . 788 [I-D.ietf-calext-jscontact-vcard] 789 Loffredo, M. and R. Stepanek, "JSContact: Converting from 790 and to vCard", Work in Progress, Internet-Draft, draft- 791 ietf-calext-jscontact-vcard-00, 7 March 2022, 792 . 795 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 796 Requirement Levels", BCP 14, RFC 2119, 797 DOI 10.17487/RFC2119, March 1997, 798 . 800 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 801 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 802 . 804 [RFC5733] Hollenbeck, S., "Extensible Provisioning Protocol (EPP) 805 Contact Mapping", STD 69, RFC 5733, DOI 10.17487/RFC5733, 806 August 2009, . 808 [RFC6350] Perreault, S., "vCard Format Specification", RFC 6350, 809 DOI 10.17487/RFC6350, August 2011, 810 . 812 [RFC7095] Kewisch, P., "jCard: The JSON Format for vCard", RFC 7095, 813 DOI 10.17487/RFC7095, January 2014, 814 . 816 [RFC7942] Sheffer, Y. and A. Farrel, "Improving Awareness of Running 817 Code: The Implementation Status Section", BCP 205, 818 RFC 7942, DOI 10.17487/RFC7942, July 2016, 819 . 821 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 822 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 823 May 2017, . 825 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 826 DOI 10.17487/RFC8288, October 2017, 827 . 829 [RFC8605] Hollenbeck, S. and R. Carney, "vCard Format Extensions: 830 ICANN Extensions for the Registration Data Access Protocol 831 (RDAP)", RFC 8605, DOI 10.17487/RFC8605, May 2019, 832 . 834 [RFC9082] Hollenbeck, S. and A. Newton, "Registration Data Access 835 Protocol (RDAP) Query Format", STD 95, RFC 9082, 836 DOI 10.17487/RFC9082, June 2021, 837 . 839 [RFC9083] Hollenbeck, S. and A. Newton, "JSON Responses for the 840 Registration Data Access Protocol (RDAP)", STD 95, 841 RFC 9083, DOI 10.17487/RFC9083, June 2021, 842 . 844 9.2. Informative References 846 [API-DEPRECATION] 847 Sandoval, K., "How to Smartly Sunset and Deprecate APIs", 848 August 2019, . 852 [I-D.ietf-jsonpath-base] 853 Gössner, S., Normington, G., and C. Bormann, "JSONPath: 854 Query expressions for JSON", Work in Progress, Internet- 855 Draft, draft-ietf-jsonpath-base-03, 16 January 2022, 856 . 859 [I-D.ietf-regext-rdap-redacted] 860 Gould, J., Smith, D., Kolker, J., and R. Carney, "Redacted 861 Fields in the Registration Data Access Protocol (RDAP) 862 Response", Work in Progress, Internet-Draft, draft-ietf- 863 regext-rdap-redacted-02, 18 November 2021, 864 . 867 [RDAP-PILOT-WG] 868 ICANN RDAP Pilot WG, "RDAP Pilot Report", April 2019, 869 . 872 Appendix A. jCard-JSContact Mapping 874 Provided that the keys defined in Section 3 are used for the 875 JSContact maps, the mapping between the most commonly used jCard 876 properties in an RDAP response and their JSContact counterparts is 877 shown in the following. The mapping is done through the use of a 878 JSONPath expression [I-D.ietf-jsonpath-base]. 880 jCard property: fn 881 Reference: Section 6.2.1 of [RFC6350] 882 Path: $..vcardArray[1][?(@[0]=='fn')][3] 883 JSContact property: fullName 884 Reference: Section 2.2.2 of [I-D.ietf-calext-jscontact] 885 Path: $..jscard_0.fullName 887 jCard property: org 888 Reference: Section 6.6.4 of [RFC6350] 889 Path: $..vcardArray[1][?(@[0]=='org')][3] 890 JSContact property: Organization.name 891 Reference: Section 2.2.4 of [I-D.ietf-calext-jscontact] 892 Path: $..jscard_0.organizations.org.name 894 jCard property: tel with type="voice" 895 Reference: Section 6.4.1 of [RFC6350] 896 Path: $..vcardArray[1][?(@[1].type=='voice')][3] 897 JSContact property: Phone.phone 898 Reference: Section 2.3.2 of [I-D.ietf-calext-jscontact] 899 Path: $..jscard_0.phones.voice.phone 901 jCard property: tel with type="fax" 902 Reference: Section 6.4.1 of [RFC6350] 903 Path: $..vcardArray[1][?(@[1].type=='fax')][3] 904 JSContact property: Phone.phone 905 Reference: Section 2.3.2 of [I-D.ietf-calext-jscontact] 906 Path: $..jscard_0.phones.fax.phone 908 jCard property: email 909 Reference: Section 6.4.2 of [RFC6350] 910 Path: $..vcardArray[1][?(@[0]=='email')][3] 911 JSContact property: Email.email 912 Reference: Section 2.3.1 of [I-D.ietf-calext-jscontact] 913 Path: $..jscard_0.emails.email.email 915 jCard property: "post office box" component of adr 916 Reference: Section 6.3.1 of [RFC6350] 917 Path: $..vcardArray[1][?(@[0]=='adr')][3][1] 918 JSContact property: "postOfficeBox" StreetComponent of 919 Address.street 920 Reference: Section 2.4.1 of [I-D.ietf-calext-jscontact] 921 Path: $..jscard_0.addresses.addr.street[?(@.type=='postOfficeBox')]. 922 value 924 jCard property: "street address" component of adr 925 Reference: Section 6.3.1 of [RFC6350] 926 Path: $..vcardArray[1][?(@[0]=='adr')][3][2] 927 JSContact property: "name" StreetComponent of Address.street 928 Reference: Section 2.4.1 of [I-D.ietf-calext-jscontact] 929 Path: $..jscard_0.addresses.addr.street[?(@.type=='name')].value 931 jCard property: "locality" component of adr 932 Reference: Section 6.3.1 of [RFC6350] 933 Path: $..vcardArray[1][?(@[0]=='adr')][3][3] 934 JSContact property: Address.locality 935 Reference: Section 2.4.1 of [I-D.ietf-calext-jscontact] 936 Path: $..jscard_0.addresses.addr.locality 938 jCard property: "region" component of adr 939 Reference: Section 6.3.1 of [RFC6350] 940 Path: $..vcardArray[1][?(@[0]=='adr')][3][4] 941 JSContact property: Address.region 942 Reference: Section 2.4.1 of [I-D.ietf-calext-jscontact] 943 Path: $..jscard_0.addresses.addr.region 945 jCard property: "postal code" component of adr 946 Reference: Section 6.3.1 of [RFC6350] 947 Path: $..vcardArray[1][?(@[0]=='adr')][3][5] 948 JSContact property: Address.postcode 949 Reference: Section 2.4.1 of [I-D.ietf-calext-jscontact] 950 Path: $..jscard_0.addresses.addr.postcode 952 jCard property: "country name" component of adr 953 Reference: Section 6.3.1 of [RFC6350] 954 Path: $..vcardArray[1][?(@[0]=='adr')][3][6] 955 JSContact property: Address.country 956 Reference: Section 2.4.1 of [I-D.ietf-calext-jscontact] 957 Path: $..jscard_0.addresses.addr.country 959 jCard property: "cc" parameter of adr 960 Reference: Section 3.1 of [RFC8605] 961 Path: $..vcardArray[1][?(@[0]=='adr')][1].cc 962 JSContact property: Address.countryCode 963 Reference: Section 2.4.1 of [I-D.ietf-calext-jscontact] 964 Path: $..jscard_0.addresses.addr.countryCode 966 Appendix B. Change Log 968 B.1. Change from 00 to 01 970 1. Changed category from "Best Current Practice" to "Standards 971 Track" 972 2. Replaced the example of Figure 2 973 3. Changed the title of the "Migration from JCard to JSCard" 974 section to "Transition Considerations" 975 4. Added Section 3.1 976 5. Updated Section 6 977 6. Updated Section 7 978 7. Rearranged the description of stage 1 in Section 4.2.2 979 8. Changed the names of the transition stages 1 and 2 980 9. Corrected Figure 3, Figure 5, Figure 6 981 10. Changed the rdapConformance tag "jscard_level_0" to "jscard" 982 11. Removed the "Best Practices for deprecating a REST API features" 983 section,but added a useful reference. 985 B.2. Change from 01 to 02 986 1. Removed the sentence "which cannot be represented using jCard" in 987 Section 1.1. 989 B.3. Change from 02 to 03 991 1. Updated section "Conventions Used in This Document". 992 2. Updated the contact in "IANA Considerations" section. 993 3. Changed the reference draft-loffredo-calext-jscontact-vcard to 994 draft-ietf-calext-jscontact-vcard. 995 4. Added reference to RFC8174. 996 5. Other minor edits. 998 B.4. Change from 03 to 04 1000 1. Updated the reference draft-dalal-deprecation-header to draft- 1001 ietf-httpapi-deprecation-header. 1003 B.5. Initial WG version 1005 1. Ported from draft-loffredo-regext-rdap-jcard-deprecation-04 1006 renamed to draft-ietf-regext-rdap-jscontact-00. 1008 B.6. Change from 00 to 01 1010 1. Updated Section 3 and Figure 2. 1012 B.7. Change from 01 to 02 1014 1. Updated Section 2 and Figure 2. 1016 B.8. Change from 02 to 03 1018 1. Replaced references to obsolete RFC7482 and RFC7483 with RFC9082 1019 and RFC9083. 1020 2. Updated Section 3 and Figure 2. 1022 B.9. Change from 03 to 04 1024 1. Changed the references to Internet Drafts. 1025 2. Added an example showing how localizations are treated in 1026 JSContact. 1027 3. Changed the position of section "Goals" in Section 4.2. 1028 4. Added three more implementations to Section 5. 1029 5. Changed the rdapConformance tag "jscard" to "jscard_0" 1030 6. Added clarifications addressing the feedback provided by Jasdip 1031 Singh about version -03. 1032 7. Added Section 8. 1033 8. Other minor edits. 1035 B.10. Change from 04 to 05 1037 1. Updated Figure 2 to make it compliant with draft-ietf-jmap- 1038 jscontact-09. 1040 B.11. Change from 05 to 06 1042 1. Reviewed the notices presented in Section 4.2.2.2 and 1043 Section 4.2.2.3. 1045 B.12. Change from 06 to 07 1047 1. Corrected the JSON Pointer expressions in Figure 1. 1048 2. Other minor edits. 1050 B.13. Change from 07 to 08 1052 1. Corrected a nit in Figure 1. 1053 2. Removed the reference to draft-ietf-httpapi-deprecation-header. 1054 3. Replaced the "deprecation" link relation type with "related". 1055 4. Moved the references to JSContact drafts to the "Normative 1056 References" section. 1058 B.14. Change from 08 to 09 1060 1. Updated the references to JSContact drafts due to the transfer 1061 from JMAP to CalExt. 1063 B.15. Change from 09 to 10 1065 1. Updated Figure 2 to make it compliant with draft-ietf-calext- 1066 jscontact-02. 1068 B.16. Change from 10 to 11 1070 1. Added Appendix "jCard-JSContact Mapping". 1072 B.17. Change from 11 to 12 1074 1. Renamed the "jscard" property to "jscard_0". 1075 2. Corrected JSONPath expressions in Appendix A. 1077 Authors' Addresses 1078 Mario Loffredo 1079 IIT-CNR/Registro.it 1080 Via Moruzzi,1 1081 56124 Pisa 1082 Italy 1083 Email: mario.loffredo@iit.cnr.it 1084 URI: http://www.iit.cnr.it 1086 Gavin Brown 1087 CentralNic Group plc 1088 Saddlers House, 44 Gutter Lane 1089 London 1090 EC2V 6BR 1091 United Kingdom 1092 Phone: +44 20 33 88 0600 1093 Email: gavin.brown@centralnic.com 1094 URI: https://www.centralnic.com