Status of this Memo

This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026.

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."

The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt.

The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html.

This Internet-Draft will expire on August 19, 2002.

Copyright Notice

Copyright (C) The Internet Society (2002). All Rights Reserved.

Abstract

This document specifies a set of methods, headers, and content-types ancillary to HTTP/1.1 for the creation and management of IMV meta and data entities, creation and management of meta and data attributes.

Table of Contents

1.  Introduction
2.  Notation Convention
3.  Terminlogy
4.  URL format
5.  Data Model for IMV
5.1  Basic system properties
5.2  Additional system properties for MetaNode
5.3  Additional system properties for DataNode
5.4  Additional system properties for MetaRelation
5.5  Additional system properties for DataRelation
5.6  Additional system properties for MetaAttribute
5.7  Additional system properties for DataAttribute
6.  HTTP methods for IMV
6.1  PROPFIND
6.1.1  Example - Retrieving named properties
6.1.2  Example - Retrieving all properties
6.1.3  Example - Retrieving properties names
6.1.4  Example - Retrieving properties of attributes
6.2  PUT
6.2.1  PUT Request on ATTRIBUTE
6.2.2  PUT Request on DATASOURCE
6.2.3  PUT Request on ENTITY
6.2.4  Response
6.2.5  Status Codes for use with 207 (Multi-Status)
6.2.6  Example - Creation of MetaNode
6.2.7  Example - Creation of DataNode
6.2.8  Example - Creating a DataNode
6.3  PROPPATCH
6.3.1  Status Codes for use with 207 (Multi-Status)
6.3.2  Example - proppatching a MetaNode
6.3.3  Example - proppatching an Attribute
6.3.4  Example - proppatching a DataNode
6.4  GET
6.5  DELETE
6.6  SEARCH
6.6.1  SEARCH on MetaNode
6.6.2  SEARCH on MetaRelation
6.6.3  Example Searching on MetaRelation
7.  Authentication
8.  Access Control
8.1  Access control for MetaEntities
8.2  Access control for DataEntities
8.3  Access control for MetaAttributes
8.4  Access control for DataAttributes
§  Authors' Addresses
§  Full Copyright Statement

1. Introduction

This memo describes how the HTTP extensions for WEBDAV defined in RFC2518 could be used for providing access to the proposed Information Meta View (IMV) system, a distributed web-based database. The reader is advised to refer to RFC2518 whenever reference to WebDAV (DAV) specific information is made.

2. Notation Convention

Since this document describes a set of extensions to the HTTP/1.1 protocol, the augmented BNF used herein to describe protocol elements is exactly the same as described sextion 2.1 of RFC2068. Since this augmented BNF uses the basic production rules provided in section 2.2 of RFC2068, these rules apply to this document as well.

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 RFC 2119.

3. Terminlogy

URI/URL

Uniform Resource Identifier and Uniform Resource Locator, respectively. These terms (and the distinction between them) are defined in RFC2396.

Entity:

An IMV entity represents a data object used for representation of nodes or relations that provide data or schema for the IMV structure. Each IMV entity is identified by a universally unique identifier (UUID).

System property:

A system defined property of an entity such as type, time of creation or value.

Attribute:

A key/value pair that can be added to an IMV entity to describe some user defined property of the entity.

MetaNode:

It is a type of IMV entity that represents the schema for a set nodes. Instances of this schema are referred to as DataNodes. Example: Hotel, Person, Movie.

DataNode:

It is a type of IMV entity that represents an instance of schema defined by a MetaNode. Example: An instance of MetaNode "Movie" could be "Lord of The Ring."

MetaRelation:

It is a type of IMV entity that describes the relationship between two MetaNodes. A MetaRelation is a schema defining the association between source and destination MetaNodes. Example: LocatedAt could be a MetaRelation between Hotel and Location.

DataRelation:

It is a type of IMV entity that represents and instnace of schema defined by a MetaNode. Example: An instance of MetaRelation "LocatedAt" could link "Hotel Le Meridean, Pune" with a node representing its "address in Pune."

MetaAttribute:

It is a type of attribute tagged to a MetaEntity (i.e. MetaNode or MetaRelation). A MetaAttribute describes the rules the govern the attributes of instances such as whether the attribute is mandatory, the data type used, etc.

DataAttribute:

It is a type of attribute tagged to a DataEntity (i.e. DataNode or DataRelation). A DataAttribute is an instance of a MetaAttribute defined by the schema of the corresponding DataEntity and contains a value and optional MIME attachment.

4. URL format

IMV-compliant URLs can be of the following types:

DATASTORE

http://someserver/path/to/imv/datasource_name

ENTITY

http://someserver/path/to/imv/datasource_name/Entity_UUID

ATTRIBUTE

http://someserver/path/to/imv/datasource_name/Entity_UUID/Attribute_name

5. Data Model for IMV

Information in IMV is organized into a user's data source in the form of entities and attributes. Entities could be either nodes, which represent an abstract data object or a relation, which joins two nodes that are inter-related. Both nodes and relations can be of two types -- meta entities, that represent schema and data entities, that represent instances. Hence we have the categories DataNode, MetaNode, DataRelation and MetaRelation.

Each IMV entity is identified by a universally unique identifier (UUID). These SHOULD be generated by the algorithm defined in the Internet Draft for generating UUIDs draft-leach-uuids-guids-01.

Each IMV entity can be associated with attributes which are descriptors of that entity. Attributes tagged to meta entities are known as MetaAttributes, whereas those tagged to data entities are known as DataAttributes. MetaAttributes of a meta entity describe the schema that governs the addition/removal of DataAttributes to the instances of that meta entity.

Apart from attributes, each IMV entity and attribute itself as a set of system properties that are defined by the system. Some of these system attributes are maintained completely by the system (eg. hitCount or timeModified), others are available to be set (eg. timeExpiry, value).

5.1 Basic system properties

These system properties are available for all types of entities and attributes.

• type
• value
• timeCreation
• timeAccessed
• timeModified
• timeExpiry
• accessVisible
• accessRead
• accessWrite
• hitCount
• importSource [Only for imported entities and attributes]

5.2 Additional system properties for MetaNode

No additional system properties are defined.

5.3 Additional system properties for DataNode

• instanceOf

5.4 Additional system properties for MetaRelation

• src
• dest
• srcCardinality
• destCardinality

5.5 Additional system properties for DataRelation

• src
• dest
• instanceOf

5.6 Additional system properties for MetaAttribute

• mandatory

5.7 Additional system properties for DataAttribute

No additional system properties are defined.

6. HTTP methods for IMV

The following new HTTP methods are defined by the WebDAV protocol specification in RFC2518. The new methods use XML as a request and response format. All DAV compliant clients and resources MUST use XML parsers that are compliant with REC-XML. All XML used in either requests or responses MUST be, at minimum, well formed. If a server receives ill-formed XML in a request it MUST reject the entire request with a 400 (Bad Request). If a client receives ill-formed XML in a response then it MUST NOT assume anything about the outcome of the executed method and SHOULD treat the server as malfunctioning.

6.1 PROPFIND

The PROPFIND method retrieves properties (system properties and attributes) defined on the entity or attribute identified by the Request-URI. All IMV entities and attributes MUST support the PROPFIND method and the propfind XML element along with all XML elements defined for use with that element.

A client may submit a propfind XML element in the body of the request method describing what information is being requested. It is possible to request particular property values, all property values, or a list of the names of the rentity's properties. A client may choose not to submit a request body. An empty PROPFIND request body MUST be treated as a request for the names and values of all properties.

All servers MUST support returning a response of content type text/xml or application/xml that contains a multistatus XML element that describes the results of the attempts to retrieve the various properties.

If there is an error retrieving a property then a proper error result MUST be included in the response. A request to retrieve the value of a property which does not exist is an error and MUST be noted, if the response uses a multistatus XML element, with a response XML element which contains a 404 (Not Found) status value.

The results of this method SHOULD NOT be cached.

6.1.1 Example - Retrieving named properties

6.1.2 Example - Retrieving all properties

6.1.3 Example - Retrieving properties names

6.1.4 Example - Retrieving properties of attributes

6.2 PUT

The PUT method is used to create a new Entity or to upload resource content to an attribute. There are three interpretations of the PUT method depending on the type of request URL.

6.2.1 PUT Request on ATTRIBUTE

A PUT performed on an ATTRIBUTE replaces the GET response of the ATTRIBUTE. The Content-Type header is stored as a property of the attribute and the body is saved to the server. The resource may be downloaded with a GET on the same ATTRIBUTE URL.

6.2.2 PUT Request on DATASOURCE

PUT creates a new entity in the datasource as specified by the request URL. The body of the PUT request contains a set xml element. This element contains the attributes and setable system property values of the entity. The consisteny of the entities has to be maintained by the PUT request. Therfore every request to create an entity must set the values of the system properties "type" and "value". In case of a data entity creation the value of the system property "instanceOf" must be given and the value be the UUID of the corresponding Meta entity. In case of a MetaRelation the values of the system properties "src" and "dest" must be set and MUST point to MetaNode entities. Similarly with DataRelation the values of the system properties "src" and "dest" MUST be set and must point to DataNode entities which are instances of the MetaNodes specified in the MetaRelation's system properties "src" and "dest" respectively.

When creating instances of meta entities, all mandatory meta attributes must have their corresponding data attributes created in the data entity. If a value is not specified for the data attribute, it is copied from the default value specified in the meta attribute

If the server recives a PUT request which does not satisfy the above requirements then the server MUST respond with a 417 EXPECTATION FAILED error code.

6.2.3 PUT Request on ENTITY

If the request URL contains ENTITY UUID, then the server MUST create a new imported entity. Imported entities MUST be specified with an "importSource" system property that contains the URL of the orginal entity. All other constraints remain the same.

6.2.4 Response

If an ATTRIBUTE type request is successful, a 201 Created response is sent. If request fails to meet the consistency, a 417 Expectation Failed error is returned. Otherwise a 207 Multistatus is sent.

6.2.5 Status Codes for use with 207 (Multi-Status)

The following are examples of response codes one would expect to be used in a 207 (Multi-Status) response for this method. Note, however, that unless explicitly prohibited any 2/3/4/5xx series response code may be used in a 207 (Multi-Status) response.

201 (Created) - The command succeeded i.e. properties have been set.

403 (Forbidden) - The client, for reasons the server chooses not to specify, cannot alter one of the properties e.g. non-settable system properties

6.2.6 Example - Creation of MetaNode

6.2.7 Example - Creation of DataNode

The system failed to create a new instance of a song because the mandatory attribute title was not specified.

6.2.8 Example - Creating a DataNode

Here, creation of DataNode was successful. Value of DataAttribute label was set to the default value specified in the MetaAttribute. The attribute 'price' which does not exist in the MetaNode is sent back with a 403 Forbidden status.

6.3 PROPPATCH

The PROPPATCH method processes instructions specified in the request body to set (settable) system properties and attributes and/or remove attributes defined on the entity identified by the Request-URI.

All entities MUST support the PROPPATCH method and MUST process instructions that are specified using the propertyupdate, set, and remove XML elements of the DAV schema. Execution of the directives in this method is, of course, subject to access control and schema consistency constraints.

The request message body of a PROPPATCH method MUST contain the propertyupdate XML element. Instruction processing MUST occur in the order instructions are received (i.e., from top to bottom).

To set system properties of the value of an attribute, PROPPATCH can be used either on the entity or on the attribute URL. Refer to below examples.

6.3.1 Status Codes for use with 207 (Multi-Status)

The following are examples of response codes one would expect to be used in a 207 (Multi-Status) response for this method. Note, however, that unless explicitly prohibited any 2/3/4/5xx series response code may be used in a 207 (Multi-Status) response.

200 (OK) - The command succeeded. As there can be a mixture of sets and removes in a body, a 201 (Created) seems inappropriate.

403 (Forbidden) - The client, for reasons the server chooses not to specify, cannot alter one of the properties.

409 (Conflict) - The client has provided a value whose semantics are not appropriate for the property. This includes trying to remove mandatory attributes.

6.3.2 Example - proppatching a MetaNode

We have added two MetaAttributes "size" and "recordlabel" and changed system property "value." We have also removed the MetaAttribute "label." Removing a MetaAttribute SHOULD NOT remove DataAttributes of the this MetaNode's instances (DataNodes).

6.3.3 Example - proppatching an Attribute

We can make modifications to the "artist" attribute of the MetaNode in the previous example by using the ATTRIBUTE URL directly.

6.3.4 Example - proppatching a DataNode

We are unable to remove "artist" because it is a mandatory attribute now. We cannot set system property hitCount because it is not settable.

6.4 GET

The GET method is not meaningful on ENTITY and DATASOURCE URLs, though the implementors may wish to use them for giving HTML descriptions of the entities and datasources.

The GET method when used with an attribute will retrieve any uploaded resource. If no resource has been uploaded previously, the method will provide a 204 No Content response. Otherwise it will respond with 200 OK and provide the resource as a MIME type with the Content-Type and optionally Content-Length in the HTTP header. The body will contain the actual content of the resource.

6.5 DELETE

The DELETE method is meaningful only on ENTITY URLs. Deletion of attributes can be done only through PROPPATCH. Delete will remove the entity from the datasource and return either "204 No Content" on success or "404 Not Found" or "403 Forbidden" on failure. Deletions are not cascaded, so deleting a MetaNode does not delete its DataNodes or MetaRelations. Explicit deletions of instances are required.

6.6 SEARCH

The SEARCH method conforms to DASL's basicsearch XML schema and is used for selecting a set of DataEntity instances of a given MetaEntity. See internet-draft-(TODO: find out) for information about DASL's proposed search mechanism for DAV. Current version of the IMV system should support at least SEARCH on two scopes -- single MetaNodes and single MetaRelations.

The search arbiter is the datasource and all SEARCH methods are valid only for DATASOURCE URLs. The datasource defines the search space, further restricted by the scope on which we are selecting data instances. The behaviour is described below

6.6.1 SEARCH on MetaNode

It should be possible to retrieve all instances of a MetaNode within a datasource (i.e. not outside the scope of the datasource, eg, imported instances). The select XML element allows specification of system properties and attributes of the DataEntities requested. The scope element should only the href of the MetaNode. The where clause contains the filter expression tree. Valid operators are eq (equals), ne (not equals), gt (greater than), lt (less than), ge (greater than or equals), le (less than or equals). Comparisons are made on strings. Later versions should support other data-types. Each binary operation takes two elements to be compared which maybe props or literals.

6.6.2 SEARCH on MetaRelation

A search on MetaRelation allows the retrieval of instances (DataRelations) of the MetaRelation. The syntax is very similar to the search on MetaNode, except that apart from allowing reference to the DataRelation's system properties and attributes, it also allows reference to the properties of the srcNode and destNode attached by the DataRelation. Distinction is made by using appropriate namespaces to distinguish prop names of the DataRelation from those of the srcNode and destNode.

6.6.3 Example Searching on MetaRelation

7. Authentication

Three types of users can login to the system -- owner, friend and guest. The owner can access his data source with an administrative password and regular HTTP authentication will follow. Guests are anonymous users (i.e. users that do not provide any password and hence have the most restricted access). Friends are people who are known to the owner of the datasource and whose entry has been made in the datasource's address book (also stored in IMV format using system defined schema).

IMV could use a public/private key mechanism to authenticate friends. The address book contains an 4-tuple (username, datasource URL, public key, access level) of each friend. The friend attempts to login with HTTP authentication providing username and datasource URL as password. The server will start a session and randomly generate a token and present it back to the user agent (browser). The browser will sign the token with the friend's private key and send it back to the server. The server will decode the token to check authenticity and allow the friend in with the predefined access level. This access level is maintained throughout the entire session.

The owner has an access level of 0 (highest) and guest has an access level of 99 (lowest)

This system is dependent on the assumption that all friends have valid address book entries in a user's datasource before they are allowed access.

8. Access Control

Access to entities is given to the the user as per his/her access level. Each entity has three basic access control properties:

accessRead

accessWrite

accessVisible

All three properties have different significance depending on the type of entity.In each case access is permitted to the user if his/her access level is lower than or equal to the respective property value.

8.1 Access control for MetaEntities

In case of MetaEntities accessRead permission allows the user to propfind on the MetaEntity and search for instances of the MetaEntity. AcessWrite permission allows the user to create instances of the MetaEntity. The MetaEntity is visible to the user only if he has the required accessVisible permission i.e if he/she tries to access without appropriate permission, a not found error is encountered. The right of editing an MetaEntity lies solely with owner of the entity.

8.2 Access control for DataEntities

In case of DataEntities accessRead permission allows the user to propfind the properties of the DataEntity. AcessWrite permission allows to set or change properties of the DataEntity. The DataEntity is visible to the user only if he has the required accessVisible permission i.e if he/she tries to access without appropriate permission, a not found error is encountered.

8.3 Access control for MetaAttributes

In case of MetaAttributes accessRead permission allows the user to propfind on the MetaAttribute. AcessWrite permission is undefined. The MetaAttribute is visible to the user only if he has the required accessVisible permission i.e if he/she tries to access without appropriate permission, a not found error is encountered. The right of editing an MetaAttribute lies solely with owner of the entity.

8.4 Access control for DataAttributes

In case of DataAttributes accessRead permission allows the user to propfind the properties of the DataAttribute. AcessWrite permission allows to set or change properties of the DataEntity. The DataAttribute is visible to the user only if he has the required accessVisible permission i.e if he/she tries to access without appropriate permission, a not found error is encountered.

Access control is hierarchial. To access an attribute, the user must have appropriate access permission from the entity to which it belongs. For example, to modify the value of a DataAttribute, the user must have accessWrite permission to the DataAttribute and accessWrite to the DataEntity.

Authors' Addresses

Full Copyright Statement

Copyright (C) The Internet Society (2002). All Rights Reserved.

This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English.

The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assigns.

This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Acknowledgement

Funding for the RFC Editor function is currently provided by the Internet Society.