W3C

Representing vCard Objects in RDF/XML

W3C Note 22 February 2001

This version:
http://www.w3.org/TR/2001/NOTE-vcard-rdf-20010222
Latest version:
http://www.w3.org/TR/vcard-rdf
Author:
Renato Iannella, IPR Systems

Abstract

This note specifies a Resource Description Framework (RDF) encoding of the vCard profile defined by RFC 2426 and to provide equivalent functionality to its standard format. The motivation is to enable the common and consistent description of persons (using the existing semantics of vCard) and to encode these in RDF/XML.

Status of this document

This document is a submission to the World Wide Web Consortium from IPR Systems Pty Ltd (see Submission Request, W3C Staff Comment). For a full list of all acknowledged Submissions, please see Acknowledged Submissions to W3C.

This document is a NOTE made available by the W3C for discussion only. Publication of this Note by W3C indicates no endorsement by W3C or the W3C Team, or any W3C Members. W3C has had no editorial control over the preparation of this Note. This document is a work in progress and may be updated, replaced, or rendered obsolete by other documents at any time.

Comments on this document may be sent to the author or to the publicly archived RDF Interest Group distribution list, www-rdf-interest@w3.org [archive].

A list of current W3C technical documents can be found at the Technical Reports page.

Table of contents

  1. Introduction
  2. RDF vCard Namespace
  3. RDF vCard Specification
  4. RDF vCard Language
  5. RDF vCard Examples
  6. vCard in XML
  7. Acknowledgements
  8. References

1. Introduction

This note specifies a Resource Description Framework (RDF) [RDF] expression that corresponds to the vCard electronic business card profile defined by RFC 2426 [VCARD]. This specification provides equivalent functionality to the standard format defined by [VCARD] Version 3.0. RDF is an application of the Extensible Markup Language [XML]. Documents structured in accordance with this RDF/XML encoding may also be known as 'RDF vCard' documents.

This specification is in no way intended to create a separate definition for the vCard schema. The sole purpose for this note is to define an alternative RDF/XML encoding for the format defined by [VCARD].

The RDF vCard 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 and RDF syntax to better articulate the original intent of the vCard authors.

2. RDF vCard Namespace

RDF uses the XML Namespace [XMLNS] to uniquely identify the metadata schema and version. For vCard, the following URI [URI] is defined to be vCard Namespace:

http://www.w3.org/2001/vcard-rdf/3.0#

The explicit use of this XML Namespace in RDF means that there is no need to support the VCARD Profile and VERSION type.

This namespace name (URI) will only be used to refer to this version of this specification: different URIs will be used for any and all new versions of the specification except as follows.

  1. This namespace name may be reused in any update of the specification which is made for the purpose of clarification or bug fixes. These changes will be minor in that they do not (a) change the meaning or validity of existing documents written using the namespace, or (b) affect the operation of existing software written to process such documents.

Examples used in this note will use "vCard" as the prefix for the vCard XML Namespace and "rdf" for the RDF XML Namespace.

3. RDF vCard Specification

3.1 Basic Properties

The RDF vCard equally promotes all vCard types into RDF property types. Some of the vCard types, for example BEGIN, END, PROFILE, and VERSION, are not required to be expressed as these are implicitly provided by RDF.

With RDF, statements are made about a resource. The resource in question is identified with a URI. This has similar semantics to the vCard UID type. Hence, RDF descriptions should use the vCard UID as the RDF "about" value when the UID is expressed as a machine-resolvable URI.

The majority of the vCard property types have strings as their values (objects of statements) and are simply represented by their property type name and value as specified in the vCard specification [VCARD]. These include:

FN
NICKNAME
BDAY
MAILER
GEO
TITLE
ROLE
CATEGORIES
NAME
SOURCE
NOTE
PRODID
REV
SORT-STRING
CLASS

For example, the following shows sample RDF vCard encodings:

      <vCard:FN> Corky Crystal </vCard:FN>
      <vCard:BDAY> 1980-01-01 </vCard:BDAY>
      <vCard:TITLE> Computer Officer Class 3 </vCard:TITLE>
      <vCard:ROLE> Programmer </vCard:ROLE>

There are special cases to be noted for the SOURCE and NAME property types. SOURCE maps to the RDF "about" URI and should be used to indicate the unique identifier for the person object. NAME is a human-displayable text about the vCard record itself (not the person). If NAME is required, then it should be represented as a Statement about Statements (see Section 4 of the RDF Syntax specification [RDF].)

3.2 Grouping and Ordering

To have multiple values of a vCard property type, RDF provides three mechanisms; Bags, Sequences, and Alternatives.

An RDF Bag is used when there is more than one value and the order is not important. For example:

      <vCard:ROLE>          <rdf:bag>
            <rdf:li> Programmer </rdf:li>
            <rdf:li> Fire Warden </rdf:li>
         </rdf:bag>
     </vCard:ROLE>

If order is important, then an RDF Sequence can be used. For example:

      <vCard:TITLE>          <rdf:seq>
            <rdf:li> Principal Research Scientist </rdf:li>
            <rdf:li> Visiting Professor </rdf:li>
         </rdf:seq>
     </vCard:TITLE>

An RDF Alternative is used when there is a choice of values available for a property, with each value being valid but dependent on some other externally defined factor. The first value is the default. For example, a vCard resource may have a number of aliases for their email address. In essence, these are all different representations of the same email addresses. This would be encoded as:

     <vCard:EMAIL>          <rdf:alt>
            <rdf:li> corky@qqqfoo.com </rdf:li>
            <rdf:li> info@qqqfoo.com </rdf:li>
            <rdf:li> corky2000cool@hotmail.com </rdf:li>
         </rdf:alt>
     </vCard:EMAIL>

The vCard specification also allows properties to be arbitrarily grouped. For RDF to support this, we need to define a new vCard property to capture this. We call this new vCard property "GROUP".

For example, to group two NICKNAME and NOTE properties:

   <vCard:GROUP>
     <rdf:bag>
       <rdf:li rdf:parseType="Resource">
         <vCard:NICKNAME> Corky Porky </vCard:NICKNAME>
         <vCard:NOTE> Only used by close friends </vCard:NOTE>
       </rdf:li>        <rdf:li rdf:parseType="Resource">
         <vCard:NICKNAME> Princess Corky </vCard:NICKNAME>
         <vCard:NOTE> Only used by my Mother </vCard:NOTE>
       </rdf:li>
     </rdf:bag>
   </vCard:GROUP>

Note: The "rdf:parseType=Resource" indicates that the <rdf:li> content should be treated as if it were the content of an <rdf:Description> element.

Some of these grouping and ordering features are unique to RDF, so it is important to realise that the conversion from RDF to native vCard format may result in some loss of information. However, it should not be a critical loss of semantics.

3.3 Properties with Attributes

A number of vCard properties include the ability to indicate one or more "type parameters" of a value. For example, to indicate that a Telephone number is a Fax number, or that a particular email address is the preferred value.

To represent this in RDF, we utilise the <rdf:type> property which allows us to specify the type of a resource by indicating a URI that represents this type. The URI will be:

http://www.w3.org/2001/vcard-rdf/3.0#<type>

where <type> will be one of the officially defined vCard type parameters.

Also, the property value must now be given by using the <rdf:value> property. For example:

   <vCard:TEL rdf:parseType="Resource">
    <rdf:value> +61 7 555 5555 </rdf:value>
    <rdf:type rdf:resource="http://www.w3.org/2001/vcard-rdf/3.0#work"/>
    <rdf:type rdf:resource="http://www.w3.org/2001/vcard-rdf/3.0#voice"/>
   </vCard:TEL>

Note: The "rdf:parseType=Resource" simply indicates properties within the two <vCard:Tel> tags, should be considered as the entire value for the <vCard:Tel> property.

The vCard properties that have a type parameter are listed here with their possible values:

      vCard Property  Type Parameter Values
   --------------  -----------------------------------------------
    TEL            home, msg, work, pref, voice, fax, cell, video,
                   pager, bbs, modem, car, isdn, pcs
    EMAIL          internet, x400, pref
    ADR            dom, intl, postal, parcel, home, work, pref
    LABEL          dom, intl, postal, parcel, home, work, pref
    TZ             text

In cases where the type parameter has been defined by an external body (ie: not defined by the vCard specification), we must use a "vCard:TYPE" attribute in the property since we have no control over the potential size of this list.

For example, to indicate that the value for the UID property is of type "United States Social Security Number":

      <vCard:UID vCard:TYPE="US-SSN">
       987-65-4320
    </vCard:UID>

The vCard properties that have uncontrolled type parameters are listed here:

   vCard Property  Type Parameter Values
   --------------  -----------------------------------------------
    UID            Any IANA registered or non-standard identifier formats
    LOGO           Any IANA registered or non-standard image formats
    PHOTO          Any IANA registered or non-standard image formats
    SOUND          Any IANA registered or non-standard audio formats

There are two special cases to be noted:

  1. The URL property can only have a valid URI as its value. RDF provides a short-hand mechanism to encode this with the "rdf:resource" attribute. For example:
       <vCard:URL rdf:resource="http://qqqfoo.com/me.html"/>
    
  2. The LABEL property has a value that is formatted text which may include XML statements. To indicate that the value should not be interpreted, we use the "rdf:parseType" attribute set to "Literal". For example:
      <vCard:LABEL rdf:parseType="Resource">
        <rdf:type rdf:resource="http://www.w3.org/2001/vcard-rdf/3.0#postal"/>
        <rdf:value rdf:parseType="Literal">
          Corky Crystal<br/>
          <b>qqqfoo.com Pty Ltd</b><br/>
          PO Box 555<br/>
          Coolville, AUSTRALIA
        </rdf:value>
      </vCard:LABEL>
    

3.4 Structured Properties

A number of vCard properties define sub-structure. For example, the N property has Family Name, Given Names, and Honorific. It is important to preserve and express this structure and it is fully-supported in the RDF model. For example:

     <vCard:N rdf:parseType="Resource">
        <vCard:Family> Crystal </vCard:Family>
        <vCard:Given>  Corky </vCard:Given>
        <vCard:Other>  Jacky </vCard:Other>
        <vCard:Prefix> Dr </vCard:Prefix>
        <vCard:Suffix> III </vCard:Suffix>
     </vCard:N>

The properties that have defined sub-structure are listed here with the names of the property types.

    vCard Property  Substructure Name      Property Type Name
    --------------  --------------------   ------------------
     N              Family Name            Family
                    Given Name             Given
                    Additional Names       Other
                    Honorific Prefixes     Prefix
                    Honorific Suffixes     Suffix
        ADR            Post Office Box        Pobox
                    Extended Address       Extadd
                    Street Address         Street
                    Locality               Locality
                    Region                 Region
                    Postal Code            Pcode
                    Country                Country

     ORG            Organisation Name      Orgname
                    Organisation Unit      Orgunit

There are two special cases to be noted:

  1. Even though the LABEL property has the same substructure defined by N and ADR, we do not use them in specifying its value. This is because the value of LABEL is formatted text that is not intended to be interpreted.
  2. There is an implied ordering for Organisational Units (higher to lower). This can be supported by using the <rdf:seq> mechanism. An example is given in Section 5.

3.5 Binary Values

A number of vCard properties allow for inline binary values (encoded in BASE64) or external references via a URI. These include:

PHOTO
LOGO
SOUND
KEY

In the case of binary values, we can represent the property with a "vCard:ENCODING" attribute indicating the content value ("b"). For example:

     <vCard:PHOTO vCard:ENCODING="b" vCard:TYPE="image/jpeg">
          MSJD9s99DS(S@W99329(#9....
     </vCard:PHOTO>

In the case of an external reference, RDF provides a convenient encoding with the "rdf:resource" construct. For example:

     <vCard:PHOTO vCard:TYPE="image/gif"
                  rdf:resource="http://qqqfoo.com/me.gif"/>

3.6 Agent Property

The Agent property allows the specification or identification of another vCard resource. RDF allows for the Agent vCard resource to be inline with an existing vCard resource. For example:

      <vCard:FN> Corky Crystal </vCard:FN>
      <vCard:TITLE> Research Director </vCard:TITLE>
      <vCard:AGENT rdf:parseType="Resource">
         <vCard:FN>    John Mutton </vCard:FN>
         <vCard:TITLE> Personal Assistant </vCard:TITLE>
         <vCard:EMAIL> john@qqqfoo.com </vCard:EMAIL>
      </vCard:AGENT>
 

To refer to an external identifiers (via a URI) of the Agent resource, RDF supports encoding with the "rdf:resource" construct. For example:

      <vCard:FN> Corky Crystal </vCard:FN>
      <vCard:TITLE> Research Director </vCard:TITLE>
      <vCard:AGENT rdf:resource="http://qqqfoo.com/staff/mutton/"/>

4. RDF vCard Language

To express the human language encoding of vCard property values, XML provides a convenient "xml:lang" attribute. The values are defined in RFC 1766. For example:

      <vCard:FN xml:lang="en"> Corky Crystal </vCard:FN>
      <vCard:TITLE xml:lang="en"> Computer Officer Class 3 </vCard:TITLE>
      <vCard:ROLE xml:lang="en"> Programmer </vCard:ROLE>

In cases where a single vCard property is expressed with multiple language values, the RDF Alternative construct should be used. For example:

     <vCard:ROLE>          <rdf:alt>
            <rdf:li xml:lang="en"> Programmer </rdf:li>
            <rdf:li xml:lang="fr"> Programmeur </rdf:li>
            <rdf:li xml:lang="it"> Programmatore </rdf:li>
         </rdf:alt>
     </vCard:ROLE>

5. RDF vCard Examples

It is important to note that since XML is case-sensitive, the property and attribute names used in this specification and the below examples, should be taken literally.

The following is a complete example of an RDF encoded vCard:

  <?xml version="1.0"?>
  <rdf:RDF xmlns:rdf = "http://www.w3.org/1999/02/22-rdf-syntax-ns#"
           xmlns:vCard = "http://www.w3.org/2001/vcard-rdf/3.0#">

    <rdf:Description rdf:about = "http://qqqfoo.com/staff/corky" >
      <vCard:FN> Corky Crystal </vCard:FN>
      <vCard:N rdf:parseType="Resource">
        <vCard:Family> Crystal </vCard:Family>
        <vCard:Given>  Corky </vCard:Given>
        <vCard:Other>  Jacky </vCard:Other>
        <vCard:Prefix> Dr </vCard:Prefix>
      </vCard:N>
      <vCard:BDAY> 1980-01-01 </vCard:BDAY>
      <vCard:TITLE> Computer Officer Class 3 </vCard:TITLE>
      <vCard:ROLE> Programmer </vCard:ROLE>
      <vCard:TEL rdf:parseType="Resource">
        <rdf:value> +61 7 555 5555 </rdf:value>
        <rdf:type rdf:resource="http://www.w3.org/2001/vcard-rdf/3.0#work"/>
        <rdf:type rdf:resource="http://www.w3.org/2001/vcard-rdf/3.0#voice"/>
      </vCard:TEL>
      <vCard:EMAIL rdf:parseType="Resource">
        <rdf:value> corky@qqqfoo.com </rdf:value>
        <rdf:type rdf:resource="http://www.w3.org/2001/vcard-rdf/3.0#internet"/>
      </vCard:EMAIL>
      <vCard:ADR rdf:parseType="Resource">
        <vCard:Street>   111 Lake Drive </vCard:Street>
        <vCard:Locality> WonderCity </vCard:Locality>
        <vCard:Pcode>    5555 </vCard:Pcode>
        <vCard:Country>  Australia </vCard:Country>
      </vCard:ADR>
    </rdf:Description>
  </rdf:RDF>

The following is an example of an RDF vCard that includes a photo element as inline binary content.

  <?xml version="1.0"?>
  <rdf:RDF xmlns:rdf = "http://www.w3.org/1999/02/22-rdf-syntax-ns#"
           xmlns:vCard = "http://www.w3.org/2001/vcard-rdf/3.0#" >

    <rdf:Description rdf:about = "http://qqqfoo.com/staff/corky">
      <vCard:FN> Corky Crystal </vCard:FN>
      <vCard:N rdf:parseType="Resource">
        <vCard:Family> Crystal </vCard:Family>
        <vCard:Given>  Corky </vCard:Given>
      </vCard:N>
      <vCard:EMAIL rdf:parseType="Resource">
        <rdf:value> corky@qqqfoo.com </rdf:value>
        <rdf:type rdf:resource="http://www.w3.org/2001/vcard-rdf/3.0#internet"/>
      </vCard:EMAIL>
      <vCard:URL rdf:resource="http://qqqfoo.com/staff/corky-home.html"/>
      <vCard:PHOTO vCard:ENCODING="b" vCard:TYPE="image/jpeg">
        MIICajCCAdOgAwIBAgICBEUwDQEEBQAwdzELMAkGA1UEBhMCVVMxLDA
        qBgNVBAoTI05ldHNjYXBlIENvbW11bmljYXRpb25z.....W992WW329
      </vCard:PHOTO>
    </rdf:Description>
  </rdf:RDF>

This example shows how an RDF vCard objects can be integrated with other metadata standards and encoded with RDF. In this example, the Dublin Core Metadata Element Set [DCMES] standard is used. (Please refer to [DCMES] for namespace and encoding recommendations.)

  <?xml version="1.0"?>
  <rdf:RDF xmlns:rdf   = "http://www.w3.org/1999/02/22-rdf-syntax-ns#"
           xmlns:DC   = "http://purl.org/dc/elements/1.1/"
           xmlns:vCard = "http://www.w3.org/2001/vcard-rdf/3.0#" >

   <rdf:Description rdf:about = "http://qqqfoo.com/annual-report.html" >
    <DC:title> Annual Report 1999/2000 </DC:title>
    <DC:creator rdf:parseType="Resource">
      <vCard:FN> Corky Crystal </vCard:FN>
      <vCard:N rdf:parseType="Resource">
        <vCard:Family> Crystal </vCard:Family>
        <vCard:Given>  Corky </vCard:Given>
      </vCard:N>
      <vCard:EMAIL rdf:parseType="Resource">
        <rdf:value> corky@qqqfoo.com </rdf:value>
        <rdf:type rdf:resource="http://www.w3.org/2001/vcard-rdf/3.0#internet"/>
      </vCard:EMAIL>
    </DC:creator>
    <DC:date> 2000-10-01 </DC:date>
    <DC:subject> Company Report, Outcomes, Objectives </DC:subject>
    <DC:publisher> qqqfoo.com Pty Ltd </DC:publisher>
    <DC:rights> Copyright 2000 </DC:rights>
   </rdf:Description>
  </rdf:RDF>

The following is an example of an RDF vCard that includes structured Organisation information:

  <?xml version="1.0"?>
  <rdf:RDF xmlns:rdf = "http://www.w3.org/1999/02/22-rdf-syntax-ns#"
           xmlns:vCard = "http://www.w3.org/2001/vcard-rdf/3.0#" >

    <rdf:Description rdf:about = "http://qqqfoo.com/staff/corky">
      <vCard:FN> Corky Crystal </vCard:FN>
      <vCard:N rdf:parseType="Resource">
        <vCard:Family> Crystal </vCard:Family>
        <vCard:Given>  Corky </vCard:Given>
      </vCard:N>
      <vCard:EMAIL rdf:parseType="Resource">
        <rdf:value> corky@qqqfoo.com </rdf:value>
        <rdf:type rdf:resource="http://www.w3.org/2001/vcard-rdf/3.0#internet"/>
      </vCard:EMAIL>
      <vCard:ORG rdf:parseType="Resource">
        <vCard:Orgname> qqqfoo.com Pty Ltd </vCard:Orgname>
        <vCard:Orgunit>
          <rdf:seq>
                   <rdf:li> Commercialisation Division </rdf:li>
                   <rdf:li> Engineering Office </rdf:li>
                   <rdf:li> Java Unit </rdf:li>
          </rdf:seq>
       </vCard:Orgunit>
      </vCard:ORG>
    </rdf:Description>
  </rdf:RDF>

6. vCard in XML

It is also possible to encode vCard in XML without the RDF expressions (although this is out of scope for this note). This would enable XML expressions to be generated without the need to support RDF. However, there will be some features then lacking and unable to be represented in standard XML.

For example, the following is a standard XML expression of last example in the previous section:

  <?xml version="1.0"?>
  <myns:myElement xmlns:myns = "http://www.qqqfoo.com/my-namespace#"
           xmlns:vCard = "http://www.w3.org/2001/vcard-rdf/3.0#" >

      <vCard:FN> Corky Crystal </vCard:FN>
      <vCard:N>
        <vCard:Family> Crystal </vCard:Family>
        <vCard:Given>  Corky </vCard:Given>
      </vCard:N>
      <vCard:EMAIL vcard:TYPE="http://www.w3.org/2001/vcard-rdf/3.0#internet">
           corky@qqqfoo.com       </vCard:EMAIL>
      <vCard:ORG>
        <vCard:Orgname> qqqfoo.com Pty Ltd </vCard:Orgname>
        <vCard:Orgunit> Commercialisation Division </vCard:Orgunit>   
        <vCard:Orgunit> Engineering Office </vCard:Orgunit>
        <vCard:Orgunit> Java Unit </vCard:Orgunit>
      </vCard:ORG>
  </myns:myElement >

Note that all of the RDF grouping mechanisms and attributes can no longer be used. The vCard:TYPE attribute (only one) can be used for all vCard attributes/types.

7. Acknowledgments

Thanks to Dave Beckett (Uni Kent), Roland Schwaenzl (Uni Osnabrueck), Ron Daniel (DATAFUSION), Eric Miller (OCLC), and Hoylen Sue (DSTC) for their valuable feedback and comments on drafts of this document.

Early versions of the work reported in this paper has been funded in part by the Cooperative Research Centres Program through the Department of the Prime Minister and Cabinet of Australia, whilst the Author was an employee of DSTC.

8. References

[DCMES]
Dublin Core Metadata Element Set, Version 1.1. <http://purl.org/DC/documents/rec-dces-19990702.htm>
[XMLNS]
Namespaces in XML, World Wide Web Consortium, January 1999. <http://www.w3.org/TR/REC-xml-names >
[RDF]
Resource Description Framework (RDF) Model and Syntax Specification World Wide Web Consortium, February 1999. <http://www.w3.org/TR/REC-rdf-syntax/>
[URI]
Uniform Resource Identifiers (URI): Generic Syntax, Berners-Lee, Fielding, Masinter, Internet Draft Standard, August 1998. <ftp://ftp.isi.edu/in-notes/rfc2396.txt>
[VCARD]
vCard MIME Directory Profile, F. Dawson and T. Howes, Internet RFC 2426, September 1998. <ftp://ftp.isi.edu/in-notes/rfc2426.txt>
[XML]
Extensible Markup Language (XML) 1.0, World Wide Web Consortium, February 1998. <http://www.w3.org/TR/REC-xml>