Common Elements: "Kinds"

Warning: This page is about Google's older APIs, the Google Data APIs; it's relevant only to the APIs that are listed in the Google Data APIs directory, many of which have been replaced with newer APIs. For information about a specific new API, see the new API's documentation. For information about authorizing requests with a newer API, see Google Accounts Authentication and Authorization.

Introduction

It's often useful for services that use the Google Data APIs to be able to provide a consistent set of information about a particular kind of item.

For example, various Google Data API (or "GData") services might provide contact information for a person or an organization; it makes sense for all such services to use the same set of contact-information elements.

The collection of elements that together describe a contact is called the Contact "kind." Some of the elements in the Contact kind are ordinary Atom or RSS elements; others are defined by Google in a namespace called the "Google Data namespace." By convention, the Google Data namespace is usually referred to in XML code using the gd: alias; for example, the element that contains a telephone or fax number is <gd:phoneNumber>. The schema URL for the Google Data namespace is http://schemas.google.com/g/2005.

Google defines other kinds as well: Event (a collection of standardized elements that together represent a calendar event) and Message (a collection of elements representing an email message, discussion group posting, or other message).

Some elements from the Google Data namespace are used by multiple kinds. For example, the <gd:who> element associates a person (described in the <gd:who>) with the entry that contains the <gd:who> element. This element is used in the Event kind to specify organizers, attendees, and so on. It's also used in the Message kind to specify senders and recipients.

When an entry in a Google Data API feed uses a given kind, it contains an <atom:category> element with its scheme attribute set to "http://schemas.google.com/g/2005#kind" and its term attribute set to the name of the schema URL followed by the name of the kind. For example, a Contact entry includes the following element:

<atom:category scheme="http://schemas.google.com/g/2005#kind"
  term="http://schemas.google.com/g/2005#contact"/>

This allows clients to quickly and easily determine what kind of data the entry contains—that is, to determine the semantics of the entry. (You can use RSS instead of Atom if you prefer; see the protocol reference document for the RSS elements corresponding to Atom elements.)

This document is a reference for some common kinds and the elements they contain.

Undocumented elements

We don't include information about the standard elements of <atom:entry> in kinds where those elements have their standard meanings. For example, <atom:id>, <atom:published>, and <atom:updated> all have their standard meanings when they appear in kinds.

We also don't include information about standard Atom elements that would be meaningless in the given context; for example, <atom:summary> isn't used in the Contact kind, and although <atom:author> is a required element in an entry (unless it's specified in the parent feed), it doesn't have a useful meaning in the Contact kind.

Creating kinds

It may be hard to figure out exactly what information you need to include when creating an entry of a particular kind, especially because some elements in the kinds contain other kinds.

One approach that might help is to use the client libraries we provide rather than to try to construct kinds by hand. The client libraries provide various methods for adding and changing data in an entry of a given kind; see the client library documentation for details.

Extensibility

The information in this document doesn't cover all possible properties and attribute values for kinds. Services may extend kinds, so a particular service may use properties and values not included in this document.

Typographical conventions

In the tables in this document, we use the following conventions for required and optional elements:

elementName Required element
elementName? Optional element
elementName* Optional element, multiple instances allowed

Elements and attributes are presented in standard XPath notation.

Contact kind

Represents a contact: a person, a venue such as a club or a restaurant, or an organization.

Category element: <atom:category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/contact/2008#contact"/>

Note: If you're using the Contact kind in the context of the Contacts API, please remember that the Contact kind version 2.0 (described in this document) is used by the Contacts API since version 3.0 of the API.

Properties

Property Description
atom:category* Categories. Instances with the @label attribute are treated as tags. For information on using the @scheme attribute, see note at beginning of this section.
atom:content Notes about the contact.
atom:link* Links to related information. Specifically, atom:link[@rel='alternate'] links to an HTML page describing the contact.
atom:title Contact's name. This field is read only. To modify the contact's name, see gd:name.
gd:email* Email addresses.
gd:extendedProperty* Extended property.
gd:deleted? Presence of this element indicates that this contact entry has been deleted.
gd:im* IM addresses.
gd:name? Name of the contact in structured form.
gd:organization* Organization.
gd:phoneNumber* Phone and fax numbers.
gd:structuredPostalAddress* Postal address of the contact in structured form.
gd:where? A place associated with the contact.

Examples

<entry xmlns='http://www.w3.org/2005/Atom' xmlns:gd='http://schemas.google.com/g/2005'>
  <category scheme='http://schemas.google.com/g/2005#kind' 
      term='http://schemas.google.com/contact/2008#contact'/>
  <title>Elizabeth Bennet</title>
  <content>My good friend, Liz.  A little quick to judge sometimes, but nice girl.</content>
  <gd:email rel='http://schemas.google.com/g/2005#work' primary='true' address='liz@gmail.com'/>
  <gd:email rel='http://schemas.google.com/g/2005#home' address='liz@example.org'/>
  <gd:phoneNumber rel='http://schemas.google.com/g/2005#work' primary='true'>
    (206)555-1212
  </gd:phoneNumber>
  <gd:phoneNumber rel='http://schemas.google.com/g/2005#home'>
    (206)555-1213
  </gd:phoneNumber>
  <gd:phoneNumber rel='http://schemas.google.com/g/2005#mobile'>
    (206) 555-1212
  </gd:phoneNumber>
  <gd:im rel='http://schemas.google.com/g/2005#home' 
      protocol='http://schemas.google.com/g/2005#GOOGLE_TALK' 
      address='liz@gmail.com'/>
  <gd:postalAddress rel='http://schemas.google.com/g/2005#work' primary='true'>
    1600 Amphitheatre Pkwy 
    Mountain View, CA 94043
  </gd:postalAddress>
  <gd:postalAddress rel='http://schemas.google.com/g/2005#home'>
    800 Main Street
    Mountain View, CA 94041
  </gd:postalAddress>
  <gd:organization>
    <gd:orgName>Google, Inc.</gd:orgName>
    <gd:orgTitle>Tech Writer</gd:orgTitle>
  </gd:organization>
</entry>

Profile kind

Represents a profile associated with a Google user or other entity. The Profile kind shares much structure with the Contact kind. However, it differs in some ways: it cannot contain extended properties or be marked as deleted, for example.

Category element: <atom:category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/contact/2008#profile"/>

The Profile kind was introduced in version 3.0 of the Contacts API.

Properties

Property Description
atom:category* Categories. Instances with the @label attribute are treated as tags. For information on using the @scheme attribute, see the "Category element" note at beginning of this section.
atom:content Notes about the profile.
atom:link* Links to related information. Specifically, atom:link[@rel='alternate'] links to an HTML page describing the profile.
atom:title Profile's name. This field is read only.
gd:email* Email addresses.
gd:im* IM addresses.
gd:name? Name, in structured form.
gd:organization* Organization.
gd:phoneNumber* Phone and fax numbers.
gd:structuredPostalAddress* Postal address, in structured form.
gd:where? A place associated with the profile.

Examples

<entry xmlns='http://www.w3.org/2005/Atom'
xmlns:gContact='http://schemas.google.com/contact/2008'
xmlns:batch='http://schemas.google.com/gdata/batch'
xmlns:gd='http://schemas.google.com/g/2005'
  <category scheme='http://schemas.google.com/g/2005#kind'
  term='http://schemas.google.com/contact/2008#profile' />
  <title>Elizabeth Bennett</title>
  <gd:name>
    <gd:givenName>Elizabeth</gd:givenName>
    <gd:familyName>Bennett</gd:familyName>
  </gd:name>
  <gd:structuredPostalAddress rel='http://schemas.google.com/g/2005#work'>
    <gd:formattedAddress>Longbourne, Nr. Meryton, Hertfordshire, England</gd:formattedAddress>
  </gd:structuredPostalAddress>
</entry>

Event kind

Represents a calendar event. The event location is represented by a Contact kind embedded in (or linked from) a <gd:where> element; the event planners and attendees are represented as Contact kinds embedded in (or linked from) <gd:who> elements.

Category element: <category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/g/2005#event"/>

Properties

Property Description
atom:author Person who created this event.
atom:category* Categories. Instances with the @label attribute are treated as tags. For information on using the @scheme attribute, see note at beginning of this section.
atom:content Longer description of the event.
atom:link* Links. Specifically, atom:link[@rel='alternate'] provides a link to an HTML page describing the event.
atom:title Brief title for the event.
gd:comments? Comments feed.
gd:eventStatus? Extensible enum documented below.
gd:extendedProperty* Extended property.
gd:originalEvent? Original event identifier for recurring events.
gd:recurrence? Recurrence rule.
gd:transparency? Extensible enum documented below, corresponding to the TRANSP property defined in RFC 2445.
gd:visibility? Extensible enum documented below.
gd:when* Event time. The startTime and endTime attributes must both be set, although for all-day events those attributes are only dates, with no times.
gd:when/gd:reminder* Reminders for the event.
gd:where* Location of the event or nearby necessities such as parking. If a <gd:where> element is specified at the feed level, but there's no <gd:where> element at the entry level, then the entries inherit the feed-level <gd:where> value.
gd:who* People associated with the event: organizer, attendees, speakers, performers, etc.
gd:who/gd:attendeeStatus? Acceptance status.
gd:who/gd:attendeeType? Attendee type: required or optional.

rel values for gd:where

rel value Description
http://schemas.google.com/g/2005#event or not specified. Place where the event takes place.
http://schemas.google.com/g/2005#event.alternate A secondary location. For example, a remote site with a videoconference link to the main site.
http://schemas.google.com/g/2005#event.parking Nearby parking lot.

gd:eventStatus values

Value Description
http://schemas.google.com/g/2005#event.canceled The event has been canceled.
http://schemas.google.com/g/2005#event.confirmed The event is planned.
http://schemas.google.com/g/2005#event.tentative The event is only tentatively scheduled.

gd:visibility values

Value Description
http://schemas.google.com/g/2005#event.confidential Allow some readers to see the event.
http://schemas.google.com/g/2005#event.default Inherit the behavior from the preferences of the owner of the calendar on which the event appears.
http://schemas.google.com/g/2005#event.private Allow fewest readers to see the event.
http://schemas.google.com/g/2005#event.public Allow most readers to see the event.

gd:transparency values

Value Description
http://schemas.google.com/g/2005#event.opaque Indicates event consumes time on calendar; event time will be marked as busy in a free/busy search.
http://schemas.google.com/g/2005#event.transparent Indicates event doesn't consume any time on calendar; event time will not be marked as busy in a free/busy search.

Examples

Meeting:

<entry xmlns:gd="http://schemas.google.com/g/2005">
  <category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/g/2005#event"/>
  <id>http://mycal.example.com/feeds/jo/home/full/e1a2af06df8a563edf9d32ec9fd61e03f7f3b67b</id>
  <published>2005-01-18T21:00:00Z</published>
  <updated>2006-01-01T00:00:00Z</updated>
  <title>Discuss BazMat API</title>
  <content>We will discuss integrating GData with BazMat.</content>
  <author>
    <name>Jo March</name>
    <email>jo@example.com</email>
  </author>
  <gd:when startTime='2005-01-18T21:00:00Z' endTime='2005-01-18T22:00:00Z'>
    <gd:reminder minutes='15'/>
  </gd:when>
  <gd:where valueString='Building 41, Room X'/>
  <gd:eventStatus value="http://schemas.google.com/g/2005#event.confirmed"/>
  <gd:visibility value="http://schemas.google.com/g/2005#event.public"/>
  <gd:transparency value="http://schemas.google.com/g/2005#event.transparent"/>
</entry>

Online event:

<entry xmlns:gd="http://schemas.google.com/g/2005">
  <category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/g/2005#event"/>
  <id>http://mycal.example.com/feeds/jo/home/full/982307e797979879a</id>
  <published>2005-01-18T21:00:00Z</published>
  <updated>2006-01-01T00:00:00Z</updated>
  <title>Online Chess Tournament</title>
  <content/>
  <author>
    <name>Jo March</name>
    <email>jo@example.com</email>
  </author>
  <gd:when startTime='2006-01-24T19:00:00-08:00' endTime='2006-01-24T20:00:00-08:00'>
    <gd:reminder minutes='15'/>
  </gd:when>
  <gd:where>
    <gd:entryLink>
      <entry>
        <category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/g/2005#contact"/>
        <id>http://contacts.example.com/jo/GamePhannz</id>
        <published>2005-01-18T21:00:00Z</published>
        <updated>2006-01-01T00:00:00Z</updated>
        <title>GamePhannz Online Game Server</title>
        <link rel="http://schemas.google.com/g/2005#onlineLocation" type="text/html" href="http://gamephannz.example.com/chess/138fd87e"/>
        <content/>
      </entry>
    </gd:entryLink>
  </gd:where>
  <gd:eventStatus value="http://schemas.google.com/g/2005#event.confirmed"/>
  <gd:visibility value="http://schemas.google.com/g/2005#event.public"/>
  <gd:transparency value="http://schemas.google.com/g/2005#event.transparent"/>
</entry>

Message kind

Represents a message, such as an email, a discussion group posting, or a comment.

Category element: <atom:category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/g/2005#message"/>

Properties

Property Description
atom:category* Categories. Instances with the @label attribute are treated as tags. For information on using the @scheme attribute, see note at beginning of this section. For information on using the @term attribute, see table below.
atom:content Message body.
atom:link* Message attachments. Specifically, to upload an attachment, use <link rel="enclosure"> and put the attachment's content in an Atom media collection.
atom:title Message subject.
gd:geoPt? Geographic location the message was posted from.
gd:rating? Quality rating (as defined by the application).
gd:who* People associated with this message. The exact semantics depends on the @rel value. See table below.

Category @term values

All categories below are in the http://schemas.google.com/g/2005 scheme.

Term Description
http://schemas.google.com/g/2005#message.chat The message is a transcript of a chat session.
http://schemas.google.com/g/2005#message.inbox The message is marked as belonging to the inbox.
http://schemas.google.com/g/2005#message.sent The message is marked as sent.
http://schemas.google.com/g/2005#message.spam The message is considered spam.
http://schemas.google.com/g/2005#message.starred The message is marked as starred.
http://schemas.google.com/g/2005#message.unread The message is unread.

rel values for gd:who

Property Description
http://schemas.google.com/g/2005#message.bcc Message BCC recipient.
http://schemas.google.com/g/2005#message.cc Message CC recipient.
http://schemas.google.com/g/2005#message.from Message (email or IM) sender.
http://schemas.google.com/g/2005#message.reply-to Intended recipient of a reply message.
http://schemas.google.com/g/2005#message.to Message primary recipient.

Example

Email message:

<entry xmlns:gd="http://schemas.google.com/g/2005">
  <category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/g/2005#message"/>
  <category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/g/2005#message.sent"/>
  <author>
    <name>Jo March</name>
    <email>jo@example.com</email>
  </author>
  <id>http://mymail.example.com/feeds/jo/home/full/e1a2af06df8a563edf9d32ec9fd61e03f7f3b67b</id>
  <published>2006-01-18T21:00:00Z</published>
  <updated>2006-01-18T21:00:00Z</updated>
  <title>Re: Info?</title>
  <content>Hi, Fritz -- The information you're looking for is on p. 47.</content>
  <gd:who rel="http://schemas.google.com/g/2005#message.from">
    <gd:entryLink href="http://contacts.example.com/jo/Jo"/>
  </gd:who>
  <gd:who rel="http://schemas.google.com/g/2005#message.to">
    <gd:entryLink href="http://contacts.example.com/fritzb/FritzB"/>
  </gd:who>
</entry>

Google Data namespace element reference

The rest of this document consists of reference material for the elements used by the kinds.

Enums

Some extension elements need to specify properties whose values come from an enumerated set. The general form of such properties is:

<gd:propertyName value="propertyValue">

If the property value comes from the Google Data namespace, it takes the form http://schemas.google.com/g/2005#{kind}.{value}. For example: http://schemas.google.com/g/2005#event.tentative. If the value space is extensible, values may also be in the form of a URI. The recommended form for extended value URIs is {schema URI}#{value}. For example: http://www.example.com/attendeeStatus#AudioConference.

gEnumConstruct =
   attribute value { text },
   anyAttribute*

gdCommonProperties

Common properties used for all Google types. Note that the presence of anyAttribute and anyElement in the schema allows all Google Data namespace elements using common properties to be further extended in any namespace. In particular it's legal to nest any gd element or any Atom/RSS element within any other gd element. This should be done judiciously, and in most cases such use should be documented as an explicit property of the containing gd element type.

Properties

Property Type Description
@xml:base uri Standard XML construct for describing base of nested relative URIs.
@xml:lang text Language of nested strings.

Schema

namespace gd = "http://schemas.google.com/g/2005"

gdCommonProperties = {
   atomCommonAttributes,
   anyAttribute*,
   (anyElement*)
}

gd:additionalName

Specifies additional (eg. middle) name of the person, eg. "Susan".

Properties

Property Type Description
@yomi? xs:string Fonetical representation.
text() xs:string Person's family name.

Example

<gd:additionalName yomi="'suz@n">Susan<gd:additionalName>

Schema

start = additionalName

additionalName =
   element gd:additionalName {
      attribute yomi { xs:string }?,
      (xs:string)
   }

gd:comments

Contains a comments feed for the enclosing entry (such as a calendar event.).

Properties

Property Type Description
@rel? xs:string Type of comments contained within. Currently, there's a distinction between regular comments and reviews.
gd:feedLink? feedLink Comments feed. This feed should implement the Message kind.

rel values

Value Description
http://schemas.google.com/g/2005#regular or not specified Regular comments (from users).
http://schemas.google.com/g/2005#reviews Professional reviews.

Examples

Comments feed:

<gd:comments>
  <gd:feedLink href="http://example.com/Jo/posts/MyFirstPost/comments" countHint="10">
    <feed>
      <id>http://example.com/Jo/posts/MyFirstPost/comments</id>
      <title>My first post: comments</title>
      ...
      <entry>
         ...
         <content>Good post.</content>
      </entry>
      <entry>
         ...
      </entry>
      ...
    </feed>
  </gd:feedLink>
</gd:comments>

Reviews feed:

<gd:comments rel="http://schemas.google.com/g/2005#reviews">
  <gd:feedLink href="http://example.com/restaurants/SanFrancisco/432432/reviews" countHint="25">
    <feed>
      <id>http://example.com/restaurants/SanFrancisco/432432/reviews</id>
      <title>La Folie reviews</title>
      ...
      <entry>
         ...
         <content>Good food.</content>
         <gd:rating value="5" min="1" max="5"/>
      </entry>
      <entry>
         ...
      </entry>
      ...
    </feed>
  </gd:feedLink>
</gd:comments>

Schema

start = comments

comments =
   element gd:comments {
      gdCommonProperties,
      attribute rel { xs:string }?,
      (feedLink?)
   }

gd:deleted

A marker element that, when present, indicates the containing entry is deleted.

Properties

None.

Schema

start = deleted

deleted =
   element gd:deleted

gd:country

Country name along with optional country code. The latter is given in accordance with ISO 3166-1 alpha-2.

Properties

Property Type Description
@code? xs:string Country code as in ISO 3166-1 alpha-2.
text() xs:string Country name.

Examples

<gd:country code='PL'>Poland</gd:country>
<gd:country>Gabon</gd:country>

Schema

start = country

country =
   element gd:country {
      attribute code { xs:string }?,
      xs:string?
   }

gd:email

An email address associated with the containing entity (which is usually an entity representing a person or a location).

Properties

Property Type Description
@address xs:string Email address.
@displayName? xs:string A display name of the entity (e.g. a person) the email address belongs to.
@label? xs:string A simple string value used to name this email address. It allows UIs to display a label such as "Work", "Personal", "Preferred", etc.
@rel? xs:string A programmatic value that identifies the type of email; see below for details.
@primary? xs:boolean When multiple email extensions appear in a contact kind, indicates which is primary. At most one email may be primary. Default value is "false".

rel values

Value Description
http://schemas.google.com/g/2005#home
http://schemas.google.com/g/2005#other An email address that is neither home nor work. label can be used to indicate the actual type.
http://schemas.google.com/g/2005#work

Examples

<gd:email address="foo@bar.example.com" displayName="Foo Bar" />
<gd:email label="Personal" rel="http://schemas.google.com/g/2005#home" address="fubar@gmail.com" primary="true"/>

Schema

start = email

email =
   element gd:email {
      attribute address { xs:string },
      attribute displayName { xs:string }?,
      attribute label { xs:string }?,
      attribute rel { xs:string }?,
      attribute primary { xs:boolean }?
   }

gd:entryLink

Represents a logically nested entry. For example, a <gd:who> representing a contact might have a nested entry from a contact feed.

Properties

Property Type Description
@href? xs:string Specifies the entry URI. If the nested entry is embedded and not linked, this attribute may be omitted.
@readOnly? xs:boolean Specifies whether the contained entry is read-only. The default value is "false".
@rel? xs:string Specifies the link relation; allows the service to provide multiple types of entry links for a single entity. Has the same semantics and allowed values as the rel attribute of the <atom:link> element.
atom:entry? atomEntry Contents of the entry.

Restrictions

  • Either or both of @href or <atom:entry> must be present.
  • If atom:entry is not present, the client can fetch the contents from the entry URI in @href. If atom:entry is present, the contents must be the same as what would be retrieved from @href at the time the entry was generated.
  • When a PUT or a POST contains a <gd:entryLink> and the @href attribute is specified, the attribute's value is used to create a link; if the atom:entry element is also present, it is ignored. If the @href attribute is not specified, then the atom:entry element is either stored as an embedded entry or stored in another feed and linked to. Note that some services may not support all of these options.

Examples

Contact information within <gd:who>:

<gd:who rel="http://schemas.google.com/g/2005#event.attendee" valueString="Jo">
  <gd:entryLink href="http://gmail.com/jo/contacts/Jo">
    <entry>
      <category scheme="http://schemas.google.com/g/2005#kind"
        term="http://schemas.google.com/g/2005#contact"/>
      <id>http://gmail.com/jo/contacts/Jo</id>
      <category term="user-tag" label="Google"/>
      <title>Jo March</title>
      <gd:email address="jo@example.com"/>
      <gd:phoneNumber label="work">(650) 555-1212</gd:phoneNumber>
    </entry>
  </gd:entryLink>
</gd:who>

External reference only (read-only entry):

<gd:who rel="http://schemas.google.com/g/2005#event.attendee" valueString="Jo">
  <gd:entryLink href="http://gmail.com/jo/contacts/Jo" readOnly="true"/>
</gd:who>

Schema

start = entryLink

entryLink =
   element gd:entryLink {
      attribute href { xs:string }?,
      attribute readOnly { xs:boolean }?,
      (atomEntry?)
   }

gd:extendedProperty

Allows you to store a limited amount of custom data as an auxiliary property of the enclosing entity.

Note that the presence of anyForeignElement allows feed to optionally embed any valid XML within gd:extendedProperty element (mutually exclusive with value attribute).

Properties

Property Type Description
@name xs:string Specifies the name of the property expressed as a URI. Extended property URIs usually follow the {schema}#{local-name} convention.
@value? xs:string Property value.
@realm? xs:string Used by some APIs to specify where the extended property applies.

Example

An external identifier for a calendar event:

<gd:extendedProperty name="http://www.example.com/schemas/2007#mycal.id"
  value="1234"></gd:extendedProperty>

Additional xml for contact entry

<gd:extendedProperty name="com.google">
  <some_xml>value</some_xml>
</gd:extendedProperty>

Schema

start = extendedProperty

extendedProperty =
   element gd:extendedProperty {
      attribute name { xs:string },
      attribute value { xs:string } ?,
      (anyForeignElement*),
      attribute realm { xs:string } ?
   }

gd:familyName

Specifies family name of the person, eg. "Smith".

Properties

Property Type Description
@yomi? xs:string Phonetic representation.
text() xs:string Person's family name.

Example

<gd:familyName yomi="smɪð">Smith<gd:familyName>

Schema

start = familyName

familyName =
   element gd:familyName {
      attribute yomi { xs:string }?,
      (xs:string)
   }

gd:feedLink

Represents a logically nested feed. For example, a calendar feed might have a nested feed representing all comments on entries.

Properties

Property Type Description
@countHint? xs:unsignedInt Hints at the number of entries in the feed. Depending on the implementation, may not be a precise count.
@href? xs:string Specifies the feed URI. If the nested feed is embedded and not linked, this attribute may be omitted.
@readOnly? xs:boolean Specifies whether the contained feed is read-only.
@rel? xs:string Specifies the link relation; allows the service to provide multiple types of feed links for a single entity. Has the same semantics and allowed values as the rel attribute of the <atom:link> element.
atom:feed? atomFeed Contents of the feed.

Restrictions

  • Either or both of @href or <atom:feed> must be present.
  • If atom:feed is not present, the client can fetch the contents from the URI in @href. If it is present, the contents must the same as what would be retrieved from @href at the time the feed was generated.
  • When a PUT or a POST contains a <gd:feedLink> and the @href attribute is specified, the attribute's value is used to create a link; if the <atom:feed> element is also present, it is ignored. If the @href attribute is not specified, then the <atom:feed> element is stored as an embedded feed. Note that some services may not support all of these options.

Examples

Blogging:

<gd:feedLink href="http://example.com/Jo/posts/MyFirstPost/comments" countHint="10">
    <feed>
      <id>http://example.com/Jo/posts/MyFirstPost/comments</id>
      <title>My first post: comments</title>
      ...
      <entry>
         ...
         <content>Good post.</content>
      </entry>
      <entry>
         ...
      </entry>
      ...
    </feed>
  </gd:feedLink>

External reference only:

<gd:feedLink href="http://example.com/Jo/posts/MyFirstPost/comments"
            countHint="10"/>

Embedded feed within an Atom entry representing a list:

<gd:feedLink>
  <feed>
    <id>cid:1</id>
    <entry>
       <id>cid:1.1</id>
       <content>list item 1</content>
    </entry>
    <entry>
       <id>cid:1.2</id>
       <content>list item 2</content>
    </entry>
  </feed>
</gd:feedLink>

Schema

start = feedLink

feedLink =
   element gd:feedLink {
      attribute href { xs:string }?,
      attribute readOnly { xs:boolean }?,
      attribute countHint { xs:unsignedInt }?,
      (atomFeed?)
   }

gd:geoPt

A geographical location (latitude, longitude, elevation).

Deprecated. This element is deprecated. For geotagging data, use GeoRSS instead.

Properties

Property Type Description
@elev? xs:float Elevation in meters. Negative values indicate depths below mean sea level.
@label? xs:string A simple string value used to name this location. It allows UIs to display a label such as "Current Position".
@lat xs:float Latitude in degrees. Positive values mean North, negative values mean South. The range is [-90.0, 90.0].
@lon xs:float Longitude in degrees. Positive values mean East, negative values mean West. The range is [-180.0, 180.0].
@time? xs:dateTime Timestamp.

Examples

<gd:geoPt lat="40.75" lon="-74.0"/>
<gd:geoPt lat="27.98778" lon="86.94444" elev="8850.0"/>

Schema

start = geoPt

geoPt =
   element gd:geoPt {
      attribute label { xs:string }?,
      attribute lat { xs:float },
      attribute lon { xs:float },
      attribute elev { xs:float }?,
      attribute time { xs:dateTime }?
   }

gd:im

An instant messaging address associated with the containing entity.

Properties

Property Type Description
@address xs:string IM address.
@label? xs:string A simple string value used to name this IM address. It allows UIs to display a label such as "Work", "Personal", "Preferred", etc.
@rel? xs:string A programmatic value that identifies the type of IM; see below for details.
@protocol? xs:string Identifies the IM network. The value may be either one of the standard values (shown below) or a URI identifying a proprietary IM network.
@primary? xs:boolean When multiple IM extensions appear in a contact kind, indicates which is primary. At most one IM may be primary. Default value is "false".

rel values

Value Description
http://schemas.google.com/g/2005#home
http://schemas.google.com/g/2005#netmeeting
http://schemas.google.com/g/2005#other An IM address that is neither home nor work. label can be used to indicate the actual type.
http://schemas.google.com/g/2005#work

protocol attribute values

The following table shows some likely possible values for the @protocol attribute.

Value Description
http://schemas.google.com/g/2005#AIM AOL Instant Messenger protocol
http://schemas.google.com/g/2005#MSN MSN Messenger protocol
http://schemas.google.com/g/2005#YAHOO Yahoo Messenger protocol
http://schemas.google.com/g/2005#SKYPE Skype protocol
http://schemas.google.com/g/2005#QQ QQ protocol
http://schemas.google.com/g/2005#GOOGLE_TALK Google Talk protocol
http://schemas.google.com/g/2005#ICQ ICQ protocol
http://schemas.google.com/g/2005#JABBER Jabber protocol

Examples

An IM address for MSN Messenger:

<gd:im protocol="http://schemas.google.com/g/2005#MSN" address="foo@bar.msn.com" rel="http://schemas.google.com/g/2005#home" primary="true"/>

A user-provided IM address with an unspecified protocol. Such an address is useful for display purposes, but is difficult to handle programmatically.

<gd:im label="Other" address="foo@baz.example.com"/>

Schema

start = im

im =
   element gd:im {
      attribute address { xs:string },
      attribute label { xs:string }?,
      attribute rel { xs:string }?,
      attribute protocol { xs:string }?,
      attribute primary { xs:boolean }?
   }

gd:givenName

Specifies given name of the person, eg. "John".

Properties

Property Type Description
@yomi? xs:string Phonetic representation.
text() xs:string Person's given name.

Example

<gd:givenName yomi="dʒon">John<gd:givenName>

Schema

start = givenName

givenName =
   element gd:givenName {
      attribute yomi { xs:string }?,
      (xs:string)
   }

gd:money

Specifies an amount of money in a particular currency.

Properties

Property Type Description
@amount xsd:float Amount of money.
@currencyCode xsd:string ISO4217 currency code.

Example

<gd:money amount='650.0' currencyCode='EUR'/>

Schema

element gd:money {
  attribute amount { xsd:float },
  attribute currencyCode { xsd:string }
}

gd:name

Allows storing person's name in a structured way. Consists of given name, additional name, family name, prefix, suffix and full name.

Properties

Property Type Description
gd:givenName? givenName Person's given name.
gd:additionalName? additionalName Additional name of the person, eg. middle name.
gd:familyName? familyName Person's family name.
gd:namePrefix? namePrefix Honorific prefix, eg. 'Mr' or 'Mrs'.
gd:nameSuffix? nameSuffix Honorific suffix, eg. 'san' or 'III'.
gd:fullName? fullName Unstructured representation of the name.

Example

Structured representation of Sir Winston Leonard Spencer-Churchill, KG

<gd:name>
  <gd:givenName>Winston</gd:givenName>
  <gd:additionalName>Leonard</gd:additionalName>
  <gd:familyName>Spencer-Churchill</gd:familyName>
  <gd:namePrefix>Sir</gd:namePrefix>
  <gd:nameSuffix>OG</gd:nameSuffix>
</gd:name>

Schema

start = name

name =
   element gd:name {
      givenName?
      & additionalName?
      & familyName?
      & namePrefix?
      & nameSuffix?
   }

Restrictions

  • Unstructured component of the name should be consistent with its structured representation.

gd:organization

An organization, typically associated with a contact.

Properties

Property Type Description
@label? xs:string A simple string value used to name this organization. It allows UIs to display a label such as "Work", "Volunteer", "Professional Society", etc.
gd:orgDepartment? orgDepartment Specifies a department within the organization.
gd:orgJobDescription? orgJobDescription Description of a job within the organization.
gd:orgName? orgName The name of the organization.
gd:orgSymbol? orgSymbol Symbol of the organization.
gd:orgTitle? orgTitle The title of a person within the organization.
@primary? xs:boolean When multiple organizations extensions appear in a contact kind, indicates which is primary. At most one organization may be primary. Default value is "false".
@rel? xs:string A programmatic value that identifies the type of organization; see below for details.
gd:where? where A place associated with the organization, e.g. office location.

rel values

Value Description
http://schemas.google.com/g/2005#other An organization that is not work. label can be used to indicate the actual type.
http://schemas.google.com/g/2005#work

Examples

<gd:organization rel="http://schemas.google.com/g/2005#work" label="Work" primary="true">
  <gd:orgName>Google, Inc.</gd:orgName>
  <gd:orgTitle>Tech Writer</gd:orgTitle>
  <gd:orgJobDescription>Writes documentation</gd:orgJobDescription>
  <gd:orgDepartment>Software Development</gd:orgDepartment>
  <gd:orgSymbol>GOOG</gd:orgSymbol>
</gd:organization>

Schema

start = organization

organization =
   element gd:organization {
      attribute label { xs:string }?,
      attribute rel { xs:string }?,
      attribute primary { xs:boolean }?,
      ( orgDepartment? &
      orgJobDescription? &
      orgName? &
      orgSymbol? &
      orgTitle? &
      where? )
   }

gd:orgDepartment

Describes a department within an organization. Must appear within a gd:organization element.

Example

<gd:orgDepartment>Research and Development</gd:orgDepartment>

Schema

start = orgDepartment

orgDepartment = element gd:orgDepartment { xs:string }

gd:orgJobDescription

Describes a job within an organization. Must appear within a gd:organization element.

Example

<gd:orgJobDescription>Documenting public APIs</gd:orgJobDescription>

Schema

start = orgJobDescription

orgJobDescription = element gd:orgJobDescription { xs:string }

gd:orgName

The name of the organization. Must appear within a gd:organization element.

Properties

Property Description
@yomi? Yomigana (Japanese reading aid) for the organization name.

Example

<gd:orgName>Google, Inc.</gd:orgName>

Schema

start = orgName

orgName =
   element gd:orgName {
     attribute yomi {xs:string},
     xs:string
   }

gd:orgSymbol

Provides a symbol of an organization. Must appear within a gd:organization element.

Example

<gd:orgSymbol>GOOG</gd:orgSymbol>

Schema

start = orgSymbol

orgSymbol = element gd:orgSymbol { xs:string }

gd:orgTitle

The title of a person within an organization. Must appear within a gd:organization element.

Example

<gd:orgTitle>President and CEO</gd:orgTitle>

Schema

start = orgTitle

orgTitle =
   element gd:orgTitle { xs:string }

gd:originalEvent

Equivalent to the Recurrence ID property specified in section 4.8.4.4 of RFC 2445. Appears in every instance of a recurring event, to identify the original event.

Contains a <gd:when> element specifying the original start time of the instance that has become an exception.

Properties

Property Type Description
@id xs:string The event ID for the original event.
@href xs:string The event feed URL for the original event.

Example

Specifying an original event:

<gd:originalEvent id="i8fl1nrv2bl57c1qgr3f0onmgg"

href="http://www.google.com/calendar/feeds/userID/private-magicCookie/full/eventID">
  <gd:when startTime="2006-03-17T22:00:00.000Z"/>
</gd:originalEvent>

Schema

start = originalEvent

originalEvent =
   element gd:originalEvent {
      attribute id { xs:string },
      attribute href { xs:string },
      when
   }

gd:phoneNumber

A phone number associated with the containing entity (which is usually an entity representing a person or a location).

Properties

Property Type Description
@label? xs:string A simple string value used to name this phone number. In most cases, @label is not necessary as @rel uniquely identifies a number and allows UIs to display a proper label such as "Mobile", "Home", "Work", etc. However, in the case where one person has (for example) multiple mobile phones, this property can be used to disambiguate them.
@rel? xs:string A programmatic value that identifies the type of phone number; see below for details.
@uri? xs:string An optional "tel URI" used to represent the number in a formal way, useful for programmatic access, such as a VoIP/PSTN bridge. See RFC 3966 for more information on tel URIs.
@primary? xs:boolean When multiple phone number extensions appear in a contact kind, indicates which is primary. At most one phone number may be primary. Default value is "false".
text() xs:string Human-readable phone number; may be in any telephone number format. Leading and trailing whitespace is insignificant. Newlines within the string are also insignificant, and may be removed or flattened out to a single space.

rel values

Value Description
http://schemas.google.com/g/2005#assistant
http://schemas.google.com/g/2005#callback
http://schemas.google.com/g/2005#car
http://schemas.google.com/g/2005#company_main
http://schemas.google.com/g/2005#fax
http://schemas.google.com/g/2005#home
http://schemas.google.com/g/2005#home_fax
http://schemas.google.com/g/2005#isdn
http://schemas.google.com/g/2005#main
http://schemas.google.com/g/2005#mobile
http://schemas.google.com/g/2005#other A special type of number for which no other rel value makes sense. label can be used to indicate the actual type.
http://schemas.google.com/g/2005#other_fax
http://schemas.google.com/g/2005#pager
http://schemas.google.com/g/2005#radio
http://schemas.google.com/g/2005#telex
http://schemas.google.com/g/2005#tty_tdd
http://schemas.google.com/g/2005#work
http://schemas.google.com/g/2005#work_fax
http://schemas.google.com/g/2005#work_mobile
http://schemas.google.com/g/2005#work_pager

Examples

Simple phone number entered by a user:

<gd:phoneNumber>(425) 555-8080 ext. 72585</gd:phoneNumber>

Same phone number drawn from a directory:

<gd:phoneNumber rel="http://schemas.google.com/g/2005#work" uri="tel:+1-425-555-8080;ext=52585">
  (425) 555-8080 ext. 52585
</gd:phoneNumber>

Number with a label:

<gd:phoneNumber rel="http://schemas.google.com/g/2005#mobile" label="Personal calls only" uri="tel:+12065551212">
  +1 206 555 1212
</gd:phoneNumber>

Schema

start = phoneNumber

phoneNumber =
   element gd:phoneNumber {
      attribute rel { xs:string }?,
      attribute label { xs:string }?,
      attribute uri { xs:string }?,
      attribute primary { xs:boolean }?,
      (xs:string)
   }

gd:postalAddress

A postal address.

Properties

Property Type Description
@label? xs:string A simple string value used to name this address.
@rel? xs:string A programmatic value that identifies the type of postal address; see below for details.
@primary? xs:boolean When multiple postal address extensions appear in a contact kind, indicates which is primary. At most one postal address may be primary. Default value is "false".
text() xs:string The address as text. Leading and trailing whitespace is insignificant. Newlines within the string are significant.

rel values

Value Description
http://schemas.google.com/g/2005#home
http://schemas.google.com/g/2005#other An address which is neither home nor work. label can be used to indicate the actual type.
http://schemas.google.com/g/2005#work

Examples

<gd:postalAddress>
  500 West 45th Street
  New York, NY 10036
</gd:postalAddress>

Schema

start = postalAddress

postalAddress =
   element gd:postalAddress {
      attribute label { xs:string }?,
      attribute rel { xs:string }?,
      attribute primary { xs:boolean }?,
      (xs:string)
   }

gd:rating

Represents a numeric rating of the enclosing entity, such as a comment. Each rating supplies its own scale, although it may be normalized by a service; for example, some services might convert all ratings to a scale from 1 to 5.

Properties

Property Type Description
@average? xs:float Average rating.
@max xs:int The rating scale's maximum value.
@min xs:int The rating scale's minimum value.
@numRaters? xs:int Number of ratings taken into account when computing the average value.
@rel? xs:string Specifies the aspect that's being rated. If not specified, the rating is an overall rating.
@value? xs:int Rating value.

rel values

Value Description
http://schemas.google.com/g/2005#overall or not specified Overall rating. Higher values mean better ratings.
http://schemas.google.com/g/2005#price Price rating. Higher values mean higher prices.
http://schemas.google.com/g/2005#quality Quality rating. Higher values mean better quality.

Examples

4/5 overall rating:

<gd:rating value="4" min="1" max="5"/>

Most expensive price range rating:

<gd:rating rel="http://schemas.google.com/g/2005#price" value="5" min="1" max="5"/>

Rated by 200 users with an average rating of 4.65 out of 5:

<gd:rating average="4.65" min="1" max="5" numRaters="200"/>

Schema

start = rating

rating =
   element gd:rating {
      gdCommonProperties,
      attribute rel { xs:string }?,
      attribute value { xs:int }?,
      attribute average { xs:float }?,
      attribute min { xs:int },
      attribute max { xs:int },
      attribute numRaters { xs:int }?
   }

gd:recurrence

Represents the dates and times when a recurring event takes place.

The string that defines the recurrence consists of a set of properties, each of which is defined in the iCalendar standard (RFC 2445).

Specifically, the string usually begins with a DTSTART property that indicates the starting time of the first instance of the event, and often a DTEND property or a DURATION property to indicate when the first instance ends. Next come RRULE, RDATE, EXRULE, and/or EXDATE properties, which collectively define a recurring event and its exceptions (but see below). (See section 4.8.5 of RFC 2445 for more information about these recurrence component properties.) Last comes a VTIMEZONE component, providing detailed timezone rules for any timezone ID mentioned in the preceding properties.

Google services like Google Calendar don't generally generate EXRULE and EXDATE properties to represent exceptions to recurring events; instead, they generate <gd:recurrenceException> elements. However, Google services may include EXRULE and/or EXDATE properties anyway; for example, users can import events and exceptions into Calendar, and if those imported events contain EXRULE or EXDATE properties, then Calendar will provide those properties when it sends a <gd:recurrence> element.

Note the the use of <gd:recurrenceException> means that you can't be sure just from examining a <gd:recurrence> element whether there are any exceptions to the recurrence description. To ensure that you find all exceptions, look for <gd:recurrenceException> elements in the feed, and use their <gd:originalEvent> elements to match them up with <gd:recurrence> elements.

Properties

Property Type Description
text() xs:string Recurrence description.

Example

A recurring event that takes place every morning from 6:00 to 7:00 a.m., Pacific time, from March 14 through March 21, 2006:

<gd:recurrence>
  DTSTART;TZID=America/Los_Angeles:20060314T060000
  DURATION:PT3600S
  RRULE:FREQ=DAILY;UNTIL=20060321T220000Z
  BEGIN:VTIMEZONE
  TZID:America/Los_Angeles
  X-LIC-LOCATION:America/Los_Angeles
  BEGIN:STANDARD
  TZOFFSETFROM:-0700
  TZOFFSETTO:-0800
  TZNAME:PST
  DTSTART:19671029T020000
  RRULE:FREQ=YEARLY;BYMONTH=10;BYDAY=-1SU
  END:STANDARD
  BEGIN:DAYLIGHT
  TZOFFSETFROM:-0800
  TZOFFSETTO:-0700
  TZNAME:PDT
  DTSTART:19870405T020000
  RRULE:FREQ=YEARLY;BYMONTH=4;BYDAY=1SU
  END:DAYLIGHT
  END:VTIMEZONE
</gd:recurrence>

Schema

start = recurrence

recurrence =
   element gd:recurrence {
      (xs:string)
   }

gd:recurrenceException

Represents an event that's an exception to a recurring event—that is, an instance of a recurring event in which one or more aspects of the recurring event (such as attendance list, time, or location) have been changed.

Contains a <gd:originalEvent> element that specifies the original recurring event that this event is an exception to.

When you change an instance of a recurring event, that instance becomes an exception. Depending on what change you made to it, the exception behaves in either of two different ways when the original recurring event is changed:

  • If you add, change, or remove comments, attendees, or attendee responses, then the exception remains tied to the original event, and changes to the original event also change the exception.
  • If you make any other changes to the exception (such as changing the time or location) then the instance becomes "specialized," which means that it's no longer as tightly tied to the original event. If you change the original event, specialized exceptions don't change. But see below.

For example, say you have a meeting every Tuesday and Thursday at 2:00 p.m. If you change the attendance list for this Thursday's meeting (but not for the regularly scheduled meeting), then it becomes an exception. If you change the time for this Thursday's meeting (but not for the regularly scheduled meeting), then it becomes specialized.

Regardless of whether an exception is specialized or not, if you do something that deletes the instance that the exception was derived from, then the exception is deleted. Note that changing the day or time of a recurring event deletes all instances, and creates new ones.

For example, after you've specialized this Thursday's meeting, say you change the recurring meeting to happen on Monday, Wednesday, and Friday. That change deletes all of the recurring instances of the Tuesday/Thursday meeting, including the specialized one.

If a particular instance of a recurring event is deleted, then that instance appears as a <gd:recurrenceException> containing a <gd:entryLink> that has its <gd:eventStatus> set to "http://schemas.google.com/g/2005#event.canceled". (For more information about canceled events, see RFC 2445.)

Properties

Property Type Description
@specialized xs:boolean Indicates whether the exception is specialized or not.
gd:entryLink entryLink An Event entry providing the details about the exception.
gd:originalEvent originalEvent The original recurring event that this is an exception to.

Example

An exception to a recurring event (with some pieces replaced by brief italicized identifiers for clarity):

<gd:recurrenceException specialized="true">
  <gd:entryLink>
    <entry>
      <id>i8fl1nrv2bl57c1qgr3f0onmgg_20060317T220000Z</id>
      <published>2006-03-17T23:00:00.000Z</published>
      <updated>2006-03-14T21:33:12.000Z</updated>
      <category scheme="http://schemas.google.com/g/2005#kind"
        term="http://schemas.google.com/g/2005#event"/>
      <title type="text">recurrence</title>
      <content type="text"/>
      <link rel="alternate" type="text/html"
        href="http://www.google.com/calendar/event?eid=idString"
        title="alternate"/>
      <author>
        <name>exception</name>
      </author>
      <gd:eventStatus
        value="http://schemas.google.com/g/2005#event.confirmed"/>
      <gd:comments>
        <gd:feedLink
            href="http://www.google.com/calendar/feeds/userID/private-magicCookie/full/eventID/comments/">
          <feed>
            <updated>2006-03-14T21:36:23.250Z</updated>
            <title type="text">Comments for: recurrence</title>
            <link rel="alternate" type="text/html"
              href="http://www.google.com/calendar/feeds/userID/private-magicCookie/full/eventID/comments/"
              title="alternate"/>
          </feed>
        </gd:feedLink>
      </gd:comments>
      <gd:transparency
        value="http://schemas.google.com/g/2005#event.opaque "/>
      <gd:originalEvent id="i8fl1nrv2bl57c1qgr3f0onmgg"
          href="http://www.google.com/calendar/feeds/userID/private-magicCookie/composite/eventID">
        <gd:when startTime="2006-03-17T22:00:00.000Z"/>
      </gd:originalEvent>
      <gd:where valueString="Home"/>
      <gd:when startTime="2006-03-17T23:00:00.000Z"
        endTime="2006-03-18T00:00:00.000Z"/>
    </entry>
  </gd:entryLink>
</gd:recurrenceException>

Schema

start = recurrenceException

recurrenceException =
   element gd:recurrenceException {
      attribute specialized { xs:boolean },
      (entryLink
       & originalEvent)
   }

gd:reminder

Most often used in: <gd:when>

A time interval, indicating how long before the containing entity's @startTime or @dueTime attribute a reminder should be issued. Alternatively, may specify an absolute time at which a reminder should be issued. Also specifies a notification method, indicating what medium the system should use to remind the user.

Properties

Property Type Description
@absoluteTime? xs:dateTime Absolute time at which the reminder should be issued. This is typically used when a user uses a "snooze" feature to delay a previous reminder. If the timezone is not specified, the observer's local time is assumed.
@method? xs:string The notification method the reminder should use. Can have any of the following values: alert (causes an alert to appear when a user is viewing the calendar in a browser), email (sends the user an email message), or sms (sends the user an SMS text message).
@days? xs:unsignedInt Period of time before gd:when/@startTime when a reminder should be issued. If the parent entity's target time is a date rather than a specific time, then these attributes are relative to midnight (00:00) on that date.
@hours? xs:unsignedInt
@minutes? xs:unsignedInt

When you create or edit a <gd:when> entry, use the following conventions to achieve particular results:

  • To tell the service to use the user's default reminders, include a <gd:reminder> element with no attributes. If you specify a duration but no method attribute, then the service uses the user's default notification methods with the duration you specified.
  • To tell the service to not issue any reminders for the event (or to remove existing reminders when updating an event), don't include any <gd:reminder> elements.

Restrictions

  • At most one of @days, @hours, @minutes, or @absoluteTime may be specified. To specify a mixed duration, convert to the most precise unit. For example, to specify 1 hour 30 minutes, use @minutes="90".
  • You can't use negative values for the attributes (so if you want a reminder to occur after the start time, you must use @absoluteTime).
  • A given event can't have more than five reminders associated with it.
  • When you're adding a reminder to an event, if you specify the alert, email, or sms methods, you must also specify a duration.

Examples

A 15-minute reminder for a meeting:

<gd:when startTime="2005-06-06T17:00:00-08:00" endTime="2005-06-06T18:00:00-08:00">
  <gd:reminder minutes="15"/>
</gd:when>

Same meeting as above, but snoozed for 10 minutes after the reminder at 16:45:

<gd:when startTime="2005-06-06T17:00:00-08:00" endTime="2005-06-06T18:00:00-08:00">
  <gd:reminder minutes="15"/>
  <gd:reminder absoluteTime="2005-06-06T16:55:00-08:00"/>
</gd:when>

Schema

start = reminder

reminder =
   element gd:reminder {
      gdCommonProperties,
      attribute absoluteTime { xs:dateTime }?,
      attribute method { xs:string }?,
      attribute days { xs:unsignedInt }?,
      attribute hours { xs:unsignedInt }?,
      attribute minutes { xs:unsignedInt }?
   }

gd:resourceId

An opaque resource identifier, distinct from atom:id as it need not be a valid URI. Some services provide a separate identifier to be used when constructing subsequent requests. Exact usage is service specific.

Example

<gd:resourceId>9749638</gd:resourceId>

Schema

start = resourceId

resourceId =
   element gd:resourceId { xs:string }

gd:structuredPostalAddress

Postal address split into components. It allows to store the address in locale independent format. The fields can be interpreted and used to generate formatted, locale dependent address. The following elements reperesent parts of the address: agent, house name, street, P.O. box, neighborhood, city, subregion, region, postal code, country. The subregion element is not used for postal addresses, it is provided for extended uses of addresses only. In order to store postal address in an unstructured form formatted address field is provided.

Properties

Property Type Description
@rel? xs:string Type of the address. Unless specified work type is assumed.
@mailClass? xs:string Classes of mail accepted at the address. Unless specified both is assumed.
@usage? xs:string The context in which this addess can be used. Local addresses may differ in layout from general addresses, and frequently use local script (as opposed to Latin script) as well, though local script is allowed in general addresses. Unless specified general usage is assumed.
@label? xs:string A general label for the address.
@primary? xs:boolean Specifies the address as primary. Default value is false.
gd:agent? agent The agent who actually receives the mail. Used in work addresses. Also for 'in care of' or 'c/o'.
gd:housename? housename Used in places where houses or buildings have names (and not necessarily numbers), eg. "The Pillars".
gd:street? street Can be street, avenue, road, etc. This element also includes the house number and room/apartment/flat/floor number.
gd:pobox? pobox Covers actual P.O. boxes, drawers, locked bags, etc. This is usually but not always mutually exclusive with street.
gd:neighborhood? neighborhood This is used to disambiguate a street address when a city contains more than one street with the same name, or to specify a small place whose mail is routed through a larger postal town. In China it could be a county or a minor city.
gd:city? city Can be city, village, town, borough, etc. This is the postal town and not necessarily the place of residence or place of business.
gd:subregion? subregion Handles administrative districts such as U.S. or U.K. counties that are not used for mail addressing purposes. Subregion is not intended for delivery addresses.
gd:region? region A state, province, county (in Ireland), Land (in Germany), departement (in France), etc.
gd:postcode? postcode Postal code. Usually country-wide, but sometimes specific to the city (e.g. "2" in "Dublin 2, Ireland" addresses).
gd:country? country The name or code of the country.
gd:formattedAddress? formattedAddress The full, unstructured postal address.

rel values

Value Description
http://schemas.google.com/g/2005#work Work address. Unless other provided this is the default value.
http://schemas.google.com/g/2005#home Home address.
http://schemas.google.com/g/2005#other Any other type of address.

mailClass values

Value Description
http://schemas.google.com/g/2005#both Parcels and letters can be sent to the address. Unless other provided this is the default value.
http://schemas.google.com/g/2005#letters Only letters can be sent to the address.
http://schemas.google.com/g/2005#parcels Only parcels can be sent to the address.
http://schemas.google.com/g/2005#neither Address is purely locational and cannot be used for mail.

usage values

Value Description
http://schemas.google.com/g/2005#general This address is for general usage. Unless other provided this is the default value.
http://schemas.google.com/g/2005#local This address is for local usage.

Examples

Corporate address:

mr. John Doe
Google Inc.
1600 Amphitheatre Parkway
Mountain View, CA 94043
<gd:structuredPostalAddress mailClass='http://schemas.google.com/g/2005#letters' label='John at Google'>
  <gd:street>1600 Amphitheatre Parkway</gd:street>
  <gd:city>Mountain View</gd:city>
  <gd:region>CA</gd:region>
  <gd:postcode>94043</gd:postcode>
</gd:structuredPostalAddress>

Private address:

Madame Duval
27, rue Pasteur
14390 CABOURG
FRANCE
<gd:structuredPostalAddress mailClass='http://schemas.google.com/g/2005#both' label='Madame Duval'>
  <gd:street>27, rue Pasteur</gd:street>
  <gd:city>CABOURG</gd:city>
  <gd:postcode>14390</gd:postcode>
  <gd:country>FRANCE</gd:country>
</gd:structuredPostalAddress>

Schema

start = structuredPostalAddress

structuredPostalAddress =
   element gd:structuredPostalAddress {
      attribute label { xs:string }?,
      attribute mailClass { xs:string }?,
      attribute primary { xs:boolean }?,
      attribute rel { xs:string }?,
      attribute usage { xs:string }?,
      (agent?
       & housename?
       & street?
       & poBox?
       & neighborhood?
       & city?
       & subregion?
       & region?
       & postcode?
       & country?
       & formattedAddress? )
}

Restrictions

  • It is forbidden to have both 'gd:postalAddress' and 'gd:structuredPostalAddress' in one entity.
  • Only one structured address can be specified as primary.
  • The unstructured postal address must be consistent with the structured data.

gd:when

Represents a period of time or an instant.

Properties

Property Type Description
@endTime? xs:dateTime or xs:date Describes when the event ends. If the timezone is not specified, the observer's local timezone is assumed.
@startTime xs:dateTime or xs:date Describes when the event starts or (for zero-duration events) when it occurs. If the timezone is not specified, the observer's local timezone is assumed.
@valueString? xs:string A simple string value that can be used as a representation of this time period.

Restrictions

  • It's not possible to mix xs:dateTime with xs:date in startTime/endTime.
  • If endTime is not specified, then the event is considered to be an instant in time (if @startTime includes a time) or a one-day event (if @startTime is only a date).

Examples

A one-day event:

<gd:when startTime="2005-06-06"/>

Alternative representation of a one-day event:

<gd:when startTime="2005-06-06" endTime="2005-06-07"/>

A two-day event (on June 6 and June 7) with a string description:

<gd:when startTime="2005-06-06" endTime="2005-06-08" valueString="This weekend"/>

A one-hour meeting:

<gd:when startTime="2005-06-06T17:00:00-08:00" endTime="2005-06-06T18:00:00-08:00"/>

A zero-duration event:

<gd:when startTime="2005-06-06T17:00:00-08:00"/>

Schema

start = when

when =
   element gd:when {
      gdCommonProperties,
      attribute startTime { (xs:date | xs:dateTime) },
      attribute endTime { (xs:date | xs:dateTime) }?,
      attribute valueString { xs:string }?
   }

gd:where

A place (such as an event location) associated with the containing entity. The type of the association is determined by the rel attribute; the details of the location are contained in an embedded or linked-to Contact entry.

A <gd:where> element is more general than a <gd:geoPt> element. The former identifies a place using a text description and/or a Contact entry, while the latter identifies a place using a specific geographic location.

Properties

Property Type Description
@label? xs:string Specifies a user-readable label to distinguish this location from other locations.
@rel? xs:string Specifies the relationship between the containing entity and the contained location. Possible values (see below) are defined by other elements. For example, <gd:when> defines http://schemas.google.com/g/2005#event.
@valueString? xs:string A simple string value that can be used as a representation of this location.
gd:entryLink? entryLink Entry representing location details. This entry should implement the Contact kind.

rel values

Value Description
http://schemas.google.com/g/2005#event or not specified Place where the enclosing event takes place.
http://schemas.google.com/g/2005#event.alternate A secondary location. For example, a remote site with a videoconference link to the main site.
http://schemas.google.com/g/2005#event.parking A nearby parking lot.

Examples

Event location:

<gd:where valueString="Google Cafeteria (Building 40)"/>

More complicated event location:

<gd:where rel="http://schemas.google.com/g/2005#event" valueString="Joe's Pub">
  <gd:entryLink href="http://local.example.com/10018/JoesPub">
    <gd:entry>
      <id>http://local.example.com/10018/JoesPub</id>
      <category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/g/2005#contact"/>
      <content>Nice place to listen to jazz music</content>
      <link href="http://www.joespub.com"/>
      <gd:postalAddress>500 West 45th Street, New York, NY 10018</gd:postalAddress>
      <gd:geoPt lat="40.75" lon="-74.0"/>
      <gd:phoneNumber>(212) 555-1212</gd:phoneNumber>
      <gd:email address="info@joespub.com"/>
    </gd:entry>
  </gd:entryLink>
</gd:where>

Event with multiple locations:

<gd:where label="Mountain View Location (main)"
         valueString="Google Cafeteria (Building 40)"/>

<gd:where rel="http://schemas.google.com/g/2005#event.alternate"
         label="New York Location (videoconference)"
         valueString="Metropolis"/>

Schema

start = where

where =
   element gd:where {
      gdCommonProperties,
      attribute rel { xs:string }?,
      attribute label { xs:string }?,
      attribute valueString { xs:string }?,
      (entryLink?)
   }

gd:who

A person associated with the containing entity. The type of the association is determined by the rel attribute; the details about the person are contained in an embedded or linked-to Contact entry.

The <gd:who> element can be used to specify email senders and recipients, calendar event organizers, and so on.

Properties

Property Type Description
@email? xs:string Email address. This property is typically used when <gd:entryLink> is not specified. The address must comply with RFC 2822, section 3.4.1.
@rel? xs:string Specifies the relationship between the containing entity and the contained person. See below for possible values.
@valueString? xs:string A simple string value that can be used as a representation of this person.
gd:attendeeStatus? gEnumConstruct Status of event attendee. Extensible enum documented below.
gd:attendeeType? gEnumConstruct Type of event attendee. Extensible enum documented below.
gd:entryLink? entryLink Entry representing person details. This entry should implement the Contact kind. In many cases, this entry will come from a contact feed.

rel values

The valid values for @rel depend on which kind the <gd:who> element appears in.

Value Kind Description
http://schemas.google.com/g/2005#event.attendee Event A general meeting/event attendee.
http://schemas.google.com/g/2005#event.organizer Event Event organizer. An organizer is not necessarily an attendee.
http://schemas.google.com/g/2005#event.performer Event Performer. Similar to http://schemas.google.com/g/2005#event.speaker, but with more emphasis on art than speech delivery.
http://schemas.google.com/g/2005#event.speaker Event Speaker.
http://schemas.google.com/g/2005#message.bcc Message Message BCC recipient.
http://schemas.google.com/g/2005#message.cc Message Message CC recipient.
http://schemas.google.com/g/2005#message.from Message Message (email or IM) sender.
http://schemas.google.com/g/2005#message.reply-to Message Intended recipient of a reply message.
http://schemas.google.com/g/2005#message.to Message Message primary recipient.

gd:attendeeType Values

Value Description
http://schemas.google.com/g/2005#event.optional Optional attendee.
http://schemas.google.com/g/2005#event.required Required attendee.

gd:attendeeStatus Values

Value Description
http://schemas.google.com/g/2005#event.accepted Attendee has accepted.
http://schemas.google.com/g/2005#event.declined Attendee has declined.
http://schemas.google.com/g/2005#event.invited Invitation has been sent, but the person has not accepted.
http://schemas.google.com/g/2005#event.tentative Attendee has accepted tentatively.

Examples

Email recipients:

<gd:who rel="http://schemas.google.com/g/2005#message.from" email="jo@example.com"/>
<gd:who rel="http://schemas.google.com/g/2005#message.to" valueString="Elizabeth" email="liz@example.com"/>

Meeting attendee:

<gd:who rel="http://schemas.google.com/g/2005#event.attendee" valueString="Jo">
  <gd:attendeeType value="http://schemas.google.com/g/2005#event.required"/>
  <gd:attendeeStatus value="http://schemas.google.com/g/2005#event.tentative"/>
  <gd:entryLink href="http://gmail.com/jo/contacts/Jo">
    <entry>
      <id>http://gmail.com/jo/contacts/Jo</id>
      <category term="user-tag" label="Google"/>
      <title>Jo March</title>
      <gd:email address="jo@example.com"/>
      <gd:phoneNumber label="work">(650) 555-1212</gd:phoneNumber>
    </entry>
  </gd:entryLink>
</gd:who>

Event organizer:

<gd:who rel="http://schemas.google.com/g/2005#event.organizer" valueString="Receptionist 41"/>

Schema

start = who

who =
   element gd:who {
      gdCommonProperties,
      attribute rel { xs:string }?,
      attribute email { xs:string }?,
      attribute valueString { xs:string }?,
      (entryLink?
       & element gd:attendeeType { gEnumConstruct }?
       & element gd:attendeeStatus { gEnumConstruct }?)
   }

Back to top

Changes since 1.0

Changes to the contact kind

The following elements not present in version 1.0 were added in version 2.0 of the contact kind:

The following phone types not present in version 1.0 were added in version 2.0:

  • http://schemas.google.com/g/2005#assistant
  • http://schemas.google.com/g/2005#callback
  • http://schemas.google.com/g/2005#car
  • http://schemas.google.com/g/2005#company_main
  • http://schemas.google.com/g/2005#isdn
  • http://schemas.google.com/g/2005#main
  • http://schemas.google.com/g/2005#other_fax
  • http://schemas.google.com/g/2005#radio
  • http://schemas.google.com/g/2005#telex
  • http://schemas.google.com/g/2005#tty_tdd
  • http://schemas.google.com/g/2005#work_mobile
  • http://schemas.google.com/g/2005#work_pager

The following IM type not present in version 1.0 was added in version 2.0:

  • http://schemas.google.com/g/2005#netmeeting

The following elements of the 1.0 contact kind are no longer supported:

Changes to gd:email

The new attribute @displayName was added in gd:email in 2.0

Changes to gd:organization

The following subelements of gd:organization were introduced in 2.0:

  • gd:orgDepartment
  • gd:orgJobDescription
  • gd:orgSymbol
  • gd:where

Changes to gd:orgName

In version 2.0 the element gd:orgName was enhanced by adding the @yomi attribute to it.

Back to top