JSContact Profile for RESTful Provisioning Protocol (RPP)

4.1.1. Version

The Card "version" member value MUST be "2.0".¶

4.1.2. Kind

If present, the Card "kind" member value MUST be "individual" (default) or "org" to represent an individual or an organization, respectively.¶

4.1.3. Language

The Card "language" member SHOULD be set when localizations are specified (i.e., when the "localizations" member is present and non-empty).¶

4.1.4. Name

Other than the optional "@type" member, the Name type MUST include only the "full" member.¶

4.1.5. Organizations

Other than the optional "@type" member, the Organization type MUST include only the "name" member.¶

4.1.6. Addresses

Other 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 [BCP47] language tag.¶

4.1.7. Emails

Other than the optional "@type" member, the EmailAddress type MUST include only the "address" member.¶

4.1.8. Phones

The 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 [RFC3966] conforming to the rpp-telephone-uri rule in Figure 1. This rule restricts the [RFC3966] global-number to the telephone number format of the e164 type in Section 2.5 of [RFC5733]: 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 [RFC3966] parameters (e.g., "isub" and "phone-context") MUST NOT be used.¶

The grammar uses ABNF [RFC5234]. "DIGIT" is defined in [RFC5234].¶

rpp-telephone-uri        = "tel:" rpp-global-number
                           ; restricts telephone-uri [RFC3966]
rpp-global-number        = rpp-global-number-digits [ rpp-extension ]
                           ; restricts global-number [RFC3966]
rpp-global-number-digits = "+" 1*3DIGIT "." 1*14DIGIT
                           ; restricts global-number-digits [RFC3966]
rpp-extension            = ";ext=" 1*DIGIT
                           ; restricts extension [RFC3966]

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

4.1.9. Links

The Link type MUST include the "uri" member and MAY include the "kind" member. When the "kind" member is present, its value MUST be "contact".¶

4.1.10. Map Keys

A JSContact map key MUST comply with the Id type definition in [RFC9553]. 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 [RFC8605]; 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 Section 4.1.11.¶

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

4.1.11. Localizations

If 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 [RFC20]. 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 [RFC9982]. 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 [BCP47] 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:¶

{
  "@type": "Card",
  "version": "2.0",
  "language": "en",
  "name": {
    "full": "Joe User"
  },
  "organizations": {
    "org": { "name": "Example Org" }
  },
  "addresses": {
    "addr": {
      "components": [
        { "kind": "name",     "value": "Main Street 1" },
        { "kind": "locality", "value": "Ludwigshafen am Rhein" },
        { "kind": "region",   "value": "Rhineland-Palatinate" },
        { "kind": "postcode", "value": "67067" }
      ],
      "countryCode": "DE"
    }
  },
  "emails": {
    "email":   { "address": "joe.user@example.com" },
    "email-1": { "address": "joe@example.net" }
  },
  "phones": {
    "voice": {
      "features": { "voice": true },
      "number": "tel:+49.6215550100"
    },
    "voice-1": {
      "number": "tel:+49.6215550101;ext=1234"
    },
    "fax": {
      "features": { "fax": true },
      "number": "tel:+49.6215550199"
    }
  },
  "localizations": {
    "de": {
      "addresses": {
        "addr": {
          "components": [
            { "kind": "name",     "value": "Hauptstrasse 1" },
            { "kind": "locality", "value": "Ludwigshafen am Rhein" },
            { "kind": "region",   "value": "Rheinland-Pfalz" },
            { "kind": "postcode", "value": "67067" }
          ],
          "countryCode": "DE"
        }
      }
    }
  }
}

4.1.12. Profile Properties

The following entries define the properties of the JSContact profile for RPP registered in the JSContact Profile registry as described in Section 5.1. The field names are those defined in [RFC10050]. Entry fields with empty values are omitted:¶

• Property Name: version
  Property Context: Card¶

• Property Name: language
  Property Context: Card¶

• Property Name: kind
  Property Context: Card
  Restricted Enum Values: individual, org¶

• Property Name: name
  Property Context: Card¶

• Property Name: full
  Property Context: Name
  Restricted Attributes: mandatory¶

• Property Name: organizations
  Property Context: Card¶

• Property Name: name
  Property Context: Organization
  Restricted Attributes: mandatory¶

• Property Name: addresses
  Property Context: Card¶

• Property Name: countryCode
  Property Context: Address
  Restricted Attributes: mandatory¶

• Property Name: components
  Property Context: Address¶

• Property Name: kind
  Property Context: AddressComponent
  Restricted Enum Values: name, locality, region, postcode¶

• Property Name: value
  Property Context: AddressComponent¶

• Property Name: emails
  Property Context: Card¶

• Property Name: address
  Property Context: EmailAddress¶

• Property Name: phones
  Property Context: Card¶

• Property Name: features
  Property Context: Phone
  Restricted Enum Values: voice, fax¶

• Property Name: number
  Property Context: Phone¶

• Property Name: links
  Property Context: Card¶

• Property Name: kind
  Property Context: Link
  Restricted Enum Values: contact¶

• Property Name: uri
  Property Context: Link¶

• Property Name: localizations
  Property Context: Card
  Restricted PatchObject: yes¶

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