XML to JSON conversion rules for RESTful EPP

XML to JSON conversion rules for RESTful EPP SIDN Labs

maarten.wullink@sidn.nl https://sidn.nl/

SIDN Labs

marco.davids@sidn.nl https://sidn.nl/

Internet Network Working Group This document describes the rules for converting an EPP XML message to a JSON message for use with RESTful EPP [REF-TO-REPP-HERE].

Introduction The Extensible Provisioning Protocol (EPP) 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 , for use with RESTful EPP (REPP).

Terminology In this document the following terminology is used. EPP RFCs - This is a reference to the EPP version 1.0 specifications , , and . RESTful EPP or REPP - The RESTful transport for EPP described in this document.

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 . 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.

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.

Empty
Pure text content
Attributes only
Pure text content and attributes
Child elements with different names
Child elements with identical names
Child element(s) and contiguous text

Empty An empty XML element MUST be mapped to to a key matching the name of the element and a null value. XML: ]]> JSON:

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:

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:

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:

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:

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:

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 ]]> JSON: 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: The rules above are based on the conversion approach found on

Examples This section lists examples for every EPP command supported by REPP, the examples

Hello The Hello request message does not exist in the context of REPP. Example XML response: 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.

Logout The Logout request and response message are not used for REPP.

Check The Check request and responses messages are not used for REPP.

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:

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:

Poll Ack The Poll Ack request message is not used for REPP. Example XML response: Command completed successfully ABC-12345 XYZ-12345 ]]> Example JSON response:

Transfer Query The Domain Transfer Query request message is not used for REPP. Example XML Domain Transfer Query response: 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:

Create Example XML Domain Create request: example.com 2 ns1.example.net ns2.example.net jd1234 sh8013 sh8013 2fooBAR ABC-12345 ]]> Example JSON Domain Create request: Example XML Domain Create response: 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:

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:

Renew The Renew request message is not used for REPP. Example XML Domain Renew response: Command completed successfully example.com 2005-04-03T22:00:00.0Z ABC-12345 54322-XYZ ]]> Example JSON Domain Renew response:

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:

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 ]]> Example JSON Domain Cancel Transfer response:

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.

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.

Update Example XML Domain Update request: example.com sh8013 2BARfoo ABC-12345 ]]> Example JSON Domain Update request: Example XML Domain Update response: Command completed successfully ABC-12345 XYZ-12345 ]]> Example JSON Domain Update response:

IANA Considerations The new application/epp+json MIME media type is used in this document, the registration template is included in Appendix A.

Internationalization Considerations TODO

Security Considerations TODO

Acknowledgments TODO

References Normative References Informative References Converting Between XML and JSON XML.com

Appendix A. Media Type Registration: application/epp+json MIME media type name: application MIME subtype name: epp+json Required parameters: none Optional parameters: Same as the charset parameter of application/json as specified in . Encoding considerations: Same as the encoding considerations of application/xml as specified in . Security considerations: This type has all of the security considerations described in 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