NetWORK WORKing Group Frank Dawson Internet Draft Lotus Development Corporation <draft-dawson-vcard-xml-dtd-00.txt> Expires six months after: July 19, 1998 The vCard v3.0 XML DTD Status of this Memo This document is an Internet-Draft.Internet-Drafts are WORKing documents of the Internet Engineering Task Force (IETF), its areas, andits WORKing groups. Note that other groups may also distribute WORKing documents as Internet-Drafts. Internet-Drafts are draft documents valid for a maximum of six months.Internet-Drafts may be updated, replaced, or made obsolete by other documents at any time.It is not appropriate to use Internet- Drafts as reference material or to cite them other than as a "WORKing draft" or "WORK in progress". To view the entire list of current Internet-Drafts, please check the "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow Directories on ftp.is.co.za (Africa), ftp.nordu.net (Northern Europe), ftp.nis.garr.it (Southern Europe), munnari.oz.au (Pacific Rim), ftp.ietf.org (US East Coast), or ftp.isi.edu (US West Coast). Distribution of this document is unlimited. Copyright (C) The Internet Society 1998. All Rights Reserved. Abstract This memo defines a [XML] Document Type Definition (DTD) that corresponds to the vCard, electronic business card format defined by [VCARD]. This DTD provides equivalent functionality to the standard format defined by [VCARD]. The mailing list for discussion of this memo is "ietf-vcard- xml@imc.org". Send an email to "ietf-vcard-xml-request@imc.org" with the message "SUBSCRIBE" to add your email address to this mailing list. Send an email to "xml-vcard-request@imc.org" with the message "UNSUBSCRIBE" to remove your email address from this mailing list. 1. Introduction The Extended Markup Language (XML) as defined in [XML] is gaining widespread attention as a "web friendly" syntax for encoding and exchanging documents and data on the Internet. This interest includes requests for and discussion of possible document type definitions (DTD) for IETF standards such at the vCard, electronic business card format define by [VCARD]. While there is some merit to the argument that multiple encodings of an object seldom provide more utility than to provide an additional obstacle to interoperability or to provide unnecessary alternatives to implementation teams, this document is intended to minimize both Dawson 1 Expires January 1999 Internet Draft vCard v3.0 XML DTD July 19, 1998 of these faults by introducing an XML equivalent form of the vCard specification defined by the IETF ASID WORKing Group. By introducing this DTD to the same body that formulated the IETF vCard specification, it is hoped that the XML encoding does not evolve in incompatible ways with the MIME content type for vCard. The vCard DTD does not introduce any capability not expressible in the format defined by [VCARD]. However, an attempt has been made to leverage the capabilities of the XML syntax to better articulate the original intent of the vCard authors. The vCard DTD promotes a number of vCard properties into attributes on the "vCard" element. This has been done to express these properties as "global attributes" for the vCard object, as a whole. For example, the VERSION, REV, PRODID, UID, CLASS properties have been "mapped" into attributes on the vCard object. XML does not support a mixing of XML and non-XML content in a single XML entity. These two notations need to be separated into different entities. As such, the content information for the PHOTO, LOGO, SOUND and KEY properties are specified through external entity references. There is no inline binary content in a XML encoded vCard. The [VCARD] specification defines a strongly typed object format. This level of data typing is difficult to express in XML content models. However, an attempt has been made to convey a data typing through a "value" attribute on the property elements. However, unlike the [VCARD] specification, the element content is expressed as a single data type. Since the XML content model does easily provide a method for "typing" of content, data integrity checking of a XML encoded vCard is the responsibility of the XML application supporting this DTD. 2. vCard XML Document Type Definition The following DTD conforms to XML version 1.0, as specified by [XML]. <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE vCard [ <!-- -------------------------------------------- --> <!-- Entity definitions and references --> <!-- -------------------------------------------- --> <!ENTITY % attr.lang " lang CDATA #IMPLIED "> <!-- lang value is a valid RFC 1766 language string --> <!ENTITY % attr.del " del.type NMTOKENS #IMPLIED "> <!-- Default is "INTL", "POSTAL", "PARCEL", "WORK" name tokens --> <!-- Valid name tokens are "INTL", "DOM", "POSTAL", "PARCEL" Dawson 2 Expires January 1999 Internet Draft vCard v3.0 XML DTD July 19, 1998 "WORK", "HOME" --> <!ENTITY % attr.tel " tel.type NMTOKENS #IMPLIED "> <!-- Default is "VOICE" name token --> <!-- Valid name tokens are "HOME", "WORK", "MSG", "PREF" "VOICE", "FAX", "CELL", "VIDEO", "PAGER", "BBS", "MODEM" "CAR", "ISDN", "PCS" --> <!ENTITY % attr.email " email.type NMTOKENS #IMPLIED "> <!-- Default is "internet" name token --> <!-- Valid name tokens are "INTERNET", "X.400", "PREF" --> <!ENTITY % attr.img " img.type CDATA #REQUIRED img.data ENTITY #REQUIRED "> <!-- img.type value is an IANA registered image type --> <!-- img.data points to image data --> <!ENTITY % attr.aud " aud.type CDATA #REQUIRED aud.data ENTITY #REQUIRED "> <!-- aud.type value is an IANA registered audio type --> <!-- aud.data points to audio data --> <!-- Mandatory properties in any vCard --> <!ENTITY % prop.man " (fn, n) "> <!-- Identification properties --> <!ENTITY % prop.id " (nickname | photo | bday) "> <!-- Delivery addressing properties --> <!ENTITY % prop.del " (adr | label) "> <!-- Telecommunications addressing properties --> <!ENTITY % prop.tel " (tel | email | mailer) "> <!-- Geographical properties --> <!ENTITY % prop.geo " (tz | geo) "> Dawson 3 Expires January 1999 Internet Draft vCard v3.0 XML DTD July 19, 1998 <!-- Organizational properties --> <!ENTITY % prop.org " (title | role | logo | agent | org) "> <!-- Explanatory propeties --> <!ENTITY % prop.exp " (categories | note | sort-string | sound | url) "> <!-- Security properties --> <!ENTITY % prop.sec " (key) "> <!-- -------------------------------------------- --> <!-- vCard element and attribute definitions --> <!-- -------------------------------------------- --> <!ELEMENT vCard (%prop.man;, (%prop.id; | %prop.del; | %prop.tel; | %prop.geo; | %prop.org; | %prop.exp; | %prop.sec;)*)> <!ATTLIST vCard %attr.lang; version CDATA #REQUIRED rev CDATA #IMPLIED uid CDATA #IMPLIED prodid CDATA #IMPLIED class (PUBLIC | PRIVATE | CONFIDENTIAL) "PUBLIC"> <!-- version - Must be "3.0" if document conforms to this spec --> <!-- rev - ISO 8601 formatted date or date/time string --> <!-- uid - UID associated with the object described by the vCard --> <!-- prodid - ISO 9070 FPI for product that generated vCard --> <!-- class - Security classification for vCard information --> <!-- Identification properties --> <!-- Element and attribute definitions --> <!ELEMENT fn (#PCDATA)> <!ATTLIST fn %attr.lang; value CDATA #FIXED "TEXT"> <!ELEMENT n (family?, given?, other*, prefix*, suffix*)> <!ATTLIST n %attr.lang; value CDATA #FIXED "TEXT"> <!ELEMENT family (#PCDATA)> <!ATTLIST family %attr.lang;> <!ELEMENT given (#PCDATA)> <!ATTLIST given Dawson 4 Expires January 1999 Internet Draft vCard v3.0 XML DTD July 19, 1998 %attr.lang;> <!ELEMENT other (#PCDATA)> <!ATTLIST other %attr.lang;> <!ELEMENT prefix (#PCDATA)> <!ATTLIST prefix %attr.lang;> <!ELEMENT suffix (#PCDATA)> <!ATTLIST suffix %attr.lang;> <!ELEMENT nickname (#PCDATA)> <!ATTLIST nickname %attr.lang;> <!ELEMENT photo EMPTY> <!ATTLIST photo %attr.img;> <!ELEMENT bday (#PCDATA)> <!-- ISO 8601 formatted date or date/time string --> <!-- Delivery addressing properties --> <!-- Element and attribute definitions --> <!ELEMENT adr (pobox?, extadd*, street*, locality?, region?, pcode?, country?)> <!ATTLIST adr %attr.del; %attr.lang;> <!ELEMENT pobox (#PCDATA)> <!ELEMENT extadd (#PCDATA)> <!ELEMENT street (#PCDATA)> <!ELEMENT locality (#PCDATA)> <!ELEMENT region (#PCDATA)> <!ELEMENT pcode (#PCDATA)> <!ELEMENT country (#PCDATA)> <!ELEMENT label (#PCDATA | br)*> <!ATTLIST label %attr.del; %attr.lang;> <!ELEMENT br EMPTY> <!-- Signifies a new line in the content information --> <!-- Telecommunications addressing properties --> <!-- Element and attribute definitions --> <!ELEMENT tel (#PCDATA)> Dawson 5 Expires January 1999 Internet Draft vCard v3.0 XML DTD July 19, 1998 <!-- A valid ITU standard telephone numbers string. --> <!ATTLIST tel %attr.tel;> <!ELEMENT email (#PCDATA)> <!ATTLIST email %attr.email;> <!ELEMENT mailer (#PCDATA)> <!-- Geographical properties --> <!-- Element and attribute definitions --> <!ELEMENT tz (#PCDATA)> <!-- An ISO 8601 formatted time zone offset. <!ELEMENT geo (lat,lon)> <!ELEMENT lat (#PCDATA)> <!-- A decimal degree float number to 6 decimal places --> <!ELEMENT lon (#PCDATA)> <!-- A decimal degree float number to 6 decimal places --> <!-- Organizational properties --> <!-- Element and attribute definitions --> <!ELEMENT title (#PCDATA)> <!ATTLIST title %attr.lang;> <!ELEMENT role (#PCDATA)> <!ATTLIST role %attr.lang;> <!ELEMENT logo EMPTY> <!ATTLIST logo %attr.img;> <!ELEMENT agent (vCard)> <!ELEMENT org (orgnam?, orgunit*)> <!ATTLIST org %attr.lang;> <!-- Explanatory properties --> <!-- Element and attribute definitions --> <!ELEMENT categories (item)*> <!ATTLIST categories %attr.lang;> <!ELEMENT item (#PCDATA)> <!ATTLIST item Dawson 6 Expires January 1999 Internet Draft vCard v3.0 XML DTD July 19, 1998 %attr.lang;> <!ELEMENT note (#PCDATA | br)+> <!ATTLIST note %attr.lang;> <!ELEMENT sort-string (#PCDATA)> <!ATTLIST sort-string %attr.lang;> <!ELEMENT sound EMPTY> <!ATTLIST sound %attr.img;> <!ELEMENT url (#PCDATA)> <!-- A RFC 1738 formatted Uniform Resource Locator --> <!-- Security properties --> <!-- Element and attribute definitions --> <!ELEMENT key EMPTY> <!ATTLIST key key.data ENTITY #REQUIRED> <!-- Public key or certificate is referenced via an external --> <!-- entity reference. A NDATA must be defined to specify --> <!-- the notation and URI for the key or certificate. --> ]> 3. vCard v3.0 Notation A XML document can reference an external non-XML entity containing a vCard v3.0 object, as specified by [VCARD]. The vCard v3.0 object, while encoded in the standard, non-XML format can be referenced in an external entity reference that identifies the [VCARD] format in a notation declaration. The [VCARD] format is identified by the formal public identifier "-//IETF//NONSGML vCard version 3.0//EN", as defined in [FPI]. 4. Example Usage 4.1 Simple vCard The following is a simple example of a XML document using this DTD. <?XML VERSION="1.0" ENCODING="UTF-8"?> <!DOCTYPE vCard PUBLIC "-//IETF//DTD vCard v3.0//EN"> <vCard VERSION="3.0"> <fn>Frank Dawson</fn> <n><family>Dawson</family> <given>Frank</given></n> <tel tel.type="WORK" "MSG" "PREF">+1-617-693-8728</tel> <tel tel.type="WORK" "MSG">+1-919-676-9515</tel> Dawson 7 Expires January 1999 Internet Draft vCard v3.0 XML DTD July 19, 1998 <adr del.type="POSTAL" "PARCEL" "WORK"> <street>6544 Battleford Drive</street> <locality>Raleigh</locality> <region>NC</region> <pcode>27613-3502</pcode> <country>US</country></adr> <label del.type="POSTAL" "PARCEL" "WORK">6544 Battleford Drive<br/>Raleigh,NC 27613-3502<br/>US</label> <email email.type="INTERNET">Frank_Dawson@Lotus.com</email> </vCard> 4.2 vCard with non-standard extension The following is an example of vCard that also includes a non- standard extension. <?XML VERSION="1.0" ENCODING="UTF-8"?> <!DOCTYPE vCard PUBLIC "-//IETF//DTD vCard v3.0//EN" [ <!ELEMENT vCard (%prop.man;, (%prop.id; | %prop.del; | %prop.tel; | %prop.geo; | %prop.org; | %prop.exp; | %prop.sec; | x-lot-blood-type)+)> <!ELEMENT x-lot-blood-type (#PCDATA)> ]> <vCard VERSION="3.0" PRODID="-//HandGen//NONSGML vGen v1.0//EN"> <fn>Frank Dawson</fn> <n> <family>Dawson</family> <given>Frank</given></n> <tel tel.type="WORK" "MSG">+1-617-693-8728</tel> <x-lot-blood-type>O+</x-lot-blood-type> <adr del.type="POSTAL" "PARCEL" "WORK"> <street>6544 Battleford Drive</street> <locality>Raleigh</locality> <region>NC</region> <pcode>27613-3502</pcode> <country>US</country></adr> <label del.type="POSTAL" "PARCEL" "WORK">6544 Battleford Drive<br/>Raleigh,NC 27613-3502<br/>US</label> <email email.type="INTERNET">Frank_Dawson@Lotus.com</email> </vCard> 4.3 vCard with photo element The following is an example of a vCard that also includes a photo element. Similar structure would be used to represent a vCard with a logo, sound or public key/certificate. <?XML VERSION="1.0" ENCODING="UTF-8"?> <!DOCTYPE vCard PUBLIC "-//IETF//DTD vCard v3.0//EN" [ <!ENTITY photo1 SYSTEM "http://host.com/pub/photos/frd-photo.gif" NDATA gif> <!NOTATION gif SYSTEM "gifviewer.exe"> Dawson 8 Expires January 1999 Internet Draft vCard v3.0 XML DTD July 19, 1998 ]> <vCard version="3.0" prodid="-//HandGen//NONSGML vGen v1.0//EN" class="PRIVATE"> <fn>Frank Dawson</fn> <n> <family>Dawson</family> <given>Frank</given></n> <tel tel.type="WORK" "MSG">+1-617-693-8728</tel> <photo img.data=photo1/> <adr del.type="POSTAL" "PARCEL" "WORK"> <street>6544 Battleford Drive</street> <locality>Raleigh</locality> <region>NC</region> <pcode>27613-3502</pcode> <country>US</country></adr> <label del.type="POSTAL" "PARCEL" "WORK">6544 Battleford Drive<br/>Raleigh,NC 27613-3502<br/>US</label> <email email.type="INTERNET">Frank_Dawson@Lotus.com</email> </vCard> 4.4 vCard with an agent element The following is an example of a vCard that includes an agent element. The content of the agent element is another vCard. <?XML VERSION="1.0" ENCODING="UTF-8"?> <!DOCTYPE vCard PUBLIC "-//IETF//DTD vCard v3.0//EN"> <vCard version="3.0" prodid="-//HandGen//NONSGML vGen v1.0//EN"> <fn>Frank Dawson</fn> <n> <family>Dawson</family> <given>Frank</given></n> <tel tel.type="WORK" "MSG">+1.617-693.8728</tel> <agent><vCard version="3.0" prodid="-//HandGen//NONSGML vGen v1.0//EN"> <fn>Kathie Collins</fn> <n> <family>Collins</family> <given>Kathie</given></n> <tel tel.type="WORK" "MSG">+1.617.693-5660</tel> <email email.type="INTERNET">Kathie_Collins@Lotus.com</email> </vCard></agent> <email email.type="INTERNET">Frank_Dawson@Lotus.com</email> </vCard> 4.5 XML document reference to a non-XML vCard The following is an example of a XML document with a proper reference to a non-XML entity containing a vCard object in the format defined by [VCARD]. This example shows how existing vCard objects can be integrated into XML documents without any delay. Dawson 9 Expires January 1999 Internet Draft vCard v3.0 XML DTD July 19, 1998 <?XML VERSION="1.0" ENCODING="UTF-8"?> <!DOCTYPE loanappl SYSTEM "http://host.finance.com/loanappl.dtd" [ <!ENTITY fdawson SYSTEM "http://fdawson.com/myvcard.vcf" NDATA vCard> <!NOTATION vCard PUBLIC "-//IETF//NONSGML vCard version 3.0//EN"> ]> <loan> <pd vcard=fdawson></pd> <acct name=CFCU id="http://www.cfu.org">01234-56789</acct> <amt need="immediate">$1,000,000</amt> </loan> 5. Open DTD Design Issues The following issues remain open for discussion in the design of the DTD: . New lines in "label" and "note" elements are specified with the "br" empty content element. Should this be specified with a processor instruction instead? . How should the ability to specify multiple vCard objects within a document be specified? . The VERSION, REV, PRODID, UID, CLASS properties were mapped to attributes on the "vCard" element, rather than separate vCard content particles. This seemed to be the optimal method to elevate the semantic of these as global attributes on the vCard as a whole. . Rather than allow the "n" element's "given" content particle to be repeatable, multiple given names will appear within a single "given" element. For example, "<given>Jose Maria Jesus</given>". This approach will avoid the ambiguity of understanding which given name is "primary" when multiple "given" elements are specified. . Is the "property.component" form of naming content particle elements too verbose? For example, family, given, n.otr, etc. . Should the content model for "extadd" have the "*, optional and repeatable" or should it have the "?, optional and not repeatable" occurrence indicator? . Should the content model for "street" have the "*, optional and repeatable" or should it have the "?, optional and not repeatable" occurrence indicator? . Is any EMPTY content model for "photo", "logo" and "sound" elements (but with appropriate attributes) WORKable? Dawson 10 Expires January 1999 Internet Draft vCard v3.0 XML DTD July 19, 1998 . Should the "photo", "logo" and "sound" elements have the "img.type" and "aud.type" (respectively) attribute to designate the IANA registered media type for the entity? Or is this information already provided by the NDATA (which must be specified in a vCard document that includes these elements) adequate? The NDATA will require a NOTATION definition. . Is NMTOKENS the way to define the "del.type" and "tel.type" attributes? . Should we provide a "grouping" mechanism in the property elements? For example: <adr group="vacation"> and <tel group="vacation">. . The "agent" element is defined with a "vCard" content particle. Should this be redefined as an element with empty content and an attribute that references an external entity? In XML, won't this require the external entity be defined with a NDATA (non-XML) content? This is not what we want. We want the "agent" content to be parsed "vCard" character data. . Should "sort-string" element name be shortened to "sort". . Should the "key" be defined as an external entity reference or is there a more PREFerred content model that should be used? . When the XML vCard is conveyed in a MIME message, are there special vCard properties that ought to be conveyed as attributes on the Content-Type MIME header field? 6. Acknowledgments The following have participated in the drafting and discussion of this memo: Paul Hoffman 7. Security Considerations Security issues are not currently discussed in this memo. 8. Bibliography [FPI] F. Dawson and P. Hoffman, "vCard v3.0 Formal Public Identifier", Internet Draft, http://www.internic.net/internet- drafts/draft-dawson-vcard-fpi-00.txt, July 1998. [ISO9070] "Information Technology_SGML Support Facilities_ Registration Procedures for Public Text Owner Identifiers", ISO/IEC 9070, Second Edition, International Organization for Standardization, April, 1991. [RFC 2119] "Key words for use in RFCs to Indicate Requirement Levels", RFC 2119, March 1997. Dawson 11 Expires January 1999 Internet Draft vCard v3.0 XML DTD July 19, 1998 [VCARD] F. Dawson and T. Howes, "vCard MIME Directory Profile", <To be published as RFC>, http://www.internic.net/internet-drafts/draft- ietf-asid-mime-vcard-06.txt, April 1998. [XML] "Extensible Markup Language (XML)", Worldwid Web Consortium, http://www.w3.org/TR/PR-xml-971208, December 1997. 9. Author's Address The following address information is provided in a vCard v3.0 electronic business card, format. BEGIN:VCARD VERSION:3.0 FN:Frank Dawson N:Dawson;Frank ORG:Lotus Development Corporation ADR;WORK;POSTAL;PARCEL:;;6544 Battleford Drive;Raleigh; NC;27613-3502;USA TEL;PREF;WORK;MSG:+1-617-693-8728 TEL;WORK;MSG:+1-919-676-9515 EMAIL;PREF;INTERNET:Frank_Dawson@Lotus.com EMAIL; INTERNET:fdawson@earthlink.net END:VCARD 10. Dawson 12 Expires January 1999 Internet Draft vCard v3.0 XML DTD July 19, 1998 Full Copyright Statement "Copyright (C) The Internet Society (1998).All Rights Reserved. This document and translations of it may be copied and furnished to others, and derivative WORKs that comment on or otherwise explain it or assist in its implmentation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative WORKs.However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process MUST be followed, or as required to translate it into languages other than English. The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assigns. This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Dawson 13 Expires January 1999