calext R. Stepanek Internet-Draft Fastmail Intended status: Standards Track M. Loffredo Expires: 17 October 2025 IIT-CNR 15 April 2025 Protocol-Specific Profiles for JSContact draft-ietf-calext-jscontact-profiles-00 Abstract This document defines JSContact profiles, a named subsets of JSContact elements that are supported in context of a contact data exchange protocol or other use case. It aims to facilitate using JSContact in contexts where supporting all of JSContact semantics is not appropriate. 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 17 October 2025. Copyright Notice Copyright (c) 2025 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. Stepanek & Loffredo Expires 17 October 2025 [Page 1] RFC draft-ietf-calext-jsconJSContactiProfiles April 2025 Table of Contents 1. Notational Conventions . . . . . . . . . . . . . . . . . . . 2 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 3. JSContact Profiles . . . . . . . . . . . . . . . . . . . . . 3 3.1. Profile Name . . . . . . . . . . . . . . . . . . . . . . 3 3.2. Profile Version . . . . . . . . . . . . . . . . . . . . . 4 3.3. Supported Properties . . . . . . . . . . . . . . . . . . 4 3.4. "uid" Property . . . . . . . . . . . . . . . . . . . . . 5 3.5. PatchObject Keys . . . . . . . . . . . . . . . . . . . . 5 4. Example Profile . . . . . . . . . . . . . . . . . . . . . . . 6 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 6. Security Considerations . . . . . . . . . . . . . . . . . . . 8 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 8 7.1. Normative References . . . . . . . . . . . . . . . . . . 8 Appendix A. ABNF definition for JSContact Profile Name . . . . . 9 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 9 1. Notational Conventions 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. The ABNF definitions in this document use the notations of [RFC5234]. ABNF rules not defined in this document are defined in either [RFC5234] (such as the ABNF for CRLF, WSP, DQUOTE, VCHAR, ALPHA, and DIGIT) or [RFC6350]. 2. Introduction The JSContact [RFC9553] contact card data model and format is designed for use in address book applications and directory services. Intended as an alternative to the prevalent vCard [RFC6350] data format, it covers vCard core semantics and extensions, and provides a rich model for personal names, postal addresses and localization. All JSContact elements are relevant for some contact card use case and, similar to vCard, implementations are expected to support these elements when exchanging contact card information using protocols such as CardDAV [RFC6352] and JMAP for Contacts [RFC9610]. In contrast, other protocols and internet standards might require to exchange _some_ contact card information, but not need all of what JSContact provides. Section 1.7.4 of [RFC9553] outlines how JSContact implementations may ignore unknown JSContact elements, but this only applies to future extensions of [RFC9553]; they are still Stepanek & Loffredo Expires 17 October 2025 [Page 2] RFC draft-ietf-calext-jsconJSContactiProfiles April 2025 expected to implement all elements of the core specification. Also, the extensibility of JSContact and the requirement to preserve arbitrary contact elements might not be adequate for some protocols. To make use of JSContact under these circumstances, this document defines a new IANA registry for JSContact that allows to register named subsets of JSContact elements. These subsets are referred to as "JSContact profiles" and are meant to bring the following benefits: * Protocol designers might be encouraged to use JSContact, rather than coming up with their own contacts format. This facilitates cross-protocol data exchange and migration. * Different protocols use the same IANA registry to express which JSContact elements they support. This facilitates understanding their commonalities and reusing existing profiles. * A central registry provides implementors of JSContact libraries with a consistent format documenting which profile supports what elements, rather than having to look up that information from possibly distinctly organized internet drafts. This document is organized as follows: Section 3 defines JSContact profiles, Section 4 illustrates JSContact profiles by example, Section 5 summarizes the relevant information for IANA to establish the JSContact Profiles registry. 3. JSContact Profiles A JSContact profile is a named subset of JSContact properties. The JSContact properties MUST be registered in the IANA JSContact registry. A JSContact extension MAY define both a new profile and new properties, as long as they are registered at the same time. A JSContact object conforms to a profile if all its properties are in the subset of properties defined by that profile and its property values comply with the profile restrictions. A JSContact profile MUST be registered at IANA (see Section 5). 3.1. Profile Name A JSContact profile MUST have a unique name. The name MUST only contain ASCII lowercase alphabetic and numeric characters, optionally separated by a hyphen. Formally, it MUST be a valid "profile-name" defined in the appendix section in Figure 1. Stepanek & Loffredo Expires 17 October 2025 [Page 3] RFC draft-ietf-calext-jsconJSContactiProfiles April 2025 3.2. Profile Version A JSContact profile MUST define its current version. That version identifier MUST be a valid "jsversion" value as defined in Section 1.9.1 of [RFC9553]. Any addition to the list of JSContact properties supported by that profile (Section 3.3) MUST update the current version. Should the semantic versioning scheme not be adequate for protocol designers making use of JSContact profiles, then an alternative approach is to register a new JSContact profile for each new version. 3.3. Supported Properties The subset of JSContact object properties supported by a profile is defined by a list of object properties. A JSContact property of an object type is part of this subset if one of the following conditions apply: 1. It explicitly is listed as supported for that object type in that profile. 2. It is defined for an object type which is the value type of an explicitly listed property and no properties are listed explicitly for this object type. 3. It is defined for the Card object and no properties are listed explicitly for the Card object type. A profile MUST explicitly list at least one property. If at least one property is listed explicitly for an object type, then all mandatory properties of that object type MUST be listed (this is to allow a profile restrict an object type to only its mandatory properties). The following properties need not be listed, they are always supported: * The "@type" of any object type that is supported by this profile. * The "version" property of the Card object. The "uid" property of the Card object is implicitly supported, unless it is explicitly not supported as outlined in Section 3.4. Stepanek & Loffredo Expires 17 October 2025 [Page 4] RFC draft-ietf-calext-jsconJSContactiProfiles April 2025 For each supported property, a profile MAY define an optional property to be mandatory for that profile. It also MAY restrict the value type signature of a multi-typed property e.g. only allow the value type "A" for a property having value type "A|B". In contrast, a profile MUST NOT define mandatory properties to be optional, except for the "uid" Card object property as outlined in Section 3.4. It also MUST NOT fully replace or expand the value type signature of a property, or change the default type of a multi-typed property. 3.4. "uid" Property The "uid" property [RFC9553] (Section 2.1.9) is defined to be mandatory for the Card object. This is preferable for use in addressbooks and other contact management systems. For example, it helps deduplicating contact data when merging addressbooks, and to use the same identifier to represent contact data in both JSContact and vCard Format [RFC6350]. Yet, protocol designer might prefer to set protocol-specific identifiers that are incompatible with the "uid" property value definition in some other Card property, or not to set any identifier at all. For this, a JSContact profile MAY define the Card "uid" property to either be optional or not supported at all for that profile. 3.5. PatchObject Keys The JSContact PatchObject value type [RFC9553] (Section 1.4.3) allows to patch both top-level properties and nested properties in a Card object. This results in a compact representation, as only the actually changed property values are included in the patch. Notably, the "localizations" property [RFC9553] (Section 2.7.1) of the Card object uses PatchObject values to localize Card properties. Yet, protocol designers might prefer not to support patching nested properties, typically the goal being to simplify the processing of JSContact data. For this, a JSContact profile MAY define nested PatchObject keys to not be supported. Each JSON Pointer key in a PatchObject then MUST consist of exactly one JSON Pointer reference token [RFC6901] (Section 3). In context of the "localizations" property, this means that a localized Card replaces one or more top- level properties entirely. Stepanek & Loffredo Expires 17 October 2025 [Page 5] RFC draft-ietf-calext-jsconJSContactiProfiles April 2025 4. Example Profile This section provides an example for a JSContact profile. This profile is just for illustration, it is not registered at IANA. Name: jscontact-simple Profile Version: 1.0 "uid" Property: Not Supported Nested PatchObject Keys: Not Supported Property Registry: +===============+===============+==========+============+=======+ | Property Name | Property |Restricted| Restricted |Since | | | Context |to be | Property |Profile| | | |Mandatory | Type |Version| +===============+===============+==========+============+=======+ | addresses | Card | | |1.0 | +---------------+---------------+----------+------------+-------+ | emails | Card | | |1.0 | +---------------+---------------+----------+------------+-------+ | kind | Card | | |1.0 | +---------------+---------------+----------+------------+-------+ | localizations | Card | | |1.0 | +---------------+---------------+----------+------------+-------+ | name | Card | | |1.0 | +---------------+---------------+----------+------------+-------+ | full | Address |Mandatory | |1.0 | +---------------+---------------+----------+------------+-------+ | components | Name | | |1.0 | +---------------+---------------+----------+------------+-------+ | full | Name | | |1.0 | +---------------+---------------+----------+------------+-------+ | kind | NameComponent | | |1.0 | +---------------+---------------+----------+------------+-------+ | value | NameComponent | | |1.0 | +---------------+---------------+----------+------------+-------+ Table 1: Properties of the "jscontact-simple" profile This profile describes contact cards that can only contain: Stepanek & Loffredo Expires 17 October 2025 [Page 6] RFC draft-ietf-calext-jsconJSContactiProfiles April 2025 * Full postal address lines, but no address components or any other property of the Address object type. * Full names and distinct name components, but no other properties of the Name object type. * Email addresses, where all properties of the EmailAddress object are supported. * Localizations, with the restriction that PatchObject keys must not patch nested properties. In addition, the profile defines that the "uid" property of the Card object type must not be set. The following Card object conforms to that profile: { "@type": "Card", "version": "1.0", "name": { "components": [ { "kind": "given", "value": "Akiyo" }, { "kind": "surname", "value": "Murakami" } ] }, "addresses": { "a1": { "full": "71 Cherry Court, Somewhere, 123SO, UK" } }, "emails": { "e1": { "address": "akiyo@example.com" } }, "localizations": { "jp": { "name": { "components": [ { "kind": "surname", "value": "村上" }, { "kind": "given", "value": "啓代" } ] } } } } Stepanek & Loffredo Expires 17 October 2025 [Page 7] RFC draft-ietf-calext-jsconJSContactiProfiles April 2025 5. IANA Considerations TBD 6. Security Considerations This document does not provide new security considerations. The security considerations of Section 4 of [RFC9553] apply. 7. References 7.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", STD 68, RFC 5234, DOI 10.17487/RFC5234, January 2008, . [RFC6350] Perreault, S., "vCard Format Specification", RFC 6350, DOI 10.17487/RFC6350, August 2011, . [RFC6352] Daboo, C., "CardDAV: vCard Extensions to Web Distributed Authoring and Versioning (WebDAV)", RFC 6352, DOI 10.17487/RFC6352, August 2011, . [RFC6901] Bryan, P., Ed., Zyp, K., and M. Nottingham, Ed., "JavaScript Object Notation (JSON) Pointer", RFC 6901, DOI 10.17487/RFC6901, April 2013, . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . [RFC9553] Stepanek, R. and M. Loffredo, "JSContact: A JSON Representation of Contact Data", RFC 9553, DOI 10.17487/RFC9553, May 2024, . Stepanek & Loffredo Expires 17 October 2025 [Page 8] RFC draft-ietf-calext-jsconJSContactiProfiles April 2025 [RFC9610] Jenkins, N., Ed., "JSON Meta Application Protocol (JMAP) for Contacts", RFC 9610, DOI 10.17487/RFC9610, December 2024, . Appendix A. ABNF definition for JSContact Profile Name profile-name = LALPHA *[ ["-"] LALPHA ] LALPHA = %x61-7A | DIGIT ; a-z or 0-9 Figure 1: ABNF Rule for JSContact Profile Name Authors' Addresses Robert Stepanek Fastmail PO Box 234 Collins St. West Melbourne VIC 8007 Australia Email: rsto@fastmailteam.com Mario Loffredo IIT-CNR Via Moruzzi, 1 56124 Pisa Italy Email: mario.loffredo@iit.cnr.it Stepanek & Loffredo Expires 17 October 2025 [Page 9]