Network Working Group C. Joy Internet-Draft Oracle Intended status: Standards Track C. Daboo Expires: July 29, 2013 Apple Inc. M. Douglass RPI January 25, 2013 vCard representation of resources draft-cal-resource-vcard-02 Abstract This specification describes the vCard representation of resources. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on July 29, 2013. Copyright Notice Copyright (c) 2013 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Joy, et al. Expires July 29, 2013 [Page 1] Internet-Draft vCard for Resources January 2013 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Conventions Used in This Document . . . . . . . . . . . . . . 3 3. General Considerations . . . . . . . . . . . . . . . . . . . . 3 4. Resource Object . . . . . . . . . . . . . . . . . . . . . . . 3 5. Resource Properties . . . . . . . . . . . . . . . . . . . . . 3 5.1. Mandatory Properties . . . . . . . . . . . . . . . . . . . 3 5.2. Special Notes: . . . . . . . . . . . . . . . . . . . . . . 3 5.2.1. KIND . . . . . . . . . . . . . . . . . . . . . . . . . 3 5.3. Base vCard Properties . . . . . . . . . . . . . . . . . . 4 5.4. New vCard Properties for resources . . . . . . . . . . . . 5 5.4.1. ACCESSIBLE . . . . . . . . . . . . . . . . . . . . . . 5 5.4.2. ACCESSIBILITYINFO . . . . . . . . . . . . . . . . . . 5 5.4.3. CAPACITY . . . . . . . . . . . . . . . . . . . . . . . 5 5.4.4. INVENTORY . . . . . . . . . . . . . . . . . . . . . . 6 5.4.5. LOCATIONTYPE . . . . . . . . . . . . . . . . . . . . . 6 5.4.6. RESTRICTED . . . . . . . . . . . . . . . . . . . . . . 7 5.4.7. RESTRICTEDACCESSINFO . . . . . . . . . . . . . . . . . 7 5.4.8. NOCOST . . . . . . . . . . . . . . . . . . . . . . . . 8 5.4.9. COSTINFO . . . . . . . . . . . . . . . . . . . . . . . 8 5.5. New Parameter Values . . . . . . . . . . . . . . . . . . . 8 5.5.1. RELATED TYPE Values . . . . . . . . . . . . . . . . . 9 6. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 6.1. Location Resource . . . . . . . . . . . . . . . . . . . . 9 6.2. Role Resources Group . . . . . . . . . . . . . . . . . . . 10 7. Security Considerations . . . . . . . . . . . . . . . . . . . 11 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 8.1. VCard Property and Value Registration . . . . . . . . . . 11 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 12 10. Unresolved Issues . . . . . . . . . . . . . . . . . . . . . . 12 11. Normative References . . . . . . . . . . . . . . . . . . . . . 13 Joy, et al. Expires July 29, 2013 [Page 2] Internet-Draft vCard for Resources January 2013 1. Introduction This specification defines the vCard representation of resources to ease their discovery by clients. 2. Conventions Used 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 [RFC2119] . 3. General Considerations Data values MUST have valid representation for the specified value type with respect to escape characters, line folding, and so on. 4. 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 Section 5 . 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 vCard Format Specification [RFC6350] can be used to include additional contact information for the resource. 5. Resource Properties 5.1. Mandatory Properties The following properties MUST be specified in a vCard representing a resource: o FN o UID o KIND 5.2. Special Notes: 5.2.1. KIND Some of the possible values for the KIND property are "Location", "Individual", "Device", or "Group". Joy, et al. Expires July 29, 2013 [Page 3] Internet-Draft vCard for Resources January 2013 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. 5.3. Base vCard Properties The following properties defined in [RFC6350] or [RFC2739] make sense for vCards representing resources (this list is not exhaustive, and other properties might be applicable as well): o ADR o CATEGORIES o EMAIL o FBURL o FN o KIND o MEMBER o NOTE o NICKNAME o ORG o PHOTO o RELATED o TZ o UID Joy, et al. Expires July 29, 2013 [Page 4] Internet-Draft vCard for Resources January 2013 5.4. New vCard Properties for resources Format and cardinality of new vCard properties are defined as described in Section 3.3 of [RFC6350]. 5.4.1. ACCESSIBLE Purpose: Specify if the resource is accessible to physically disabled people. ValueType: Boolean value. Cardinality: *1 ABNF: ACCESSIBLE-param = "VALUE=boolean" / any-param ACCESSIBLE-value = boolean Default value: FALSE. Example value: TRUE 5.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 5.4.3. CAPACITY Joy, et al. Expires July 29, 2013 [Page 5] Internet-Draft vCard for Resources January 2013 Purpose: Provide information on the capacity of the resource. ValueType: Integer. Cardinality: *1 ABNF: CAPACITY-param = "VALUE=integer" / any-param CAPACITY-value = integer Default value: None Example value: 10 5.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 http://www.example.com/Room1Inventory.vcf 5.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 [RFC4589] Joy, et al. Expires July 29, 2013 [Page 6] Internet-Draft vCard for Resources January 2013 Cardinality: * ABNF: LOCATIONTYPE-param = "VALUE=text" / any-param LOCATIONTYPE-value = text Default value: None Example value: office 5.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: *1 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 5.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 Joy, et al. Expires July 29, 2013 [Page 7] Internet-Draft vCard for Resources January 2013 Default value: None Example value: http://www.example.com/room1_entryinfo.html 5.4.8. NOCOST Purpose: Specify if there is a cost associated with using the resource. ValueType: Boolean value. Cardinality: *1 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 5.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 5.5. New Parameter Values Joy, et al. Expires July 29, 2013 [Page 8] Internet-Draft vCard for Resources January 2013 5.5.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 Section 6.6.6 of [RFC6350]. o container: an entity that contains the entity associated with this vCard. For example, the building that contains the room resource specified by the vCard. o manager: an entity that manages the resource entity associated with this vCard. o owner: an entity that owns the resource entity associated with this vCard. 6. Examples 6.1. Location Resource Joy, et al. Expires July 29, 2013 [Page 9] Internet-Draft vCard for Resources January 2013 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 6.2. Role Resources Group Joy, et al. Expires July 29, 2013 [Page 10] Internet-Draft vCard for Resources January 2013 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 7. 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. 8. IANA Considerations 8.1. VCard Property and Value Registration The following new VCard Properties need to be registered by IANA. Joy, et al. Expires July 29, 2013 [Page 11] Internet-Draft vCard for Resources January 2013 New VCard Properties Table: +----------------------+---------------------------+ | VCard Property Name | VCard Property Definition | +----------------------+---------------------------+ | ACCESSIBLE | Section 5.4.1 | | ACCESSIBILITYINFO | Section 5.4.2 | | CAPACITY | Section 5.4.3 | | COSTINFO | Section 5.4.9 | | INVENTORY | Section 5.4.4 | | LOCATIONTYPE | Section 5.4.5 | | NOCOST | Section 5.4.8 | | RESTRICTED | Section 5.4.6 | | RESTRICTEDACCESSINFO | Section 5.4.7 | +----------------------+---------------------------+ The following new VCard Parameter Values need to be registered by IANA. New VCard Properties Table: +--------------------+---------------------+------------------------+ | VCard Property | VCard Parameter | VCard Parameter Value | | Name | Name | | +--------------------+---------------------+------------------------+ | RELATED | TYPE | container | | | | Section 5.5.1 | | RELATED | TYPE | manager Section 5.5.1 | | RELATED | TYPE | owner Section 5.5.1 | +--------------------+---------------------+------------------------+ 9. 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. 10. 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 Joy, et al. Expires July 29, 2013 [Page 12] Internet-Draft vCard for Resources January 2013 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? 11. Normative References [ISO.8601.2004] International Organization for Standardization, "Data elements and interchange formats -- Information interchange -- Representation of dates and times", 2004. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC2739] Small, T., Hennessy, D., and F. Dawson, "Calendar Attributes for vCard and LDAP", RFC 2739, January 2000. [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the Internet: Timestamps", RFC 3339, July 2002. [RFC4589] Schulzrinne, H. and H. Tschofenig, "Location Types Registry", RFC 4589, July 2006. [RFC6350] Perreault, S., "vCard Format Specification", RFC 6350, August 2011. Authors' Addresses Ciny Joy Oracle Corporation 4210 Network Circle Santa Clara, CA 95054 USA EMail: ciny.joy@oracle.com URI: http://www.oracle.com/ Joy, et al. Expires July 29, 2013 [Page 13] Internet-Draft vCard for Resources January 2013 Cyrus Daboo Apple Inc. 1 Infinite Loop Cupertino, CA 95014 USA EMail: cyrus@daboo.name URI: http://www.apple.com/ Michael Douglass Rensselaer Polytechnic Institute 110 8th Street Troy, NY 12180 USA EMail: douglm@rpi.edu URI: http://www.rpi.edu/ Joy, et al. Expires July 29, 2013 [Page 14]