Abstract

This specification describes the vCard representation of resources.

vCard representation of resources

1. Scope

This document specifies the vCard representation of resources to ease their discovery by clients.

2. Normative references

The following documents are referred to in the text in such a way that some or all of their content constitutes requirements of this document. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments) applies.

IETF RFC 2119, BRADNER, S. Key words for use in RFCs to Indicate Requirement Levels. 1997. RFC Publisher. https://www.rfc-editor.org/info/rfc2119.

IETF RFC 2739, SMALL, T., D. HENNESSY, F. DAWSON and Internet Engineering Task Force. Calendar Attributes for vCard and LDAP. 2000. RFC Publisher. https://www.rfc-editor.org/info/rfc2739.

IETF RFC 3339, KLYNE, G., C. NEWMAN and Internet Engineering Task Force. Date and Time on the Internet: Timestamps. 2002. RFC Publisher. https://www.rfc-editor.org/info/rfc3339.

IETF RFC 4589, SCHULZRINNE, H., H. TSCHOFENIG and Internet Engineering Task Force. Location Types Registry. 2006. RFC Publisher. https://www.rfc-editor.org/info/rfc4589.

IETF RFC 6350, PERREAULT, S. and Internet Engineering Task Force. vCard Format Specification. 2011. RFC Publisher. https://www.rfc-editor.org/info/rfc6350.

ISO 8601:2004, International Organization for Standardization (committee). Data elements and interchange formats — Information interchange — Representation of dates and times. Third edition. 2004. Geneva: International Organization for Standardization. https://www.iso.org/standard/40874.html.

3. Terms and definitions

No terms and definitions are listed in this document.

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in IETF RFC 2119.

4. General Considerations

Data values MUST have valid representation for the specified value type with respect to escape characters, line folding, and so on.

5. Resource Object

A resource object definition SHOULD contain all information required to find the right resource. For this, it SHOULD contain all, or a set of properties described in Clause 6. Additional proprietary properties may be defined as well, but MUST begin with “X-”. Clients encountering properties they don’t know about MUST ignore them.

Properties required to contact the resource are not included in this specification. vCard properties defined in IETF RFC 6350 can be used to include additional contact information for the resource.

6. Resource Properties

6.1. Mandatory Properties

The following properties MUST be specified in a vCard representing a resource:

FN
UID
KIND

6.2. Special Notes:

6.2.1. KIND

Some of the possible values for the KIND property are “Location”, “Individual”, “Device”, or “Group”.

Location is used for any physical location resource such as room, building, etc.

Individual is used for a human resource such as driver, technician, etc.

Device is used for a computing device such as an appliance, a computer, or a network element.

Group is used to specify a group of resources with a specific skill set. For example: drivers, electricians, etc.

6.3. Base vCard Properties

The following properties defined in IETF RFC 6350 or IETF RFC 2739 make sense for vCards representing resources (this list is not exhaustive, and other properties might be applicable as well):

ADR
CATEGORIES
EMAIL
FBURL
FN
KIND
MEMBER
NOTE
NICKNAME
ORG
PHOTO
RELATED
TZ
UID

6.4. New vCard Properties for resources

Format and cardinality of new vCard properties are defined as described in IETF RFC 6350, Section 3.3.

6.4.1. ACCESSIBLE

Purpose

Specify if the resource is accessible to physically disabled people.

ValueType

Boolean value.

Cardinality

ABNF

ACCESSIBLE-param = "VALUE=boolean" / any-param
ACCESSIBLE-value = boolean

Default value

FALSE.

Example value

TRUE

6.4.2. ACCESSIBILITYINFO

Purpose

Specify special resource accessibility info for the physically disabled people.

ValueType

URI value. It MAY also be a free-form text value.

Cardinality

ABNF

ACCESSIBILITYINFO-param = "VALUE=" ("text" / "uri") /
                           any-param
ACCESSIBILITYINFO-value = URI / text

Default value

None

Example value

http://www.example.com/room1_specialaccess.html

6.4.3. CAPACITY

Purpose

Provide information on the capacity of the resource.

ValueType

Integer.

Cardinality

ABNF

CAPACITY-param = "VALUE=integer" / any-param
CAPACITY-value = integer

Default value

None

Example value

6.4.4. INVENTORY

Purpose

List other resources available as part of this resource.

ValueType

Value MAY be a URI that could be a vCard. The vCard could be of the KIND group whose members point to the various inventory items.

Value MAY also be a free form text listing one or more inventory items.

Cardinality

ABNF

INVENTORY-param = "VALUE=" ("text" / "uri") / any-param
INVENTORY-value = uri / text

Default value

None

Example values

Printer, Projector or http://www.example.com/Room1Inventory.vcf

6.4.5. LOCATIONTYPE

Purpose

Provide more information on the type of a LOCATION resource.

ValueType

Text. The value SHOULD be one of the values defined in RFC 4589.

Cardinality

ABNF

LOCATIONTYPE-param = "VALUE=text" / any-param
LOCATIONTYPE-value = text

Default value

None

Example value

office

6.4.6. RESTRICTED

Purpose

Specify if there are restrictions to physically accessing the resource. For example locked doors, or other barriers.

ValueType

Boolean value.

Cardinality

ABNF

RESTRICTED-param = "VALUE=boolean" / any-param
RESTRICTED-value = boolean

Default value

FALSE.

Absence of this property indicates no restriction to physically accessing the resource.

Example value

TRUE

6.4.7. RESTRICTEDACCESSINFO

Purpose

Specify extra information on physically accessing resources that have restrictions. For example where to pick up keys to a locked resource.

ValueType

URI value. It MAY also be a free-form text value.

Cardinality

ABNF

RESTRICTEDACCESSINFO-param = "VALUE=" ("text" / "uri") /
                             any-param
RESTRICTEDACCESSINFO-value = URI / text

Default value

None

Example value

http://www.example.com/room1_entryinfo.html

6.4.8. NOCOST

Purpose

Specify if there is a cost associated with using the resource.

ValueType

Boolean value.

Cardinality

ABNF

NOCOST-param = "VALUE=boolean" / any-param
NOCOST-value = boolean

Special Notes

If this property is absent, it indicates that the resource may be booked free of cost.

Default value

TRUE

Example value

TRUE

6.4.9. COSTINFO

Purpose

Provide the URL pointing to complete pricing information for usage of the resource.

ValueType

URI value. It MAY also be a free-form text value.

Cardinality

ABNF

COSTINFO-param = "VALUE=" ("text" / "uri") / any-param
COSTINFO-value = uri / text

Default value

None

Example value

http://www.example.com/cost.html

7. New Parameter Values

7.1. RELATED TYPE Values

This document specifies the following additional values that can be used as the value for the TYPE parameter of the RELATED property defined in IETF RFC 6350, Section 6.6.6.

container: an entity that contains the entity associated with this vCard. For example, the building that contains the room resource specified by the vCard.
manager: an entity that manages the resource entity associated with this vCard.
owner: an entity that owns the resource entity associated with this vCard.

8. Examples

8.1. Location Resource

In this example we make use of OBJECTCLASS:schedulable to make this a schedulable resource.

BEGIN:VCARD
VERSION:4.0
UID:urn:uuid:room1-id
KIND: location
LOCATIONTYPE: classroom
FN: Room One
ORG: Engineering
NICKNAME: The One
NOTE: Room 1 in Engineering Building X
CATEGORIES: rooms, engineering_resources
OBJECTCLASS:schedulable
BOOKINGRESTRICTED: TRUE
BOOKINGINFO: http://www.example.com/room1_booking.html
CALADRURI: mailto:room1@example.com
MULTIBOOK: 1
MAXINSTANCES: 10
BOOKINGWINDOWSTART:P3M
BOOKINGWINDOWEND: P3D
AUTOSCHEDULE: AUTO
RELATED;TYPE=schedule-admin:
 http://www.example.com/SchedAdmin1.vcf
ACCESSIBLE: TRUE
ACCESSIBILITYINFO: http://www.example.com/room1_disabledaccess.html
CAPACITY: 100
INVENTORY: phone, projector
FBURL: http://www.example.com/freebusy/home/Room1/
TZ: America/Los_Angeles
RELATED;TYPE=owner: http://www.example.com/ResOwner1.vcf
RELATED;TYPE=manager: http://www.example.com/ResManager1.vcf
RELATED;TYPE=container:http://www.example.com/BldX.vcf
RESTRICTED: TRUE
RESTRICTEDACCESSINFO: http://www.example.com/room1_specialaccess.html
NOCOST: FALSE
COSTINFO: http://www.example.com/cost.html
END:VCARD

8.2. Role Resources Group

This example also makes use of OBJECTCLASS:schedulable to make this a schedulable resource.

BEGIN:VCARD
VERSION:4.0
UID:urn:uuid:driverXPool-id
KIND: group
FN: Driver X Pool
ORG: Transportation
NICKNAME: The X Group
NOTE: Drivers in the Transportation department driver pool X
CATEGORIES: drivers
MEMBER:urn:uuid:driver1-id
MEMBER:urn:uuid:driver2-id
MEMBER:urn:uuid:driver3-id
FBURL: http://www.example.com/freebusy/home/DriversX/
OBJECTCLASS:schedulable
CALADRURI: mailto:driversX@example.com
MULTIBOOK: 3
MAXINSTANCES: 10
BOOKINGWINDOWSTART:P3M
BOOKINGWINDOWEND: P3D
AUTOSCHEDULE: NONE
RELATED;TYPE=schedule-admin:
 http://www.example.com/DriversX_SchedAdmin.vcf
TZ: America/Los_Angeles
BOOKINGINFO: http://www.example.com/driversX_approval.html
RELATED;TYPE=manager:
 http://www.example.com/DriversManager.vcf
NOCOST: FALSE
COSTINFO: http://www.example.com/driversXcost.html
END:VCARD

9. Security Considerations

As this document only defines schema for representing resource information for calendaring and scheduling and does not refer to the actual storage mechanism itself, or the calendaring and scheduling protocol, no special security considerations are required as part of this document.

10. IANA Considerations

10.1. VCard Property and Value Registration

The following new VCard Properties need to be registered by IANA.

Table 1 — New VCard Properties Table
VCard Property Name	VCard Property Definition
`ACCESSIBLE`	Clause 6.4.1
`ACCESSIBILITYINFO`	Clause 6.4.2
`CAPACITY`	Clause 6.4.3
`COSTINFO`	Clause 6.4.9
`INVENTORY`	Clause 6.4.4
`LOCATIONTYPE`	Clause 6.4.5
`NOCOST`	Clause 6.4.8
`RESTRICTED`	Clause 6.4.6
`RESTRICTEDACCESSINFO`	Clause 6.4.7

The following new VCard Parameter Values need to be registered by IANA.

Table 2 — New VCard Parameter Values Table
VCard Property Name	VCard Parameter Name	VCard Parameter Value
`RELATED`	`TYPE`	container Clause 7.1
`RELATED`	`TYPE`	manager Clause 7.1
`RELATED`	`TYPE`	owner Clause 7.1

11. Acknowledgments

This specification is a result of discussions that took place within the Calendaring and Scheduling Consortium’s Resource Technical Committee. The authors thank the participants of that group, and specifically the following individuals for contributing their ideas and support: Arnaud Quillaud, Adam Lewenberg, Andrew Laurence, Guy Stalnaker, Mimi Mugler, Dave Thewlis, Bernard Desruisseaux, Alain Petit, Andrew Sciberras, Adrian Apthorp, and Jason Miller.

12. Unresolved Issues

Defining finer granularity of resource KIND — A schedulable resource might not exactly correspond to a specific one in the list of pre-defined values for KIND. Question is how to convey the additional information. Possibilities are extending KIND values to include all combinations, defining an objectclass model where an object is built out of many pre-defined KINDs, or defining standard parameter extensions to KIND to include more information.

Defining RESOURCETYPE — For a location resource, a new property LOCATIONTYPE was added to provide more information. Are similar new properties required for non-location resources? Or do we need a generic RESOURCETYPE property with a set of predefined values?