Status of this Memo

This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026 except that the right to produce derivative works is not granted. (If this document becomes part of an IETF working group activity, then it will be brought into full compliance with 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 September 7, 2000.

Copyright Notice

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

Abstract

Blocks[1] is an architecture for managing metadata. The architecture supports two models: the Blocks exchange model organizes information into navigation spaces, whilst the Blocks convergence model allows for bulk synchronization and knowledge management.

This memo describes the Simple Exchange Profile (SEP) used to exchange objects, termed blocks, residing in an SEP datastore.

To subscribe to the Blocks discussion list, send e-mail; there is also a developers' site.

Table of Contents

1.  Introduction
2.  The SEP Datastore
2.1  Naming
2.2  Data types
2.3  Entities
2.4  The Top-Level
3.  Profile Identification and Initialization
4.  Request and Response Messages
5.  Message Semantics
5.1  The Fetch Operation
5.1.1  The Related and MaxNum Attribute
5.1.2  The Ordering Element
5.1.3  The Notification, PrevStamp, and ReqStamp Attributes
5.2  The Notify Operation
5.3  The Store Operation
5.4  The Lock Operation
5.5  The Release Operation
5.6  Other Operations
6.  Simple Exchange Profile Registration
7.  The SEP datastore DTD
8.  The Simple Exchange Profile DTD
9.  Security Considerations
§  References
§  Author's Address
A.  Acknowledgements
B.  Changes from draft-mrose-blocks-exchange-00
§  Full Copyright Statement

1. Introduction

In the Blocks Architecture[1], the Simple Exchange Profile (SEP) is used to exchange objects, termed blocks, residing in an SEP datastore.

2. The SEP Datastore

An SEP datastore is a collection of blocks. A block can be viewed from two perspectives:

semantic:

a block is simply metadata about an external object; in this sense, an SEP datastore is not unlike a shared, distributed management system for documents;

syntactic:

a block is a unit of retrieval; in this sense, an SEP datastore is a collection of related XML documents[2].

A block is a well-formed XML document that satisfies four constraints:

• the root element of each block must contain a "name" attribute;
• each XML element in the block, termed a property, contains either character data or subordinate elements, but not both;
• if there is a DTD that describes the validity of the XML document, then any implicit values must be populated in the block; and,
• a block may contain no entities other than "&", "<", "'" and """.

Blocks are expressed using either:

the generic syntax:

in which each property of the block is explicitly tagged using a "property" element; or,

the specific syntax:

in which a syntactic minimization technique is used to increase readability and reduce size.

2.1 Naming

Naming of blocks in an SEP datastore is hierarchical, with labels separated by slash, and read left-to-right, e.g.,

A naming scope refers to the collection of blocks whose names are contained with a proper subtree, e.g.,

are both contained within the naming scope of "doc/rfc".

2.2 Data types

The SEP datastore DTD begins by specifying several data types for use when defining a block:

NAME:

Each block has a unique name. This datatype is used wherever the syntax of a name is required.

TYPE:

Each block consists of one or more properties. This datatype is used wherever the syntax for a property's type is required.

TYPES:

Sometimes it is convenient to refer to the types associated with a list of properties. This datatype is used for that purpose.

URI:

Although the attribute values associated with a property are textual, it is often useful to treat the character string as a higher-level construct. This datatype is used wherever the syntax for a URI[3] is required.

UINT16:

This data type is used wherever the syntax for a 16-bit unsigned integer value is required.

UINT32:

This data type is used wherever the syntax for a 32-bit unsigned integer value is required.

ATEXT:

This data type is used wherever the syntax for unstructured text in an attribute value is required.

CTEXT:

This data type is used wherever the syntax for single line, unstructured text is required.

TEXT:

This data type is used wherever the syntax for (potentially multiline) unstructured text is required.

2.3 Entities

At a minimum, each block must have a "name" attribute in its root element. In addition, each block may also have three optional attributes present in its root element:

serial:

an integer that is increased each time the block is updated;

ttl:

an integer, in seconds, that indicates how long this copy of the block should be considered authoritative; and,

creator:

a URI identifying the process that created or last updated this block.

The "%block.attrs;" entity is used to denote the mandatory "name" attribute and these three optional attributes.

2.4 The Top-Level

Each block consists of the four attributes defined by "%block.attrs;", and zero or more "property" elements.

Each "property" element consists of:

• zero or more uniquely named "attribute" elements (each "attribute" element is simply a key/value pairing); and,
• either:
  • one or more "property" elements; or,
  • character data consisting of zero or more characters.

For example, consider:

which is a block containing one property, called "remote.props". That property contains two attributes (one called "uri" and the other "language") and a subordinate property. The subordinate property, called "title", contains character data.

This example shows a block expressed using the generic syntax. Because XML elements may contain uniquely-named attributes, we can minimize the syntax:

The rules to convert from the generic to the specific syntax are simple:

1. Change the name of the top-level element from "block" to something else.
2. For each "attribute" element subordinate to any "property" element: add the corresponding name/value pair as an attribute to that "property" element and remove the "attribute" element.
3. For each "property" element contained within the block, change the name of that "property" element to the value of its corresponding "type" attribute and remove the "type" attribute from that element.

3. Profile Identification and Initialization

Simple Exchange Profile Registration contains the registration for this profile.

The SEP is identified as

Refer to [4]'s Section 2.1 for a discussion of the roles that a BXXP peer may perform, i.e., initiator ("I:") or listener ("L:"), and client ("C:") or server ("S:").

During channel creation, the corresponding "profile" element in the BXXP "start" element may contain a "request" element. If channel creation is successful, then before sending the corresponding "RSP" message, the BXXP peer processes the "request" element and includes the resulting "response" element in the "RSP" message, e.g.,

Note that it is possible for the channel to be created, but for the encapsulated operation to fail, e.g.,

In this case, a positive "RSP" message is returned (as channel creation succeeded), but the encapsulated response contains an indication as to why the operation failed.

4. Request and Response Messages

The Simple Exchange Profile DTD defines the messages that are used in the SEP:

• "REQ" messages carry only the "request" element as data;
• positive "RSP" messages carry only the "response" element (containing an "answers" element and, optionally, an "additional" element) as data; and,
• negative "RSP" messages carry only the "response" element (containing an "error" element) as data.

5. Message Semantics

The "request" element contains a "reqno" attribute and one of: a "fetch" element, a "notify" element, a "store" element, a "lock" element, or, a "release" element.

The "reqno" attribute (an integer in the range 0..4294967295) is used to correlate "request" elements sent by a BXXP peer acting in the client role with the "response" elements sent by a BXXP peer acting in the server role.

5.1 The Fetch Operation

The "fetch" element contains four attributes, a "union" element, and, optionally, an "ordering" element:

• the "related" attribute, if present, contains a space-separated list of property names that cause similar blocks to be returned in the "additional" element of the response (c.f., The Related and MaxNum Attribute);
• the "offset" attribute, if present, contains a non-negative integer (in the range 0..32767) indicates the starting position for the blocks to be returned;
• the "maxNum" attribute, if present, contains a positive integer (in the range 1..32767) indicates the maximum number of blocks allowed to be returned;
• the "notification" attribute, if present, is either "true" or "false" (the default) to indicate whether the BXXP peer acting in the server role should periodically check for changes to the blocks returned in the "answers" element of the response (c.f., The Notification, PrevStamp, and ReqStamp Attributes);
• the "union" element defines the set-union of one or more "intersect" elements, each of which define the set-intersection of one or more "union" or "compare" elements, each of latter describing an containment/value assertion; and,
• the "ordering" element, if present, defines the order in which matches are returned (c.f., The Ordering Element).

• the "subtree" attribute identifies the naming scope for the comparison;
• the "operator" attribute, if present, identifies the comparison to be made between the "path" element and the "value" element, one of: "eq" (equals, the default), "ne" (not equals), "contains", or "excludes";
• the "caseSensitive" attribute, if present, is either "true" (the default) or "false" to indicate whether the comparison should consider textual case significant;
• the "approximate" attribute, if present, is either "true" or "false" (the default) to indicate whether the comparison should be approximate (e.g., through the use of stemming);
• the "path" element identifies a partial containment hierarchy for the comparison; and,
• the "value" element contains the text to compare against.

If the fetch operation is successful, then a "response" element containing an "answers" element, and optionally an "additional" element is returned as data in a positive "RSP" message; otherwise, a "response" element containing a BXXP "error" element (c.f., [4]'s Section 2.3.1.3) is returned as data in a negative "RSP" message.

If a "response" element is returned, then the order of blocks in the "answers" element are ordered from "most relevant" to "least relevant" (c.f., The Ordering Element). Accordingly, if all blocks satisfying the set-union are enumerated as a list starting at position 0, then the block at the position corresponding to the "offset" attribute is the first block returned in the "answers" element.

If a "response" element is returned, then the optional "actualNum" attribute may be present in the "answers" element. This attribute indicates the total number of matches for the corresponding "fetch" operation. If absent, the value of this attribute defaults to the number of blocks present in the "answers" element.

At the core of the fetch operation is the notion of a containment/value assertion. Each assertion identifies a comparison between a partial containment hierarchy and a textual value.

Several examples serve to illustrate these relationships.

First, consider:

which looks for blocks satisfying several criteria: first, the block is named under "doc/rfc"; second, the block has at least one property called "email"; and, third, any of those properties contains the string "mrose@" somewhere within it, according to a case-insensitive comparison. Note that in this example, the "email" property may occur at any level of nesting within a block.

Second, a similar example:

which looks for blocks in the same subtree, but is concerned only with attribute, not property, values. That is, if any property with a block has attribute called "surname" and the value of that attribute precisely matches the string "Rose", then this assertion succeeds. (Recall that the default value for "operator" is "eq" and the default value for "caseSensitive" is "true".)

Of course, if we wanted to limit containment of the attribute:

which looks for blocks in the same subtree, but performs comparisons only on attributes called "surname" within a "doc.author" property.

In addition, if we wanted to further contain the attribute's property:

which looks for "doc.author" properties contained within a "doc.front" property contained within a "doc.props" property contained within a "rfc" property before looking at the "surname" attribute. Note however, that there is no concept of "rooting" in a containment hierarchy, e.g., in this example, the "rfc" property needn't be the top-level property of the block (i.e., the root element of the corresponding XML document).

Of course, an empty containment hierarchy is also possible, e.g.,

which looks for the string "Rose" in any property. Similarly, to look for the string "Rose" in any attribute value, the containment "<path attribute='*' />" is used.

Note that in all the preceding examples, both the "union" and "intersect" elements had only one immediate subordinate, rendering each as the identity function. However, the presence of the elements is always required, regardless of whether their functionality is needed. To set-intersect the results of multiple assertions, the "intersect" element is given multiple subordinates, e.g.,

which evaluates two assertions and returns only those blocks satisfying both.

Similarly, to set-union the results of multiple intersections, the "union" element is given multiple subordinates, e.g.,

which evaluates two assertions and returns blocks that satisfy either. Of course, recursion is permissible between "union" and "intersect" elements, owing to their defintion.

5.1.1 The Related and MaxNum Attribute

Blocks satisfying the constraints of the "union" element are returned in the "response" element's "answers" element. These are termed satisfying blocks.

The "related" attribute, if present, causes blocks similar to the satisfying blocks to be returned in the "response" element's "additional" element. These are termed similar blocks.

A similar block is one that has the same value for any of related properties as any of the satisfying blocks. Note that when determining if a block is similar, the BXXP peer acting in the server role consults its entire SEP datastore -- a similar block may belong to an entirely different naming scope than any corresponding satisfying block.

Regardless, note that the "maxNum" attribute limits the actual number of blocks returned. As many satisfying blocks as possible must be returned; if the "maxNum" limit is not yet reached, then as many similar blocks within the limit may be returned. No additional constraints are placed on implementations if the value of the "maxNum" attribute is less than the number of satisfying and similar blocks.

5.1.2 The Ordering Element

If the "ordering" element is present in the "fetch" element, then this provides guidelines as to how blocks should be ordered in the "answers" element.

The "ordering" element contains one or more "path" elements, ordered as sort keys (i.e., the first "path" element is the primary sort key, the second "path" element, if any, is the secondary sort key, and so on). Each "path" element contains an "order" attribute indicating whether relevance is in ascending (the default) or descending order.

For example, to look for blocks containing a "surname" attribute of "Rose", and then order the blocks according to the value of their "doc.title" element:

5.1.3 The Notification, PrevStamp, and ReqStamp Attributes

If a fetch operation is successful and the "notification" attribute is "true", then it is referred to as a persistent fetch operation.

When performing the fetch operation, if the "notification" attribute is true, then the "prevStamp" attribute is also consulted. If empty, this indicates that the fetch operation is performed against the entire SEP datastore; otherwise, the value is identical to a previously returned value of the "reqStamp" in an "answers" element. In this latter case, the fetch operation returns an empty "answer" element with a "reqStamp" attribute value equal to the "prevStamp" attribute value, and all corresponding notify operations for this persistent fetch will contain information about changes that occurred after the "reqStamp" attribute value.

The fetch operation persists until either:

• a corresponding release operation is successful;
• a corresponding notify operation fails;
• the BXXP session is released; or,
• the underlying transport service indicates that the connection has been reset.

In the interim:

1. The BXXP peer acting in the client role may not use the value of "reqno" in other requests.
2. The BXXP peer acting in the server role periodically checks for changes to the blocks returned in the "answers" element in the original response. If so, a notify operation is generated.

Every "answers" element generated for a persistent fetch (contained in either a "response" or "notify" element) has a non-empty "reqStamp" attribute. This provides a mechanism to restart a persistent fetch operation after a connection loss: the BXXP peer acting in the client role records the most recent "reqStamp" attribute value whenever it sees an "answer" element corresponding to a persistent fetch. If the connection is lost (or the SEP channel is closed), then after re-establishing the connection and starting an SEP channel, the BXXP peer acting in the client role initiates a new persistent fetch by setting the "notification" attribute to true and the "prevStamp" attribute to the most recent "reqStamp" attribute value.

5.2 The Notify Operation

For each persistent fetch operation known to a BXXP acting in the server role, a periodic check is made for changes to the blocks returned in the "answers" element in the original response. If any of the blocks are changed or deleted, or, if new blocks are created that qualify as satisfying blocks for the original request, then a notify operation is sent.

The "notify" element consists of a "prevno" attribute, an "answers" element, and, optionally, either or both of a "additional" element and a "deletions" element:

• the "prevno" attribute (an integer in the range 0..4294967295) is used to correlate this operation with the corresponding persistent fetch operation;
• the "answers" element contains both newly-changed blocks previously returned in an "answers" element for this persistent fetch operation, along with newly-created blocks that qualify as satisfying blocks for the original request;
• the "additional" element, if present, contains similar blocks to the newly-created blocks, if any, in the "answers" element of this operation; and,
• the "deletions" element, if present, contains newly-deleted blocks previously returned in an "answers" element for this persistent fetch operation.

Note that when constructing the "deletions" element, the blocks generic syntax may be used, e.g.,

This strategy is useful if a server knows that a block was deleted, but the actual block is no longer available.

If the notify operation is successful, then a "response" element containing an empty "answers" element is returned as data in a positive "RSP" message; otherwise, a "response" element containing a BXXP "error" element (c.f., [4]'s Section 2.3.1.3) is returned as data in a negative "RSP" message. In the latter case, the fetch operation is no longer considered persistent.

Note that the BXXP peers switch server and client roles when going from a fetch operation to a notify operation, e.g.,

5.3 The Store Operation

The store operation contains one attribute and one or more blocks to store.

• the "action" attribute, if present, is one of:

  create:

  verifies that the blocks do not exist in the SEP datastore before creating them;

  write:

  creates or overwrites the blocks in the SEP datastore (the default);

  update:

  verifies that the blocks exist in the SEP datastore before overwriting them; or,

  delete:

  removes the blocks from the SEP datastore.

In order to provide coordination between independent BXXP peers acting in the client role, a lock operation must be successfully performed before the store operation.

If the store operation is successful, then a "response" element containing an empty "answers" element is returned as data in a positive "RSP" message; otherwise, a "response" element containing a BXXP "error" element (c.f., [4]'s Section 2.3.1.3) is returned as data in a negative "RSP" message.

5.4 The Lock Operation

The lock operation contains one attribute:

• the "subtree" attribute that identifies the naming scope to lock.

If a lock operation is successful, then it is referred to as a persistent lock operation. It remains so until either:

• a corresponding release operation is successful;
• the BXXP session is released;
• the underlying transport service indicates that the connection has been reset; or,
• an implementation-specific inactivity timer expires in the BXXP peer acting in the server role.

In the interim:

1. No other connection or channel may successfully lock within the subtree.
2. No other connection or channel may successfully store within the subtree.
3. Any store operations on this channel are journaled until a subsequent release operation.

If the lock operation is successful, then a "response" element containing an empty "answers" element is returned as data in a positive "RSP" message; otherwise, a "response" element containing a BXXP "error" element (c.f., [4]'s Section 2.3.1.3) is returned as data in a negative "RSP" message.

5.5 The Release Operation

The "release" element contains two attributes:

• the "prevno" attribute (an integer in the range 0..4294967295) is used to correlate this operation with a persistent fetch or lock operation; and,
• the "action" attribute, if present, is either "commit" (the default) or "rollback".

If the previous operation refers to a persistent lock operation, then the "action" attribute indicates whether the BXXP peer acting in the server role should either:

commit:

perform any journaled store operations for this channel; or,

rollback:

discard any journaled store operations for this channel.

If the release operation is successful, then a "response" element containing an empty "answers" element is returned as data in a positive "RSP" message; otherwise, a "response" element containing a BXXP "error" element (c.f., [4]'s Section 2.3.1.3) is returned as data in a negative "RSP" message.

5.6 Other Operations

If the BXXP peer receives a "request" element containing any other element, a "response" element containing a BXXP "error" element (c.f., [4]'s Section 2.3.1.3) is returned as data in a negative "RSP" message.

6. Simple Exchange Profile Registration

Profile Identification:

http://xml.resource.org/profiles/SEP

Messages in Profile Initialization:

request

Messages in "REQ" frames:

request

Messages in positive "RSP" frames:

response

Messages in negative "RSP" frames:

error

Message Syntax:

c.f., The Simple Exchange Profile DTD

Message Semantics:

c.f., Message Semantics

7. The SEP datastore DTD

8. The Simple Exchange Profile DTD

9. Security Considerations

The SEP is a profile of BXXP. In BXXP, transport security, user authentication, and data exchange are entirely orthogonal. Refer to [4]'s Section 8 for a discussion of these issues.

References

Author's Address

Appendix A. Acknowledgements

The author gratefully acknowledges the contributions of: Darren New.

Appendix B. Changes from draft-mrose-blocks-exchange-00

• The profile is now identified as http://xml.resource.org/profiles/SEP
• In The Ordering Element, an XML nesting error was corrected.
• In The Notification, PrevStamp, and ReqStamp Attributes, the behavior of connection re-establishment was clarified.
• In The Simple Exchange Profile DTD, the correct URI is used to reflect the location of the DTD.

Full Copyright Statement

Copyright (C) The Internet Society (2000). 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.

Invisible Worlds expressly disclaims any and all warranties regarding this contribution including any warranty that (a) this contribution does not violate the rights of others, (b) the owners, if any, of other rights in this contribution have been informed of the rights and permissions granted to IETF herein, and (c) any required authorizations from such owners have been obtained. This document and the information contained herein is provided on an "AS IS" basis and INVISIBLE WORLDS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OFTHE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

IN NO EVENT WILL INVISIBLE WORLDS BE LIABLE TO ANY OTHER PARTY INCLUDING THE IETF AND ITS MEMBERS FOR THE COST OF PROCURING SUBSTITUTE GOODS OR SERVICES, LOST PROFITS, LOSS OF USE, LOSS OF DATA, OR ANY INCIDENTAL, CONSEQUENTIAL, INDIRECT, OR SPECIAL DAMAGES WHETHER UNDER CONTRACT, TORT, WARRANTY, OR OTHERWISE, ARISING IN ANY WAY OUT OF THIS OR ANY OTHER AGREEMENT RELATING TO THIS DOCUMENT, WHETHER OR NOT SUCH PARTY HAD ADVANCE NOTICE OF THE POSSIBILITY OF SUCH DAMAGES.

Acknowledgement

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