Network Working Group M. Wullink Internet-Draft M. Davids Intended status: Standards Track SIDN Labs Expires: 19 July 2024 16 January 2024 XML to JSON conversion rules for RESTful EPP draft-wullink-restful-epp-json-00 Abstract This document describes the rules for converting an EPP [RFC5730] XML message to a JSON [RFC8259] message for use with RESTful EPP [REF-TO- REPP-HERE]. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on 19 July 2024. Copyright Notice Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/ license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License. Wullink & Davids Expires 19 July 2024 [Page 1] Internet-Draft XML to JSON for RESTful EPP January 2024 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 3. Conventions Used in This Document . . . . . . . . . . . . . . 3 4. Conversion Rules . . . . . . . . . . . . . . . . . . . . . . 3 4.1. Empty . . . . . . . . . . . . . . . . . . . . . . . . . . 4 4.2. Pure text content . . . . . . . . . . . . . . . . . . . . 4 4.3. Attributes only . . . . . . . . . . . . . . . . . . . . . 4 4.4. Pure text content and attributes . . . . . . . . . . . . 5 4.5. Child elements with different names . . . . . . . . . . . 5 4.6. Child elements with identical names . . . . . . . . . . . 6 4.7. Child elements and contiguous text . . . . . . . . . . . 6 5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 7 5.1. Hello . . . . . . . . . . . . . . . . . . . . . . . . . . 7 5.2. Login . . . . . . . . . . . . . . . . . . . . . . . . . . 9 5.3. Logout . . . . . . . . . . . . . . . . . . . . . . . . . 9 5.4. Check . . . . . . . . . . . . . . . . . . . . . . . . . . 9 5.5. Info . . . . . . . . . . . . . . . . . . . . . . . . . . 10 5.6. Poll . . . . . . . . . . . . . . . . . . . . . . . . . . 12 5.7. Poll Ack . . . . . . . . . . . . . . . . . . . . . . . . 13 5.8. Transfer Query . . . . . . . . . . . . . . . . . . . . . 14 5.9. Create . . . . . . . . . . . . . . . . . . . . . . . . . 16 5.10. Delete . . . . . . . . . . . . . . . . . . . . . . . . . 20 5.11. Renew . . . . . . . . . . . . . . . . . . . . . . . . . . 20 5.12. Transfer Request . . . . . . . . . . . . . . . . . . . . 22 5.13. Transfer Cancel . . . . . . . . . . . . . . . . . . . . . 23 5.14. Transfer Reject . . . . . . . . . . . . . . . . . . . . . 24 5.15. Transfer Approve . . . . . . . . . . . . . . . . . . . . 24 5.16. Update . . . . . . . . . . . . . . . . . . . . . . . . . 24 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 26 7. Internationalization Considerations . . . . . . . . . . . . . 26 8. Security Considerations . . . . . . . . . . . . . . . . . . . 26 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 27 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 27 10.1. Normative References . . . . . . . . . . . . . . . . . . 27 10.2. Informative References . . . . . . . . . . . . . . . . . 27 Appendix A. Appendix A. Media Type Registration: application/ epp+json . . . . . . . . . . . . . . . . . . . . . . . . 27 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 28 Wullink & Davids Expires 19 July 2024 [Page 2] Internet-Draft XML to JSON for RESTful EPP January 2024 1. Introduction The Extensible Provisioning Protocol (EPP) [RFC5730] uses an on XML based protocol. The EPP protocol is well defined, using XML Schema Definition (XSD) for validation of XML messages, the XSDs are published as part of the EPP RFCs. This document describes rules for converting valid EPP XML messages to the JavaScript Object Notation (JSON) Data Interchange Format [RFC8259], for use with RESTful EPP (REPP). 2. Terminology In this document the following terminology is used. EPP RFCs - This is a reference to the EPP version 1.0 specifications [RFC5730], [RFC5731], [RFC5732] and [RFC5733]. RESTful EPP or REPP - The RESTful transport for EPP described in this document. 3. Conventions Used in This Document The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119]. JSON is case sensitive. Unless stated otherwise, JSON specifications and examples provided in this document MUST be interpreted in the character case presented. The examples in this document assume that request and response messages are properly formatted JSON documents. Indentation and white space in examples are provided only to illustrate element relationships and for improving readability, and are not REQUIRED features of the protocol. 4. Conversion Rules A XML element may use one of 7 possible forms, the sections below describe how these forms MUST be translated to valid JSON. 1. Empty 2. Pure text content 3. Attributes only 4. Pure text content and attributes 5. Child elements with different names 6. Child elements with identical names 7. Child element(s) and contiguous text Wullink & Davids Expires 19 July 2024 [Page 3] Internet-Draft XML to JSON for RESTful EPP January 2024 4.1. Empty An empty XML element MUST be mapped to to a key matching the name of the element and a null value. XML: JSON: { "hello": null } 4.2. Pure text content An XML element containing text only MUST be mapped to a key matching the name of the element and the text MUST be used for the value XML: en JSON: { "lang": "en" } 4.3. Attributes only An XML element containing one or more atributes only, MUST be mapped to a JSON object matching the name of the element. Each XML attribute, prefixed using the @ character, MUST be added as a key- value pair to the object. XML: JSON: Wullink & Davids Expires 19 July 2024 [Page 4] Internet-Draft XML to JSON for RESTful EPP January 2024 { "msgQ": { "@count": "5", "@id": "12345" } } 4.4. Pure text content and attributes An XML element containing one or more atributes and text content only, MUST be mapped to a JSON object matching the name of the element. The text content MUST, prefixed using the string #text, MUST be added as a key-value pair to the object. XML: Command completed successfully JSON: { "msg": { "@lang": "en", "#text": "Command completed successfully" } } 4.5. Child elements with different names An XML element containing one or more child elements, where each child uses an unique name, MUST be mapped to a JSON object matching the name of the element. Each child element MUST be added as a key- value pair to the parent object. XML: ABC-12345 54321-XYZ JSON: Wullink & Davids Expires 19 July 2024 [Page 5] Internet-Draft XML to JSON for RESTful EPP January 2024 { "trID": { "clTRID": "ABC-12345", "svTRID": "54321-XYZ" } } 4.6. Child elements with identical names An XML element containing multiple child elements, where multiple child elements use the same name, MUST be mapped to a JSON object containing an array. The name of the array MUST match the name of the non-unique children, each child element MUST be converted to JSON and added to the array. XML: 192.0.2.1 192.0.2.2 JSON: { "host": { "addr": [ "192.0.2.1", "192.0.2.2" ] } } 4.7. Child elements and contiguous text An XML element containing one or more child elements and contiguous text, MUST be mapped to a JSON object containing a key-value entry for each child element, the text value MUST result in a key named #text. XML: Credit balance low. 100 5 Wullink & Davids Expires 19 July 2024 [Page 6] Internet-Draft XML to JSON for RESTful EPP January 2024 JSON: { "msg": { "@lang": "en", "limit": 100, "bal": 5, "#text": "Credit balance low." } } When child elements are mixed with multiple text segments, the resulting #text key-value entry MUST be an array, containing all text segments. XML: Credit balance low. 100 5 Please increase balance. JSON: { "msg": { "@lang": "en", "limit": 100, "bal": 5, "#text": ["Credit balance low.", "Please increase balance asap."] } } The rules above are based on the conversion approach found on [XMLCOM-WEB] 5. Examples This section lists examples for every EPP command supported by REPP, the examples 5.1. Hello The Hello request message does not exist in the context of REPP. Example XML response: Wullink & Davids Expires 19 July 2024 [Page 7] Internet-Draft XML to JSON for RESTful EPP January 2024 Example EPP server epp.example.com 2000-06-08T22:00:00.0Z 1.0 en fr urn:ietf:params:xml:ns:obj1 urn:ietf:params:xml:ns:obj2 urn:ietf:params:xml:ns:obj3 http://custom/obj1ext-1.0 Example JSON response: XML namespaces are not converted to JSON and are ignored. Wullink & Davids Expires 19 July 2024 [Page 8] Internet-Draft XML to JSON for RESTful EPP January 2024 { "epp": { "@xmlns": "urn:ietf:params:xml:ns:epp-1.0", "greeting": { "svID": "Example REPP server v1.0", "svDate": "2000-06-08T22:00:00.0Z", "svcMenu": { "version": "1.0", "lang": [ "en", "fr" ] }, "dcp": { "access": { "all": null }, "statement": { "purpose": { "admin": null, "prov": null }, "recipient": { "ours": null, "public": null }, "retention": { "stated": null } } } } } } 5.2. Login The Login request and response message are not used for REPP. 5.3. Logout The Logout request and response message are not used for REPP. 5.4. Check The Check request and responses messages are not used for REPP. Wullink & Davids Expires 19 July 2024 [Page 9] Internet-Draft XML to JSON for RESTful EPP January 2024 5.5. Info The Info request message is not used for REPP. Example XML Domain Info response: Command completed successfully example.com EXAMPLE1-REP jd1234 sh8013 sh8013 ns1.example.com ns1.example.net ns1.example.com ns2.example.com ClientX ClientY 1999-04-03T22:00:00.0Z ClientX 1999-12-03T09:00:00.0Z 2005-04-03T22:00:00.0Z 2000-04-08T09:00:00.0Z 2fooBAR ABC-12345 54322-XYZ Example JSON Domain Info response: Wullink & Davids Expires 19 July 2024 [Page 10] Internet-Draft XML to JSON for RESTful EPP January 2024 { "epp": { "@xmlns": "urn:ietf:params:xml:ns:epp-1.0", "response": { "result": { "@code": "1000", "msg": "Command completed successfully" }, "resData": { "domain:infData": { "@xmlns:domain": "urn:ietf:params:xml:ns:domain-1.0", "domain:name": "example.com", "domain:roid": "EXAMPLE1-REP", "domain:status": { "@s": "ok" }, "domain:registrant": "jd1234", "domain:contact": [ { "@type": "admin", "#text": "sh8013" }, { "@type": "tech", "#text": "sh8013" } ], "domain:ns": { "domain:hostObj": [ "ns1.example.com", "ns1.example.net" ] }, "domain:host": [ "ns1.example.com", "ns2.example.com" ], "domain:clID": "ClientX", "domain:crID": "ClientY", "domain:crDate": "1999-04-03T22:00:00.0Z", "domain:upID": "ClientX", "domain:upDate": "1999-12-03T09:00:00.0Z", "domain:exDate": "2005-04-03T22:00:00.0Z", "domain:trDate": "2000-04-08T09:00:00.0Z", "domain:authInfo": { "domain:pw": "2fooBAR" } } Wullink & Davids Expires 19 July 2024 [Page 11] Internet-Draft XML to JSON for RESTful EPP January 2024 }, "trID": { "clTRID": "ABC-12345", "svTRID": "54322-XYZ" } } } } 5.6. Poll The Poll request message is not used for REPP. Example XML response: Command completed successfully; ack to dequeue 2000-06-08T22:10:00.0Z Credit balance low. 100 5 ABC-12346 54321-XYZ Example JSON response: Wullink & Davids Expires 19 July 2024 [Page 12] Internet-Draft XML to JSON for RESTful EPP January 2024 { "epp": { "@xmlns": "urn:ietf:params:xml:ns:epp-1.0", "response": { "result": { "@code": "1301", "msg": "Command completed successfully; ack to dequeue" }, "msgQ": { "@count": "4", "@id": "12346", "qDate": "2024-01-15T22:10:00.0Z", "msg": { "@lang": "en", "limit": "100", "bal": "5", "#text": "Credit balance low." } }, "trID": { "clTRID": "ABC-12346", "svTRID": "54321-XYZ" } } } } 5.7. Poll Ack The Poll Ack request message is not used for REPP. Example XML response: Command completed successfully ABC-12345 XYZ-12345 Wullink & Davids Expires 19 July 2024 [Page 13] Internet-Draft XML to JSON for RESTful EPP January 2024 Example JSON response: { "epp": { "@xmlns": "urn:ietf:params:xml:ns:epp-1.0", "response": { "result": { "@code": "1000", "msg": "Command completed successfully" }, "msgQ": { "@count": "0", "@id": "12345" }, "trID": { "clTRID": "ABC-12345", "svTRID": "XYZ-12345" } } } } 5.8. Transfer Query The Domain Transfer Query request message is not used for REPP. Example XML Domain Transfer Query response: Wullink & Davids Expires 19 July 2024 [Page 14] Internet-Draft XML to JSON for RESTful EPP January 2024 Command completed successfully example.com pending ClientX 2000-06-06T22:00:00.0Z ClientY 2000-06-11T22:00:00.0Z 2002-09-08T22:00:00.0Z ABC-12345 54322-XYZ Example JSON Domain Transfer Query response: Wullink & Davids Expires 19 July 2024 [Page 15] Internet-Draft XML to JSON for RESTful EPP January 2024 { "epp": { "@xmlns": "urn:ietf:params:xml:ns:epp-1.0", "response": { "result": { "@code": "1000", "msg": "Command completed successfully" }, "resData": { "domain:trnData": { "@xmlns:domain": "urn:ietf:params:xml:ns:domain-1.0", "domain:name": "example.com", "domain:trStatus": "pending", "domain:reID": "ClientX", "domain:reDate": "2000-06-06T22:00:00.0Z", "domain:acID": "ClientY", "domain:acDate": "2000-06-11T22:00:00.0Z", "domain:exDate": "2002-09-08T22:00:00.0Z" } }, "trID": { "clTRID": "ABC-12345", "svTRID": "54322-XYZ" } } } } 5.9. Create Example XML Domain Create request: Wullink & Davids Expires 19 July 2024 [Page 16] Internet-Draft XML to JSON for RESTful EPP January 2024 example.com 2 ns1.example.net ns2.example.net jd1234 sh8013 sh8013 2fooBAR ABC-12345 Example JSON Domain Create request: Wullink & Davids Expires 19 July 2024 [Page 17] Internet-Draft XML to JSON for RESTful EPP January 2024 { "epp": { "@xmlns": "urn:ietf:params:xml:ns:epp-1.0", "command": { "create": { "domain:create": { "@xmlns:domain": "urn:ietf:params:xml:ns:domain-1.0", "domain:name": "example.com", "domain:period": { "@unit": "y", "#text": "2" }, "domain:ns": { "domain:hostObj": [ "ns1.example.net", "ns2.example.net" ] }, "domain:registrant": "jd1234", "domain:contact": [ { "@type": "admin", "#text": "sh8013" }, { "@type": "tech", "#text": "sh8013" } ], "domain:authInfo": { "domain:pw": "2fooBAR" } } }, "clTRID": "ABC-12345" } } } Example XML Domain Create response: Wullink & Davids Expires 19 July 2024 [Page 18] Internet-Draft XML to JSON for RESTful EPP January 2024 Command completed successfully example.com 1999-04-03T22:00:00.0Z 2001-04-03T22:00:00.0Z ABC-12345 54321-XYZ Example JSON Domain Create response: { "epp": { "@xmlns": "urn:ietf:params:xml:ns:epp-1.0", "response": { "result": { "@code": "1000", "msg": "Command completed successfully" }, "resData": { "domain:creData": { "@xmlns:domain": "urn:ietf:params:xml:ns:domain-1.0", "domain:name": "example.com", "domain:crDate": "1999-04-03T22:00:00.0Z", "domain:exDate": "2001-04-03T22:00:00.0Z" } }, "trID": { "clTRID": "ABC-12345", "svTRID": "54321-XYZ" } } } } Wullink & Davids Expires 19 July 2024 [Page 19] Internet-Draft XML to JSON for RESTful EPP January 2024 5.10. Delete The Delete request message is not used for REPP. Example XML Domain Delete response: Command completed successfully ABC-12345 54321-XYZ Example JSON Domain Delete response: { "epp": { "@xmlns": "urn:ietf:params:xml:ns:epp-1.0", "response": { "result": { "@code": "1000", "msg": "Command completed successfully" }, "trID": { "clTRID": "ABC-12345", "svTRID": "54321-XYZ" } } } } 5.11. Renew The Renew request message is not used for REPP. Example XML Domain Renew response: Wullink & Davids Expires 19 July 2024 [Page 20] Internet-Draft XML to JSON for RESTful EPP January 2024 Command completed successfully example.com 2005-04-03T22:00:00.0Z ABC-12345 54322-XYZ Example JSON Domain Renew response: { "epp": { "@xmlns": "urn:ietf:params:xml:ns:epp-1.0", "response": { "result": { "@code": "1000", "msg": "Command completed successfully" }, "resData": { "domain:renData": { "@xmlns:domain": "urn:ietf:params:xml:ns:domain-1.0", "domain:name": "example.com", "domain:exDate": "2005-04-03T22:00:00.0Z" } }, "trID": { "clTRID": "ABC-12345", "svTRID": "54322-XYZ" } } } } Wullink & Davids Expires 19 July 2024 [Page 21] Internet-Draft XML to JSON for RESTful EPP January 2024 5.12. Transfer Request The Transfer request message is not used for REPP. Example XML Domain Transfer response: Command completed successfully; action pending example.com pending ClientX 2000-06-08T22:00:00.0Z ClientY 2000-06-13T22:00:00.0Z 2002-09-08T22:00:00.0Z ABC-12345 54322-XYZ Example JSON Domain Transfer response: Wullink & Davids Expires 19 July 2024 [Page 22] Internet-Draft XML to JSON for RESTful EPP January 2024 { "epp": { "@xmlns": "urn:ietf:params:xml:ns:epp-1.0", "response": { "result": { "@code": "1001", "msg": "Command completed successfully; action pending" }, "resData": { "domain:trnData": { "@xmlns:domain": "urn:ietf:params:xml:ns:domain-1.0", "domain:name": "example.com", "domain:trStatus": "pending", "domain:reID": "ClientX", "domain:reDate": "2000-06-08T22:00:00.0Z", "domain:acID": "ClientY", "domain:acDate": "2000-06-13T22:00:00.0Z", "domain:exDate": "2002-09-08T22:00:00.0Z" } }, "trID": { "clTRID": "ABC-12345", "svTRID": "54322-XYZ" } } } } 5.13. Transfer Cancel The Transfer Cancel request message is not used for REPP. Example XML Domain Cancel Transfer response: Command completed successfully ABC-12345 XYZ-12345 Wullink & Davids Expires 19 July 2024 [Page 23] Internet-Draft XML to JSON for RESTful EPP January 2024 Example JSON Domain Cancel Transfer response: { "epp": { "@xmlns": "urn:ietf:params:xml:ns:epp-1.0", "response": { "result": { "@code": "1000", "msg": "Command completed successfully" }, "trID": { "clTRID": "ABC-12345", "svTRID": "XYZ-12345" } } } } 5.14. Transfer Reject The Transfer Reject request message is not used for REPP and the response message is the same as for the Transfer Cancel command. 5.15. Transfer Approve The Transfer Approve request message is not used for REPP and the response message is the same as for the Transfer Cancel command. 5.16. Update Example XML Domain Update request: Wullink & Davids Expires 19 July 2024 [Page 24] Internet-Draft XML to JSON for RESTful EPP January 2024 example.com sh8013 2BARfoo ABC-12345 Example JSON Domain Update request: { "epp": { "@xmlns": "urn:ietf:params:xml:ns:epp-1.0", "command": { "update": { "domain:update": { "@xmlns:domain": "urn:ietf:params:xml:ns:domain-1.0", "domain:name": "example.com", "domain:chg": { "domain:registrant": "sh8013", "domain:authInfo": { "domain:pw": "2BARfoo" } } } }, "clTRID": "ABC-12345" } } } Example XML Domain Update response: Wullink & Davids Expires 19 July 2024 [Page 25] Internet-Draft XML to JSON for RESTful EPP January 2024 Command completed successfully ABC-12345 XYZ-12345 Example JSON Domain Update response: { "epp": { "@xmlns": "urn:ietf:params:xml:ns:epp-1.0", "response": { "result": { "@code": "1000", "msg": "Command completed successfully" }, "trID": { "clTRID": "ABC-12345", "svTRID": "XYZ-12345" } } } } 6. IANA Considerations The new application/epp+json MIME media type is used in this document, the registration template is included in Appendix A. 7. Internationalization Considerations TODO 8. Security Considerations TODO Wullink & Davids Expires 19 July 2024 [Page 26] Internet-Draft XML to JSON for RESTful EPP January 2024 9. Acknowledgments TODO 10. References 10.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC5730] Hollenbeck, S., "Extensible Provisioning Protocol (EPP)", STD 69, RFC 5730, DOI 10.17487/RFC5730, August 2009, . [RFC5731] Hollenbeck, S., "Extensible Provisioning Protocol (EPP) Domain Name Mapping", STD 69, RFC 5731, DOI 10.17487/RFC5731, August 2009, . [RFC5732] Hollenbeck, S., "Extensible Provisioning Protocol (EPP) Host Mapping", STD 69, RFC 5732, DOI 10.17487/RFC5732, August 2009, . [RFC5733] Hollenbeck, S., "Extensible Provisioning Protocol (EPP) Contact Mapping", STD 69, RFC 5733, DOI 10.17487/RFC5733, August 2009, . [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", STD 90, RFC 8259, DOI 10.17487/RFC8259, December 2017, . 10.2. Informative References [XMLCOM-WEB] XML.com, "Converting Between XML and JSON", 2006, . Appendix A. Appendix A. Media Type Registration: application/epp+json MIME media type name: application MIME subtype name: epp+json Wullink & Davids Expires 19 July 2024 [Page 27] Internet-Draft XML to JSON for RESTful EPP January 2024 Required parameters: none Optional parameters: Same as the charset parameter of application/ json as specified in [RFC8259]. Encoding considerations: Same as the encoding considerations of application/xml as specified in [RFC8259]. Security considerations: This type has all of the security considerations described in [RFC8259] plus the considerations specified in the Security Considerations section of this document. Published specification: This document. Applications that use this media type: RESTful EPP client and server implementations. Additional information: None Magic number(s): None. File extension(s): .json Macintosh file type code(s): "TEXT" Person & email address for further information: See the "Author's Address" section of this document. Intended usage: COMMON Author/Change controller: IETF Authors' Addresses Maarten Wullink SIDN Labs Email: maarten.wullink@sidn.nl URI: https://sidn.nl/ Marco Davids SIDN Labs Email: marco.davids@sidn.nl URI: https://sidn.nl/ Wullink & Davids Expires 19 July 2024 [Page 28]