EPP XML to RPP JSON conversion rules

Introduction EPP employs XML to define its protocol interactions, with XML Schema Definitions (XSD) serving as the formal schema language to outline the structure and validate the conformance of EPP XML messages. These XSDs, integral to the EPP RFCs, ensure that EPP messages adhere to the expected syntax and semantic rules. This document describes the rules and methodologies for converting these XSDs, to JSON Schema, which serves a similar purpose for JSON formatted data. JSON Schema provides a robust framework for describing and validating the structure of JSON data, offering a parallel method for enforcing syntactical correctness and logical consistency in JSON formatted EPP messages. As the domain registration industry evolves towards adopting RESTful APIs and other JSON-based interactions, there's a need for analogous schema definitions to ensure consistency, validation, and interoperability of JSON representations of EPP messages. This document aims to bridge this gap by providing a standardized approach to translating the rigorously defined XSDs of EPP into JSON Schema, facilitating the use of JSON in the RESTful Provisioning Protocol and potential future EPP-related protocols and transports. This approach eventually allows for converting valid EPP XML messages to the JavaScript Object Notation (JSON) Data Interchange Format , for use with EPP.

Motivation The RESTful Provisioning Protocol (RPP) introduces a new provisiong mechanism that aligns more closely with modern cloud infrastructure, enhancing the scalability of server deployments. While RESTful protocols do not mandate a specific media type for resource description, the widespread adoption of JSON in web services has established it as the de facto standard for modern APIs. The increasing availability of tools, software libraries, and a skilled workforce, coupled with the declining popularity of XML, has led several registries to adopt JSON for data exchange within their API ecosystems. Registries supporting JSON, can offer a unified API ecosystem that extends beyond domain name and IP address provisioning, maintaining a consistent technology stack, data formats, and developer experience. JSON's syntax, known for its straightforwardness and minimal verbosity compared to XML, significantly eases the tasks of writing, reading, and maintaining code. This simplicity is especially advantageous for the rapid comprehension and integration of provisioning APIs. The lightweight nature of JSON can result in faster processing and data transfers, a critical aspect in high-volume transaction environments such as domain registration. Enhanced API response times can lead to more efficient domain lookups, registrations, and updates. Moreover, JSON parsing is typically faster and more straightforward than XML parsing, contributing to improved system performance amid frequent interactions between RPP clients and servers. However, the absence of a standardized JSON format for domain provisioning has led to the emergence of TLD-specific implementations that lack interoperability, increasing the development effort required for integration. Similarly, at the registrar level, the absence of standards has resulted in numerous incompatible API implementations provided to clients and resellers. Standardizing a JSON format for domain provisioning within the RPP framework could mitigate these challenges, reducing fragmentation and simplifying integration efforts across the domain registration industry.

Terminology In this document the following terminology is used. EPP RFCs - This is a reference to the EPP version 1.0 specifications , , and . RESTful Provisioning Protocol - A RESTful protocol for provisiong heterogeneous database objects.

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.

XSD Conversion Rules This chapter presents rules for converting EPP XSD into JSON Schema.

Elements and Attributes Rule 1: Elements in XSD must be converted to properties in the JSON Schema, preserving names. XSD: ]]> JSON Schema: Rule 2: Attributes in XSD must be represented as JSON properties, prefixed with "@", retaining original names with the prefix addition. XSD: ]]> JSON Schema

Simple Types and Enumerations Rule 3: Simple types, including elements with only text content, must be converted to appropriate JSON types, e.g., xs:string to type: string. XSD: ]]> JSON Schema: Rule 4: Enumerations in XSD must be represented using the enum keyword in JSON Schema. XSD: ... ]]> JSON Schema:

Occurrence Constraints Rule 5: Elements with minOccurs: 0 and maxOccurs: 1 should be represented as optional properties in the JSON Schema. XSD: ... ]]> JSON Schema: Rule 6: Elements with minOccurs: 1 and maxOccurs: 1 or omitted attributes must be represented as mandatory properties in the JSON Schema. XSD: ... ]]> JSON Schema: Rule 7: Elements allowing multiple occurrences must be represented as JSON arrays, using minItems and maxItems to enforce minOccurs and maxOccurs. XSD: ]]> JSON Schema:

Complex Types Rule 8: Complex types in XSD must be converted to JSON objects in the JSON Schema, with properties adhering to subsequent rules for elements and attributes. Properties rendered through choice or sequence elements included in complex types shall be included in the same object definition as opposed to creating a separate object level. XSD: ... ]]> JSON Schema:

Sequences Rule 9: Sequences in XSD must be converted to JSON objects in the JSON Schema, with each sequence element becoming a property of the object. Cardinality dictated by minOccurs and maxOccurs must be applied to determine if an element is represented as optional, mandatory, or an array. XSD: ... ]]> JSON Schema:

Choices Rule 10: The choice construct in XSD must be represented in JSON Schema using the oneOf keyword, allowing for representation of multiple possible structures with only one being valid at a time. Each choice property MUST be marked as required to make a clear and unambigous distinction between the variants. XSD: ... ]]> JSON Schema:

Mixed Content and Special Cases Rule 11: Elements with mixed content must be represented as JSON objects with #text for text content and properties for each child element. If schema allows for multiple instances of text content the #text property should be defined as an array. XSD: ]]> JSON Schema: Rule 12: Empty elements in XSD or EPP normative text must be represented as properties with a null fixed value in the JSON Schema. XSD: ... ... ]]> JSON Schema: Rule 13: Elements with attributes and text content must be represented as JSON objects with #text for text and properties for each attribute, prefixed with "@". XSD: ]]> JSON Schema:

XML Conversion Rules A XML element may exist in one of 7 distinct 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 each of the existing EPP commands that are support by RPP.

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

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

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

Info The Info request message is not used for RPP. 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 RPP. 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 RPP. 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 RPP. 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 RPP. 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 RPP. 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 RPP. 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 RPP. 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 RPP and the response message is the same as for the Transfer Cancel command.

Transfer Approve The Transfer Approve request message is not used for RPP 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 TODO

Internationalization Considerations TODO

Security Considerations TODO

Acknowledgments TODO