Guidelines for Extending the RESTful Provisioning Protocol (RPP)

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 6 May 2027.¶

Copyright Notice

Copyright (c) 2026 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.¶

Table of Contents

1. Introduction

The RESTful Provisioning Protocol (RPP), as defined in [I-D.ietf-rpp-core], [I-D.ietf-rpp-data-objects], and [I-D.ietf-rpp-json], provides a base set of data objects, component objects, and operations for the provisioning of registry data. Deployments may need to add functionality beyond this base set, for example to support policies specific to a registry, a jurisdiction, or a class of registered objects. RPP is designed to accommodate such needs through extension specifications, so that additional functionality can be introduced without modifying the base specification that defines the object or operation being extended.¶

Because independently developed extension specifications may be deployed together, and because RPP relies on JSON Schema, as defined in [I-D.ietf-rpp-json], to validate protocol messages, extensions need to follow a common, predictable pattern. Without such a pattern, extensions that are individually valid could conflict when combined at a given deployment, or could require ad-hoc, per-combination schema and code to be written for every deployment profile. This document defines that common pattern.¶

This document identifies the set of extension points along which an RPP base specification MAY be extended, including new data objects, new data elements on existing objects, new operations, new operation inputs and outputs, external data types, new RPP result codes, error object extension fields, additional query parameters, and additions to the RPP Discovery document. For each extension point, this document states the applicable registration requirements.¶

This document further discusses considerations for client and server implementations that need to compose, validate, and process RPP messages that may include data contributed by more than one extension.¶

An extension specification MAY be published as an Internet-Draft and RFC when the extension requires coordination, interoperability and broad distribution. The intended status of such a document depends on what is extended and on the amount of general interest in the extension. An extension that is intended for a closed environment or a limited audience does not need to be published, and MAY be documented in a form that is appropriate for its audience. Such a private extension SHOULD still follow the structure and the rules in this document, so that it can be combined with other extensions at a deployment.¶

This document does not itself define any RPP extension. It defines the rules that extension specifications, and the deployments that support them, are expected to follow.¶

TODO: Make sure there is no normative language in the sections below that should be moved to the core specifications¶

2. Terminology

In this document the following terminology is used.¶

URL - A Uniform Resource Locator as defined in [RFC3986].¶

Terms of the RPP data model, such as Data Object, Component Object, Process Object, Common Data Type, data element, cardinality, mutability, Identifier, Unique Identifier, Input Data Element, Parameter, Visibility, Direct Access, Input, Output, Reference, Owner Data Object, and This Object, are used as defined in [I-D.ietf-rpp-data-objects].¶

Discovery document - The JSON document, published by an RPP server at a well-known location, that describes the capabilities of the server, including the extensions it supports, as defined in [I-D.ietf-rpp-data-objects].¶

JSON Schema - A vocabulary for describing and validating JSON documents, as defined in [JSON-SCHEMA]. This document uses JSON Schema draft 2020-12.¶

Extension Mapper (rpp:extends) - The property of an extension JSON Schema that maps the reference of an existing object definition to the local definition in the extension schema that contributes the new properties, as defined in [I-D.ietf-rpp-json].¶

Effective Schema - The Effective Schema as defined in [I-D.ietf-rpp-json].¶

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

In examples, indentation and white space are provided only to illustrate element relationships and are not REQUIRED features of the protocol.¶

4. Restrictions on Extensions

An extension MUST NOT remove, redefine, or otherwise alter the semantics of a property defined by the RPP base specification.¶

5. RPP Extension Points

An extension specification MAY extend RPP along one or more of the following independent extension points. Each extension point may have its own registration requirements.¶

6. Selecting an Extension Point

An extension SHOULD use the simplest extension point, as listed in Section 5, that fulfils the requirement. A more complex extension point increases the impact on implementations and the risk of conflicts between extensions.¶

The forms below are listed in order of increasing complexity and of increasing impact on implementations.¶

1. Reuse an existing extension point of a base specification. The base specifications define open-ended elements to which new values can be added without adding new properties, for example the labels of status objects. In such cases, the new values MUST be listed in the IANA Considerations section of the extension specification.¶
2. Add data elements to an existing object, or add input or output parameters to an existing operation, as described in Section 8.¶
3. Define a new operation, or a new process object for a long-running or multi-step operation.¶
4. Define a new data object. A new data object SHOULD NOT replicate a significant number of the data elements of an existing object.¶
5. Add protocol-level elements, such as new HTTP headers, query parameters, result codes, Problem Detail fields or Discovery document properties. These elements apply independently of any object and can have a larger impact on implementations.¶

Before defining an extension, a designer SHOULD check the IANA RPP Extensions registry, the RPP Data Object Registry and the published extension specifications for an existing extension that provides the same function, and SHOULD reuse it. Multiple extensions that provide the same function fragment the ecosystem and SHOULD be avoided.¶

An extension may use multiple extension points to fulfil its requirements, but it SHOULD still aim to use the simplest combination that achieves the desired functionality.¶

7. Identifying Extensions

Every extension must have a unique identifier, which is published using the id property of the extensions listed in the Discovery document. Standardised extensions MUST use as globally unique identifier a URN as specified below. Private extensions MUST use a URL as specified below and MUST be unique in the scope of a RPP deployment.¶

The identifier value should follow the rules as described below.¶

• The identifier of a standardised extension MUST be a URN, using the URN sub-namespace defined in [I-D.ietf-rpp-core], of the form urn:ietf:params:rpp:extension:<name>, and MUST be registered in the IANA RPP Extensions registry.¶
• The identifier of a private extension MUST be a URL using the reverse domain name notation, for example example.rpp.myextension.¶
• The version of an extension is published in the version property of the Extension Component Object. The identifier of an extension SHOULD NOT contain the version.¶

8. JSON Schema

This section defines the normative method an extension specification MUST follow when it extends the JSON Schema defined in a base specification. JSON Schema validation, as defined in [I-D.ietf-rpp-json], MUST keep functioning correctly when combining the base schema with additional schemas defined by one or more new extensions.¶

9. Extension Specification Format

An extension specification SHOULD follow the structure defined in this section, so that all extension specifications are uniform and can be read, reviewed and processed in the same way.¶

An extension specification contains the following sections, in this order:¶

1. Introduction: the purpose of the extension, the base specifications that it builds upon, and its motivation.¶
2. Extension Overview: the name, the identifier, the version, the minimum RPP version with which the extension is compatible, the $id of the JSON Schema document, the base objects that the extension updates, and the new objects that the extension defines.¶
3. External Data Types: the types, defined in an external specification, that the extension references.¶
4. Result Codes: the new result codes that the extension defines.¶
5. Problem Details: the fields that the extension adds to the Problem Detail error object.¶
6. HTTP Headers: the HTTP headers that the extension defines.¶
7. Discovery Document: the properties that the extension adds to the RPP Discovery document, in addition to its entry in the extensions list.¶

8. Updated Data Objects: the existing data objects and component objects that the extension updates.¶

   1. Data Elements: the data elements and associations that the extension adds to each updated object.¶
   2. Operations: the operations that the extension adds to each updated object.¶

9. New Data Objects: the data objects and component objects that the extension defines, including the description of each object.¶

   1. Data Elements: the data elements and associations of each new object.¶
   2. Operations: the operations of each new object.¶

10. Updated Process Objects: the existing process objects that the extension updates.¶

    1. Data Elements: the data elements and associations that the extension adds to each updated process object.¶
    2. Operations: the operations and operation parameters that the extension adds to each updated process object.¶

11. New Process Objects: the process objects that the extension defines.¶

    1. Data Elements: the data elements and associations of each new process object.¶
    2. Operations: the operations of each new process object, including their input and output parameters.¶
12. Endpoints: the endpoint URLs, HTTP methods and query parameters that result from the new data objects, associations and operations, as derived by the rules in [I-D.ietf-rpp-core]. This section is informative.¶
13. JSON Schema: the JSON Schema document of the extension, which defines the structure and constraints of the new and updated objects.¶
14. Examples: valid and invalid examples of the new and updated objects.¶
15. IANA Considerations: the values that the extension registers in the RPP IANA registries, and the new registries that the extension requests in the RPP registry group, as described in Section 10.¶
16. Security Considerations.¶
17. Privacy Considerations (optional).¶
18. Internationalization Considerations (optional).¶

Every data element that is listed in a Data Elements section MUST be defined using the data element attributes defined in [I-D.ietf-rpp-data-objects]: name, identifier, cardinality, mutability, data type, description and constraints.¶

An extension specification that follows this structure MUST include every section that is not marked as optional. A section that does not apply to the extension MUST contain the text "None".¶

The extension specification MUST define exactly one JSON Schema document, which contains the definitions for all changed and all new objects of the extension. The document MUST have a top-level $id, MUST declare the changed base objects using the Extension Mapper (rpp:extends) as described in "JSON Schema Composition", and MUST NOT contain unevaluatedProperties or additionalProperties set to false, see "Validation". An extension specification MUST NOT split its schema over multiple documents.¶

The specification MUST include at least one JSON example of a request or response representation for each operation impacted by the extension. Every example MUST validate successfully against the Effective Schema that is composed from the base schema and the JSON Schema document defined by the extension, as described in Section 8.6.¶

10. IANA Registrations

RPP defines the IANA registries listed below. When an extension specification is intended to be published as a standard track extension, the new extension MUST be registered in the relevant registries. The IANA Considerations section of the extension specification MUST request these registrations. An extension specification MUST NOT define its own registry for values that belong in one of the already defined registries. If no suitable registry exists for a value that the extension needs to register, the extension specification MUST request the creation of a new registry in its IANA Considerations section, in the RPP registry group defined in [I-D.ietf-rpp-core].¶

Private extensions are not required to use these IANA registries, but should consider reusing currently registered values where possible. They MUST still use identifiers that do not conflict with already registered identifiers.¶

The registrations are used as follows:¶

• The extension MUST be registered in the RPP Extensions registry. The identifier of the extension in the RPP Discovery document is a URN below the RPP URN sub-namespace.¶
• New and changed objects, data elements, operations and operation parameters MUST be registered in the RPP Data Object Registry. Each entry MUST reference the extension specification, so that implementations can distinguish elements of the base specifications from elements defined by extensions.¶
• The @type value of every new object MUST be the object identifier that is registered in the RPP Data Object Registry, as required by [I-D.ietf-rpp-json].¶
• New result codes MUST be registered in the RPP Result Codes registry, in the range reserved for extensions.¶

The RPP data objects also reuse values from registries that are defined outside of RPP, such as the IANA Repository of IDN Practices (IDN tables). An extension that needs a new value from one of these registries MUST use the procedure of that registry.¶

11. IANA Considerations

TODO¶

12. Security Considerations

An extension inherits the security services of the protocol structure that it extends. For example, an extension of a data object inherits the authentication, authorisation and confidentiality services that apply to that object. An extension MAY specify additional security services, such as additional authorisation checks. An extension MUST NOT mandate the removal of a security service that is available for the protocol structure that it extends.¶

An extension is subject to the same security requirements as the base specifications. The Security Considerations section of an extension specification MUST describe the security threats that are introduced by the extension and the measures to counter them, following the guidelines in [RFC3552].¶

A server MUST apply authentication and authorisation to the data elements, operations and other elements that an extension adds, in the same way as for the elements of the base specifications. A server MUST reject undeclared properties, as described in Section 8.6, and MUST reject the use of extensions that it does not support, as described in the Discovery document extension point.¶

13. Internationalization Considerations

An extension MUST observe the Internationalization Considerations of the base specifications [I-D.ietf-rpp-core], [I-D.ietf-rpp-data-objects] and [I-D.ietf-rpp-json], and the IETF policy on character sets and languages described in [RFC2277]. Human-readable text that an extension adds to a request or a response MUST be capable of being expressed in the language that is negotiated between the client and the server.¶

14. Privacy Considerations

TODO¶

15. Change History

TODO¶

Appendix A. Example Extension

This appendix is informative. It shows an extension specification that follows the structure defined in "Extension Specification Format", and it shows how the extension can be validated with a generic Java library. The example extension adds the property extProperty1 to the Domain Name data object.¶

This example extension, its schema and the examples above can be validated with the generic Java library in the rpp-json-java-lib repository [RPP-JSON-JAVA-LIB]. The library loads the base schema and the extension schemas supported by a deployment, builds Effective Schemas from the rpp:extends mappings, applies the injection of unevaluatedProperties described in Section 8.6, and validates JSON instances against the result. The repository contains this example extension, the example instances and unit tests, and its README describes how to build and run them.¶

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://rpp.example/schemas/ext-domain-extproperty1.json",

  "rpp:extends": {
    "https://rpp.example/rpp/schema.json#/$defs/domainName.create": "#/$defs/ext.domainName.create",
    "https://rpp.example/rpp/schema.json#/$defs/domainName.read": "#/$defs/ext.domainName.read"
  },

  "$defs": {
    "ext.domainName.create": {
      "type": "object",
      "properties": {
        "extProperty1": { "type": "string", "minLength": 1, "maxLength": 64 }
      },
      "required": ["extProperty1"]
    },
    "ext.domainName.read": {
      "type": "object",
      "properties": {
        "extProperty1": { "type": "string" }
      }
    }
  }
}

{
  "@type": "domainName",
  "name": "example.example",
  "registrant": { "@type": "contact", "id": "c-1234" },
  "nameservers": [
    { "@type": "host", "hostName": "ns1.example.net" }
  ],
  "extProperty1": "some value"
}

{ "@type": "domainName", "name": "example.example" }

{ "@type": "domainName", "name": "example.example", "extProperty1": 42 }

{
  "@type": "domainName",
  "name": "example.example",
  "extProperty1": "some value",
  "extProperty2": "not declared by any supported extension"
}

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://rpp.example/rpp/effective/domain.create.json",
  "$ref": "#/$defs/effective.domainName.create",
  "$defs": {
    "effective.domainName.create": {
      "allOf": [
        { "$ref": "https://rpp.example/rpp/schema.json#/$defs/domainName.create" },
        { "$ref": "https://rpp.example/schemas/ext-domain-extproperty1.json#/$defs/ext.domainName.create" }
      ]
    }
  }
}

Acknowledgements

TODO¶

Authors' Addresses