RESTful Provisioning Protocol M. Wullink Internet-Draft SIDN Labs Intended status: Best Current Practice P. Kowalik Expires: 6 May 2027 DENIC 2 November 2026 Guidelines for Extending the RESTful Provisioning Protocol (RPP) draft-wullink-rpp-extension-guidelines-00 Abstract The RESTful Provisioning Protocol (RPP) defines a base set of data objects, component objects, and operations for provisioning objects. This document defines guidelines and a normative mechanism for extension specifications that add data elements, associations, operations, result codes, or other functionality, without modifying the base specifications itself. 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. Wullink & Kowalik Expires 6 May 2027 [Page 1] Internet-Draft RPP Extension Guidelines November 2026 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 . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 3. Conventions Used in This Document . . . . . . . . . . . . . . 5 4. Restrictions on Extensions . . . . . . . . . . . . . . . . . 5 5. RPP Extension Points . . . . . . . . . . . . . . . . . . . . 5 5.1. Component Objects . . . . . . . . . . . . . . . . . . . . 6 5.2. Data Objects . . . . . . . . . . . . . . . . . . . . . . 6 5.3. Process Objects . . . . . . . . . . . . . . . . . . . . . 6 5.3.1. Input Data . . . . . . . . . . . . . . . . . . . . . 6 5.4. Data Elements . . . . . . . . . . . . . . . . . . . . . . 6 5.5. Operations . . . . . . . . . . . . . . . . . . . . . . . 6 5.5.1. Inputs and Outputs . . . . . . . . . . . . . . . . . 6 5.6. External Data Types . . . . . . . . . . . . . . . . . . . 6 5.7. HTTP Endpoints . . . . . . . . . . . . . . . . . . . . . 7 5.8. HTTP Query Parameters . . . . . . . . . . . . . . . . . . 7 5.9. HTTP Headers . . . . . . . . . . . . . . . . . . . . . . 7 5.10. Result Codes . . . . . . . . . . . . . . . . . . . . . . 7 5.11. Problem Details . . . . . . . . . . . . . . . . . . . . . 7 5.12. IANA Registrations . . . . . . . . . . . . . . . . . . . 8 5.13. Discovery . . . . . . . . . . . . . . . . . . . . . . . . 8 6. Selecting an Extension Point . . . . . . . . . . . . . . . . 8 7. Identifying Extensions . . . . . . . . . . . . . . . . . . . 9 8. JSON Schema . . . . . . . . . . . . . . . . . . . . . . . . . 10 8.1. Composition . . . . . . . . . . . . . . . . . . . . . . . 10 8.2. Identification . . . . . . . . . . . . . . . . . . . . . 10 8.3. Independence of Extensions . . . . . . . . . . . . . . . 10 8.4. Consumer Implementation . . . . . . . . . . . . . . . . . 11 8.5. Registration . . . . . . . . . . . . . . . . . . . . . . 12 8.6. Validation . . . . . . . . . . . . . . . . . . . . . . . 12 9. Extension Specification Format . . . . . . . . . . . . . . . 12 10. IANA Registrations . . . . . . . . . . . . . . . . . . . . . 14 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 12. Security Considerations . . . . . . . . . . . . . . . . . . . 16 13. Internationalization Considerations . . . . . . . . . . . . . 16 14. Privacy Considerations . . . . . . . . . . . . . . . . . . . 17 15. Change History . . . . . . . . . . . . . . . . . . . . . . . 17 16. References . . . . . . . . . . . . . . . . . . . . . . . . . 17 Wullink & Kowalik Expires 6 May 2027 [Page 2] Internet-Draft RPP Extension Guidelines November 2026 16.1. Normative References . . . . . . . . . . . . . . . . . . 17 16.2. Informative References . . . . . . . . . . . . . . . . . 18 Appendix A. Example Extension . . . . . . . . . . . . . . . . . 18 A.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 19 A.2. Extension Overview . . . . . . . . . . . . . . . . . . . 19 A.3. External Data Types . . . . . . . . . . . . . . . . . . . 20 A.4. Result Codes . . . . . . . . . . . . . . . . . . . . . . 20 A.5. Problem Details . . . . . . . . . . . . . . . . . . . . . 20 A.6. HTTP Headers . . . . . . . . . . . . . . . . . . . . . . 20 A.7. Discovery Document . . . . . . . . . . . . . . . . . . . 20 A.8. Updated Data Objects . . . . . . . . . . . . . . . . . . 20 A.8.1. Domain Name Data Object . . . . . . . . . . . . . . . 20 A.8.1.1. Data Elements . . . . . . . . . . . . . . . . . . 20 A.8.1.2. Operations . . . . . . . . . . . . . . . . . . . 20 A.9. New Data Objects . . . . . . . . . . . . . . . . . . . . 21 A.10. Updated Process Objects . . . . . . . . . . . . . . . . . 21 A.11. New Process Objects . . . . . . . . . . . . . . . . . . . 21 A.12. Endpoints . . . . . . . . . . . . . . . . . . . . . . . . 21 A.13. JSON Schema . . . . . . . . . . . . . . . . . . . . . . . 21 A.14. Examples . . . . . . . . . . . . . . . . . . . . . . . . 22 A.14.1. Composition and Validation . . . . . . . . . . . . . 22 A.15. IANA Considerations . . . . . . . . . . . . . . . . . . . 23 A.16. Security Considerations . . . . . . . . . . . . . . . . . 23 A.17. Privacy Considerations . . . . . . . . . . . . . . . . . 23 A.18. Internationalization Considerations . . . . . . . . . . . 23 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 23 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 23 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. Wullink & Kowalik Expires 6 May 2027 [Page 3] Internet-Draft RPP Extension Guidelines November 2026 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]. Wullink & Kowalik Expires 6 May 2027 [Page 4] Internet-Draft RPP Extension Guidelines November 2026 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. Wullink & Kowalik Expires 6 May 2027 [Page 5] Internet-Draft RPP Extension Guidelines November 2026 5.1. Component Objects Extensions MAY define shared components that can be reused across multiple data objects, operations, or other extension points. 5.2. Data Objects Extensions MAY define entirely new data objects or extend an existing data object defined in the base specification or in another extension specification. 5.3. Process Objects Extensions MAY define entirely new process objects or extend existing ones defined in the base specification or in another extension specification. 5.3.1. Input Data Extensions MAY define new Input Data Elements for an existing or new process object. 5.4. Data Elements Extensions MAY add new data elements (properties) to an existing data object, component object, or process object defined in a base specification. 5.5. Operations Extensions MAY define entirely new operations on existing or new data objects, or extend existing operations with additional inputs, outputs, or behaviour. 5.5.1. Inputs and Outputs Extensions MAY define both input and output data elements for operations; parameters are restricted to operation inputs only. 5.6. External Data Types Instead of adding properties to an object, an extension MAY reference a type defined entirely in an external specification (e.g. External:RPP-JSContact-Profile:Card), as described in [I-D.ietf-rpp-data-objects]. This is the appropriate mechanism when substituting or supplying a whole, independently versioned data type, rather than adding fields to an existing RPP-defined object. Wullink & Kowalik Expires 6 May 2027 [Page 6] Internet-Draft RPP Extension Guidelines November 2026 5.7. HTTP Endpoints As defined in [I-D.ietf-rpp-core], every endpoint URL and HTTP method is derived mechanically from a Data Object's properties; no endpoint is defined independently of a corresponding Data Object. Consequently: * A new Data Object automatically obtains a collection endpoint once its "Identifier" is registered. * A new association with Direct Access set to true automatically obtains a sub-resource path, derived recursively from the parent resource's path. * A new operation automatically obtains its HTTP method and URL path once its "Identifier" is registered. 5.8. HTTP Query Parameters As defined in [I-D.ietf-rpp-core], every HTTP query parameter is derived mechanically from an operation parameter; no HTTP query parameter is defined independently of a corresponding operation parameter. Consequently, any transient parameter for a read, query, update, and delete operation MUST be translated into an HTTP query parameter, named by the operation's parameter identifier. 5.9. HTTP Headers Extensions MAY define new HTTP headers for existing operations, as described in [I-D.ietf-rpp-core]. Any new headers MUST be registered in the appropriate IANA registry. 5.10. Result Codes Extensions MAY define new RPP result codes within the reserved result code classes. New result codes MUST be registered in the RPP Result Codes registry defined in [I-D.ietf-rpp-core] and the extension specification MUST include a mapping of the new result codes to their corresponding HTTP status codes. 5.11. Problem Details Extensions MAY add new fields to the Problem Detail error object to convey additional, extension-specific information about the cause of an error, as described in [I-D.ietf-rpp-core]. Wullink & Kowalik Expires 6 May 2027 [Page 7] Internet-Draft RPP Extension Guidelines November 2026 5.12. IANA Registrations Extensions MAY define new IANA registries or add new entries to existing registries as required by the extension specification. The extension specification MUST clearly indicate any such IANA considerations. 5.13. Discovery A server that supports one or more extensions MUST publish every supported extension in the extensions list of its RPP Discovery document, as defined in [I-D.ietf-rpp-core]. Each entry MUST contain the name, id, version and url of the extension, using the name, identifier and version defined in the Extension Overview section of the extension specification. A client MUST NOT use an extension that is not listed in the Discovery document of the server. A server MUST reject a request that uses an extension that is not listed in its Discovery document with the RPP result code 02103 (Unimplemented extension) defined in [I-D.ietf-rpp-core], and MUST NOT include data of an unlisted extension in its responses. A server MAY restrict the use of a listed extension to specific clients, based on the identity and the authorisations of the client. The Discovery document is available without authentication, so a client can find extensions listed that it is not authorised to use. A server MUST reject a request from an unauthorised client for such an extension with an authorisation error. New properties added by an extension to the RPP Discovery document MUST be included in the appropriate section of the document, following the structure defined in [I-D.ietf-rpp-core]. 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. Wullink & Kowalik Expires 6 May 2027 [Page 8] Internet-Draft RPP Extension Guidelines November 2026 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:, 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. Wullink & Kowalik Expires 6 May 2027 [Page 9] Internet-Draft RPP Extension Guidelines November 2026 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. 8.1. Composition Every data object defined in a base specification, when modified by an extension specification, must be extended using an extension specification. The extension specification MUST define a new JSON Schema document that composes the base object's schema with the new properties using allOf. The extension specification MUST NOT copy, redefine, or otherwise restate the JSON Schema definition of the base object. Instead, it MUST reference the base object's definition by its fully qualified $id-relative pointer (e.g. https://www.iana.org/.../domainName.json#/$defs/domainName) in an allOf branch, and add its own new properties in a separate branch. An extension schema MUST declare which base object definitions it extends using the Extension Mapper (rpp:extends) property, as defined in [I-D.ietf-rpp-json]. The property maps the fully qualified reference of each base object definition to the local definition, within the extension schema, that contributes the new properties. This mapping allows an implementation to construct, for a given base object, the Effective Schema that combines the base definition with every supported extension, without any knowledge of the extensions in advance. 8.2. Identification A specification that defines JSON Schema for RPP objects MUST assign a stable $id to its schema document(s). Extension specifications MUST reference a base object's definition by its $id (e.g. https://www.iana.org/.../domainName.json#/$defs/domainName) rather than copying the base definition into their own schema. 8.3. Independence of Extensions Extensions MUST be independent of one another. An extension MUST NOT extend, change or otherwise depend on a definition that is introduced by another extension, such as a data object, data element or operation. The Extension Mapper (rpp:extends) property of an extension schema MUST only reference definitions of base specifications, and an extension MUST NOT require that another Wullink & Kowalik Expires 6 May 2027 [Page 10] Internet-Draft RPP Extension Guidelines November 2026 extension is supported. When the functionality of an existing extension needs to be extended, a new version of that extension MUST be defined instead of a second extension that builds upon the first one. The new version keeps the identifier of the extension and updates the version, as described in Section 7. A server publishes the version of the extension that it supports in its Discovery document. 8.4. Consumer Implementation A consumer, which can be a server or client, does not need to generate a distinct set of code classes for every base object and extension combination offered by a particular server. Because extension schemas are additive, self-contained, and independent of one another, a consumer implementation SHOULD instead maintain one set of code classes for each base object and a separate set of code classes for each extension it supports, keeping an extension's classes distinct from the base object's classes rather than flattening their properties together. Composing a base object with whichever extensions apply then becomes a runtime decision, rather than something fixed by code generation for every individual server. A consumer learns at runtime which extensions a given server supports from the extensions list in that server's RPP Discovery response, as defined in [I-D.ietf-rpp-core]. It SHOULD attach, populate, and validate extension class instances only for the extensions the server has advertised as supported, and SHOULD ignore any properties in a response that belong to an extension it does not recognise or does not support. Because an extension that is not attached to a given base object instance contributes no properties at all, a consumer naturally serialises only the base object together with the properties of whichever extensions are actually in use, without needing to distinguish this case from a property that is merely absent or null within a supported extension. Attached extensions are merged flat with the base object on the wire, consistent with the schema composition described in "JSON Schema Composition". Within an attached extension, an optional property without a value continues to follow Rule 2 and is omitted from the output rather than represented as null. Wullink & Kowalik Expires 6 May 2027 [Page 11] Internet-Draft RPP Extension Guidelines November 2026 8.5. Registration A standardised extension specification MUST be registered in the RPP Extensions registry defined in [I-D.ietf-rpp-core], see Section 10. The registration MUST contain the values of the Extension Overview section of the extension specification, see Section 9: the name, the identifier, the version, the RPP version, the $id of the JSON Schema document, the changed base objects and the new objects. The identifier of the extension in the RPP Discovery document is a URN below the RPP URN sub-namespace. The registration MUST include a dereferenceable URL to the JSON Schema document. *TODO:* The registration registry in rpp-data-objects needs to be updated to support what is described here. 8.6. Validation A deployment that supports a specific combination of extensions (a profile, as defined in [I-D.ietf-rpp-core]) MUST build, for every extended object type, a combined schema consisting of the base object's definition and the allOf branch contributed by every supported extension registered for that object type. Before using a combined schema to validate a JSON instance, implementations MUST inject "unevaluatedProperties": false at every object-schema node of the combined schema, following the algorithm described in [I-D.ietf-rpp-json]. This injection MUST be performed only on the combined, per-deployment schema, and MUST NOT be present in the schema document published by any individual base or extension specification. This ensures undeclared properties are rejected while any supported combination of registered extensions validates successfully. 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. Wullink & Kowalik Expires 6 May 2027 [Page 12] Internet-Draft RPP Extension Guidelines November 2026 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. Wullink & Kowalik Expires 6 May 2027 [Page 13] Internet-Draft RPP Extension Guidelines November 2026 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]. Wullink & Kowalik Expires 6 May 2027 [Page 14] Internet-Draft RPP Extension Guidelines November 2026 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. +===================+===========================+=============+====================================+ |Registry |Defined in |Registration |An extension registers an entry when| | | |procedure |it | +===================+===========================+=============+====================================+ |RPP Extensions |[I-D.ietf-rpp-core] |Expert Review|is published; every standardised | | | | |extension MUST be registered, with | | | | |its name, version and specification | | | | |URL | +-------------------+---------------------------+-------------+------------------------------------+ |RPP Data Object |[I-D.ietf-rpp-data-objects]|Specification|introduces a new data object, | |Registry | |Required |component object or process object, | | | | |adds a data element to an existing | | | | |object, or defines a new operation | | | | |or operation parameter | +-------------------+---------------------------+-------------+------------------------------------+ |RPP Result Codes |[I-D.ietf-rpp-core] |Expert Review|defines a new result code | +-------------------+---------------------------+-------------+------------------------------------+ |Link Relation Types|[RFC8288], used by |as defined in|defines a new link relation type, in| | |[I-D.ietf-rpp-core] |RFC 8288 |addition to rpp-process | +-------------------+---------------------------+-------------+------------------------------------+ |Media Types |[RFC6838], used by |as defined in|defines a representation format with| | |[I-D.ietf-rpp-core] |RFC 6838 |its own media type, in addition to | | | | |application/rpp+json | +-------------------+---------------------------+-------------+------------------------------------+ |IETF URN Sub- |[I-D.ietf-rpp-core] |as defined in|needs an identifier below the RPP | |namespace, | |RFC 3553 |URN namespace, for example | |urn:ietf:params:rpp| | |urn:ietf:params:rpp:extension:| +-------------------+---------------------------+-------------+------------------------------------+ Table 1 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. Wullink & Kowalik Expires 6 May 2027 [Page 15] Internet-Draft RPP Extension Guidelines November 2026 * 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. Wullink & Kowalik Expires 6 May 2027 [Page 16] Internet-Draft RPP Extension Guidelines November 2026 14. Privacy Considerations *TODO* 15. Change History *TODO* 16. References 16.1. Normative References [I-D.ietf-rpp-core] Wullink, M. and P. Kowalik, "RESTful Provisioning Protocol (RPP)", Work in Progress, Internet-Draft, draft-ietf-rpp- core-01, 2 November 2026, . [I-D.ietf-rpp-data-objects] Kowalik, P. and M. Wullink, "RESTful Provisioning Protocol (RPP) Data Objects", Work in Progress, Internet-Draft, draft-ietf-rpp-data-objects-01, 3 July 2026, . [I-D.ietf-rpp-json] Wullink, M. and P. Kowalik, "JSON for RESTful Provisioning Protocol (RPP)", Work in Progress, Internet-Draft, draft- ietf-rpp-json-01, 2 November 2026, . [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC2277] Alvestrand, H., "IETF Policy on Character Sets and Languages", BCP 18, RFC 2277, DOI 10.17487/RFC2277, January 1998, . [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, January 2005, . Wullink & Kowalik Expires 6 May 2027 [Page 17] Internet-Draft RPP Extension Guidelines November 2026 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type Specifications and Registration Procedures", BCP 13, RFC 6838, DOI 10.17487/RFC6838, January 2013, . [RFC8288] Nottingham, M., "Web Linking", RFC 8288, DOI 10.17487/RFC8288, October 2017, . 16.2. Informative References [I-D.wullink-rpp-extension-guidelines] Wullink, M. and P. Kowalik, "Guidelines for Extending the RESTful Provisioning Protocol (RPP)", Work in Progress, Internet-Draft, draft-wullink-rpp-extension-guidelines-00, 2026, . [JSON-SCHEMA] JSON Schema, "JSON Schema: A vocabulary for describing JSON Data", 2020, . [RFC3552] Rescorla, E. and B. Korver, "Guidelines for Writing RFC Text on Security Considerations", BCP 72, RFC 3552, DOI 10.17487/RFC3552, July 2003, . [RPP-JSON-JAVA-LIB] SIDN Labs, "rpp-json-java-lib: Java library for RPP JSON Schema extensions", 2026, . 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. Wullink & Kowalik Expires 6 May 2027 [Page 18] Internet-Draft RPP Extension Guidelines November 2026 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. A.1. Introduction This document provides an example of an extension specification, following the guidelines defined in [I-D.wullink-rpp-extension-guidelines]. The example demonstrates how to add a new property to an existing data object and how to define the corresponding JSON Schema and examples. A.2. Extension Overview +============+====================================================+ | Field | Value | +============+====================================================+ | Name | RPP Example Extension Property | +------------+----------------------------------------------------+ | Identifier | urn:ietf:params:rpp:extension:example-ext-property | +------------+----------------------------------------------------+ | Version | 1.0 | +------------+----------------------------------------------------+ | RPP | 1.0 | | version | | +------------+----------------------------------------------------+ | Schema $id | https://rpp.example/schemas/ext-domain- | | | extproperty1.json (https://rpp.example/schemas/ | | | ext-domain-extproperty1.json) | +------------+----------------------------------------------------+ | Changed | domainName | | base | | | objects | | +------------+----------------------------------------------------+ | New | None | | objects | | +------------+----------------------------------------------------+ Table 2 Wullink & Kowalik Expires 6 May 2027 [Page 19] Internet-Draft RPP Extension Guidelines November 2026 A.3. External Data Types None. A.4. Result Codes None. A.5. Problem Details None. A.6. HTTP Headers None. A.7. Discovery Document None. A.8. Updated Data Objects A.8.1. Domain Name Data Object * Identifier: domainName A.8.1.1. Data Elements The following data element is added to the Domain Name Data Object. * Extension Property 1 - Identifier: extProperty1 - Cardinality: 1 - Mutability: create-only - Data Type: String - Description: An example property that is added to the Domain Name Data Object by the extension. - Constraints: o The value MUST contain between 1 and 64 characters. o The value MUST be provided in the Create operation. The Read operation returns extProperty1 when the domain name was created with a value for it. A.8.1.2. Operations None. Wullink & Kowalik Expires 6 May 2027 [Page 20] Internet-Draft RPP Extension Guidelines November 2026 A.9. New Data Objects None. A.10. Updated Process Objects None. A.11. New Process Objects None. A.12. Endpoints None. A.13. JSON Schema The extension defines a single JSON Schema document. The document declares, using the Extension Mapper (rpp:extends) property, that it extends the create and read definitions of the base object, and contributes the new property in a separate definition: { "$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" } } } } } Wullink & Kowalik Expires 6 May 2027 [Page 21] Internet-Draft RPP Extension Guidelines November 2026 A.14. Examples The following instance is valid, because extProperty1 is declared by the supported extension: { "@type": "domainName", "name": "example.example", "registrant": { "@type": "contact", "id": "c-1234" }, "nameservers": [ { "@type": "host", "hostName": "ns1.example.net" } ], "extProperty1": "some value" } The following instances are invalid. The first omits the required extProperty1, the second gives extProperty1 the wrong type, and the third contains extProperty2, which no supported extension declares and which is therefore rejected by the injected unevaluatedProperties keyword: { "@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" } The same instance that uses extProperty1 is rejected by a deployment that does not support the extension, since in that deployment extProperty1 is an undeclared property. This is the behaviour required by "Validation": the set of accepted properties is determined only by the extensions that the deployment supports. A.14.1. Composition and Validation For a deployment that supports the example extension, the Effective Schema for domainName.create references the base definition and the extension definition, and has its own $id: Wullink & Kowalik Expires 6 May 2027 [Page 22] Internet-Draft RPP Extension Guidelines November 2026 { "$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" } ] } } } A.15. IANA Considerations *TODO:* A.16. Security Considerations *TODO:* A.17. Privacy Considerations *TODO:* A.18. Internationalization Considerations *TODO:* Acknowledgements *TODO* Authors' Addresses Maarten Wullink SIDN Labs Email: maarten.wullink@sidn.nl URI: https://sidn.nl/ Pawel Kowalik DENIC Email: pawel.kowalik@denic.de URI: https://denic.de/ Wullink & Kowalik Expires 6 May 2027 [Page 23]