JSContact Profile for RESTful Provisioning Protocol (RPP)SIDN Labsmaarten.wullink@sidn.nlhttps://sidn.nl/DENICpawel.kowalik@denic.dehttps://denic.de/
Internet
Network Working GroupRPPJSContactcontactprovisioningThis document defines a JSContact usage profile, conforming to the rules described in RFC 10050, for the RESTful Provisioning Protocol (RPP). The JSContact Profile for RPP specifies how the JSContact format defined in RFC 9982 can be used as a standardized representation of contact information within RPP operations, enabling interoperability and consistency across RPP implementations that manage contact data.IntroductionJSContact is a flexible, JSON-based format for representing contact
information. Its flexibility allows the same data to be expressed in multiple
valid ways, which can hinder interoperability in a provisioning context where
data must be stored and interpreted consistently.This document defines a JSContact usage profile for the RESTful Provisioning
Protocol (RPP), restricting the set of JSContact constructs that RPP clients and
servers are required to support when provisioning contact information.Relationship to the RDAP JSContact ProfileThe Registration Data Access Protocol (RDAP) provides read-only
access to registration data managed by RPP. Both protocols use JSContact for
contact representation, but with profiles suited to their respective roles.The RDAP JSContact profile defines the constructs used when serving registration data to read-only consumers. The RPP profile, defined in this document, is a subset of these constructs. All JSContact constructs permitted by the RPP profile can be used for RDAP.The converse does not hold. RDAP supports additional JSContact constructs that are useful in the read-only context of RDAP responses but that may hinder interoperability. These constructs are not present in RPP requests and responses.TerminologyIn this document, the following terminology is used.RESTful Provisioning Protocol or RPP - The protocol described in this document.URL - A Uniform Resource Locator as defined in .RPP client - An HTTP user agent performing an RPP request.RPP server - An HTTP server responsible for processing requests and returning results in any supported media type.Internationalized form - The representation of contact information in the Card members outside the "localizations" map.Localized form - A representation of contact information placed in the "localizations" map, keyed by a language tag.Conventions Used in This DocumentThe 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 .Using JSContact in RPPJSContact Profile for RPPSince JSContact is a generalized representation of contact data, many of its
capabilities are not optimized for interoperable use in RPP payloads. This
document therefore defines a usage profile for JSContact that simplifies
implementation for both RPP clients and RPP servers.The JSContact profile for RPP is compliant with the rules described in
. The profile properties are formally
listed in . All types mentioned in this section refer to
the JSContact specification .VersionThe Card "version" member value MUST be "2.0".KindIf present, the Card "kind" member value MUST be "individual" (default) or
"org" to represent an individual or an organization, respectively.LanguageThe Card "language" member SHOULD be set when localizations are specified
(i.e., when the "localizations" member is present and non-empty).NameOther than the optional "@type" member, the Name type MUST include only the "full" member.OrganizationsOther than the optional "@type" member, the Organization type MUST include only the "name" member.AddressesOther than the optional "@type" member, the Address type MUST include only the "components" and "countryCode" members.Other than the optional "@type" member, the AddressComponent type MUST include only the "kind" and "value" members. The "kind" member value MUST be one of "name", "locality", "region", or "postcode".The Address type MUST include the "countryCode" member. The "components" member MUST contain exactly one "locality" component, at most one "region" component, and at most one "postcode" component.The "name" components represent street lines. The server MAY constrain the maximum number of "name" components supported. Their order in the "components" array is significant and MUST be preserved.When both an internationalized and a localized version of an address are used, the localized version MUST be placed in the "localizations" map keyed by an appropriate language tag.EmailsOther than the optional "@type" member, the EmailAddress type MUST include only the "address" member.PhonesThe Phone type MUST include the "number" member and MAY include the
"features" member. If present, the "features" member MUST contain only the
"voice" or "fax" keys, and the value associated with each key MUST be
true. When the "features" member is absent, the phone number is assumed to
be a voice number.The "number" member value MUST be a "tel" URI conforming to
the rpp-telephone-uri rule in . This rule restricts the
global-number to the telephone number format of the e164 type in Section 2.5 of : a leading "+", a country code of one to three digits, a ".", and a subscriber number of up to 14 digits, optionally followed by an "ext" parameter carrying one or more digits. The total number of digits in the country code and subscriber number MUST NOT exceed 15. Local
numbers, other visual separators, and other parameters (e.g., "isub" and "phone-context") MUST NOT be used.The grammar uses ABNF . "DIGIT" is defined in .ABNF for the Phone number member
Examples of valid values are "tel:+49.6215550100" and
"tel:+49.6215550100;ext=123". An RPP server MUST reject a Phone whose
"number" member value does not conform to this format.LinksThe Link type MUST include the "uri" member and MAY include the "kind" member.
When the "kind" member is present, its value MUST be "contact".Map KeysA JSContact map key MUST comply with the Id type definition in . RPP implementations MUST use the following predefined keys:
"org" in the "organizations" map for a single preferred organization.
"addr" in the "addresses" map for a single preferred postal address.
"email" in the "emails" map for the preferred email address.
"voice" in the "phones" map for the preferred voice number.
"fax" in the "phones" map for the preferred fax number.
"url" in the "links" map for a preferred contact URL; the "kind" member of
the Link object MUST NOT be set.
"contact-uri" in the "links" map for a contact URI as defined in ;
the "kind" member of the Link object MUST be set to "contact".
When internationalized and localized versions of an organization, postal address, or email exist, the internationalized version MUST be included under the predefined map key, while the localized version MUST be placed in the "localizations" map as described in .Keys MUST be of the form "<predefined key>-<sequential number>" for any additional entry in the "emails" or "phones" map, where the sequential number is a decimal integer starting at 1. For example, a "phones" map containing three voice numbers contains the keys "voice", "voice-1", and "voice-2". An additional key MUST NOT be used unless the corresponding predefined key is also present, and the sequential numbers MUST NOT contain gaps.LocalizationsIf present, localized variants of name, organization, postal address, and email MUST be added to the "localizations" map. RPP implementations MUST
expand all localizations, meaning a nested PatchObject key of the form "{key1}/{key2}/.../{keyN}" MUST NOT be used.The internationalized form MUST contain only characters that can be represented in the 7-bit US-ASCII character set . This applies to the "full" member of Name, the "name" member of Organization, the "value" member of AddressComponent, and the "address" member of EmailAddress. A localized form MAY contain any character permitted by . When contact information is available only in a form containing non-ASCII characters, the RPP client MUST provide a US-ASCII transliteration as the internationalized form. An RPP server MUST reject a Card whose internationalized form contains characters outside the US-ASCII character set.An RPP server MUST support at least one localization per Card. An RPP server MAY support more localizations, as determined by server policy. An RPP server MUST reject a Card that contains more localizations than it supports. The language of each localization MUST be indicated by a language tag as the key in the "localizations" map.The following example of a Card includes two email addresses, two voice numbers, a fax number, and a localized version of the postal address:Example of handling localizations in JSContact
Profile PropertiesThe following entries define the properties of the JSContact profile for RPP
registered in the JSContact Profile registry as described in
. The field names are those defined in
. Entry fields with empty values are omitted:
The "@type" member is permitted on every JSContact object in this profile and
is therefore not listed above.An RPP server MUST reject a Card that contains a JSContact property not listed in this section.IANA ConsiderationsJSContact Profile RegistryIANA is requested to register the following entry in the "JSContact Profile" registry :Name: rpp
Version: 1.0
Reference: of this documentTODOInternationalization ConsiderationsTODOSecurity ConsiderationsRPP servers should impose appropriate limits on the size and complexity of
JSContact objects received from RPP clients, including the number and size of
expanded localizations.TODOChange HistoryRFC Editor: please remove this section before publication.Version 01 to 02
Replaced the reference to draft-ietf-calext-jscontact-profiles with RFC 10050
Aligned with draft-ietf-regext-rdap-jscontact-27, making the RPP profile a
subset of the RDAP JSContact profile, and made that reference informative
(Issue #20)
Made the Address "countryCode" member mandatory, removed Address "full"
from the profile properties, limited the number of each AddressComponent
kind, and made the order of street lines significant (Issue #19)
Restricted the internationalized form to US-ASCII and required RPP servers to
support at least one localization, with additional localizations subject to
server policy (Issue #6)
Allowed multiple email addresses and voice and fax numbers using sequentially
numbered map keys (Issue #5)
Required the Phone "number" member to be a "tel" URI (RFC 3966)
restricted to the Extensible Provisioning Protocol (EPP) telephone number
format, and added ABNF for it
Added the terms internationalized form and localized form
Permitted the "@type" member on every JSContact object and corrected the
Organization member to "name"
Made the Card "kind" member optional
Converted the profile properties table into a list using the RFC 10050 field
names
Referenced RFC 8605 for the "contact-uri" map key
Added the Card "version" member to the profile properties
Required RPP servers, instead of client validation, to reject a Card
containing properties outside the profile