| Related Objects Extension for EPP | September 2026 | |
| Brown | Informational | [Page] |
This document describes an extension to the Extensible Provisioning Protocol (EPP) that allows EPP clients to request the inclusion of related objects in responses to <info> commands.¶
The source for this document, and an issue tracker, may can be found at https://github.com/gbxyz/epp-related-objects-extension.¶
This work is licensed under Creative Commons Attribution 4.0 International. To view a copy of this license, visit https://creativecommons.org/licenses/by/4.0/.¶
The Extensible Provisioning Protocol (EPP) [RFC5730] is an object provisioning and management protocol, allowing clients to create, view and transform objects in a central repository.¶
The EPP <info> command allows clients to retrieve information (subject to authorisation) about objects in the repository. Since EPP operates on a strictly per-object basis, and since objects may be related to one another, a client may often need to issue multiple <info> commands in order to retrieve the data it needs to carry out its operation.¶
This document describes an extension to the <info> command that allows clients to request the inclusion of information about related objects in responses. This allows clients to retrieve all the required information about an object in a single round-trip to the server.¶
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶
In examples, C: represents lines sent by a protocol client and S: represents lines returned by a protocol server.
Indentation and white space in examples are provided only to illustrate element relationships and are not REQUIRED features of this protocol.¶
A protocol client that is authorized to manage an existing object is described as a "sponsoring" client throughout this document.¶
XML is case sensitive. Unless stated otherwise, XML specifications and examples provided in this document MUST be interpreted in the character case presented in order to develop a conforming implementation.¶
EPP uses XML namespaces to provide an extensible object management framework and to identify schemas required for XML instance parsing and validation. These namespaces and schema definitions are used to identify both the base protocol schema and the schemas for managed objects.¶
The XML namespace prefixes used in examples (such as the string ro in ro:include) are solely for illustrative purposes.
A conforming implementation MUST NOT require the use of these or any other specific namespace prefixes.¶
In accordance with Section 3.2.2.1 of XML Schema Part 2: Datatypes [XSD-DATATYPES],
the allowable lexical representations for the xs:boolean datatype are the strings "0" and "false" for the concept 'false' and the strings "1" and "true" for the concept 'true'.
Implementations MUST support both styles of lexical representation.¶
This specification defines additional elements to extend the EPP <info> command and response. No other EPP commands and responses are extended.¶
Clients wishing to request related object information MUST include a <ro:info> element in the <extension> element of the <info> frame. The <ro:info> element contains a <ro:include> element which MUST contain one or more of the following child elements:¶
<ro:registrant/>, which requests the inclusion of the contact object [RFC5733] corresponding to a domain's registrant;¶
<ro:contacts/>, which requests the inclusion of the administrative, technical and billing contacts for a domain;¶
<ro:orgs/>, which requests the inclusion of the organisations [RFC8544] associated with a domain;¶
<ro:ns/>, which requests the inclusion of the host object(s) [RFC5732] to which a domain is delegated;¶
<ro:hosts/>, which requests the inclusion of any subordinate host objects of a domain (see Section 1.1 of [RFC5731]);¶
<ro:other/>, which requests the inclusion of other related objects not covered by the previous elements, such as those described in future EPP extensions.¶
Example <info> command:¶
C: <?xml version="1.0" encoding="UTF-8" standalone="no"?> C: <epp xmlns="urn:ietf:params:xml:ns:epp-1.0"> C: <command> C: <info> C: <domain:info xmlns:domain="urn:ietf:params:xml:ns:domain-1.0"> C: <domain:name hosts="all">example.com</domain:name> C: </domain:info> C: </info> C: <extension> C: <ro:info C: xmlns:ro="https://gavinbrown.xyz/xmlns/epp/related-objects-1.0"> C: <ro:include> C: <ro:registrant/> C: <ro:ns/> C: <ro:other/> C: </ro:include> C: </ro:info> C: </extension> C: <clTRID>ABC-12345</clTRID> C: </command> C: </epp> END¶
A server responding to an <info> command that has been extended with a <ro:info> element MAY include an <ro:infData> element in the <extension> element of the response.¶
If present, the <ro:infData> element MUST include one or more <infData> elements, scoped to the namespace URI of an EPP object mapping.¶
Example <info> response:¶
S: <?xml version="1.0" encoding="UTF-8" standalone="no"?> S: <epp xmlns="urn:ietf:params:xml:ns:epp-1.0"> S: <response> S: <result code="1000"> S: <msg>Command completed successfully</msg> S: </result> S: <resData> S: <domain:infData S: xmlns:domain="urn:ietf:params:xml:ns:domain-1.0"> S: <domain:name>example.com</domain:name> S: <domain:roid>EXAMPLE1-REP</domain:roid> S: <domain:status s="ok"/> S: <domain:registrant>jd1234</domain:registrant> S: <domain:contact type="admin">sh8013</domain:contact> S: <domain:contact type="tech">sh8013</domain:contact> S: <domain:ns> S: <domain:hostObj>ns1.example.com</domain:hostObj> S: <domain:hostObj>ns1.example.net</domain:hostObj> S: </domain:ns> S: <domain:host>ns1.example.com</domain:host> S: <domain:host>ns2.example.com</domain:host> S: <domain:clID>ClientX</domain:clID> S: <domain:crID>ClientY</domain:crID> S: <domain:crDate>1999-04-03T22:00:00.0Z</domain:crDate> S: <domain:upID>ClientX</domain:upID> S: <domain:upDate>1999-12-03T09:00:00.0Z</domain:upDate> S: <domain:exDate>2005-04-03T22:00:00.0Z</domain:exDate> S: <domain:trDate>2000-04-08T09:00:00.0Z</domain:trDate> S: <domain:authInfo> S: <domain:pw>2fooBAR</domain:pw> S: </domain:authInfo> S: </domain:infData> S: </resData> S: <extension> S: <ro:infData S: xmlns:ro="https://gavinbrown.xyz/xmlns/epp/related-objects-1.0"> S: <contact:infData S: xmlns:contact="urn:ietf:params:xml:ns:contact-1.0"> S: <contact:id>jd1234</contact:id> S: <contact:roid>JD1234-REP</contact:roid> S: <contact:status s="linked"/> S: <contact:status s="clientDeleteProhibited"/> S: <contact:postalInfo type="int"> S: <contact:name>John Doe</contact:name> S: <contact:org>Example Inc.</contact:org> S: <contact:addr> S: <contact:street>123 Example Dr.</contact:street> S: <contact:street>Suite 100</contact:street> S: <contact:city>Dulles</contact:city> S: <contact:sp>VA</contact:sp> S: <contact:pc>20166-6503</contact:pc> S: <contact:cc>US</contact:cc> S: </contact:addr> S: </contact:postalInfo> S: <contact:voice x="1234">+1.7035555555</contact:voice> S: <contact:email>[email protected]</contact:email> S: <contact:clID>ClientY</contact:clID> S: <contact:crID>ClientX</contact:crID> S: <contact:crDate>1999-04-03T22:00:00.0Z</contact:crDate> S: </contact:infData> S: <host:infData S: xmlns:host="urn:ietf:params:xml:ns:host-1.0"> S: <host:name>ns1.example.com</host:name> S: <host:roid>NS1_EXAMPLE1-REP</host:roid> S: <host:status s="linked"/> S: <host:addr ip="v4">192.0.2.2</host:addr> S: <host:clID>ClientY</host:clID> S: <host:crID>ClientX</host:crID> S: <host:crDate>1999-04-03T22:00:00.0Z</host:crDate> S: </host:infData> S: <host:infData S: xmlns:host="urn:ietf:params:xml:ns:host-1.0"> S: <host:name>ns1.example.net</host:name> S: <host:roid>NS1_EXAMPLE2-REP</host:roid> S: <host:status s="linked"/> S: <host:addr ip="v4">192.0.2.29</host:addr> S: <host:clID>ClientY</host:clID> S: <host:crID>ClientX</host:crID> S: <host:crDate>1999-04-03T22:00:00.0Z</host:crDate> S: </host:infData> S: </ro:infData> S: </extension> S: <trID> S: <clTRID>ABC-12345</clTRID> S: <svTRID>54322-XYZ</svTRID> S: </trID> S: </response> S: </epp>END¶
Servers MAY choose to include all, some, or none of the relevant requested objects in the <ro:infData> element, according to applicable policies.¶
When determining whether to include a related object in the <ro:infData> element, servers SHOULD apply the same access control rules that are used to determine whether a client is authorised to perform an <info> on those objects.¶
Since EPP does not provide a way for servers to indicate a partial success or failure of a command, servers MUST NOT return an error if a related object cannot be included in a response. Instead, the object should simply be omitted from the <ro:infData> element. An error response MUST only be used when the server cannot disclose the information about the "primary" object, that is, the object specified in the <info> command.¶
The extension described in this document does not provide any security services or introduce any additional considerations beyond those described by [RFC5730] or those caused by the protocol layers used by EPP.¶
This document uses URIs to describe XML namespaces and XML schemas conforming to a registry mechanism described in [RFC3688]. IANA has made the following registrations in the IETF XML Registry [IETF-XML-REGISTRY]:¶
Registration for the XML namespace ("ns" subregistry):¶
URI: https://gavinbrown.xyz/xmlns/epp/related-objects-1.0¶
Registrant Contact: See the author of this document¶
XML: None. Namespace URIs do not represent an XML specification¶
Registration for the XML schema ("schema" subregistry):¶
URI: https://gavinbrown.xyz/xmlns/epp/related-objects-1.0¶
Registrant Contact: See the author of this document¶
XML: See the "Formal specification" section of this document¶
IANA has made the following registration in the Extensions for the "Extensible Provisioning Protocol (EPP)" [EPP-EXTENSION-REGISTRY] registry described in [RFC7451]. The details of the registration are as follows:¶
An EPP object mapping is specified in XML Schema notation. The formal syntax presented here is a complete schema representation of the object mapping suitable for automated validation of EPP XML instances.¶
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.¶
BEGIN
<?xml version="1.0" encoding="UTF-8"?>
<schema
targetNamespace="https://gavinbrown.xyz/xmlns/epp/related-objects-1.0"
xmlns:ro="https://gavinbrown.xyz/xmlns/epp/related-objects-1.0"
xmlns="http://www.w3.org/2001/XMLSchema"
elementFormDefault="qualified">
<annotation>
<documentation>
Extensible Provisioning Protocol v1.0 extension schema for
related objects.
</documentation>
</annotation>
<element name="info" type="ro:info" />
<element name="infData" type="ro:infData" />
<complexType name="info">
<sequence>
<element name="include" type="ro:include" />
</sequence>
</complexType>
<complexType name="include">
<all>
<element name="registrant" minOccurs="0" maxOccurs="1" />
<element name="contacts" minOccurs="0" maxOccurs="1" />
<element name="orgs" minOccurs="0" maxOccurs="1" />
<element name="ns" minOccurs="0" maxOccurs="1" />
<element name="hosts" minOccurs="0" maxOccurs="1" />
<element name="other" minOccurs="0" maxOccurs="1" />
</all>
</complexType>
<complexType name="infData">
<sequence>
<!--
note: a limitation of XSD 1.0 prevents forcing child elements to
have the local name "infData", but the narrative of the
specification makes it clear that this is required.
-->
<any namespace="##other" minOccurs="1" maxOccurs="unbounded" />
</sequence>
</complexType>
</schema>
END¶