RFC 6350
vCard Format Specification
RFC 6350: vCard Format Specification 🎀
okay bestie, this one is the vCard spec 📇 It was written by S. Perreault at Viagenie and published in August 2011 as RFC 6350. It's on the Standards Track (ISSN 2070-1721), and it was published by the Internet Engineering Task Force (IETF). It's giving official Internet standard 💅 It obsoletes RFCs 2425, 2426, and 4770, and it updates RFC 2739. So if you're still reading the old ones, this is the newer version. 🦋
Abstract ✨
so the vCard data format is the way we represent and swap all kinds of info about people and other entities 💖 think formatted and structured names, delivery addresses, email addresses, multiple phone numbers, photos, logos, audio clips, and more. this doc obsoletes RFCs 2425, 2426, and 4770, and updates RFC 2739. 🌸
Status of This Memo
this is an Internet Standards Track document. 🎀
this doc is a product of the Internet Engineering Task Force (IETF). it represents the consensus of the IETF community 🫶 it went through public review and got approved for publication by the Internet Engineering Steering Group (IESG). if you want more info on Internet Standards, check out Section 2 of RFC 5741 📚
info about the current status of this document, any errata, and how to give feedback on it can be found at http://www.rfc-editor.org/info/rfc6350 🔗 (sorry, no clickable links in here, copy and paste it 💕)
Copyright Notice
Copyright (c) 2011 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 (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. please read these carefully, bestie, because they explain your rights and restrictions for this document 🙈 code components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions, and they're provided without warranty as described in the Simplified BSD License.
this document may contain material from IETF Documents or IETF Contributions published or made publicly available before November 10, 2008. the person(s) controlling the copyright in some of that material may not have granted the IETF Trust the right to allow modifications outside the IETF Standards Process. without getting an adequate license from the person(s) controlling the copyright in those materials, this document may not be modified outside the IETF Standards Process, and derivative works of it may not be created outside the IETF Standards Process. the exceptions are formatting it for publication as an RFC or translating it into languages other than English 🌍
Table of Contents 📑
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5
2. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . 5
3. vCard Format Specification . . . . . . . . . . . . . . . . . . 5
3.1. Charset . . . . . . . . . . . . . . . . . . . . . . . . . 5
3.2. Line Delimiting and Folding . . . . . . . . . . . . . . . 5
3.3. ABNF Format Definition . . . . . . . . . . . . . . . . . . 6
3.4. Property Value Escaping . . . . . . . . . . . . . . . . . 9
4. Property Value Data Types . . . . . . . . . . . . . . . . . . 9
4.1. TEXT . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.2. URI . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
4.3. DATE, TIME, DATE-TIME, DATE-AND-OR-TIME, and TIMESTAMP . . 12
4.3.1. DATE . . . . . . . . . . . . . . . . . . . . . . . . . 12
4.3.2. TIME . . . . . . . . . . . . . . . . . . . . . . . . . 13
4.3.3. DATE-TIME . . . . . . . . . . . . . . . . . . . . . . 13
4.3.4. DATE-AND-OR-TIME . . . . . . . . . . . . . . . . . . . 14
4.3.5. TIMESTAMP . . . . . . . . . . . . . . . . . . . . . . 14
4.4. BOOLEAN . . . . . . . . . . . . . . . . . . . . . . . . . 14
4.5. INTEGER . . . . . . . . . . . . . . . . . . . . . . . . . 15
4.6. FLOAT . . . . . . . . . . . . . . . . . . . . . . . . . . 15
4.7. UTC-OFFSET . . . . . . . . . . . . . . . . . . . . . . . . 15
4.8. LANGUAGE-TAG . . . . . . . . . . . . . . . . . . . . . . . 16
5. Property Parameters . . . . . . . . . . . . . . . . . . . . . 16
5.1. LANGUAGE . . . . . . . . . . . . . . . . . . . . . . . . . 16
5.2. VALUE . . . . . . . . . . . . . . . . . . . . . . . . . . 16
5.3. PREF . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
5.4. ALTID . . . . . . . . . . . . . . . . . . . . . . . . . . 18
5.5. PID . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
5.6. TYPE . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
5.7. MEDIATYPE . . . . . . . . . . . . . . . . . . . . . . . . 20
5.8. CALSCALE . . . . . . . . . . . . . . . . . . . . . . . . . 20
5.9. SORT-AS . . . . . . . . . . . . . . . . . . . . . . . . . 21
5.10. GEO . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
5.11. TZ . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
6. vCard Properties . . . . . . . . . . . . . . . . . . . . . . . 23
6.1. General Properties . . . . . . . . . . . . . . . . . . . . 23
6.1.1. BEGIN . . . . . . . . . . . . . . . . . . . . . . . . 23
6.1.2. END . . . . . . . . . . . . . . . . . . . . . . . . . 23
6.1.3. SOURCE . . . . . . . . . . . . . . . . . . . . . . . . 24
6.1.4. KIND . . . . . . . . . . . . . . . . . . . . . . . . . 25
6.1.5. XML . . . . . . . . . . . . . . . . . . . . . . . . . 27
6.2. Identification Properties . . . . . . . . . . . . . . . . 28
6.2.1. FN . . . . . . . . . . . . . . . . . . . . . . . . . . 28
6.2.2. N . . . . . . . . . . . . . . . . . . . . . . . . . . 29
6.2.3. NICKNAME . . . . . . . . . . . . . . . . . . . . . . . 29
6.2.4. PHOTO . . . . . . . . . . . . . . . . . . . . . . . . 30
6.2.5. BDAY . . . . . . . . . . . . . . . . . . . . . . . . . 30
6.2.6. ANNIVERSARY . . . . . . . . . . . . . . . . . . . . . 31
6.2.7. GENDER . . . . . . . . . . . . . . . . . . . . . . . . 32
6.3. Delivery Addressing Properties . . . . . . . . . . . . . . 32
6.3.1. ADR . . . . . . . . . . . . . . . . . . . . . . . . . 32
6.4. Communications Properties . . . . . . . . . . . . . . . . 34
6.4.1. TEL . . . . . . . . . . . . . . . . . . . . . . . . . 34
6.4.2. EMAIL . . . . . . . . . . . . . . . . . . . . . . . . 36
6.4.3. IMPP . . . . . . . . . . . . . . . . . . . . . . . . . 36
6.4.4. LANG . . . . . . . . . . . . . . . . . . . . . . . . . 37
6.5. Geographical Properties . . . . . . . . . . . . . . . . . 37
6.5.1. TZ . . . . . . . . . . . . . . . . . . . . . . . . . . 37
6.5.2. GEO . . . . . . . . . . . . . . . . . . . . . . . . . 38
6.6. Organizational Properties . . . . . . . . . . . . . . . . 39
6.6.1. TITLE . . . . . . . . . . . . . . . . . . . . . . . . 39
6.6.2. ROLE . . . . . . . . . . . . . . . . . . . . . . . . . 39
6.6.3. LOGO . . . . . . . . . . . . . . . . . . . . . . . . . 40
6.6.4. ORG . . . . . . . . . . . . . . . . . . . . . . . . . 40
6.6.5. MEMBER . . . . . . . . . . . . . . . . . . . . . . . . 41
6.6.6. RELATED . . . . . . . . . . . . . . . . . . . . . . . 42
6.7. Explanatory Properties . . . . . . . . . . . . . . . . . . 43
6.7.1. CATEGORIES . . . . . . . . . . . . . . . . . . . . . . 43
6.7.2. NOTE . . . . . . . . . . . . . . . . . . . . . . . . . 44
6.7.3. PRODID . . . . . . . . . . . . . . . . . . . . . . . . 44
6.7.4. REV . . . . . . . . . . . . . . . . . . . . . . . . . 45
6.7.5. SOUND . . . . . . . . . . . . . . . . . . . . . . . . 45
6.7.6. UID . . . . . . . . . . . . . . . . . . . . . . . . . 46
6.7.7. CLIENTPIDMAP . . . . . . . . . . . . . . . . . . . . . 47
6.7.8. URL . . . . . . . . . . . . . . . . . . . . . . . . . 47
6.7.9. VERSION . . . . . . . . . . . . . . . . . . . . . . . 48
6.8. Security Properties . . . . . . . . . . . . . . . . . . . 48
6.8.1. KEY . . . . . . . . . . . . . . . . . . . . . . . . . 48
6.9. Calendar Properties . . . . . . . . . . . . . . . . . . . 49
6.9.1. FBURL . . . . . . . . . . . . . . . . . . . . . . . . 49
6.9.2. CALADRURI . . . . . . . . . . . . . . . . . . . . . . 50
6.9.3. CALURI . . . . . . . . . . . . . . . . . . . . . . . . 50
6.10. Extended Properties and Parameters . . . . . . . . . . . . 51
7. Synchronization . . . . . . . . . . . . . . . . . . . . . . . 51
7.1. Mechanisms . . . . . . . . . . . . . . . . . . . . . . . . 51
7.1.1. Matching vCard Instances . . . . . . . . . . . . . . . 51
7.1.2. Matching Property Instances . . . . . . . . . . . . . 52
7.1.3. PID Matching . . . . . . . . . . . . . . . . . . . . . 52
7.2. Example . . . . . . . . . . . . . . . . . . . . . . . . . 53
7.2.1. Creation . . . . . . . . . . . . . . . . . . . . . . . 53
7.2.2. Initial Sharing . . . . . . . . . . . . . . . . . . . 53
7.2.3. Adding and Sharing a Property . . . . . . . . . . . . 54
7.2.4. Simultaneous Editing . . . . . . . . . . . . . . . . . 54
7.2.5. Global Context Simplification . . . . . . . . . . . . 56
8. Example: Author's vCard . . . . . . . . . . . . . . . . . . . 56
9. Security Considerations . . . . . . . . . . . . . . . . . . . 57
10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 58
10.1. Media Type Registration . . . . . . . . . . . . . . . . . 58
10.2. Registering New vCard Elements . . . . . . . . . . . . . . 59
10.2.1. Registration Procedure . . . . . . . . . . . . . . . . 59
10.2.2. Vendor Namespace . . . . . . . . . . . . . . . . . . . 60
10.2.3. Registration Template for Properties . . . . . . . . . 61
10.2.4. Registration Template for Parameters . . . . . . . . . 61
10.2.5. Registration Template for Value Data Types . . . . . . 62
10.2.6. Registration Template for Values . . . . . . . . . . . 62
10.3. Initial vCard Elements Registries . . . . . . . . . . . . 63
10.3.1. Properties Registry . . . . . . . . . . . . . . . . . 64
10.3.2. Parameters Registry . . . . . . . . . . . . . . . . . 65
10.3.3. Value Data Types Registry . . . . . . . . . . . . . . 65
10.3.4. Values Registries . . . . . . . . . . . . . . . . . . 66
11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 69
12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 69
12.1. Normative References . . . . . . . . . . . . . . . . . . . 69
12.2. Informative References . . . . . . . . . . . . . . . . . . 71
Appendix A. Differences from RFCs 2425 and 2426 . . . . . . . . . 73
A.1. New Structure . . . . . . . . . . . . . . . . . . . . . . 73
A.2. Removed Features . . . . . . . . . . . . . . . . . . . . . 73
A.3. New Properties and Parameters . . . . . . . . . . . . . . 731. Introduction ✨
electronic address books are literally everywhere now 📱 and they show up on portable, connected devices, plus there's a huge variety of platforms swapping contact data around. so yeah, we need a standard 🫶 this memo defines the vCard format, which lets you capture and exchange the kind of info you'd normally keep in an address book or directory app 💜
a high-level overview of the differences from RFCs 2425 and 2426 can be found in Appendix A 📖
2. 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 [RFC2119]. these are the official requirement words, so pay attention to them, bestie 👑
part 1 of 12 is done! 🦋 more parts are coming, so stay tuned 💅
3. vCard Format Specification ✨
okay so the text/vcard MIME content type (we're calling it "vCard" from here on, see Section 10.1 🎀) is the thing that holds contact info, usually for one contact or a whole group of them 💖 A vCard is built out of one or more lines in the format below, and we're about to go through all of it 🦋
3.1. Charset
the charset for vCard is UTF-8 🌸 as defined in [RFC3629]. if you want the internationalization terminology, peep [RFC3536]. there is no way to override this, periodt 💅 and specifying any value other than "UTF-8" in the "charset" MIME parameter is invalid (see Section 10.1) 💀
3.2. Line Delimiting and Folding
lines in vCard are separated by the [RFC5322] line break, which is a CRLF sequence (U+000D followed by U+000A) 🧚 long logical lines can get split into a multiple-physical-line thing using folding. content lines SHOULD be folded to a max width of 75 octets, not counting the line break. multi-octet characters MUST remain contiguous, so no chopping a character in half 😭 the reasoning behind all this folding lives in [RFC5322], Section 2.1.1.
a logical line MAY be continued on the next physical line anywhere between two characters, by putting a CRLF right before a single white space character (space (U+0020) or horizontal tab (U+0009)) 🫶 the folded line MUST contain at least one character. any CRLF immediately followed by one single white space character gets ignored (removed) when the content type is processed ✨ here's a lil example:
NOTE:This is a long description that exists on a long line.can be folded like this:
NOTE:This is a long description
that exists on a long line.it could also be folded like this, which is wild 🙈
NOTE:This is a long descrip
tion that exists o
n a long line.going from the folded version back to the single-line version is called unfolding 🌈 you unfold by treating a CRLF immediately followed by a white space character (HTAB (U+0009) or SPACE (U+0020)) as if it were nothing at all, so the CRLF and that single white space character both get removed.
Note: very simple implementations might generate folded lines in the middle of a UTF-8 multi-octet sequence 😬 because of that, implementations SHOULD unfold lines in a way that properly restores the original sequence.
Note: unfolding works differently than in [RFC5322]. in [RFC5322], unfolding only removes the CRLF and keeps the space after it, but here the space goes too 👑
folding happens after any content encoding of a type value, and unfolding happens before any decoding of a type value in a content line 💜
3.3. ABNF Format Definition
the ABNF below uses the notation of [RFC5234], which also defines CRLF, WSP, DQUOTE, VCHAR, ALPHA, and DIGIT 🍓
vcard-entity = 1*vcard
vcard = "BEGIN:VCARD" CRLF
"VERSION:4.0" CRLF
1*contentline
"END:VCARD" CRLF
; A vCard object MUST include the VERSION and FN properties.
; VERSION MUST come immediately after BEGIN:VCARD.
contentline = [group "."] name *(";" param) ":" value CRLF
; When parsing a content line, folded lines must first
; be unfolded according to the unfolding procedure
; described in Section 3.2.
; When generating a content line, lines longer than 75
; characters SHOULD be folded according to the folding
; procedure described in Section 3.2.
group = 1*(ALPHA / DIGIT / "-")
name = "SOURCE" / "KIND" / "FN" / "N" / "NICKNAME"
/ "PHOTO" / "BDAY" / "ANNIVERSARY" / "GENDER" / "ADR" / "TEL"
/ "EMAIL" / "IMPP" / "LANG" / "TZ" / "GEO" / "TITLE" / "ROLE"
/ "LOGO" / "ORG" / "MEMBER" / "RELATED" / "CATEGORIES"
/ "NOTE" / "PRODID" / "REV" / "SOUND" / "UID" / "CLIENTPIDMAP"
/ "URL" / "KEY" / "FBURL" / "CALADRURI" / "CALURI" / "XML"
/ iana-token / x-name
; Parsing of the param and value is based on the "name" as
; defined in ABNF sections below.
; Group and name are case-insensitive.
iana-token = 1*(ALPHA / DIGIT / "-")
; identifier registered with IANA
x-name = "x-" 1*(ALPHA / DIGIT / "-")
; Names that begin with "x-" or "X-" are
; reserved for experimental use, not intended for released
; products, or for use in bilateral agreements.
param = language-param / value-param / pref-param / pid-param
/ type-param / geo-parameter / tz-parameter / sort-as-param
/ calscale-param / any-param
; Allowed parameters depend on property name.
param-value = *SAFE-CHAR / DQUOTE *QSAFE-CHAR DQUOTE
any-param = (iana-token / x-name) "=" param-value *("," param-value)
NON-ASCII = UTF8-2 / UTF8-3 / UTF8-4
; UTF8-{2,3,4} are defined in [RFC3629]
QSAFE-CHAR = WSP / "!" / %x23-7E / NON-ASCII
; Any character except CTLs, DQUOTE
SAFE-CHAR = WSP / "!" / %x23-39 / %x3C-7E / NON-ASCII
; Any character except CTLs, DQUOTE, ";", ":"
VALUE-CHAR = WSP / VCHAR / NON-ASCII
; Any textual charactera line that starts with a white space character is a continuation of the previous line, like we covered in Section 3.2 🦋 the white space character and the immediately preceeding CRLF should be discarded when you rebuild the original line. heads up, this line-folding convention is different from the one in [RFC5322], because there the sequence <CRLF><WSP> only counts as a continued line when it shows up in the right spot, but here it indicates a continued line and should be removed anywhere in the content 😤
property names and parameter names are case-insensitive, so "fn" is the same as "FN" and "Fn" 💖 parameter values MAY be case-sensitive or case-insensitive, depending on how they're defined. parameter values that aren't explicitly defined as case-sensitive are case-insensitive. based on experience with vCard 3 interoperability, it is RECOMMENDED that property and parameter names be upper-case on output 🎀
the group construct is how you group related properties together 🌸 the group name is just a syntactic convention that says all the property names with the same group name SHOULD be grouped together when an application displays them. it has no other significance, so don't overthink it 🙅 implementations that don't understand or support grouping MAY simply strip off any text before a "." to the left of the type name and present the types and values as normal.
property cardinalities are written using the notation below, which is based on ABNF (see [RFC5234], Section 3.6) 📊
+-------------+--------------------------------------------------+
| Cardinality | Meaning |
+-------------+--------------------------------------------------+
| 1 | Exactly one instance per vCard MUST be present. |
| *1 | Exactly one instance per vCard MAY be present. |
| 1* | One or more instances per vCard MUST be present. |
| * | One or more instances per vCard MAY be present. |
+-------------+--------------------------------------------------+properties in a vCard instance can have multiple values, depending on the property cardinality 🧚 the general rule for encoding multi-valued properties is to just create a new content line for each value (including the property name). however, it should be noted that some value types can encode multiple values in a single content line by separating them with a comma ",". this approach was taken for several of the content types defined below (date, time, integer, float) 💅
3.4. Property Value Escaping
some properties can contain one or more values separated by a COMMA character (U+002C) ✨ so a COMMA character in a value MUST be escaped with a BACKSLASH character (U+005C), even for properties that don't allow multiple instances (for consistency) 🫶
some properties (like N and ADR) are made of multiple fields separated by a SEMICOLON character (U+003B) 🌈 so a SEMICOLON in a field of one of these "compound" properties MUST be escaped with a BACKSLASH character. SEMICOLON characters in non-compound properties MAY be escaped. on input, an escaped SEMICOLON is never a field separator, and an unescaped SEMICOLON may or may not be a field separator, depending on the property it shows up in 👑
some fields of compound properties can hold a list of values separated by a COMMA character, so a COMMA character in one of a field's values MUST be escaped with a BACKSLASH character, even for fields that don't allow multiple values (for consistency) 💜 compound properties that allow multiple instances MUST NOT be encoded in a single content line 🙅
last one: BACKSLASH characters in values MUST be escaped with a BACKSLASH character 🍓 and NEWLINE (U+000A) characters in values MUST be encoded as two characters: a BACKSLASH followed by either an 'n' (U+006E) or an 'N' (U+004E) 🌸 in all other cases, escaping MUST NOT be used, bestie 💀
4. Property Value Data Types ✨
okay so this is where the actual values get their outfits 👗 standard value types are defined below, and the ABNF is the blueprint for every single one of them 🎀
value = text
/ text-list
/ date-list
/ time-list
/ date-time-list
/ date-and-or-time-list
/ timestamp-list
/ boolean
/ integer-list
/ float-list
/ URI ; from Section 3 of [RFC3986]
/ utc-offset
/ Language-Tag
/ iana-valuespec
; Actual value type depends on property name and VALUE parameter.
text = *TEXT-CHAR
TEXT-CHAR = "\\" / "\," / "\n" / WSP / NON-ASCII
/ %x21-2B / %x2D-5B / %x5D-7E
; Backslashes, commas, and newlines must be encoded.
component = "\\" / "\," / "\;" / "\n" / WSP / NON-ASCII
/ %x21-2B / %x2D-3A / %x3C-5B / %x5D-7E
list-component = component *("," component)
text-list = text *("," text)
date-list = date *("," date)
time-list = time *("," time)
date-time-list = date-time *("," date-time)
date-and-or-time-list = date-and-or-time *("," date-and-or-time)
timestamp-list = timestamp *("," timestamp)
integer-list = integer *("," integer)
float-list = float *("," float)
boolean = "TRUE" / "FALSE"
integer = [sign] 1*DIGIT
float = [sign] 1*DIGIT ["." 1*DIGIT]
sign = "+" / "-"
year = 4DIGIT ; 0000-9999
month = 2DIGIT ; 01-12
day = 2DIGIT ; 01-28/29/30/31 depending on month and leap year
hour = 2DIGIT ; 00-23
minute = 2DIGIT ; 00-59
second = 2DIGIT ; 00-58/59/60 depending on leap second
zone = utc-designator / utc-offset
utc-designator = %x5A ; uppercase "Z"
date = year [month day]
/ year "-" month
/ "--" month [day]
/ "--" "-" day
date-noreduc = year month day
/ "--" month day
/ "--" "-" day
date-complete = year month day
time = hour [minute [second]] [zone]
/ "-" minute [second] [zone]
/ "-" "-" second [zone]
time-notrunc = hour [minute [second]] [zone]
time-complete = hour minute second [zone]
time-designator = %x54 ; uppercase "T"
date-time = date-noreduc time-designator time-notrunc
timestamp = date-complete time-designator time-complete
date-and-or-time = date-time / date / time-designator time
utc-offset = sign hour [minute]
Language-Tag = <Language-Tag, defined in [RFC5646], Section 2.1>
iana-valuespec = <value-spec, see Section 12>
; a publicly defined valuetype format, registered
; with IANA, as defined in Section 12 of this
; document.4.1. TEXT
"text" is the one for human-readable stuff 📝 the LANGUAGE property parameter (Section 5.1) is what tells you which language it's in, so it's giving teamwork 🫶
Examples for "text":
this is a text value
this is one value,this is another
this is a single value\, with a comma encodedA formatted text line break in a text value type MUST be represented as the character sequence backslash (U+005C) followed by a Latin small letter n (U+006E) or a Latin capital letter N (U+004E), that is, "\n" or "\N". 🚨 this one is a must, bestie 🚨
For example, a multiple line NOTE value of:
Mythical Manager
Hyjinx Software Division
BabsCo, Inc.could be represented as:
NOTE:Mythical Manager\nHyjinx Software Division\n
BabsCo\, Inc.\nthis shows off the \n literal line break trick, the CRLF-followed-by-space line folding trick, and the backslash escape trick all at once 🦋 so iconic 😭
4.2. URI
"uri" is for when the value is too big or just not something you want to stuff inline 📦 so instead you point at it with a URI. The format is as defined in Section 3 of [RFC3986]. ⚠️ the thing to remember is that the value of a "uri" property is what the URI points to, NOT the URI itself. (okay that was me being dramatic, the original just says it plainly, but the point stands 💅)
Examples for "uri":
http://www.example.com/my/picture.jpg
ldap://ldap.example.com/cn=babs%20jensen
4.3. DATE, TIME, DATE-TIME, DATE-AND-OR-TIME, and TIMESTAMP
these five are all built on the ISO 8601 stuff in [ISO.8601.2004] 🌸 you can list several of them with commas if you're feeling fancy.
Only the basic format is supported. no dashes-and-colons drama here 🙅♀️
4.3.1. DATE
A calendar date as specified in [ISO.8601.2004], Section 4.1.2.
Reduced accuracy, as specified in [ISO.8601.2004], Sections 4.1.2.3 a) and b), but not c), is permitted.
Expanded representation, as specified in [ISO.8601.2004], Section 4.1.4, is forbidden. 💀 nope.
Truncated representation, as specified in [ISO.8601.2000], Sections 5.2.1.3 d), e), and f), is permitted.
Examples for "date":
19850412
1985-04
1985
--0412
---12okay, the second one is the YYYY-MM example. YYYYMM is disallowed so nobody confuses it with YYMMDD 🙈 and YYYY-MM-DD is also out, because we're using the basic format and not the extended one. no mixing, periodt ✨
4.3.2. TIME
A time of day as specified in [ISO.8601.2004], Section 4.2.
Reduced accuracy, as specified in [ISO.8601.2004], Section 4.2.2.3, is permitted.
Representation with decimal fraction, as specified in [ISO.8601.2004], Section 4.2.2.4, is forbidden. no decimals for you 🙅♀️
The midnight hour is always represented by 00, never 24 (see [ISO.8601.2004], Section 4.2.3). midnight is 00 and that's the whole tea 🌙
Truncated representation, as specified in [ISO.8601.2000], Sections 5.3.1.4 a), b), and c), is permitted.
Examples for "time":
102200
1022
10
-2200
--00
102200Z
102200-08004.3.3. DATE-TIME
A date and time of day combination as specified in [ISO.8601.2004], Section 4.3.
Truncation of the date part, as specified in [ISO.8601.2000], Section 5.4.2 c), is permitted.
Examples for "date-time":
19961022T140000
--1022T1400
---22T144.3.4. DATE-AND-OR-TIME
Either a DATE-TIME, a DATE, or a TIME value. so it's whichever one fits 💖 to keep things unambiguous, a stand-alone TIME value always gets a "T" in front of it.
Examples for "date-and-or-time":
19961022T140000
--1022T1400
---22T14
19850412
1985-04
1985
--0412
---12
T102200
T1022
T10
T-2200
T--00
T102200Z
T102200-08004.3.5. TIMESTAMP
A complete date and time of day combination as specified in [ISO.8601.2004], Section 4.3.2. the full package 🎁
Examples for "timestamp":
19961022T140000
19961022T140000Z
19961022T140000-05
19961022T140000-05004.4. BOOLEAN
"boolean" is for true-or-false energy ✨ and it's case-insensitive, so you get to pick your favourite capitalisation 🌈
Examples:
TRUE
false
True4.5. INTEGER
"integer" is for signed whole numbers in decimal 🔢 if you don't write a sign, it's assumed to be positive "+". you can list several with commas, and the limits are 9223372036854775807 at the top and -9223372036854775808 at the bottom. those are the edges of a signed 64-bit integer using two's-complement arithmetic, so it's a whole vibe 👑
Examples:
1234567890
-1234556790
+1234556790,4321098764.6. FLOAT
"float" is for real numbers 🦋 no sign means positive "+", and you can comma-separate them too. Implementations MUST support a precision equal or better than that of the IEEE "binary64" format [IEEE.754.2008]. that's the non-negotiable part 🔥
Note: Scientific notation is disallowed. Implementers wishing to use their favorite language's %f formatting should be careful. 🙈 (translation: no "1e5" energy, and watch your %f 😅)
Examples:
20.30
1000000.0000001
1.333,3.144.7. UTC-OFFSET
"utc-offset" is a signed offset from UTC, and it can show up in the TZ property 🌍
It's the difference from Coordinated Universal Time (UTC), written as a positive or negative amount in hours and minutes (like +hhmm). The time runs on a 24-hour clock, so hours go from 00 to 23 and minutes go from 00 to 59. Both hours and minutes are always 2 digits, with leading zeroes when needed to keep the count right 🕰️ and the basic format for ISO 8601 UTC offsets MUST be used. no getting creative with the format 🙅♀️
4.8. LANGUAGE-TAG
"language-tag" is just one single language tag, as defined in [RFC5646] 🗣️ easy peasy.
5. Property Parameters
okay so a property can have attributes stuck to it too 🎀 these "property parameters" hold meta-information about the property or its value. Sometimes a parameter can hold several values, and those get separated by a COMMA (U+002C) 💜
Property parameter value elements that contain the COLON (U+003A), SEMICOLON (U+003B), or COMMA (U+002C) character separators MUST be specified as quoted-string text values. Property parameter values MUST NOT contain the DQUOTE (U+0022) character. the DQUOTE character is the delimiter for parameter values that have restricted characters or URI text, so it's basically the bouncer 🚪
Applications MUST ignore x-param and iana-param values they don't recognize. they can just vibe past anything they don't know 🫠
5.1. LANGUAGE
The LANGUAGE property parameter is for identifying data that shows up in multiple languages 🌏 there's no concept of a "default" language, except as specified by any "Content-Language" MIME header parameter that's present [RFC3282]. The value is a language tag as defined in Section 2 of [RFC5646].
Examples:
ROLE;LANGUAGE=tr:hocaABNF:
language-param = "LANGUAGE=" Language-Tag
; Language-Tag is defined in section 2.1 of RFC 56465.2. VALUE
The VALUE parameter is OPTIONAL 💖 it tells you the value type (data type) and format of the value. Using these predefined formats is encouraged, even when you don't spell out the VALUE parameter, because then existing parsing and processing code can be leveraged. The predefined data type values MUST NOT be repeated in COMMA-separated value lists, except within the N, NICKNAME, ADR, and CATEGORIES properties ✨
ABNF:
value-param = "VALUE=" value-type
value-type = "text"
/ "uri"
/ "date"
/ "time"
/ "date-time"
/ "date-and-or-time"
/ "timestamp"
/ "boolean"
/ "integer"
/ "float"
/ "utc-offset"
/ "language-tag"
/ iana-token ; registered as described in section 12
/ x-name5.3. PREF 🎀
okay so the PREF parameter is OPTIONAL 🫶 and it's how a vCard author says "hey, this exact instance of a property is the one I like best." Its value MUST be an integer between 1 and 100 that measures how much preference there is. Lower numbers mean higher preference, so 1 is the most preferred 👑
When the parameter is absent, the default MUST be to interpret the property instance as being least preferred. 💀
Here's the tea: the number only means something compared to the numbers on the other instances of the same property in the same vCard. A given value, or the absence of a value, MUST NOT be interpreted on its own 🙈
This parameter MAY be applied to any property that allows multiple instances. ✨
pref-param = "PREF=" (1*2DIGIT / "100")
; An integer between 1 and 100.5.4. ALTID 🦋
the ALTID parameter is how you "tag" property instances as alternative representations of the same logical property 💜 Translations are the classic example: put the same name in several languages, each with a different LANGUAGE (Section 5.1) parameter, and tag them all with the same ALTID value.
This parameter's value is treated as an opaque string. Its only job is to get compared for equality against other ALTID parameter values 🧚
Two property instances count as alternative representations of the same logical property if and only if their names and their ALTID values are identical. Property instances without the ALTID parameter MUST NOT be considered an alternative representation of any other property instance. ALTID values aren't globally unique either, so they MAY be reused for different property names 🌸
Property instances with the same ALTID value count as 1 toward cardinality. So since N (Section 6.2.2) has cardinality *1 and TITLE (Section 6.6.1) has cardinality *, these three examples are all legal 💅
N;ALTID=1;LANGUAGE=jp:<U+5C71><U+7530>;<U+592A><U+90CE>;;;
N;ALTID=1;LANGUAGE=en:Yamada;Taro;;;
(<U+XXXX> denotes a UTF8-encoded Unicode character.)
TITLE;ALTID=1;LANGUAGE=fr:Patron
TITLE;ALTID=1;LANGUAGE=en:Boss
TITLE;ALTID=1;LANGUAGE=fr:Patron
TITLE;ALTID=1;LANGUAGE=en:Boss
TITLE;ALTID=2;LANGUAGE=en:Chief vCard Evangelistthis one would NOT be legal, because there are two instances of N 🙅♀️
N;ALTID=1;LANGUAGE=jp:<U+5C71><U+7530>;<U+592A><U+90CE>;;;
N:Yamada;Taro;;;
(Two instances of the N property.)and these three would be legal but questionable 🤔
TITLE;ALTID=1;LANGUAGE=fr:Patron
TITLE;ALTID=2;LANGUAGE=en:Boss
(Should probably have the same ALTID value.)
TITLE;ALTID=1;LANGUAGE=fr:Patron
TITLE:LANGUAGE=en:Boss
(Second line should probably have ALTID=1.)
N;ALTID=1;LANGUAGE=jp:<U+5C71><U+7530>;<U+592A><U+90CE>;;;
N;ALTID=1;LANGUAGE=en:Yamada;Taro;;;
N;ALTID=1;LANGUAGE=en:Smith;John;;;
(The last line should probably have ALTID=2. But that would be
illegal because N has cardinality *1.)The ALTID property MAY also be used in may contexts other than with the LANGUAGE parameter. Here's a photo example with the same picture in two different file formats 📸
PHOTO;ALTID=1:data:image/jpeg;base64,...
PHOTO;ALTID=1;data:image/jp2;base64,...ABNF:
altid-param = "ALTID=" param-value5.5. PID 🍓
the PID parameter identifies one specific property among several instances. Think of it like the UID property (Section 6.7.6), except it works per property instead of per vCard 🪪 It MAY appear more than once in a given property. It MUST NOT appear on properties that may have only one instance per vCard. Its value is either one small positive integer or a pair of small positive integers separated by a dot. You can squish multiple values into one PID parameter by separating them with a comma ",". Check out Section 7 for more on how it's used ✨
ABNF:
pid-param = "PID=" pid-value *("," pid-value)
pid-value = 1*DIGIT ["." 1*DIGIT]5.6. TYPE 🌷
the TYPE parameter has lots of different jobs 🧩 Generally it describes the class characteristics of the property it's attached to, and most of the time its value is a comma-separated subset of a predefined list. In this document, these properties use it: FN, NICKNAME, PHOTO, ADR, TEL, EMAIL, IMPP, LANG, TZ, GEO, TITLE, ROLE, LOGO, ORG, RELATED, CATEGORIES, NOTE, SOUND, URL, KEY, FBURL, CALADRURI, and CALURI. The TYPE parameter MUST NOT be applied on other properties defined in this document 🚫
The "work" and "home" values act like tags. "work" means the property is related to someone's workplace, and "home" means it's related to their personal life 🏠💼 When neither one is present, the property is treated as related to both work and personal life if the KIND property's value is "individual". In every other case it's treated as related to neither.
ABNF:
type-param = "TYPE=" type-value *("," type-value)
type-value = "work" / "home" / type-param-tel
/ type-param-related / iana-token / x-name
; This is further defined in individual property sections.5.7. MEDIATYPE 🦋
the MEDIATYPE parameter goes on properties whose value is a URI. Using it is OPTIONAL. It gives the vCard consumer app a hint about the media type [RFC2046] of the resource the URI points to 🎧 Some URI schemes don't need it. For example, the "data" scheme lets you spell out the media type right inside the URI [RFC2397]. The "http" scheme gets the media type during URI resolution, through the Content-Type HTTP header [RFC2616]. So MEDIATYPE is meant for schemes that can't do that on their own, like "ftp" [RFC1738] 💖
ABNF:
mediatype-param = "MEDIATYPE=" mediatype
mediatype = type-name "/" subtype-name *( ";" attribute "=" value )
; "attribute" and "value" are from [RFC2045]
; "type-name" and "subtype-name" are from [RFC4288]5.8. CALSCALE 🗓️
the CALSCALE parameter is identical to the CALSCALE property in iCalendar (see [RFC5545], Section 3.7.1) 🧠 It defines the calendar system that a date or date-time value is written in. iCalendar only specifies "gregorian", which is the Gregorian system, and that's the default when the parameter is absent. Extension documents can define more values and register them with IANA (see Section 10.3.4) 🌍 A vCard implementation MUST ignore properties with a CALSCALE parameter value it does not understand. Respect the boundaries, bestie 🫶
ABNF:
calscale-param = "CALSCALE=" calscale-value
calscale-value = "gregorian" / iana-token / x-name5.9. SORT-AS 🔤
the "sort-as" parameter tells sorting algorithms which string to use for national-language-specific sorting 🌏 Without it, sorting could put this vCard in the wrong spot in a sequence of sorted vCards 😭 When this property is present, the given strings are what gets used for sorting the vCard.
This parameter's value is a comma-separated list that MUST have as many or fewer elements as the corresponding property value has components. The value is case-sensitive too ✨
ABNF:
sort-as-param = "SORT-AS=" sort-as-value
sort-as-value = param-value *("," param-value)Examples! For sorting by surname and given name, these show common sort string usage with the N property 💅
FN:Rene van der Harten
N;SORT-AS="Harten,Rene":van der Harten;Rene,J.;Sir;R.D.O.N.
FN:Robert Pau Shou Chang
N;SORT-AS="Pau Shou Chang,Robert":Shou Chang;Robert,Pau;;
FN:Osamu Koura
N;SORT-AS="Koura,Osamu":Koura;Osamu;;
FN:Oscar del Pozo
N;SORT-AS="Pozo,Oscar":del Pozo Triscon;Oscar;;
FN:Chistine d'Aboville
N;SORT-AS="Aboville,Christine":d'Aboville;Christine;;
FN:H. James de Mann
N;SORT-AS="Mann,James":de Mann;Henry,James;;If you sort by surname, you get:
Christine d'Aboville
Rene van der Harten
Osamu Koura
H. James de Mann
Robert Pau Shou Chang
Oscar del Pozoand if you sort by given name, you get:
Christine d'Aboville
H. James de Mann
Osamu Koura
Oscar del Pozo
Rene van der Harten
Robert Pau Shou Chang5.10. GEO 📍
the GEO parameter can point out global positioning info that's specific to an address 🗺️ Its value is the same as the GEO property's (see Section 6.5.2).
ABNF:
geo-parameter = "GEO=" DQUOTE URI DQUOTE5.11. TZ ⏰
the TZ parameter can share time zone info that's specific to an address 🕰️ Its value is the same as the TZ property's.
ABNF:
tz-parameter = "TZ=" (param-value / DQUOTE URI DQUOTE)6. vCard Properties 🌈
what follows is the list of standard vCard properties, so let's get into it 💜
6.1. General Properties 🍓
6.1.1. BEGIN 🎬
- Purpose: To denote the beginning of a syntactic entity within a text/vcard content-type.
- Value type: text
- Cardinality: 1
- Special notes: The content entity MUST begin with the BEGIN property with a value of "VCARD". The value is case-insensitive.
The BEGIN property is used in conjunction with the END property to delimit an entity containing a related set of properties within a text/vcard content-type. This construct can be used instead of including multiple vCards as body parts inside of a multipart/ alternative MIME message. It is provided for applications that wish to define content that can contain multiple entities within the same text/vcard content-type or to define content that can be identifiable outside of a MIME environment.
ABNF:
BEGIN-param = 0" " ; no parameter allowed
BEGIN-value = "VCARD"Example:
BEGIN:VCARD6.1.2. END 🎀
- Purpose: To denote the end of a syntactic entity within a text/vcard content-type.
- Value type: text
- Cardinality: 1
- Special notes: The content entity MUST end with the END type with a value of "VCARD". The value is case-insensitive.
The END property is used in conjunction with the BEGIN property to delimit an entity containing a related set of properties within a text/vcard content-type. This construct can be used instead of or in addition to wrapping separate sets of information inside additional MIME headers. It is provided for applications that wish to define content that can contain multiple entities within the same text/vcard content-type or to define content that can be identifiable outside of a MIME environment.
ABNF:
END-param = 0" " ; no parameter allowed
END-value = "VCARD"Example:
END:VCARD6.1.3. SOURCE 🧭
Purpose: okay so this one's how you tell people where the directory info came from 📇 It's the signpost that says "hey, if you want fresher or extra details, go here."
Value type: uri 🔗
Cardinality: * 💅
Special notes: this property is the way apps that speak the given directory service protocol can grab more info or the newest version from that service 🦋 It holds a URI as defined in [RFC3986] and/or other info that points back at the vCard the information is about. If directory info comes from more than one place, the sending entity can pick the source it thinks is the best one, or it can include multiple SOURCE properties 🌈 Main character energy, honestly.
ABNF:
SOURCE-param = "VALUE=uri" / pid-param / pref-param / altid-param
/ mediatype-param / any-param
SOURCE-value = URIExamples:
SOURCE:ldap://ldap.example.com/cn=Babs%20Jensen,%20o=Babsco,%20c=US
SOURCE:http://directory.example.com/addressbooks/jdoe/
Jean%20Dupont.vcf6.1.4. KIND 👑
Purpose: this is how a vCard says what kind of thing it's representing 🎀
Value type: a single text value 🌸
Cardinality: *1 ✨
Special notes: the value can be one of these:
"individual"is for a vCard representing one single person or entity. This is the default kind of vCard, so it's giving classic 🧍♀️"group"is for a vCard representing a group of persons or entities. The members can be other vCards or other kinds of stuff, like email addresses or websites 🫶 A group vCard will usually have MEMBER properties to list who's in it, but it's not required to. A group vCard with no MEMBER properties can be seen as an abstract grouping, or one whose members are known empirically (think "IETF Participants" or "Republican U.S. Senators") 👀- All properties in a group vCard apply to the group as a whole, not to any particular MEMBER 💜 For example, an EMAIL property might give the address of a mailing list for the group, and an IMPP property might point at a group chat room 💬
"org"is for a vCard representing an organization. An organization vCard MUST NOT contain MEMBER properties, so it's kind of a mix between "individual" and "group" 🍓 An organization is a single entity, but not a person. It might be a business or government, a department or division inside one, a club, an association, or something like that 🏢- All properties in an organization vCard apply to the organization as a whole, same as with a group vCard 🌈 For example, an EMAIL property might give the address of a contact point for the organization 📧
"location"is for a named geographical place. A location vCard will usually contain a GEO property, but it's not required to 🗺️ A location vCard without a GEO property can be seen as an abstract location, or one whose definition is known empirically (maybe "New England" or "The Seashore") 🌊- All properties in a location vCard apply to the location itself, not to any entity that might exist there 🏛️ For example, in a vCard for an office building, an ADR property might give the building's mailing address, and a TEL property might give the receptionist's phone number 📞
- An x-name. vCards MAY include private or experimental values for KIND. Remember that x-name values aren't meant for general use and probably won't interoperate 🧪
- An iana-token. More values can be registered with IANA (see Section 10.3.4). A new value's specification document MUST specify which properties make sense for that new kind of vCard and which ones don't 📝
Implementations MUST support the specific string values defined above 💯 If this property is absent, "individual" MUST be assumed as the default. If the property is present but the implementation doesn't understand its value (the value is an x-name or iana-token the implementation doesn't support), the implementation SHOULD act in a neutral way, which usually means treating the vCard as though its kind were "individual" 🫠 The presence of MEMBER properties MAY, however, be taken as a sign that the unknown kind is an extension of "group" 🔍
Clients often need to visually tell contacts apart based on what they represent, and KIND gives them a direct way to do that ✨ For example, when showing contacts in a list, an icon could sit next to each one, with different icons for the different kinds. A client might use an outline of one person for an "individual", an outline of several people for a "group", and so on 👥 Or, or in addition, a client might split different kinds of vCards into different panes, tabs, or selections in the UI 🗂️
Some clients might also make functional distinctions between kinds, ignoring "location" vCards for some purposes and only looking at "location" vCards for others 🧭
When you design those visual and functional distinctions, client implementations have to decide how to fit unsupported kinds into the scheme. What icon do they get? The one for "individual"? A unique one, like a question mark? Which tab do they go in? 🤔 It's beyond the scope of this specification to answer these questions, but implementers need to think about them 💭
ABNF:
KIND-param = "VALUE=text" / any-param
KIND-value = "individual" / "group" / "org" / "location"
/ iana-token / x-nameExample:
This represents someone named Jane Doe working in the marketing department of the North American division of ABC Inc. 💼
BEGIN:VCARD
VERSION:4.0
KIND:individual
FN:Jane Doe
ORG:ABC\, Inc.;North American Division;Marketing
END:VCARDThis represents the department itself, commonly known as ABC Marketing. 🎉
BEGIN:VCARD
VERSION:4.0
KIND:org
FN:ABC Marketing
ORG:ABC\, Inc.;North American Division;Marketing
END:VCARD6.1.5. XML 🧩
Purpose: this lets you pop extended XML-encoded vCard data into a plain vCard 🌟
Value type: a single text value 🌸
Cardinality: * 💅
Special notes: the content is a single XML 1.0 [W3C.REC-xml-20081126] element whose namespace MUST be explicitly specified using the xmlns attribute, and it MUST NOT be the vCard 4 namespace (urn:ietf:params:xml:ns:vcard-4.0) 🙅♀️ (This means it can't duplicate a standard vCard property, obviously.) The element is interpreted as if it were inside a <vcard> element, as defined in [RFC6351] 🎀
The fragment gets normal line folding and escaping, which means you replace all backslashes with \\, then replace all newlines with \n, and then fold long lines 🧵
Support for this property is OPTIONAL, but implementations of this specification MUST preserve instances of this property when propagating vCards 🫶 Don't you dare drop it!
See [RFC6351] for more info on what this property is meant for ✨
ABNF:
XML-param = "VALUE=text" / altid-param
XML-value = text6.2. Identification Properties 🪪
These types capture info about the identity and naming of the entity the vCard is about, so this is the "who is this?" section 🕵️♀️
6.2.1. FN 💖
Purpose: this gives the formatted text for the name of the object the vCard represents 📛
Value type: a single text value 🌸
Cardinality: 1* 🫶
Special notes: this property is based on the semantics of the X.520 Common Name attribute [CCITT.X520.1988]. The property MUST be present in the vCard object. No skipping, bestie 🚨
ABNF:
FN-param = "VALUE=text" / type-param / language-param / altid-param
/ pid-param / pref-param / any-param
FN-value = textExample:
FN:Mr. John Q. Public\, Esq.6.2.2. N 🧾
Purpose: this gives the parts of the name of the object the vCard represents 🎀
Value type: a single structured text value. Each component can have multiple values 🧩
Cardinality: *1 ✨
Special note: the structured value lines up, in order, with Family Names (also known as surnames), Given Names, Additional Names, Honorific Prefixes, and Honorific Suffixes 💅 The text components are separated by the SEMICOLON character (U+003B). Each text component can hold multiple text values separated by the COMMA character (U+002C) 📝 This property is based on the semantics of the X.520 individual name attributes [CCITT.X520.1988]. The property SHOULD be present in the vCard object when the name of the object follows the X.520 model 🌈
The SORT-AS parameter MAY be applied to this property 🔁
ABNF:
N-param = "VALUE=text" / sort-as-param / language-param
/ altid-param / any-param
N-value = list-component 4(";" list-component)Examples:
N:Public;John;Quinlan;Mr.;Esq.N:Stevenson;John;Philip,Paul;Dr.;Jr.,M.D.,A.C.P.6.2.3. NICKNAME 🦋
Purpose: this gives the text for the nickname of the object the vCard represents 🍓
Value type: one or more text values separated by a COMMA character (U+002C) 💜
Cardinality: * 🌸
Special note: the nickname is the descriptive name given instead of, or in addition to, the one that belongs to the object the vCard represents 🫶 It can also be used to give a familiar form of a proper name specified by the FN or N properties 🥰
ABNF:
NICKNAME-param = "VALUE=text" / type-param / language-param
/ altid-param / pid-param / pref-param / any-param
NICKNAME-value = text-listExamples:
NICKNAME:RobbieNICKNAME:Jim,JimmieNICKNAME;TYPE=work:Boss6.2.4. PHOTO 📸
Purpose: this gives an image or photograph that annotates some aspect of the object the vCard represents 🌷
Value type: a single URI 🔗
Cardinality: * 🌈
ABNF:
PHOTO-param = "VALUE=uri" / altid-param / type-param
/ mediatype-param / pref-param / pid-param / any-param
PHOTO-value = URIExamples:
PHOTO:http://www.example.com/pub/photos/jqpublic.gif
PHOTO:data:image/jpeg;base64,MIICajCCAdOgAwIBAgICBEUwDQYJKoZIhv
AQEEBQAwdzELMAkGA1UEBhMCVVMxLDAqBgNVBAoTI05ldHNjYXBlIENvbW11bm
ljYXRpb25zIENvcnBvcmF0aW9uMRwwGgYDVQQLExNJbmZvcm1hdGlvbiBTeXN0
<...remainder of base64-encoded data...>6.2.5. BDAY 🎂
Okay bestie, this one is the birthday property 🎂 It says when the object the vCard represents was born, aka its birth date. 🎀
Value type: By default it's a single date-and-or-time value 📅 but you can also reset it to a single text value, which is perfect for vibes like "circa 1800" 🕰️
Cardinality: *1 ✨ (just one, no cap)
ABNF:
BDAY-param = BDAY-param-date / BDAY-param-text
BDAY-value = date-and-or-time / text
; Value and parameter MUST match.
BDAY-param-date = "VALUE=date-and-or-time"
BDAY-param-text = "VALUE=text" / language-param
BDAY-param =/ altid-param / calscale-param / any-param
; calscale-param can only be present when BDAY-value is
; date-and-or-time and actually contains a date or date-time.Examples:
BDAY:19960415
BDAY:--0415
BDAY;19531015T231000Z
BDAY;VALUE=text:circa 18006.2.6. ANNIVERSARY 💍
This one is the big "we got married" date 💍 It's the date of marriage, or the equivalent, for the object the vCard represents. Iconic romance energy 🥹
Value type: Also a single date-and-or-time value by default 📅 and it can be reset to a single text value 💫
Cardinality: *1 🌸
ABNF:
ANNIVERSARY-param = "VALUE=" ("date-and-or-time" / "text")
ANNIVERSARY-value = date-and-or-time / text
; Value and parameter MUST match.
ANNIVERSARY-param =/ altid-param / calscale-param / any-param
; calscale-param can only be present when ANNIVERSARY-value is
; date-and-or-time and actually contains a date or date-time.Examples:
ANNIVERSARY:199604156.2.7. GENDER 🌈
This property is all about the sex and gender identity of the object the vCard represents 🌈 It's giving honesty and respect, and every part is optional, so you only fill in what you want 🫶
Value type: A single structured value with two components 🧩 Each component has a single text value.
Cardinality: *1 ✨
Special notes: The components show up in order: first the sex (biological), then the gender identity. Each component is optional.
- Sex component: A single letter. M stands for "male", F stands for "female", O stands for "other", N stands for "none or not applicable", U stands for "unknown".
- Gender identity component: Free-form text, so say your truth 💜
ABNF:
GENDER-param = "VALUE=text" / any-param
GENDER-value = sex [";" text]
sex = "" / "M" / "F" / "O" / "N" / "U"Examples:
GENDER:M
GENDER:F
GENDER:M;Fellow
GENDER:F;grrrl
GENDER:O;intersex
GENDER:;it's complicated6.3. Delivery Addressing Properties 📬
These types are all about the delivery addressing or label for the vCard object. Basically, where the mail goes 💌
6.3.1. ADR 🏠
Purpose-wise, this one spells out the components of the delivery address for the vCard object 🏡
Value type: A single structured text value, separated by the SEMICOLON character (U+003B) 🧁
Cardinality: * 💫
Special notes: The structured type value is a sequence of address components. The component values MUST be specified in their corresponding position. In order, the structured type value corresponds to:
- the post office box;
- the extended address (e.g., apartment or suite number);
- the street address;
- the locality (e.g., city);
- the region (e.g., state or province);
- the postal code;
- the country name (full name in the language specified in Section 5.1).
When a component value is missing, the associated component separator MUST still be specified. Keep those semicolons 🙏
Okay, real talk: experience with vCard 3 showed that the first two components (post office box and extended address) are plagued with many interoperability issues 💀 So for maximal interoperability, their values SHOULD be empty. 🫠
The text components are separated by the SEMICOLON character (U+003B). Where it makes semantic sense, individual text components can include multiple text values (e.g., a "street" component with multiple lines) separated by the COMMA character (U+002C) 🎀
The property can include the "PREF" parameter to indicate the preferred delivery address when more than one address is specified. ⭐
The GEO and TZ parameters MAY be used with this property. 🌍
The property can also include a "LABEL" parameter to present a delivery address label for the address. Its value is a plain-text string representing the formatted address. Newlines are encoded as \n, as they are for property values. 📝
ABNF:
label-param = "LABEL=" param-value
ADR-param = "VALUE=text" / label-param / language-param
/ geo-parameter / tz-parameter / altid-param / pid-param
/ pref-param / type-param / any-param
ADR-value = ADR-component-pobox ";" ADR-component-ext ";"
ADR-component-street ";" ADR-component-locality ";"
ADR-component-region ";" ADR-component-code ";"
ADR-component-country
ADR-component-pobox = list-component
ADR-component-ext = list-component
ADR-component-street = list-component
ADR-component-locality = list-component
ADR-component-region = list-component
ADR-component-code = list-component
ADR-component-country = list-componentExample: In this example, the post office box and the extended address are absent. 📮
ADR;GEO="geo:12.3457,78.910";LABEL="Mr. John Q. Public, Esq.\n
Mail Drop: TNE QB\n123 Main Street\nAny Town, CA 91921-1234\n
U.S.A.":;;123 Main Street;Any Town;CA;91921-1234;U.S.A.6.4. Communications Properties 📞
These properties describe how to communicate with the object the vCard represents. Slide into those DMs 💖
6.4.1. TEL ☎️
Purpose: this one specifies the telephone number for telephony communication with the object the vCard represents. Ring ring 📱
Value type: By default it's a single free-form text value (for backward compatibility with vCard 3) 🕰️ but it SHOULD be reset to a URI value. The URI scheme is expected to be "tel", as specified in [RFC3966], but other schemes MAY be used. 🔗
Cardinality: * ✨
Special notes: This property is based on the X.520 Telephone Number attribute [CCITT.X520.1988]. 🧠
The property can include the "PREF" parameter to indicate a preferred-use telephone number. 🌟
The property can include the parameter "TYPE" to specify the intended use for the telephone number. The predefined values for the TYPE parameter are:
+-----------+-------------------------------------------------------+
| Value | Description |
+-----------+-------------------------------------------------------+
| text | Indicates that the telephone number supports text |
| | messages (SMS). |
| voice | Indicates a voice telephone number. |
| fax | Indicates a facsimile telephone number. |
| cell | Indicates a cellular or mobile telephone number. |
| video | Indicates a video conferencing telephone number. |
| pager | Indicates a paging device telephone number. |
| textphone | Indicates a telecommunication device for people with |
| | hearing or speech difficulties. |
+-----------+-------------------------------------------------------+The default type is "voice" 📞 These type parameter values can be specified as a parameter list (e.g., TYPE=text;TYPE=voice) or as a value list (e.g., TYPE="text,voice"). The default can be overridden to another set of values by specifying one or more alternate values. For example, the default TYPE of "voice" can be reset to a VOICE and FAX telephone number by the value list TYPE="voice,fax". 🫶
If this property's value is a URI that can also be used for instant messaging, the IMPP (Section 6.4.3) property SHOULD be used in addition to this property. 💬
ABNF:
TEL-param = TEL-text-param / TEL-uri-param
TEL-value = TEL-text-value / TEL-uri-value
; Value and parameter MUST match.
TEL-text-param = "VALUE=text"
TEL-text-value = text
TEL-uri-param = "VALUE=uri" / mediatype-param
TEL-uri-value = URI
TEL-param =/ type-param / pid-param / pref-param / altid-param
/ any-param
type-param-tel = "text" / "voice" / "fax" / "cell" / "video"
/ "pager" / "textphone" / iana-token / x-name
; type-param-tel MUST NOT be used with a property other than TEL.Examples:
TEL;VALUE=uri;PREF=1;TYPE="voice,home":tel:+1-555-555-5555;ext=5555
TEL;VALUE=uri;TYPE=home:tel:+33-01-23-45-676.4.2. EMAIL 📧
This property specifies the electronic mail address for communication with the object the vCard represents. Send it 💌
Value type: A single text value.
Cardinality: * 🌸
Special notes: The property can include the "PREF" parameter to indicate a preferred-use email address when more than one is specified. ⭐
Even though the value is free-form UTF-8 text, it's likely to be interpreted by a Mail User Agent (MUA) as an "addr-spec", as defined in [RFC5322], Section 3.4.1. Readers should also be aware of the current work toward internationalized email addresses [RFC5335bis]. 🌍
ABNF:
EMAIL-param = "VALUE=text" / pid-param / pref-param / type-param
/ altid-param / any-param
EMAIL-value = textExample:
EMAIL;TYPE=work:jqpublic@xyz.example.com
EMAIL;PREF=1:jane_doe@example.com6.4.3. IMPP 💬
This property specifies the URI for instant messaging and presence protocol communications with the object the vCard represents. Bestie, slide into the chat 🦋
Value type: A single URI. 🔗
Cardinality: * ✨
Special notes: The property may include the "PREF" parameter to indicate that this is a preferred address. It has the same semantics as the "PREF" parameter in a TEL property. 🌟
If this property's value is a URI that can be used for voice and/or video, the TEL property (Section 6.4.1) SHOULD be used in addition to this property. 📞
This property is adapted from [RFC4770], which is made obsolete by this document. 🙈
ABNF:
IMPP-param = "VALUE=uri" / pid-param / pref-param / type-param
/ mediatype-param / altid-param / any-param
IMPP-value = URIExample:
IMPP;PREF=1:xmpp:alice@example.com6.4.4. LANG 🗣️
This property specifies the language(s) that may be used for contacting the entity associated with the vCard. Say hi in your best language 🌏
Value type: A single language-tag value. 🏳️🌈
Cardinality: * 💫
ABNF:
LANG-param = "VALUE=language-tag" / pid-param / pref-param
/ altid-param / type-param / any-param
LANG-value = Language-TagExample:
LANG;TYPE=work;PREF=1:en
LANG;TYPE=work;PREF=2:fr
LANG;TYPE=home:fr6.5. Geographical Properties 🗺️
These properties are concerned with information associated with geographical positions or regions associated with the object the vCard represents. Location, location, location 📍
6.5.1. TZ 🌍
Purpose: Okay so this one is all about the time zone of the object the vCard represents. 🕰️✨
Value type: The default is a single text value, but it can also be reset to a single URI or utc-offset value. 💅
Cardinality: * 🎀
Special notes: Names from the public-domain Olson database [TZ-DB] are what everyone's expected to use, but it's not a strict rule, so you do you. Also check out [IANA-TZ] 🧚
Efforts are currently in progress to make a standard URI scheme for time zone info. If that happens, anything using it gets way better interop between implementations that support it. Iconic behaviour 🦋
Heads up though, utc-offset values SHOULD NOT be used. 🙈 The UTC offset changes over time, and it's not just the usual daylight saving shifts, because whole regions will sometimes "re-base" their overall offset. So the real offset might be +/- 1 hour (or a bit more) from the one you wrote down. Ngl that's chaos 💀
ABNF:
TZ-param = "VALUE=" ("text" / "uri" / "utc-offset")
TZ-value = text / URI / utc-offset
; Value and parameter MUST match.
TZ-param =/ altid-param / pid-param / pref-param / type-param
/ mediatype-param / any-paramExamples:
TZ:Raleigh/North America
TZ;VALUE=utc-offset:-0500
; Note: utc-offset format is NOT RECOMMENDED.6.5.2. GEO 📍
Purpose: To specify info about where the object the vCard represents sits in the world, using global positioning. Main character location energy 🗺️
Value type: A single URI. 🔗
Cardinality: * 🌸
Special notes: The "geo" URI scheme [RFC5870] is super well suited for this property, but other schemes MAY be used. 💖
ABNF:
GEO-param = "VALUE=uri" / pid-param / pref-param / type-param
/ mediatype-param / altid-param / any-param
GEO-value = URIExample:
GEO:geo:37.386013,-122.0829326.6. Organizational Properties 🏢
These properties are all about the organization, or the organizational units, that the object the vCard represents is tied to. Corporate girlie era 💼✨
6.6.1. TITLE 👑
Purpose: To specify the position or job of the object the vCard represents. Career slay 💅
Value type: A single text value. 📝
Cardinality: * 🎀
Special notes: This property is based on the X.520 Title attribute [CCITT.X520.1988]. 🧠
ABNF:
TITLE-param = "VALUE=text" / language-param / pid-param
/ pref-param / altid-param / type-param / any-param
TITLE-value = textExample:
TITLE:Research Scientist6.6.2. ROLE 🎭
Purpose: To specify the function, or part played in a particular situation, by the object the vCard represents. It's giving role-playing 🎬
Value type: A single text value. 📝
Cardinality: * 🌈
Special notes: This property is based on the X.520 Business Category explanatory attribute [CCITT.X520.1988]. It exists as an organizational type so nobody gets confused with the semantics of TITLE, and so people don't misuse TITLE when they actually mean this one. Iykyk 🙈
ABNF:
ROLE-param = "VALUE=text" / language-param / pid-param / pref-param
/ type-param / altid-param / any-param
ROLE-value = textExample:
ROLE:Project Leader6.6.3. LOGO 🖼️
Purpose: To specify a graphic image of a logo associated with the object the vCard represents. Brand aesthetic unlocked 🦋
Value type: A single URI. 🔗
Cardinality: * ✨
ABNF:
LOGO-param = "VALUE=uri" / language-param / pid-param / pref-param
/ type-param / mediatype-param / altid-param / any-param
LOGO-value = URIExamples:
LOGO:http://www.example.com/pub/logos/abccorp.jpg
LOGO:data:image/jpeg;base64,MIICajCCAdOgAwIBAgICBEUwDQYJKoZIhvc
AQEEBQAwdzELMAkGA1UEBhMCVVMxLDAqBgNVBAoTI05ldHNjYXBlIENvbW11bm
ljYXRpb25zIENvcnBvcmF0aW9uMRwwGgYDVQQLExNJbmZvcm1hdGlvbiBTeXN0
<...the remainder of base64-encoded data...>
6.6.4. ORG 🏬
Purpose: To specify the organization name and units associated with the vCard. The whole org chart, bestie 🗂️
Value type: A single structured text value made of components separated by the SEMICOLON character (U+003B). 🧩
Cardinality: * 💜
Special notes: This property is based on the X.520 Organization Name and Organization Unit attributes [CCITT.X520.1988]. The value is a structured type: the organization name first, then zero or more levels of organizational unit names. 🏛️
The SORT-AS parameter MAY be applied to this property. 🔥
ABNF:
ORG-param = "VALUE=text" / sort-as-param / language-param
/ pid-param / pref-param / altid-param / type-param
/ any-param
ORG-value = component *(";" component)Example: A value with an organization name, organizational unit #1 name, and organizational unit #2 name. 🌸
ORG:ABC\, Inc.;North American Division;Marketing6.6.5. MEMBER 👯
Purpose: To include a member in the group this vCard represents. Squad goals 🫶
Value type: A single URI. It MAY refer to something other than a vCard object. For example, an email distribution list could use the "mailto" URI scheme [RFC6068] for efficiency. 📧✨
Cardinality: * 🎀
Special notes: This property MUST NOT be present unless the value of the KIND property is "group". No group, no MEMBER, periodt 🙅♀️
ABNF:
MEMBER-param = "VALUE=uri" / pid-param / pref-param / altid-param
/ mediatype-param / any-param
MEMBER-value = URIExamples:
BEGIN:VCARD
VERSION:4.0
KIND:group
FN:The Doe family
MEMBER:urn:uuid:03a0e51f-d1aa-4385-8a53-e29025acd8af
MEMBER:urn:uuid:b8767877-b4a1-4c70-9acc-505d3819e519
END:VCARD
BEGIN:VCARD
VERSION:4.0
FN:John Doe
UID:urn:uuid:03a0e51f-d1aa-4385-8a53-e29025acd8af
END:VCARD
BEGIN:VCARD
VERSION:4.0
FN:Jane Doe
UID:urn:uuid:b8767877-b4a1-4c70-9acc-505d3819e519
END:VCARD
BEGIN:VCARD
VERSION:4.0
KIND:group
FN:Funky distribution list
MEMBER:mailto:subscriber1@example.com
MEMBER:xmpp:subscriber2@example.com
MEMBER:sip:subscriber3@example.com
MEMBER:tel:+1-418-555-5555
END:VCARD6.6.6. RELATED 💞
Purpose: To specify a relationship between another entity and the entity represented by this vCard. The relationship drama is real 😭
Value type: A single URI. It can also be reset to a single text value, which is handy when you want textual info. 📝
Cardinality: * 🌷
Special notes: The TYPE parameter MAY be used to describe the related entity. It holds a comma-separated list of values registered with IANA as described in Section 10.2. The registry comes pre-populated with the values defined in [xfn]. This document also adds two extra values: 🧡
agent: an entity who may sometimes act on behalf of the entity associated with the vCard. Your hype person 📣emergency: indicates an emergency contact. Call them if things get messy 🚑
ABNF:
RELATED-param = RELATED-param-uri / RELATED-param-text
RELATED-value = URI / text
; Parameter and value MUST match.
RELATED-param-uri = "VALUE=uri" / mediatype-param
RELATED-param-text = "VALUE=text" / language-param
RELATED-param =/ pid-param / pref-param / altid-param / type-param
/ any-param
type-param-related = related-type-value *("," related-type-value)
; type-param-related MUST NOT be used with a property other than
; RELATED.
related-type-value = "contact" / "acquaintance" / "friend" / "met"
/ "co-worker" / "colleague" / "co-resident"
/ "neighbor" / "child" / "parent"
/ "sibling" / "spouse" / "kin" / "muse"
/ "crush" / "date" / "sweetheart" / "me"
/ "agent" / "emergency"Examples:
RELATED;TYPE=friend:urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6
RELATED;TYPE=contact:http://example.com/directory/jdoe.vcf
RELATED;TYPE=co-worker;VALUE=text:Please contact my assistant Jane
Doe for any inquiries.6.7. Explanatory Properties 📖
These properties hold extra explanations, like informational notes or revisions specific to the vCard. The context era 🧠💭
6.7.1. CATEGORIES 🏷️
Purpose: To specify application category info about the vCard, also known as "tags". Hashtag energy #️⃣
Value type: One or more text values separated by a COMMA character (U+002C). 🎀
Cardinality: * 🌟
ABNF:
CATEGORIES-param = "VALUE=text" / pid-param / pref-param
/ type-param / altid-param / any-param
CATEGORIES-value = text-listExamples:
CATEGORIES:TRAVEL AGENT
CATEGORIES:INTERNET,IETF,INDUSTRY,INFORMATION TECHNOLOGY6.7.2. NOTE 📝
Purpose: To specify supplemental info or a comment associated with the vCard. Little sticky note vibes 🗒️
Value type: A single text value. 📝
Cardinality: * 🦋
Special notes: This property is based on the X.520 Description attribute [CCITT.X520.1988]. 🧠
ABNF:
NOTE-param = "VALUE=text" / language-param / pid-param / pref-param
/ type-param / altid-param / any-param
NOTE-value = textExample:
NOTE:This fax number is operational 0800 to 1715
EST\, Mon-Fri.6.7.3. PRODID 🆔
Purpose: To specify the identifier for the product that created the vCard object. Who made this, though? 🤔
Type value: A single text value. 📝
Cardinality: *1 🔒
Special notes: Implementations SHOULD use a method such as the one specified for Formal Public Identifiers in [ISO9070], or for Universal Resource Names in [RFC3406], to make sure the text value is unique. Uniqueness is everything 💅
ABNF:
PRODID-param = "VALUE=text" / any-param
PRODID-value = textExample:
PRODID:-//ONLINE DIRECTORY//NONSGML Version 1//EN6.7.4. REV ⏰
Purpose: To specify revision info about the current vCard. Timestamp receipts 🧾
Value type: A single timestamp value. ⏳
Cardinality: *1 🔐
Special notes: The value tells the current revision of the information in this vCard apart from other renditions of that information. Like a glow-up timeline ✨
ABNF:
REV-param = "VALUE=timestamp" / any-param
REV-value = timestampExample:
REV:19951031T222710Z6.7.5. SOUND 🔊
Purpose: To specify digital sound content that annotates some aspect of the vCard. This one is often used to show how to pronounce the name property value, so you never mispronounce your bestie's name again 🫶🎧
Value type: A single URI. 🔗
Cardinality: * 🎶
ABNF:
SOUND-param = "VALUE=uri" / language-param / pid-param / pref-param
/ type-param / mediatype-param / altid-param
/ any-param
SOUND-value = URIExample:
SOUND:CID:JOHNQPUBLIC.part8.19960229T080000.xyzMail@example.com
SOUND:data:audio/basic;base64,MIICajCCAdOgAwIBAgICBEUwDQYJKoZIh
AQEEBQAwdzELMAkGA1UEBhMCVVMxLDAqBgNVBAoTI05ldHNjYXBlIENvbW11bm
ljYXRpb25zIENvcnBvcmF0aW9uMRwwGgYDVQQLExNJbmZvcm1hdGlvbiBTeXN0
<...the remainder of base64-encoded data...>6.7.6. UID 🪪
Purpose: This one gives the vCard its own globally unique identifier, tied to the entity the vCard represents. Think of it as the vCard's ID card 💖
Value type: It's a single URI value, but it MAY also be reset to free-form text, so you've got options 🌸
Cardinality: *1
Special notes: UID is how the vCard gets identified as the vCard for that object ✨ The "uuid" URN namespace from [RFC4122] is especially iconic for this job, but other URI schemes MAY be used too. Free-form text MAY also be used. Main character energy for flexibility 💅
ABNF:
UID-param = UID-uri-param / UID-text-param
UID-value = UID-uri-value / UID-text-value
; Value and parameter MUST match.
UID-uri-param = "VALUE=uri"
UID-uri-value = URI
UID-text-param = "VALUE=text"
UID-text-value = text
UID-param =/ any-paramExample:
UID:urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf66.7.7. CLIENTPIDMAP 🗺️
Purpose: This property gives a global meaning to a local PID source identifier. It's basically the translator between "my little local number" and "the real global thing" 🧚
Value type: It's a semicolon-separated pair of values. The first field is a small integer that matches the second field of a PID parameter instance. The second field is a URI. The "uuid" URN namespace from [RFC4122] is particularly well suited here too, but other URI schemes MAY be used.
Cardinality: *
Special notes: PID source identifiers (the source identifier is that second field in a PID parameter instance) are small integers, and they only mean something inside one single vCard instance 🦋 Every distinct source identifier in a vCard MUST have an associated CLIENTPIDMAP. Check out Section 7 for more on how CLIENTPIDMAP gets used.
PID source identifiers MUST be strictly positive. Zero is not allowed, no exceptions 🙅♀️
Okay, and here's the big plot twist: the PID parameter MUST NOT be applied to this property. CLIENTPIDMAP can't have a PID of its own 💀
ABNF:
CLIENTPIDMAP-param = any-param
CLIENTPIDMAP-value = 1*DIGIT ";" URIExample:
TEL;PID=3.1,4.2;VALUE=uri:tel:+1-555-555-5555
EMAIL;PID=4.1,5.2:jdoe@example.com
CLIENTPIDMAP:1;urn:uuid:3df403f4-5924-4bb7-b077-3c711d9eb34b
CLIENTPIDMAP:2;urn:uuid:d89c9c7a-2e1b-4832-82de-7e992d95faa56.7.8. URL 🌐
Purpose: This specifies a uniform resource locator linked to the object the vCard refers to. For individuals, that's stuff like personal websites, blogs, and social networking site identifiers 🦋
Cardinality: *
Value type: A single URI value, bestie 🎀
ABNF:
URL-param = "VALUE=uri" / pid-param / pref-param / type-param
/ mediatype-param / altid-param / any-param
URL-value = URIExample:
URL:http://example.org/restaurant.french/~chezchic.html6.7.9. VERSION 🔖
Purpose: This tells you which version of the vCard spec was used to format this vCard. It's the label on the box 📦
Value type: A single text value.
Cardinality: 1
Special notes: This property MUST be present in the vCard object, and it must appear immediately after BEGIN:VCARD. Non-negotiable 😤 The value MUST be "4.0" if the vCard corresponds to this specification.
Okay, history lesson: earlier versions of vCard let this property float anywhere in the vCard object, or even skip it entirely. Iconic, but that's the past 🕰️
ABNF:
VERSION-param = "VALUE=text" / any-param
VERSION-value = "4.0"Example:
VERSION:4.06.8. Security Properties 🔐
These properties are all about keeping the communication pathways and access to the vCard safe. Protect your main character 👑
6.8.1. KEY 🗝️
Purpose: This specifies a public key or authentication certificate associated with the object the vCard represents.
Value type: A single URI. It can also be reset to a text value 🌈
Cardinality: *
ABNF:
KEY-param = KEY-uri-param / KEY-text-param
KEY-value = KEY-uri-value / KEY-text-value
; Value and parameter MUST match.
KEY-uri-param = "VALUE=uri" / mediatype-param
KEY-uri-value = URI
KEY-text-param = "VALUE=text"
KEY-text-value = text
KEY-param =/ altid-param / pid-param / pref-param / type-param
/ any-paramExamples:
KEY:http://www.example.com/keys/jdoe.cer
KEY;MEDIATYPE=application/pgp-keys:ftp://example.com/keys/jdoe
KEY:data:application/pgp-keys;base64,MIICajCCAdOgAwIBAgICBE
UwDQYJKoZIhvcNAQEEBQAwdzELMAkGA1UEBhMCVVMxLDAqBgNVBAoTI05l
<... remainder of base64-encoded data ...>6.9. Calendar Properties 📅
These properties are further specified in [RFC2739]. Scheduling era, let's go 🗓️
6.9.1. FBURL 🕒
Purpose: This specifies the URI for the busy time associated with the object the vCard represents. Basically, "when is this person free?" in URI form 👀
Value type: A single URI value.
Cardinality: *
Special notes: When there are multiple FBURL properties, the default one is marked with the PREF parameter ⭐ The FTP [RFC1738] or HTTP [RFC2616] type of URI points to an iCalendar [RFC5545] object, which is a snapshot of the next few weeks or months of busy time data. If that iCalendar object is stored as a file or document, its file extension should be ".ifb" 📁
ABNF:
FBURL-param = "VALUE=uri" / pid-param / pref-param / type-param
/ mediatype-param / altid-param / any-param
FBURL-value = URIExamples:
FBURL;PREF=1:http://www.example.com/busy/janedoe
FBURL;MEDIATYPE=text/calendar:ftp://example.com/busy/project-a.ifb6.9.2. CALADRURI 📨
Purpose: This specifies the calendar user address [RFC5545] that a scheduling request [RFC5546] should be sent to for the object the vCard represents. It's where the meeting invites go 💌
Value type: A single URI value.
Cardinality: *
Special notes: When there are multiple CALADRURI properties, the default one is marked with the PREF parameter 🎀
ABNF:
CALADRURI-param = "VALUE=uri" / pid-param / pref-param / type-param
/ mediatype-param / altid-param / any-param
CALADRURI-value = URIExample:
CALADRURI;PREF=1:mailto:janedoe@example.com
CALADRURI:http://example.com/calendar/jdoe6.9.3. CALURI 🗓️
Purpose: This specifies the URI for a calendar linked to the object the vCard represents.
Value type: A single URI value.
Cardinality: *
Special notes: When there are multiple CALURI properties, the default one is marked with the PREF parameter 🌸 The property should contain a URI pointing to an iCalendar [RFC5545] object, which is a snapshot of the user's calendar store. If that iCalendar object is stored as a file or document, its file extension should be ".ics" 📂
ABNF:
CALURI-param = "VALUE=uri" / pid-param / pref-param / type-param
/ mediatype-param / altid-param / any-param
CALURI-value = URIExamples:
CALURI;PREF=1:http://cal.example.com/calA
CALURI;MEDIATYPE=text/calendar:ftp://ftp.example.com/calA.ics6.10. Extended Properties and Parameters 🧩
The properties and parameters in this document can be extended. Non-standard, private properties and parameters whose names start with "X-" may be defined bilaterally between two cooperating agents, with no outside registration or standardization needed. Private group chat energy, but make it protocol 🤫
7. Synchronization 🔄
vCard data often needs to be synced between devices. In this context, synchronization means intelligently merging two representations of the same object. vCard 4.0 includes mechanisms to help with exactly that ✨
7.1. Mechanisms ⚙️
There are two mechanisms here. The UID property is what matches multiple instances of the same vCard, while the PID parameter matches multiple instances of the same property 🦋
"Matching" just means recognizing that two instances are actually representations of the same object. For example, if one vCard gets shared with someone, you end up with two vCard instances. After they've evolved separately, they still represent the same object, so a synchronization engine can match them 🫶
7.1.1. Matching vCard Instances
vCard instances whose UID properties (Section 6.7.6) are equivalent MUST be matched. Equivalence is determined as specified in [RFC3986], Section 6 💜
In all other cases, vCard instances MAY be matched, at the discretion of the synchronization engine.
7.1.2. Matching Property Instances
Property instances belonging to unmatched vCards MUST NOT be matched. Not my circus, not my monkeys 🙈
Property instances whose names (like EMAIL, TEL, and so on) are different MUST NOT be matched.
Property instances whose name is CLIENTPIDMAP are handled separately, and they MUST NOT be matched. The synchronization MUST ensure that CLIENTPIDMAPs are consistent among matched vCard instances 🎀
Property instances belonging to matched vCards, whose name is the same, and whose maximum cardinality is 1, MUST be matched 💖
Property instances belonging to matched vCards, whose name is the same, and whose PID parameters match, MUST be matched. Check Section 7.1.3 for the details on PID matching 🧚
In all other cases, property instances MAY be matched, at the discretion of the synchronization engine.
7.1.3. PID Matching 🔍
Two PID values whose first fields are equivalent represent the same local value ✨
Two PID values that represent the same local value, and whose second fields point to CLIENTPIDMAP properties whose second field URIs are equivalent (as specified in [RFC3986], Section 6), also represent the same global value 🌍
PID parameters where at least one pair of values represents the same global value MUST be matched.
In all other cases, PID parameters MAY be matched, at the discretion of the synchronization engine.
For example, PID value "5.1" in the first vCard below and PID value "5.2" in the second vCard below represent the same global value. Bestie, look at those numbers go 🤯
BEGIN:VCARD
VERSION:4.0
EMAIL;PID=4.2,5.1:jdoe@example.com
CLIENTPIDMAP:1;urn:uuid:3eef374e-7179-4196-a914-27358c3e6527
CLIENTPIDMAP:2;urn:uuid:42bcd5a7-1699-4514-87b4-056edf68e9cc
END:VCARD
BEGIN:VCARD
VERSION:4.0
EMAIL;PID=5.1,5.2:john@example.com
CLIENTPIDMAP:1;urn:uuid:0c75c629-6a8d-4d5e-a07f-1bb35846854d
CLIENTPIDMAP:2;urn:uuid:3eef374e-7179-4196-a914-27358c3e6527
END:VCARD7.2. Example 📖
7.2.1. Creation 🌱
First up, this simple vCard gets created on a given device 💅
BEGIN:VCARD
VERSION:4.0
UID:urn:uuid:4fbe8971-0bc3-424c-9c26-36c3e1eff6b1
FN;PID=1.1:J. Doe
N:Doe;J.;;;
EMAIL;PID=1.1:jdoe@example.com
CLIENTPIDMAP:1;urn:uuid:53e374d9-337e-4727-8803-a1e9c14e0556
END:VCARDThe creating device gives this new vCard the UID "urn:uuid:4fbe8971-0bc3-424c-9c26-36c3e1eff6b1". The FN and EMAIL properties both get the same local value of 1, and that value gets global context by being linked to "urn:uuid:53e374d9-337e-4727-8803-a1e9c14e0556", which represents the creating device 🔥 We're free to reuse the same local value because instances of different properties will never be matched. The N property has no PID, since its maximum cardinality of 1 forbids one 🙃
7.2.2. Initial Sharing 🤝
This vCard gets shared with a second device. When the second device inspects the UID property, it realizes this is a brand-new vCard (so, unmatched), and the synchronization ends up being a simple copy 🫶✨
7.2.3. Adding and Sharing a Property ✨
Okay so a brand new phone number gets created on the first device, and then the vCard gets shared over to the second device. Here's what the second device receives 💖:
BEGIN:VCARD
VERSION:4.0
UID:urn:uuid:4fbe8971-0bc3-424c-9c26-36c3e1eff6b1
FN;PID=1.1:J. Doe
N:Doe;J.;;;
EMAIL;PID=1.1:jdoe@example.com
TEL;PID=1.1;VALUE=uri:tel:+1-555-555-5555
CLIENTPIDMAP:1;urn:uuid:53e374d9-337e-4727-8803-a1e9c14e0556
END:VCARDThe second device looks at the UID property first 🔍, and it's a match for the vCard it already has stored. Then it starts comparing the properties of the two vCards in same-named pairs. It's giving detective energy, honestly.
The FN properties are matched because their PID parameters have the same global value. The property value is the same too, so nothing gets updated. ✨
The N properties are matched automatically because their maximum cardinality is 1. The value is the same, so no update takes place. Easy 🫶
The EMAIL properties are matched because the PID parameters have the same global value. The value matches as well, so again no update. Slay.
The TEL property in the new vCard doesn't get matched to anything, because no property in the stored vCard has the same name. So this one just gets copied from the new vCard into the stored vCard. New number, who dis 📱
The CLIENTPIDMAP property is handled separately by the synchronization engine 🧚. The engine makes sure it stays consistent with the stored one. If it didn't stay consistent, the results would be up to the synchronization engine, and this document doesn't define that, so it's undefined territory 💀
7.2.4. Simultaneous Editing
Now this is the drama 🍿. A new email address and a new phone number get added to the vCard on each of the two devices, and then a new synchronization event happens. Here are the vCards that get communicated to each other:
BEGIN:VCARD
VERSION:4.0
UID:urn:uuid:4fbe8971-0bc3-424c-9c26-36c3e1eff6b1
FN;PID=1.1:J. Doe
N:Doe;J.;;;
EMAIL;PID=1.1:jdoe@example.com
EMAIL;PID=2.1:boss@example.com
TEL;PID=1.1;VALUE=uri:tel:+1-555-555-5555
TEL;PID=2.1;VALUE=uri:tel:+1-666-666-6666
CLIENTPIDMAP:1;urn:uuid:53e374d9-337e-4727-8803-a1e9c14e0556
END:VCARD
BEGIN:VCARD
VERSION:4.0
UID:urn:uuid:4fbe8971-0bc3-424c-9c26-36c3e1eff6b1
FN;PID=1.1:J. Doe
N:Doe;J.;;;
EMAIL;PID=1.1:jdoe@example.com
EMAIL;PID=2.2:ceo@example.com
TEL;PID=1.1;VALUE=uri:tel:+1-555-555-5555
TEL;PID=2.2;VALUE=uri:tel:+1-666-666-6666
CLIENTPIDMAP:1;urn:uuid:53e374d9-337e-4727-8803-a1e9c14e0556
CLIENTPIDMAP:2;urn:uuid:1f762d2b-03c4-4a83-9a03-75ff658a6eee
END:VCARDSo on the first device, the same PID source identifier (1) gets reused for the new EMAIL and TEL properties. On the second device, a new source identifier (2) is generated, and a matching CLIENTPIDMAP property is created. That one contains the second device's identifier, "urn:uuid:1f762d2b-03c4-4a83-9a03-75ff658a6eee". Very organized of them 📋
The new EMAIL properties are unmatched on both sides, since the PID global value is new in both cases. So the sync results in a copy on both sides. Everyone gets everything 🌈
Here's the plot twist 😭. The situation looks the same for the TEL properties, but in this case the synchronization engine is particularly smart and matches the two new TEL properties even though their PID global values are different. Note that the rules of Section 7.1.2 say two properties MAY be matched at the discretion of the synchronization engine. So these two properties get merged. Galaxy brain move 🧠✨
All of this results in the following vCard, which gets stored on both devices:
BEGIN:VCARD
VERSION:4.0
UID:urn:uuid:4fbe8971-0bc3-424c-9c26-36c3e1eff6b1
FN:J. Doe
N:Doe;J.;;;
EMAIL;PID=1.1:jdoe@example.com
EMAIL;PID=2.1:boss@example.com
EMAIL;PID=2.2:ceo@example.com
TEL;PID=1.1;VALUE=uri:tel:+1-555-555-5555
TEL;PID=2.1,2.2;VALUE=uri:tel:+1-666-666-6666
CLIENTPIDMAP:1;urn:uuid:53e374d9-337e-4727-8803-a1e9c14e0556
CLIENTPIDMAP:2;urn:uuid:1f762d2b-03c4-4a83-9a03-75ff658a6eee
END:VCARD7.2.5. Global Context Simplification
The two devices wrap up their synchronization procedure by simplifying their global contexts 🧹. Since they haven't talked to any other device, the following vCard is for all purposes equivalent to the one above. It's also shorter, which is always a vibe 💅
BEGIN:VCARD
VERSION:4.0
UID:urn:uuid:4fbe8971-0bc3-424c-9c26-36c3e1eff6b1
FN:J. Doe
N:Doe;J.;;;
EMAIL;PID=1.1:jdoe@example.com
EMAIL;PID=2.1:boss@example.com
EMAIL;PID=3.1:ceo@example.com
TEL;PID=1.1;VALUE=uri:tel:+1-555-555-5555
TEL;PID=2.1;VALUE=uri:tel:+1-666-666-6666
CLIENTPIDMAP:1;urn:uuid:53e374d9-337e-4727-8803-a1e9c14e0556
END:VCARDThe details of global context simplification are unspecified by this document. They're left up to the synchronization engine 🤷♀️. This example is just meant to show the possibility, and in the author's opinion, looking into it would be worthwhile 🎀
8. Example: Author's vCard ✨
BEGIN:VCARD
VERSION:4.0
FN:Simon Perreault
N:Perreault;Simon;;;ing. jr,M.Sc.
BDAY:--0203
ANNIVERSARY:20090808T1430-0500
GENDER:M
LANG;PREF=1:fr
LANG;PREF=2:en
ORG;TYPE=work:Viagenie
ADR;TYPE=work:;Suite D2-630;2875 Laurier;
Quebec;QC;G1V 2M2;Canada
TEL;VALUE=uri;TYPE="work,voice";PREF=1:tel:+1-418-656-9254;ext=102
TEL;VALUE=uri;TYPE="work,cell,voice,video,text":tel:+1-418-262-6501
EMAIL;TYPE=work:simon.perreault@viagenie.ca
GEO;TYPE=work:geo:46.772673,-71.282945
KEY;TYPE=work;VALUE=uri:
http://www.viagenie.ca/simon.perreault/simon.asc
TZ:-0500
URL;TYPE=home:http://nomis80.org
END:VCARD9. Security Considerations 🔒
- Internet mail is often used to transport vCards, and it's subject to lots of well-known security attacks, including monitoring, replay, and forgery. 😬 Any directory service should be careful about letting information leave the scope of the service itself, because once it's out there, any access controls or confidentiality can no longer be guaranteed. Applications should also take care to display directory data in a "safe" environment.
- vCards can carry cryptographic keys or certificates, as described in Section 6.8.1. 🔑
- vCards often carry information that can be sensitive, like birthday, address, and phone information 🙈. Although vCards have no inherent authentication or confidentiality provisions, they can easily be carried by any security mechanism that transfers MIME objects to address authentication or confidentiality (for example, S/MIME [RFC5751] or OpenPGP [RFC4880]). In cases where the confidentiality or authenticity of information contained in a vCard is a concern, the vCard SHOULD be transported using one of these secure mechanisms. The KEY property (Section 6.8.1) can be used to transport the public key used by these mechanisms.
- The information in a vCard may become out of date. In cases where the vitality of data is important to the originator of a vCard, the SOURCE property (Section 6.1.3) SHOULD be specified. On top of that, the "REV" type described in Section 6.7.4 can be specified to indicate the last time the vCard data was updated. ⏰
- Lots of vCard properties may be used to transport URIs. For considerations related to URIs, please refer to [RFC3986], Section 7. 🦋
10. IANA Considerations 📚
10.1. Media Type Registration
IANA has registered the following Media Type (in <http://www.iana.org/>) and marked the text/directory Media Type as DEPRECATED. Here's the registration, exactly as it's written 💜:
To: ietf-types@iana.org
Subject: Registration of media type text/vcard
Type name: text
Subtype name: vcard
Required parameters: none
Optional parameters: version
The "version" parameter is to be interpreted identically as the
VERSION vCard property. If this parameter is present, all vCards
in a text/vcard body part MUST have a VERSION property with value
identical to that of this MIME parameter.
"charset": as defined for text/plain [RFC2046]; encodings other
than UTF-8 [RFC3629] MUST NOT be used.
Encoding considerations: 8bit
Security considerations: See Section 9.
Interoperability considerations: The text/vcard media type is
intended to identify vCard data of any version. There are older
specifications of vCard [RFC2426][vCard21] still in common use.
While these formats are similar, they are not strictly compatible.
In general, it is necessary to inspect the value of the VERSION
property (see Section 6.7.9) for identifying the standard to which
a given vCard object conforms.
In addition, the following media types are known to have been used
to refer to vCard data. They should be considered deprecated in
favor of text/vcard.
* text/directory
* text/directory; profile=vcard
* text/x-vcard
Published specification: RFC 6350
Applications that use this media type: They are numerous, diverse,
and include mail user agents, instant messaging clients, address
book applications, directory servers, and customer relationship
management software.
Additional information:
Magic number(s):
File extension(s): .vcf .vcard
Macintosh file type code(s):
Person & email address to contact for further information: vCard
discussion mailing list <vcarddav@ietf.org>
Intended usage: COMMON
Restrictions on usage: none
Author: Simon Perreault
Change controller: IETF10.2. Registering New vCard Elements
This section defines the process for registering new or modified vCard elements (that is, properties, parameters, value data types, and values) with IANA 🌸.
10.2.1. Registration Procedure
okay so the IETF made a mailing list, vcarddav@ietf.org, where you can totally chat about vCard element proposals before registering anything 💌 using it is strongly encouraged. the IESG also appointed a designated expert who keeps an eye on that list and reviews registrations 👀
Registration of new vCard elements MUST be reviewed by the designated expert and published in an RFC. no shortcuts, bestie 💅 If you're registering a new value data type that modifies existing properties, a Standards Track RFC is REQUIRED. same energy for vCard elements that modify vCard elements already documented in a Standards Track RFC: a Standards Track RFC is also REQUIRED 🔥
the registration procedure starts when a completed registration template (the ones in the sections below) gets sent to vcarddav@ietf.org and iana@iana.org 📬 within two weeks, the designated expert is expected to tell IANA and the submitter whether it's approved, approved with minor changes, or rejected with cause. if it gets rejected with cause, you can re-submit once the concerns listed in the cause are addressed 🫶 decisions from the designated expert can be appealed to the IESG Applications Area Director, then to the IESG. they follow the normal appeals procedure for IESG decisions. very procedural, very iconic ✨
once the registration procedure wraps up successfully, IANA creates or modifies the corresponding record in the vCard registry 🎀 and the completed registration template gets discarded 🗑️
An RFC specifying new vCard elements MUST include the completed registration templates, which MAY be expanded with additional information. these completed templates are meant to live in the body of the document, not in the IANA Considerations section 📝
last thing: there's an XML representation for vCard defined in [RFC6351] 🧚 An XML representation SHOULD be defined for new vCard elements.
10.2.2. Vendor Namespace
the vendor namespace is for vCard elements tied to commercially available products 🛍️ "Vendor" and "producer" are treated as equivalent, and very broadly in this context, so don't overthink it 💖
anyone who needs to swap files associated with a particular product can place a registration in the vendor namespace 🦋 BUT the registration formally belongs to the vendor or organization handling the vCard elements in that namespace. changes to the specification get made at their request, as discussed in later sections 👑
vendor namespace elements are marked with the "VND-" prefix, then an IANA-registered Private Enterprise Number (PEN), then a dash, then a vCard element designation the vendor picks (e.g., "VND-123456-MUDPIE") 🌸
public exposure and review of vendor namespace elements aren't required 🙈 but using the vcarddav@ietf.org mailing list for review is strongly encouraged, because it helps level up the quality of those specs ✨ registrations in the vendor namespace may be submitted directly to the IANA 💅
10.2.3. Registration Template for Properties
a property gets defined by filling out this template 🌈
- Namespace: Empty for the global namespace,
"VND-NNNN-"for a vendor-specific property (where NNNN is replaced by the vendor's PEN). - Property name: The name of the property.
- Purpose: The purpose of the property. Give a short but clear description.
- Value type: Any of the valid value types for the property value needs to be specified. The default value type also needs to be specified.
- Cardinality: See Section 6.
- Property parameters: Any of the valid property parameters for the property MUST be specified.
- Description: Any special notes about the property, how it is to be used, etc.
- Format definition: The ABNF for the property definition needs to be specified.
- Example(s): One or more examples of instances of the property need to be specified.
10.2.4. Registration Template for Parameters
a parameter gets defined by filling out this template 🧁
- Namespace: Empty for the global namespace,
"VND-NNNN-"for a vendor-specific property (where NNNN is replaced by the vendor's PEN). - Parameter name: The name of the parameter.
- Purpose: The purpose of the parameter. Give a short but clear description.
- Description: Any special notes about the parameter, how it is to be used, etc.
- Format definition: The ABNF for the parameter definition needs to be specified.
- Example(s): One or more examples of instances of the parameter need to be specified.
10.2.5. Registration Template for Value Data Types
a value data type gets defined by filling out this template 🫧
- Value name: The name of the value type.
- Purpose: The purpose of the value type. Give a short but clear description.
- Description: Any special notes about the value type, how it is to be used, etc.
- Format definition: The ABNF for the value type definition needs to be specified.
- Example(s): One or more examples of instances of the value type need to be specified.
10.2.6. Registration Template for Values
a value gets defined by filling out this template 💜
- Value: The value literal.
- Purpose: The purpose of the value. Give a short but clear description.
- Conformance: The vCard properties and/or parameters that can take this value needs to be specified.
- Example(s): One or more examples of instances of the value need to be specified.
here's a fictitious example of a registration of a vCard value, because examples make everything click 🍓
- Value: supervisor
- Purpose: It means that the related entity is the direct hierarchical superior (i.e., supervisor or manager) of the entity this vCard represents. the boss energy is real 👑
- Conformance: This value can be used with the "TYPE" parameter applied on the "RELATED" property.
- Example(s):
RELATED;TYPE=supervisor:urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf610.3. Initial vCard Elements Registries
the IANA has created and will maintain the following registries for vCard elements, with pointers to the appropriate reference documents 🗂️ they're all grouped together under the heading "vCard Elements" 🦋
10.3.1. Properties Registry
the following table was used to initialize the properties registry 🌷
+-----------+--------------+-------------------------+
| Namespace | Property | Reference |
+-----------+--------------+-------------------------+
| | SOURCE | RFC 6350, Section 6.1.3 |
| | KIND | RFC 6350, Section 6.1.4 |
| | XML | RFC 6350, Section 6.1.5 |
| | FN | RFC 6350, Section 6.2.1 |
| | N | RFC 6350, Section 6.2.2 |
| | NICKNAME | RFC 6350, Section 6.2.3 |
| | PHOTO | RFC 6350, Section 6.2.4 |
| | BDAY | RFC 6350, Section 6.2.5 |
| | ANNIVERSARY | RFC 6350, Section 6.2.6 |
| | GENDER | RFC 6350, Section 6.2.7 |
| | ADR | RFC 6350, Section 6.3.1 |
| | TEL | RFC 6350, Section 6.4.1 |
| | EMAIL | RFC 6350, Section 6.4.2 |
| | IMPP | RFC 6350, Section 6.4.3 |
| | LANG | RFC 6350, Section 6.4.4 |
| | TZ | RFC 6350, Section 6.5.1 |
| | GEO | RFC 6350, Section 6.5.2 |
| | TITLE | RFC 6350, Section 6.6.1 |
| | ROLE | RFC 6350, Section 6.6.2 |
| | LOGO | RFC 6350, Section 6.6.3 |
| | ORG | RFC 6350, Section 6.6.4 |
| | MEMBER | RFC 6350, Section 6.6.5 |
| | RELATED | RFC 6350, Section 6.6.6 |
| | CATEGORIES | RFC 6350, Section 6.7.1 |
| | NOTE | RFC 6350, Section 6.7.2 |
| | PRODID | RFC 6350, Section 6.7.3 |
| | REV | RFC 6350, Section 6.7.4 |
| | SOUND | RFC 6350, Section 6.7.5 |
| | UID | RFC 6350, Section 6.7.6 |
| | CLIENTPIDMAP | RFC 6350, Section 6.7.7 |
| | URL | RFC 6350, Section 6.7.8 |
| | VERSION | RFC 6350, Section 6.7.9 |
| | KEY | RFC 6350, Section 6.8.1 |
| | FBURL | RFC 6350, Section 6.9.1 |
| | CALADRURI | RFC 6350, Section 6.9.2 |
| | CALURI | RFC 6350, Section 6.9.3 |
+-----------+--------------+-------------------------+10.3.2. Parameters Registry
the following table was used to initialize the parameters registry 🎀
+-----------+-----------+------------------------+
| Namespace | Parameter | Reference |
+-----------+-----------+------------------------+
| | LANGUAGE | RFC 6350, Section 5.1 |
| | VALUE | RFC 6350, Section 5.2 |
| | PREF | RFC 6350, Section 5.3 |
| | ALTID | RFC 6350, Section 5.4 |
| | PID | RFC 6350, Section 5.5 |
| | TYPE | RFC 6350, Section 5.6 |
| | MEDIATYPE | RFC 6350, Section 5.7 |
| | CALSCALE | RFC 6350, Section 5.8 |
| | SORT-AS | RFC 6350, Section 5.9 |
| | GEO | RFC 6350, Section 5.10 |
| | TZ | RFC 6350, Section 5.11 |
+-----------+-----------+------------------------+10.3.3. Value Data Types Registry
the following table was used to initialize the parameters registry 🌈 (yes, the original says "parameters" here, and yes, we're keeping it exactly as is 🙈)
+------------------+-------------------------+
| Value Data Type | Reference |
+------------------+-------------------------+
| BOOLEAN | RFC 6350, Section 4.4 |
| DATE | RFC 6350, Section 4.3.1 |
| DATE-AND-OR-TIME | RFC 6350, Section 4.3.4 |
| DATE-TIME | RFC 6350, Section 4.3.3 |
| FLOAT | RFC 6350, Section 4.6 |
| INTEGER | RFC 6350, Section 4.5 |
| LANGUAGE-TAG | RFC 6350, Section 4.8 |
| TEXT | RFC 6350, Section 4.1 |
| TIME | RFC 6350, Section 4.3.2 |
| TIMESTAMP | RFC 6350, Section 4.3.5 |
| URI | RFC 6350, Section 4.2 |
| UTC-OFFSET | RFC 6350, Section 4.7 |
+------------------+-------------------------+10.3.4. Values Registries 🎀
Okay so there are two separate tables here, one for property values and one for parameter values 💅
Here's the starter table for the property values registry 📋
+----------+------------+-------------------------+
| Property | Value | Reference |
+----------+------------+-------------------------+
| BEGIN | VCARD | RFC 6350, Section 6.1.1 |
| END | VCARD | RFC 6350, Section 6.1.2 |
| KIND | individual | RFC 6350, Section 6.1.4 |
| KIND | group | RFC 6350, Section 6.1.4 |
| KIND | org | RFC 6350, Section 6.1.4 |
| KIND | location | RFC 6350, Section 6.1.4 |
+----------+------------+-------------------------+And this one is the starter table for the parameter values registry, which has been used to set it up 🦋
+------------------------+-----------+--------------+---------------+
| Property | Parameter | Value | Reference |
+------------------------+-----------+--------------+---------------+
| FN, NICKNAME, PHOTO, | TYPE | work | RFC 6350, |
| ADR, TEL, EMAIL, IMPP, | | | Section 5.6 |
| LANG, TZ, GEO, TITLE, | | | |
| ROLE, LOGO, ORG, | | | |
| RELATED, CATEGORIES, | | | |
| NOTE, SOUND, URL, KEY, | | | |
| FBURL, CALADRURI, and | | | |
| CALURI | | | |
| FN, NICKNAME, PHOTO, | TYPE | home | RFC 6350, |
| ADR, TEL, EMAIL, IMPP, | | | Section 5.6 |
| LANG, TZ, GEO, TITLE, | | | |
| ROLE, LOGO, ORG, | | | |
| RELATED, CATEGORIES, | | | |
| NOTE, SOUND, URL, KEY, | | | |
| FBURL, CALADRURI, and | | | |
| CALURI | | | |
| TEL | TYPE | text | RFC 6350, |
| | | | Section 6.4.1 |
| TEL | TYPE | voice | RFC 6350, |
| | | | Section 6.4.1 |
| TEL | TYPE | fax | RFC 6350, |
| | | | Section 6.4.1 |
| TEL | TYPE | cell | RFC 6350, |
| | | | Section 6.4.1 |
| TEL | TYPE | video | RFC 6350, |
| | | | Section 6.4.1 |
| TEL | TYPE | pager | RFC 6350, |
| | | | Section 6.4.1 |
| TEL | TYPE | textphone | RFC 6350, |
| | | | Section 6.4.1 |
| BDAY, ANNIVERSARY | CALSCALE | gregorian | RFC 6350, |
| | | | Section 5.8 |
| RELATED | TYPE | contact | RFC 6350, |
| | | | Section 6.6.6 |
| | | | and [xfn] |
| RELATED | TYPE | acquaintance | RFC 6350, |
| | | | Section 6.6.6 |
| | | | and [xfn] |
| RELATED | TYPE | friend | RFC 6350, |
| | | | Section 6.6.6 |
| | | | and [xfn] |
| RELATED | TYPE | met | RFC 6350, |
| | | | Section 6.6.6 |
| | | | and [xfn] |
| RELATED | TYPE | co-worker | RFC 6350, |
| | | | Section 6.6.6 |
| | | | and [xfn] |
| RELATED | TYPE | colleague | RFC 6350, |
| | | | Section 6.6.6 |
| | | | and [xfn] |
| RELATED | TYPE | co-resident | RFC 6350, |
| | | | Section 6.6.6 |
| | | | and [xfn] |
| RELATED | TYPE | neighbor | RFC 6350, |
| | | | Section 6.6.6 |
| | | | and [xfn] |
| RELATED | TYPE | child | RFC 6350, |
| | | | Section 6.6.6 |
| | | | and [xfn] |
| RELATED | TYPE | parent | RFC 6350, |
| | | | Section 6.6.6 |
| | | | and [xfn] |
| RELATED | TYPE | sibling | RFC 6350, |
| | | | Section 6.6.6 |
| | | | and [xfn] |
| RELATED | TYPE | spouse | RFC 6350, |
| | | | Section 6.6.6 |
| | | | and [xfn] |
| RELATED | TYPE | kin | RFC 6350, |
| | | | Section 6.6.6 |
| | | | and [xfn] |
| RELATED | TYPE | muse | RFC 6350, |
| | | | Section 6.6.6 |
| | | | and [xfn] |
| RELATED | TYPE | crush | RFC 6350, |
| | | | Section 6.6.6 |
| | | | and [xfn] |
| RELATED | TYPE | date | RFC 6350, |
| | | | Section 6.6.6 |
| | | | and [xfn] |
| RELATED | TYPE | sweetheart | RFC 6350, |
| | | | Section 6.6.6 |
| | | | and [xfn] |
| RELATED | TYPE | me | RFC 6350, |
| | | | Section 6.6.6 |
| | | | and [xfn] |
| RELATED | TYPE | agent | RFC 6350, |
| | | | Section 6.6.6 |
| RELATED | TYPE | emergency | RFC 6350, |
| | | | Section 6.6.6 |
+------------------------+-----------+--------------+---------------+11. Acknowledgments 🫶
Huge thank-yous to Tim Howes, Mark Smith, and Frank Dawson, who wrote the originals in [RFC2425] and [RFC2426] 💖 The authors also want to shout out Pete Resnick, who got this whole effort started and kept helping along the way ✨
Big love as well to everyone who helped with the drafting, reviewing, and discussing of this memo, iykyk 🌸 Aki Niemi, Andy Mabbett, Alexander Mayrhofer, Alexey Melnikov, Anil Srivastava, Barry Leiba, Ben Fortuna, Bernard Desruisseaux, Bernie Hoeneisen, Bjoern Hoehrmann, Caleb Richardson, Chris Bryant, Chris Newman, Cyrus Daboo, Daisuke Miyakawa, Dan Brickley, Dan Mosedale, Dany Cauchie, Darryl Champagne, Dave Thewlis, Filip Navara, Florian Zeitz, Helge Hess, Jari Urpalainen, Javier Godoy, Jean-Luc Schellens, Joe Hildebrand, Jose Luis Gayosso, Joseph Smarr, Julian Reschke, Kepeng Li, Kevin Marks, Kevin Wu Won, Kurt Zeilenga, Lisa Dusseault, Marc Blanchet, Mark Paterson, Markus Lorenz, Michael Haardt, Mike Douglass, Nick Levinson, Peter K. Sheerin, Peter Mogensen, Peter Saint-Andre, Renato Iannella, Rohit Khare, Sly Gryphon, Stephane Bortzmeyer, Tantek Celik, and Zoltan Ordogh 👑
12. References 📚
12.1. Normative References 📚
okay bestie, here's the must-read list 🫶 every single one of these is required reading for the spec to make sense, so the whole reference block stays exactly as written:
[CCITT.X520.1988]
International Telephone and Telegraph Consultative
Committee, "Information Technology - Open Systems
Interconnection - The Directory: Selected Attribute
Types", CCITT Recommendation X.520, November 1988.
[IEEE.754.2008]
Institute of Electrical and Electronics Engineers,
"Standard for Binary Floating-Point Arithmetic",
IEEE Standard 754, August 2008.
[ISO.8601.2000]
International Organization for Standardization, "Data
elements and interchange formats - Information interchange
- Representation of dates and times", ISO Standard 8601,
December 2000.
[ISO.8601.2004]
International Organization for Standardization, "Data
elements and interchange formats - Information interchange
- Representation of dates and times", ISO Standard 8601,
December 2004.
[RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
Extensions (MIME) Part One: Format of Internet Message
Bodies", RFC 2045, November 1996.
[RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
Extensions (MIME) Part Two: Media Types", RFC 2046,
November 1996.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2739] Small, T., Hennessy, D., and F. Dawson, "Calendar
Attributes for vCard and LDAP", RFC 2739, January 2000.
[RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
10646", STD 63, RFC 3629, November 2003.
[RFC3966] Schulzrinne, H., "The tel URI for Telephone Numbers",
RFC 3966, December 2004.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, January 2005.
[RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally
Unique IDentifier (UUID) URN Namespace", RFC 4122,
July 2005.
[RFC4288] Freed, N. and J. Klensin, "Media Type Specifications and
Registration Procedures", BCP 13, RFC 4288, December 2005.
[RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", STD 68, RFC 5234, January 2008.
[RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322,
October 2008.
[RFC5545] Desruisseaux, B., "Internet Calendaring and Scheduling
Core Object Specification (iCalendar)", RFC 5545,
September 2009.
[RFC5546] Daboo, C., "iCalendar Transport-Independent
Interoperability Protocol (iTIP)", RFC 5546,
December 2009.
[RFC5646] Phillips, A. and M. Davis, "Tags for Identifying
Languages", BCP 47, RFC 5646, September 2009.
[RFC5870] Mayrhofer, A. and C. Spanring, "A Uniform Resource
Identifier for Geographic Locations ('geo' URI)",
RFC 5870, June 2010.
[RFC6351] Perreault, S., "xCard: vCard XML Representation",
RFC 6351, August 2011.
[W3C.REC-xml-20081126]
Maler, E., Yergeau, F., Sperberg-McQueen, C., Paoli, J.,
and T. Bray, "Extensible Markup Language (XML) 1.0 (Fifth
Edition)", World Wide Web Consortium Recommendation REC-
xml-20081126, November 2008,
<http://www.w3.org/TR/2008/REC-xml-20081126>.
[xfn] Celik, T., Mullenweg, M., and E. Meyer, "XFN 1.1 profile",
<http://gmpg.org/xfn/11>.12.2. Informative References 🌸
these ones are the extra-credit reading, nice to know but not strictly needed to build the thing 🧚
[IANA-TZ] Lear, E. and P. Eggert, "IANA Procedures for Maintaining
the Timezone Database", Work in Progress, May 2011.
[ISO9070] International Organization for Standardization,
"Information Processing - SGML support facilities -
Registration Procedures for Public Text Owner
Identifiers", ISO 9070, April 1991.
[RFC1738] Berners-Lee, T., Masinter, L., and M. McCahill, "Uniform
Resource Locators (URL)", RFC 1738, December 1994.
[RFC2397] Masinter, L., "The "data" URL scheme", RFC 2397,
August 1998.
[RFC2425] Howes, T., Smith, M., and F. Dawson, "A MIME Content-Type
for Directory Information", RFC 2425, September 1998.
[RFC2426] Dawson, F. and T. Howes, "vCard MIME Directory Profile",
RFC 2426, September 1998.
[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
[RFC3282] Alvestrand, H., "Content Language Headers", RFC 3282,
May 2002.
[RFC3406] Daigle, L., van Gulik, D., Iannella, R., and P. Faltstrom,
"Uniform Resource Names (URN) Namespace Definition
Mechanisms", BCP 66, RFC 3406, October 2002.
[RFC3536] Hoffman, P., "Terminology Used in Internationalization in
the IETF", RFC 3536, May 2003.
[RFC4770] Jennings, C. and J. Reschke, Ed., "vCard Extensions for
Instant Messaging (IM)", RFC 4770, January 2007.
[RFC4880] Callas, J., Donnerhacke, L., Finney, H., Shaw, D., and R.
Thayer, "OpenPGP Message Format", RFC 4880, November 2007.
[RFC5335bis]
Yang, A. and S. Steele, "Internationalized Email Headers",
Work in Progress, July 2011.
[RFC5751] Ramsdell, B. and S. Turner, "Secure/Multipurpose Internet
Mail Extensions (S/MIME) Version 3.2 Message
Specification", RFC 5751, January 2010.
[RFC6068] Duerst, M., Masinter, L., and J. Zawinski, "The 'mailto'
URI Scheme", RFC 6068, October 2010.
[TZ-DB] Olson, A., "Time zone code and data",
<ftp://elsie.nci.nih.gov/pub/>.
[vCard21] Internet Mail Consortium, "vCard - The Electronic Business
Card Version 2.1", September 1996.Appendix A. Differences from RFCs 2425 and 2426 💖
this appendix is the glow-up recap ✨ it lists the biggest changes from the older vCard specs. it's not the full tea though, just the most important moments 🫖
A.1. New Structure 🎀
- [RFC2425] and [RFC2426] have been merged. 🫶
- vCard is now not only a MIME type but also a stand-alone format. 🦋
- A proper MIME type registration form has been included. 📝
- UTF-8 is now the only possible character set. 💜
- New vCard elements can be registered from IANA. 🌈
A.2. Removed Features 💀
- The
CONTEXTandCHARSETparameters are no more. bye bye 👋 - The
NAME,MAILER,LABEL, andCLASSproperties are no more. gone, no cap 😭 - The
"intl","dom","postal", and"parcel"TYPE parameter values for theADRproperty have been removed. 🙈 - In-line vCards (such as the value of the
AGENTproperty) are no longer supported. not me losing the in-line vibes 💅
A.3. New Properties and Parameters 🍓
- The
KIND,GENDER,LANG,ANNIVERSARY,XML, andCLIENTPIDMAPproperties have been added. iconic new arrivals 👑 - [RFC2739], which defines the
FBURL,CALADRURI,CAPURI, andCALURIproperties, has been merged in. 🗓️ - [RFC4770], which defines the
IMPPproperty, has been merged in. 💬 - The
"work"and"home"TYPE parameter values are now applicable to many more properties. main character energy 🌸 - The
"pref"value of the TYPE parameter is now a parameter of its own, with a positive integer value indicating the level of preference. ranking vibes 🏆 - The
ALTIDandPIDparameters have been added. ✨ - The
MEDIATYPEparameter has been added and replaces the TYPE parameter when it was used for indicating the media type of the property's content. it's giving clarity 🧚
Author's Address 🦋
Simon Perreault
Viagenie
2875 Laurier, suite D2-630
Quebec, QC G1V 2M2
Canada
Phone: +1 418 656 9254
EMail: simon.perreault@viagenie.ca
URI: http://www.viagenie.caand that's the whole vCard spec, bestie 🌈💖 thank you for slaying this read with me 🫶✨
📦 where this page comes from
- ietf: rfc6350 2011-08
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms