INTERNET-DRAFT Jeff Bone, Activerse Expires: Sept 1998 Lisa Dusseault, Microsoft RVP Schemas draft-dusseault-rvp-schema-00.txt 1. Status of this Memo This document is an Internet-Draft. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts. Internet-Drafts are draft documents valid for a maximum of six months 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." To learn the current status of any Internet-Draft, please check the "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow Directories on ds.internic.net (US East Coast), nic.nordu.net (Europe), ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific Rim). 2. Abstract The RVP protocol [2] can be used to query properties of objects, subscribe to certain kinds of events, and send instant messages to objects. These objects are often users, but there are other classes of objects as well. A schema needs to be defined which applies to all kinds of RVP objects, as well as more detailed schemas for the most commonly used objects, users and groups. The required properties for all RVP objects include common name (Cn), schema type and access control list. The required properties for a user object, which represents a single human user of the system, include status, status message, email address and directory server address. The required properties for a group object, which represents a list of objects which may be messaged all at once by messaging this group, include member- count and owner. Bone & Dusseault [Page 1] INTERNET-DRAFT RVP Schemas Mar 13, 1998 3. Contents 1. Status of this Memo.........................................1 2. Abstract....................................................1 3. Contents....................................................2 4. Overview....................................................3 4.1. The User Schema.......................................3 4.2. Group Schema..........................................3 5. Outline of a Schema.........................................4 5.1. Properties............................................4 5.2. Subscriptions Lists...................................4 5.3. Access Control lists..................................4 5.4. Timeouts..............................................4 5.5. Default Values........................................5 6. Schemas.....................................................5 6.1. Format of schema properties...........................5 6.2. All RVP Objects.......................................6 6.2.1. Schema-type property..............................6 6.2.2. Cn...............................................6 6.2.3. Link..............................................6 6.3. User Schema...........................................7 6.3.1. Status............................................7 6.3.2. Online-status.....................................7 6.3.3. Dir-entry.........................................8 6.3.4. V-Card............................................8 6.3.5. LastOn............................................8 6.3.6. LastOff...........................................8 6.3.7. Offline-msg.......................................9 6.3.8. Online-msg........................................9 6.3.9. Active-clients....................................9 6.4. Group Schema.........................................10 6.4.1. Online-members...................................10 6.4.2. Expires-offline..................................11 6.4.3. Multicast-addr...................................11 6.4.4. Max-Timeout......................................11 6.4.5. Total-members....................................12 6.4.6. Archive..........................................12 6.4.7. Owner............................................12 6.4.8. List-info........................................12 6.4.9. Recurses.........................................12 7. Extending Schemas..........................................13 7.1. Extending Existing Schemas...........................13 7.1.1. Storing private information in namespace.........13 7.2. Defining New Schemas.................................13 7.3. Auto-discovery of schemas............................14 8. REFERENCES.................................................14 9. Authors' Addresses.........................................14 Bone & Dusseault [Page 2] INTERNET-DRAFT RVP Schemas Mar 13, 1998 4. Overview The RVP system is designed to provide dynamic information, not static information. As such, all properties of objects are dynamic, RVP-specific or very frequently queried by RVP users. Some static properties such as the "directory address" property for users and the "list-info" property for groups are required so that users can find out where static information is supposed to reside. 4.1. The User Schema The user object is the most easily understood RVP object: it represents a user. Some interesting properties of a user: - They can have a status of offline, active, idle or busy. - They may have a directory entry with static information. - They may have a message intended for other users to see when they are offline. - They may have a message intended for other users to see when they are online. - They have an access control list (ACL) which defines who can see the user object and who can message the user object. - They have a subscription list (SL) which defines who wants to receive instant messages which are sent to this user, and who wants to receive notifications of things which change (certain events) on the user object. There must also be an access control list for each property which defines who can read and who can write this property. There may also be a timeout value for each property: for example, the status of "active" times out to "offline" if the user does not refresh the status property with a new timeout value. Every entry in a subscription list contains the RVP address of the subscriber, the address to send the notification to (the callback, which may be a proxy address), and the kind of notification they are interested in. Each entry in the subscription list may also have a timeout entry and an access control list. Some access control or other security mechanism for the subscription list is required so that a malicious third- party cannot cancel other people's subscriptions at will, but subscribers can cancel their own subscriptions. 4.2. Group Schema The next object to define is the group schema. A group is a list of RVP objects which all receive an instant message sent to the group. The group is an object itself because it is in many ways similar to the user object. - Users can post to the group just like a user, the server forwards to the members of the group. Bone & Dusseault [Page 3] INTERNET-DRAFT RVP Schemas Mar 13, 1998 - Users will want to know how many members of the group are online, similar to knowing if a user is online. Other aspects of groups are unique: - Some groups will have a dynamic list of members who are all online - Some groups will have a static list of members, some of whom may be online. - Users may want to know what the total number of online & offline members is 5. Outline of a Schema 5.1. Properties Any property may have an ACL, default value, timeout value and max timeout value. 5.2. Subscriptions Lists Every entry in an SL may have an ACL and a timeout value. The SL might have a max timeout value. The SL itself may also have an ACL to decide who can GET the list, delete it, etc. 5.3. Access Control lists Access Control Lists (ACL) are defined for DAV in [3]. These are very flexible lists which can define access per user, per access type. A user might be able to GET a property, but not SUBSCRIBE to it or set it with PUT. ACL may define access by inclusion or exclusion. ACLs are set on a property or object by sending an ACL method message with a text/XML body. XML is flexible enough to allow for additional access types and levels not foreseen here. Every object and property may have an ACL. The ACL for the object defines who send NOTIFY messages to the object, who can SUBSCRIBE to messages from the object, who can use PUT to change ACLs within the object, who can use GET to read ACLs within the object, and who can DELETE the entire object. For example, on a user object, SUBSCRIBE access is typically granted to the user only, NOTIFY access to everybody except a few people who hassle the user, and ACL/PUT/GET/DELETE access to the user and their admin only. An example of ACLs on a property: for the status property of a user object, PUT would be restricted to the user, GET and SUBSCRIBE would be granted to everybody but a few users, and NOTIFY/DELETE would be meaningless and therefore might be disallowed to everybody. 5.4. Timeouts Timeout fields indicate the exact date and time when a property or a list entry should expire. These fields are formatted Bone & Dusseault [Page 4] INTERNET-DRAFT RVP Schemas Mar 13, 1998 according to ISO8601. The value of the timeout field may also be "never". For any property which can have a timeout, the server may also maintain a maximum expiry duration. For example, if a user tries to set the timeout on a subscription entry for longer than a day away, the server may return a message which indicates that the subscription was accepted but the timeout value was set to a value of the server's choosing (specified in the return message). When a list entry (ACL or SL) expires, the server should delete the entry. It is not required that an implementation support timeouts on ACL entries. It is required that an implementation support timeouts on SL entries. When a property expires, the server should set the property to the default value. 5.5. Default Values Properties which can expire (have timeout fields) should also have default values. When the timeout is reached, the server should set the property to the default value. For example, the default value for the "status" field must be "offline". 6. Schemas 6.1. Format of schema properties Each schema property listed hereafter has several things specified. The format of the property, the value, a description of what the property is for, and an example are all pretty self- explanatory. The "required" bit specifies whether or not this must be supported by a server implementation. Properties which are supported by a server may still have a null value, and where that is possible this is noted explicitly. The "subscribable" information specifies whether the server implementation must permit subscriptions to this property. "No" means that an implementation is not required to support subscriptions to this property, although an implementation may support it anyway. The "has" entry specifies what the server needs to have for each property. All properties must have an Access Control List (ACL) and may have to specify certain kinds of access, such as GET, PUT and SUBSCRIBE, which are explicitly included in this specification. Finally, the property may have to have a timeout Bone & Dusseault [Page 5] INTERNET-DRAFT RVP Schemas Mar 13, 1998 (TO) and default value (DV). When a specific DV is required by this specification, it is included. Items which are missing from the "has" entry are optional. 6.2. All RVP Objects All RVP Objects have an ACL and an SL. The SL is used to list all subscriptions relating to that object, including subscriptions to receive notifications sent to that object and subscriptions to receive notifications when a particular property of the object changes. RVP objects can have content. For example, the authors envision the content of an online document would be its text, and users can subscribe to its properties. The issue has been raised that user objects might have some sort of dynamic content to replace some of their properties, but this issue has not been resolved yet. In addition, all RVP Objects have the following properties: 6.2.1. Schema-type property Format: string Value: "user" | "group" | other defined schema Has: ACL (put, get) Required: Yes Subscribable: No Description: This allows the client to look up which scheme to apply to the object. The client can then know what properties are likely to be present. Issue: We also need to define some way of showing that a new schema is a sub-class of a known schema. 6.2.2. Cn Format: String Value: Common name of object Has: ACL (put, get) Required: Yes Subscribable: No Example: "Joe User" 6.2.3. Link Format: String Value: "REFER":[url] | "REFER-IM":[url] | "PROXY":[url] | "LINK":[url] | null Has: ACL (put, get) TO Required: No Subscribable: No Example: REFER:rvp://host.com/joeuser Bone & Dusseault [Page 6] INTERNET-DRAFT RVP Schemas Mar 13, 1998 Description: this is how another server or client can take over control of the node. A detailed discussion of referral and proxying can be found in the RVP draft [2]. Linking is much simpler: the LINK value merely means that this object is only a pointer to an object stored elsewhere, but which this server is still responsible for. 6.3. User Schema All user objects may have the following properties in addition to properties required for all objects. 6.3.1. Status Format: String Value: "offline" | "online" Has: ACL (put, get, subscribe), TO, DV = "offline" Required: Yes Subscribable: Yes Description: This indicates the user's online status. Online status is used only when the user's has an open TCP connection to the server which is responsible for the user's status, or if UDP is used between client and server then this property must be refreshed before the timeout (recommended 10 minutes) or the user will be marked as "offline". If the server realizes that the connection is lost or the property has not been refreshed, the server is responsible for marking the user as offline. Thus, online/offline status is determined by the client/server connection. The exception is when a client wishes to be online yet appear offline (invisible). 6.3.2. Online-status Format: String Value: "available" | "busy" | "idle" Has: ACL (put, get, subscribe), TO, DV = "offline" Required: Yes Subscribable: Yes Description: Idle status is determined by the user's client. If the client detects no input on the system hardware after a certain time, the client should set this property on the server to "idle". The client may change status back to "active" if new input is detected, or the server may change status to "offline" if the connection is dropped or the property times out. Busy status is set by the user and can be taken to mean "do not disturb". The user decides when they are busy, and when they are no longer busy (active). The server can change the status to "offline" if the connection is dropped or the property times out. Bone & Dusseault [Page 7] INTERNET-DRAFT RVP Schemas Mar 13, 1998 Keeping these two status fields accurate, a job for clients, servers and users, is important for a presence system. A user should never appear as "available" if they have not touched their computer (or other client) in over 15 minutes, or "online" if the connection was lost. 6.3.3. Dir-entry Format: String Value: URL or blank Has: ACL (put, get) Required: Yes Subscribable: No Example: "URI:ldap://host.com:6666/o=3DABC%20Industries\, c=3DUS??(cn=3DBJoe%20Users" Description: this field points to the directory entry, typically a LDAP URL but possibly a web page or other URL/URI, where static information for the user can be found. Static information might include phone number, email address, public key, etc. 6.3.4. V-Card Format: String Value: URL or blank Has: ACL (put, get) Required: No Subscribable: No Description: this field points to a location where a VCard can be found for the user object. 6.3.5. LastOn Format: date/time (RFC 1123) Value: Date and time user last logged on Required: No Has: ACL (put, get) Subscribable: No Example: 06 Nov 1994 08:49:37 GMT Description: This field records the last time the user became active. The server should set this field. If multiple clients are used, the server records the last time any client became active. 6.3.6. LastOff Format: date/time (RFC 1123) Value: Date and time user last logged off (became "offline") Required: No Subscribable: No Has: ACL (put, get) Bone & Dusseault [Page 8] INTERNET-DRAFT RVP Schemas Mar 13, 1998 Description: If the user has multiple clients, the server records the last time the user was completely offline (no online clients). 6.3.7. Offline-msg Format: MIME-type, typically text/plain Value: Message intended for use when user is offline Has: ACL (put, get, subscribe), TO, DV. Required: no Subscribable: Yes Example: "I'm not logged in right now, please send email." Description: This message will typically be like the voice mail user messages or email OOF messages. We have not decided whether or not the server must return the offline-msg in response to an instant message sent when the user is offline. 6.3.8. Online-msg Format: MIME-type, typically text/plain Value: Message intended for use when user is online. Has: ACL (put, get, subscribe), may also have TO/DV) Required: no Subscribable: Yes Example: "I'm chatting in #foo if anybody wants to join me." Description: This message will typically offer some information about what the user is doing while online. This may help other users decide how to get in touch. 6.3.9. Nickname Format: String Value: User's current nickname Has: ACL (put, get) Required: no Subscribable: no Description: Some group nodes MAY forward users' nicknames, if provided, rather than users' real names. These group nodes will typically be those provided for social interaction rather than work. In cases where the user wishes to remain anonymous, the client MAY send the nickname and not the Cn (common name) with an instant message. The recipient of an "anonymous" message of this type may refuse it. More details need to be worked out on the use of nickname. 6.3.10. Active-clients Format: string Value: List of active client for this user, or null. Has: ACL (put, get), TO, DV = null Required: no Subscribable: No Description: Frequently users will have more than one client connected. Clients should have types and may have simple Bone & Dusseault [Page 9] INTERNET-DRAFT RVP Schemas Mar 13, 1998 identities. Each client type/identity is separated by a comma. For example: "desktop=lisadu, desktop=lisa2, laptop=lisa, cellphone=, pager=555-5555, PDA" In this example, the cellphone identity is left blank because the user doesn't want their phone number known that widely, and the PDA doesn't have an identity. 6.4. Group Schema A group is similar to an email distribution list: it is a way of redistributing instant messages to a list of users. A group is structured similarly to users for ease of implementation. Like any RVP object, the group object has a ACL and a SL. The SL includes the list of users who wish to receive messages sent to that group, and may also include users who wish to be notified when a property of the group changes. The ACL for the group object defines: - who can send NOTIFY messages to the group - who can GET the subscription list to see all members - who can use ACL to change any of the ACLs under the group object - who can SUBSCRIBE to notifications sent to group - who can DELETE the group object Using PUT on the group object itself has no meaning. An interesting aspect of groups is that in a dynamic system such as RVP, group membership may also be very dynamic. For example, a group such as "people looking for a ride home now" might have a very dynamic member list. The server might have a maximum timeout value on subscription list entries of twenty minutes hence. Another group such as "members of this test team" might have a very static member list, with timeout entries of "never". In addition to the base object properties, the Group Schema has the following properties. 6.4.1. Online-members Format: Integer Value: Number of online group members | NULL Has: ACL (GET, SUBSCRIBE) Required: Yes Subscribable: no Example: 42 Description: This value records the number of entities which are currently online and subscribed to receive notifications sent to the group, and should be maintained accurately by the server when possible. A value of NULL can mean several things: - The number of online members is indefinite because there are sub-groups Bone & Dusseault [Page 10] INTERNET-DRAFT RVP Schemas Mar 13, 1998 - The number of online members is unknown because this is a public group which may be fanned out by any proxy. 6.4.2. Expires-offline Format: Boolean Value: True | False Has: ACL (Get, Subscribe) Required: Yes Subscribable: No Description: This property, which should be GETable by all potential members of the list, indicates whether the server expires subscription list entries when the receiver is offline. If TRUE, then offline recipients are dropped from the list. This occurs if the response to a message from the publishing server is an error/offline or no connection. If a server ever decides to drop a member from a subscription list without an explicit cancellation, the server should send a subscription cancellation message to the client. Note that this property also indicates to the client what the client is supposed to do when it goes offline. The graceful thing to do when expires-offline is TRUE is for the client to cancel their subscription before going offline. Similarly, if a proxy server is in the call-back path and the proxy server becomes aware that the subscriber has gone offline, the proxy server should cancel the subscription. The ability of the publishing server to drop subscriptions from the list is supposed to be used only when the graceful method fails. 6.4.3. Multicast-addr Format: IP multicast addr Value: Address which messages for this group are sent to Has: ACL (Get, subscribe) Required: No Subscribable: no Description: Large and public groups may support multicast: messages to the group are sent to the multicast address. If a multicast address is listed here and the client supports multicast, the client should listen on the multicast address rather than become a member of the group. Note that use of this feature improves scalability but eliminates read ACLs. 6.4.4. Max-Timeout Format: Integer Value: Number of seconds Has: ACL (GET, PUT) Required: Yes Subscribable: no Example: 3600 Description: The max-timeout value should be queryable in most cases, by most potential list members. A max-timeout of 0 Bone & Dusseault [Page 11] INTERNET-DRAFT RVP Schemas Mar 13, 1998 indicates "never": users can subscribe to this list without any timeout on their subscriptions. 6.4.5. Total-members Format: Integer Value: Number of offline & online members | NULL Has: ACL (get, put) Required: Yes Subscribable: no Example: 58 Description: The value of this property is different from the online-members property only for lists for which expires-offline is false. The NULL value indicates the number of members is unknown or uncertain. 6.4.6. Archive Format: URL Value: Location of archives | Null Has: ACL (Get, put) Required: No Subscribable: no Example: http://host.com/archives/rvpdisc Description: if archives of this list are stored, this points to them. 6.4.7. Owner Format: URL Value: Pointer to owner/moderator of list | Null Has: ACL (Get,put) Required: No Subscribable: no Example: rvp://host.com/joeuser Description: This could be a RVP URL, mailto URL, web-page with list of URLs, or other pointer to the owner/moderator of the list. 6.4.8. List-info Format: URL Value: Pointer to more information about the list | Null Has: ACL (Get, put) Required: No Subscribable: No Example: http://host.com/protocols/rvpdisc/policies.html Description: Any further information about the list, such as requirements for getting onto the list, rules of behavior etc, should be at the list-info URL or linked to from there. 6.4.9. Recurses Format: Boolean Bone & Dusseault [Page 12] INTERNET-DRAFT RVP Schemas Mar 13, 1998 Value: True | False Has: ACL (GET, PUT) Required: No Subscribable: No Description: If the server supports recursion of groups, and if the value of "recurses" for a group is "true", then a message sent to that group will also be sent to all child nodes of that group. This allows large groups which don't have individual members but which have child nodes, or groups which make up the larger group. For example, the group rvp://host.com/groups/rvpdisc could have child nodes rvp://host.com/groups/rvpdisc/newschemas rvp://host.com/groups/rvpdisc/prot-methods If recurses is set to true for rvpdisc, then both sub-groups receive a message sent to rvpdisc. 7. Extending Schemas 7.1. Extending Existing Schemas The user and group schemas are bound to be extended, with properties for users such as "phone-status". Extensions to existing, known schemas should always add, and not take away. If this guideline is followed, then the extensions can all be listed in this property after the base schema name, or in a new property. Old clients which understand the "user" schema but not any of the extensions can then ignore the extensions. The format for listing extensions is undefined and suggestions are welcome. When an extension to a schema is defined, it should be published with a unique name. 7.1.1. Storing private information in namespace This is entirely an optional feature. Servers may store information in the namespace which is only intended for the server and any of its users to get and set. For example, if a user has a number of subscriptions which they wish to have active every time they are online, then to minimize logon time the server may allow the subscription information to be stored online somewhere under the user's node in the namespace. When the user logs on, the user may send a command to tell the user to activate all the subscriptions stored in a particular location in the local namespace. 7.2. Defining New Schemas New schemas must be clearly justified and specified, published and assigned a unique name. Bone & Dusseault [Page 13] INTERNET-DRAFT RVP Schemas Mar 13, 1998 A new schema type of "automaton" has been suggested, with potential sub-types of "gateway" and "archiver". This would clearly identify automatic and special-purpose processes. 7.3. Auto-discovery of schemas An unknown object can first be identified by the schema-type property. However, the value of this field may not be known by the client. It would be desirable to define a mechanism through which the new schemas may be discovered on-the-fly. This mechanism would have to communicate the name, format and presence of SL/ACL/TO fields for each undefined property of the schema. The name would have to be included so that a user could decide whether to view the property, the format so that the client could guess how to display the property, and the presence of SL/ACL/TO information so that the client knows what may be done with the property. This mechanism could also be used to discover the nature of extensions to known schemas. 8. REFERENCES [1] S. Bradner, "Key words for use in RFCs to indicate requirement levels," RFC 2119, Internet Engineering Task Force, Mar. 1997. [2] M. Calsyn, L. Dusseault and G. Mohr, "RVP: A Presence Information Protocol", INTERNET-DRAFT , March 1998 [3] Leach P. and Goland Y., "WebDAV ACL Protocol", INTERNET-DRAFT , November 1997. 9. Authors' Addresses Lisa Dusseault Microsoft Corporation One Microsoft Way Redmond, WA 98052 EMail: lisadu@microsoft.com Jeff Bone Activerse, Inc. 1301 W. 25th St Suite 500 Austin, TX 78705 Email: jbone@activerse.com Bone & Dusseault [Page 14]