Network Working Group M.T. Rose
Internet-Draft M.R. Gazzetta
Expires: September 7, 2000 Invisible Worlds, Inc.
March 9, 2000
Blocks eXtensible eXchange Service
draft-mrose-blocks-service-01
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 how to provision a Blocks service.
To subscribe to the Blocks discussion list, send e-mail[9]; there is
also a developers' site[10].
Rose & Gazzetta Expires September 7, 2000 [Page 1]
Internet-Draft Blocks eXtensible eXchange Service March 2000
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . 3
2. Defining Object Types . . . . . . . . . . . . . . . . 4
2.1 Pre-defined Blocks . . . . . . . . . . . . . . . . . . 5
2.1.1 Commonly-used Properties . . . . . . . . . . . . . . . 5
2.1.2 Scripts . . . . . . . . . . . . . . . . . . . . . . . 7
3. Naming Objects . . . . . . . . . . . . . . . . . . . . 8
4. Creating and Storing Objects . . . . . . . . . . . . . 9
5. Retrieving, Evaluating, and Publishing Objects . . . . 10
5.1 CGI-based Builders . . . . . . . . . . . . . . . . . . 10
5.1.1 CGI Parameters . . . . . . . . . . . . . . . . . . . . 10
5.1.1.1 Retrieval Parameters . . . . . . . . . . . . . . . . . 10
5.1.1.1.1 Union Parameters . . . . . . . . . . . . . . . . . . . 10
5.1.1.1.2 Tag Parameters . . . . . . . . . . . . . . . . . . . . 10
5.1.1.1.2.1 Normalization . . . . . . . . . . . . . . . . . . . . 11
5.1.1.1.2.2 Boolean Expressions . . . . . . . . . . . . . . . . . 12
5.1.1.1.3 Text Parameters . . . . . . . . . . . . . . . . . . . 13
5.1.1.1.4 Block Parameters . . . . . . . . . . . . . . . . . . . 14
5.1.1.1.5 Miscellaneous Parameters . . . . . . . . . . . . . . . 14
5.1.1.2 Evaluation Parameters . . . . . . . . . . . . . . . . 15
5.1.1.2.1 Evaluation Scripts . . . . . . . . . . . . . . . . . . 15
5.1.1.3 Publication Parameters . . . . . . . . . . . . . . . . 16
5.1.1.3.1 Publication Scripts . . . . . . . . . . . . . . . . . 16
5.1.1.4 URL Parameters . . . . . . . . . . . . . . . . . . . . 16
5.2 Well-known Scripts . . . . . . . . . . . . . . . . . . 17
5.2.1 Evaluation Scripts . . . . . . . . . . . . . . . . . . 17
5.2.1.1 evaluate.null.1 . . . . . . . . . . . . . . . . . . . 17
5.2.1.2 evaluate.doc.*.generic.1 . . . . . . . . . . . . . . . 17
5.2.1.3 evaluate.sort.1 . . . . . . . . . . . . . . . . . . . 17
5.2.2 Publication Scripts . . . . . . . . . . . . . . . . . 18
5.2.2.1 publish.doc.edgar.spacescript and
publish.doc.spacescript20 . . . . . . . . . . . . . . 18
5.2.2.2 publish.debug.1 . . . . . . . . . . . . . . . . . . . 18
6. The BXXS DTD . . . . . . . . . . . . . . . . . . . . . 19
References . . . . . . . . . . . . . . . . . . . . . . 22
Authors' Addresses . . . . . . . . . . . . . . . . . . 23
A. The RFC space DTD . . . . . . . . . . . . . . . . . . 24
B. Reference Blocks Structure Specification . . . . . . . 27
C. The BANANA DTD . . . . . . . . . . . . . . . . . . . . 28
D. An Example of a Delegation Request . . . . . . . . . . 31
E. Changes from draft-mrose-blocks-service-00 . . . . . . 33
Full Copyright Statement . . . . . . . . . . . . . . . 34
Rose & Gazzetta Expires September 7, 2000 [Page 2]
Internet-Draft Blocks eXtensible eXchange Service March 2000
1. Introduction
This document describes how to provision a Blocks service.
Service provisioning consists of several activities:
o defining the structure of the object types for exchange;
o defining the naming hierarchy used for objects;
o configuring mixers to create objects and store them in one or
more BXXP servers; and,
o configuring builders to perform the retrieve-evaluate-publish
paradigm.
Rose & Gazzetta Expires September 7, 2000 [Page 3]
Internet-Draft Blocks eXtensible eXchange Service March 2000
2. Defining Object Types
The SEP datastore DTD (c.f., [2]'s Section 7) defines the rules used
for structuring objects in an SEP datastore. In brief:
o each object must be a well-formed XML document[3];
o the root element of each object must contain a "name" attribute;
and,
o each element in the object, termed a property, may contain either
character data or subordinate elements, but not both.
The SEP datastore DTD describes both a generic syntax and a specific
syntax for an object type. The specific syntax uses a syntactic
minimization technique to increase readability and reduce size. For
this reason, use of a specific syntax is recommended.
For example, Appendix A uses an XML Document Type Definition (DTD)
to define the "rfc" object type. The DTD has four parts:
o a comment describing how to reference the DTD for inclusion in an
XML application;
o a collection of data type definitions (XML entities) used when
defining an object type (e.g., "DAY");
o a definition of an entity that corresponds to the object type
being defined (i.e., "RFCSPACE.BLOCK"); and,
o the definition of the object type.
By organizing a DTD in this fashion, object types are systematically
described and XML validators may be used during the development
process.
Rose & Gazzetta Expires September 7, 2000 [Page 4]
Internet-Draft Blocks eXtensible eXchange Service March 2000
2.1 Pre-defined Blocks
Section 6 defines the BXXS DTD, which defines commonly-used
properties used in object types, along with an important object type.
2.1.1 Commonly-used Properties
The BXXS DTD defines several elements known as the "generic" content
set:
title: a brief textual name for an object, e.g.,
<title>Request for Comments 2629</title>
description: a (possibly) multi-line description of an object;
image: an iconic representation of an object, having several
attributes:
src: a URI[4] to the corresponding image;
alt: an very brief textual name for the icon (optional);
height: the height in pixels of the icon (optional); and,
width: the width in pixels of the icon (optional), e.g.,
<image src='http://example.com/images/rfcicon.gif'
height='16' width='16' />
organization: a textual name for the organization "responsible" for
the object (if the length of this string is greater than 42
characters, then an abbreviated value should be placed in the
element's "abbrev" attribute), e.g.,
<organization abbrev='Invisible Worlds'>Invisible Worlds,
Incorporated</organization>
Rose & Gazzetta Expires September 7, 2000 [Page 5]
Internet-Draft Blocks eXtensible eXchange Service March 2000
address: contact information for the entity "responsible" for the
object, consisting of several optional elements:
postal: a postal address containing one or more "street"
elements, followed by any combination of "city", "region"
(state or province), "code" (zipcode or postal code), and
"country" elements, e.g.,
<postal>
<street>1179 North MacDowell Boulevard</street>
<street>M/S 40</street>
<city>Petaluma</city>
<region>CA</region>
<code>94954-6559</code>
<country>US</country>
</postal>
phone: a telephone number for voice purposes, e.g.,
<phone>+1 707 789 3700</phone>
facsimile: a telephone number for facsimile purposes;
email: an email address[5], e.g.,
<email>postmaster@example.com</email>
uri: a URI[4], e.g.,
<uri>http://example.com/</uri>
The flexibility in postal addresses is provided to allow for
different national formats. Note however, that although the order of
the "city", "region", "code", and "country" elements isn't
specified, at most one of each may be present. Regardless, these
elements must not be re-ordered during processing by an XML
application (e.g., display applications must preserve the ordering
of the information contained in these elements). Finally, the value
of the "country" element should be a two-letter code from ISO 3166.
Rose & Gazzetta Expires September 7, 2000 [Page 6]
Internet-Draft Blocks eXtensible eXchange Service March 2000
When defining a new object type (e.g., "rfc" in Appendix A), the
"%generic.content;" entity is included in the content model to allow
automatic inclusion of:
o an optional "title" element;
o an optional "description" element;
o zero or more "image" elements;
o an optional "organization" element; and,
o an optional "address" element in each object.
2.1.2 Scripts
An "xscript" object type consists of one or more "remote.props"
element along with generic content.
Each of the script's "remote.props" elements has the same semantic
content -- they differ only in the scripting language used to
implement the semantics. The two attributes in a "remote.props"
element are:
uri: a URI to the actual script; and,
language: the language the script is written in.
In addition, each "remote.props" element has zero or more "property"
elements, an optional "title" element, and an optional "description"
element. The "property" elements, if present, are used to pass
additional information to the URI (e.g., POST parameters for the
"http:" method).
As with all object types, the SEP requires that the "xscript"
element have a "name" attribute at its top-level, e.g.,
<xscript name='evaluate.doc.rfc.generic.1'>
<remote.props uri='ftp://example.com/scripts/5.tcl'
language='tcl' />
</xscript>
Rose & Gazzetta Expires September 7, 2000 [Page 7]
Internet-Draft Blocks eXtensible eXchange Service March 2000
3. Naming Objects
The Blocks naming structure is hierarchical, with labels separated
by dots, and read left-to-right, e.g.,
net.ipv4.207.67.199.3
doc.rfc.2629
The "Blocks Assigned Names and Numbers Allocator" (BANANA) is
responsible for assigning meaning to the most-significant (leftmost)
labels in a name. The prefix "private" is always available for
experimental uses, though collisions in naming within this space are
possible.
Until the Blocks convergence model is published and its service
provisioned, allocation of the Blocks namespace is done manually by
the BANANA using a mechanism of email-based requests for delegation
of authority. The BANANA DTD (Appendix C) defines the "soa.request"
document type, which should be mailed as an "text/xml" MIME
attachment to [11]. As the allocator will be an automated process in
the future, requests that require human intervention may be sent to
[12].
Once the BANANA has assigned a prefix to a developer, care should be
given to how blocks are named under that prefix. Although the SEP
allows for agressive searching within a high-level naming scope
(e.g., "doc.rfc"), if additional hierarchy is meaningfully applied,
then searching can be more focused.
For example, in the doc.rfc space, additional blocks are defined as
a mapping between RFC numbers as assigned by the RFC editor. This
naming convention (e.g., doc.rfc.2629) scales because of the limited
number of objects for which metadata are stored. However, for the
doc.edgar space which consists of metadata extracted from the SEC
EDGAR filing stream, a 3-level name space would be impractical,
containing over 500,000 objects at the third level. In the case of
doc.edgar, more meaning was added to the naming hierarchy by using
the year as the third level, a "CIK" (which is a unique
identification for a particular filer) as the fourth level, and
using a unique sequence number for the fifth (and final) level of
naming.
Synchronization of replicas of a particular portion of the Blocks
namespace and schema management are both addressed in the Blocks
convergence model. Until publication of those documents, relevant
schema information in the form of DTDs can be found at [13] with
directories conforming to the Blocks namespace, e.g., if you are
looking for relevant DTDs about doc.edgar, go look at [14].
Rose & Gazzetta Expires September 7, 2000 [Page 8]
Internet-Draft Blocks eXtensible eXchange Service March 2000
4. Creating and Storing Objects
Configuration of a mixer to create objects is a local matter. Once a
object is created (or modified), the mixer uses the Simple Exchange
Profile to store or update the object in one or more Blocks servers.
Rose & Gazzetta Expires September 7, 2000 [Page 9]
Internet-Draft Blocks eXtensible eXchange Service March 2000
5. Retrieving, Evaluating, and Publishing Objects
Builders take many forms. Web-based development with browsers as the
end-user's interface suggests CGI scripts as an important target
application of the architecture outlined above.
5.1 CGI-based Builders
This section defines the "space" interface for CGI-based builders.
5.1.1 CGI Parameters
There are four sets of parameters, prefixed by either "retrieve.",
"evaluate.", "publish.", or "url.".
5.1.1.1 Retrieval Parameters
There are five kinds of retrieval parameters: union, tag, text,
block, and miscellaneous.
5.1.1.1.1 Union Parameters
If you have a well-formed SEP "<union>" query (c.f., [2]'s Section
5), then use "retrieve.union".
5.1.1.1.2 Tag Parameters
If you want to retrieve based on XML content, use the retrieve.tag.*
parameters. This searches a subtree of blocks, on each element you
specify and merge the results from each search.
So, the first two tag parameters are:
1. retrieve.tag.subtrees, which contains a list of subtrees to
search separated by spaces (e.g., "doc.rfcs gloss.rfcs"); and,
2. retrieve.tag.merge, which says how to merge results, i.e., "and"
or "or" (the default)
Next, you specify how to search the XML content. Searching is
case-insensitive. There are three (or five) ways to do this:
1. retrieve.tag.[Ee].*, which looks for text inside an element's
character data, either exactly (retrieve.tag.E.*) or contained
within (retrieve.tag.e.*);
2. retrieve.tag.[Aa].*, which looks for text inside a particular
attribute value, either exactly (retrieve.tag.A.*) or contained
within (retrieve.tag.a.*); or,
Rose & Gazzetta Expires September 7, 2000 [Page 10]
Internet-Draft Blocks eXtensible eXchange Service March 2000
3. retrieve.tag.x.*, which looks for text inside any attribute
value in a particular element.
These parameters may occur multiple times (with results combined
according to the value of retrieve.tag.merge parameter). Because it
may be inconvenient to specify these parameters multiple times,
these special parameters may be used instead:
1. retrieve.tag.[Ll].*, which is analagous to retrieve.tag.[Ee].*;
and,
2. retrieve.tag.[Uu].*, which is analagous to retrieve.tag.[Aa].*.
These special parameters should occur at most once. Their values are
space-separated strings, each of which is treated as a value for
retrieve.tag.[Ee] or retrieve.tag.[Aa], respectively.
To specify a partial containment hierarchy, use the solidus
character to separate the element names, e.g.,
"retrieve.tag.a.doc.props/doc.title" or
"retrieve.tag.e.doc.author/fullname".
5.1.1.1.2.1 Normalization
If a parameter has the name of retrieve.tag.n.*, then it defines how
the text for that tag should be normalized (e.g.,
"retrieve.tag.n.conformed.name" determines how the value of
"retrieve.tag.e.conformed.name" should be normalized).
At present, there is only one defined value:
1: normalizes user-input for use with conformed names, e.g., removes
words like "INC.", replaces hyphens with spaces, and so on.
Rose & Gazzetta Expires September 7, 2000 [Page 11]
Internet-Draft Blocks eXtensible eXchange Service March 2000
5.1.1.1.2.2 Boolean Expressions
If the parameter retrieve.tag.boolean is not present, then the
retrieve.tag.merge parameter determines how the results from
searching for each retrieve.tag.[aex] parameter is merged.
If retrieve.tag.boolean is present, then it contains an infix
boolean expression describing how to merge the search results, e.g.,
"(Q1 OR Q2) AND Q3", where "Qx" is defined using two parameters,
retrieve.tag.k.Qx and retrieve.tag.v.Qx. The value of
retrieve.tag.k.* is the name of a retrieve.tag parameter, whilst the
value of retrieve.tag.v.* is the associated value to match for, e.g.,
retrieve.tag.boolean = "(Q1 OR Q2) AND Q3"
retrieve.tag.k.Q1 = "retrieve.tag.e.conformed.name"
retrieve.tag.v.Q1 = "AMAZON.COM"
retrieve.tag.k.Q2 = "retrieve.tag.e.conformed.name"
retrieve.tag.v.Q2 = "Message Media, Inc."
retrieve.tag.v.Q3 = "retrieve.tag.a.type"
retrieve.tag.v.q3 = "10-K"
In the case where you want to use a single value in different terms
you would use retrieve.tag.r.* as well, e.g.,
retrieve.tag.boolean = "(Q1 OR Q2) AND Q3"
retrieve.tag.k.Q1 = "retrieve.tag.e.conformed.name"
retrieve.tag.v.Q1 = "AMAZON.COM"
retrieve.tag.k.Q2 = "retrieve.tag.e.former.conformed.name"
retrieve.tag.r.Q2 = "retrieve.tag.v.Q1"
retrieve.tag.k.Q3 = "retrieve.tag.a.type"
retrieve.tag.v.Q3 = "10-K"
Note that value of the retrieve.tar.r term MUST be the name of a
retrieve.tag.v.* term defined for the boolean.
Rose & Gazzetta Expires September 7, 2000 [Page 12]
Internet-Draft Blocks eXtensible eXchange Service March 2000
5.1.1.1.3 Text Parameters
If you want to retrieve based on a fulltext searching, use:
o retrieve.text.full, which specifies a value consisting of one or
more words separated by spaces;
o retrieve.text.subtree, which contains a single subtree to direct
the search; and,
o retrieve.text.merge, which says how to merge results, i.e., "and"
or "or" (the default)
The retrieve.text.full parameter may occur multiple times (with
results combined according to the value of retrieve.text.merge
parameter).
Rose & Gazzetta Expires September 7, 2000 [Page 13]
Internet-Draft Blocks eXtensible eXchange Service March 2000
5.1.1.1.4 Block Parameters
If you always want the retrieval to include certain blocks (or don't
want to search at all), simply specify the blocks you're interested
in, separated by spaces:
o retrieve.blocks, e.g., "doc.rfc.2629 doc.rfc.2223"
o retrieve.blocks.element, e.g., "rfc".
The latter parameter, if present, specifies the top-level XML
element of the block, and often speeds performance.
5.1.1.1.5 Miscellaneous Parameters
o retrieve.maxhits: the maximum number of blocks to return
o retrieve.offset: where to start returning hits from (starting at
0);
o retrieve.server: the domain name (or IP address) of the BXXP
server to use; and,
o retrieve.port: the port on which to connect to the server
specified by the retrieve.server option (10288 by default).
Finally, three parameters are set prior to execution of the first
evaluation script:
o retrieve.names: a list containing the names, in order, of the
matches returned (upto retrieve.maxhits names starting at
position retrieve.offset);
o retrieve.allhits: the actual number of matches generated during
the retrieval process; and,
o space.query: the actual query given to the builder, regardless of
whether it was issued via a GET or POST.
To provide a "scrolling" interface, invoke the builder with a
reasonable value for retrieve.maxhits and a zero-valued
retrieve.offset. When the publication script runs, if:
retrieve.offset+retrieve.maxhits < retrieve.allhits
then create a "more" button which invokes the builder with an
identical set of parameters except that retrieve.offset is
incremented by the value of retrieve.maxhits.
Rose & Gazzetta Expires September 7, 2000 [Page 14]
Internet-Draft Blocks eXtensible eXchange Service March 2000
5.1.1.2 Evaluation Parameters
One or more Tcl[8] scripts are executed to evaluate the relationship
between the retrieved blocks:
o evaluate.scripts, e.g., evaluate.doc.rfc.generic.1; or,
o evaluate.uris, e.g., http://example.com/evaluate.tcl
As usual, separate the scripts or URIs with spaces in the value of
these parameters. Note that "evaluate.uris" is consulted only if
"evaluate.scripts" is not present.
Section 5.2.1 contains a list of commonly used evaluation scripts.
5.1.1.2.1 Evaluation Scripts
Each script is evaluated in a safe-interpreter. "Safe" filesystem
and socket access are allowed.
Prior to invoking the script, the options, env, and blocks arrays
are initialized. Upon completion of the script, the relates array is
read.
The options array contains an entry for each argument supplied to
the script, e.g.,
set options(publish.script) publish.doc.rfc.generic.1
The env array contains an entry for each environment variable
available to the script, e.g.,
set env(HTTP_SERVER) www.example.com
The blocks array contains an entry for each block retrieved by the
script. The syntax of this entry varies depending on the builder
version. The reference specification is described in Appendix B.
Finally, at completion, the relates array should contain an entry
for each block. The syntax of each entry is a serialized array, e.g.,
set relates(doc.rfc.1234) \
{score 1 superiors {doc.rfc.5678 doc.rfc.3456} luminance 1}
The semantics of each entry is dependent on how the publication
script will use it.
Rose & Gazzetta Expires September 7, 2000 [Page 15]
Internet-Draft Blocks eXtensible eXchange Service March 2000
5.1.1.3 Publication Parameters
A Tcl script will be executed to generate output:
o publish.script, e.g., publish.doc.rfc.generic.1; or,
o publish.uri, e.g., http://example.com/publish.tcl
Note that "publish.uri" is consulted only if "publish.script" is not
present.
The "publish.mime" parameter specifies the content-type generated by
the publication script, defaulting to "text/html". A publication
script producing some other type of output, should modify this
parameter accordingly.
The "publish.cookies" parameter, if created by the publication
script, contains a serialized array of cookies. Each element of the
array is a serialized array containing a "value", and optionally:
"domain", "expires", "path", and "secure".
5.1.1.3.1 Publication Scripts
Section 5.2.2 contains a list of well-known publishing scripts.
A publication script is evaluated in a safe-interpreter. "Safe"
filesystem and socket access are allowed.
Prior to invoking the script, the options, env, blocks, and relates
arrays are initialized. Upon completion of the script, the result is
returned to the browser.
5.1.1.4 URL Parameters
The builder uses HTTP to access the evaluation and publication
scripts references by the "evaluate.scripts", "evaluate.uris",
"publish.script", and "publish.uri" parameters. Because these URLs
may reside on sites with password protection, two additional
parameters are provided:
o *.username, which specifies a username for basic authentication
for the HTTP server at a given domain name (e.g., use a parameter
of "url.example.com.username" to specify the username for basic
authentication for http://example.com).
o *.password, which specifies the corresponding password.
Rose & Gazzetta Expires September 7, 2000 [Page 16]
Internet-Draft Blocks eXtensible eXchange Service March 2000
5.2 Well-known Scripts
5.2.1 Evaluation Scripts
5.2.1.1 evaluate.null.1
To specify that no evaluation is to be performed on the returned
blocks, use the evaluate.null.1 script.
5.2.1.2 evaluate.doc.*.generic.1
These scripts looks for a parameter called evaluate.luminance that
contains a list of URLs. Each URL references a .txt file that is
available via the http: method. Each line of the file starts with a
block name (e.g., "doc.rfc.2629") followed by an even number of
name/value pairs. All items are separated by spaces, e.g.,
doc.rfc.2629 luminance 100
Currently, valid luminance evaluations can be performed on edgar and
rfc documents.
5.2.1.3 evaluate.sort.1
This script sorts the returned blocks according to the following
options:
o user.evaluate.generic.sort.type, one of 'dictionary', 'ascii',
'integer', 'real' or 'calendar';
o user.evaluate.generic.sort.order, either 'ascending' or
'descending';
o user.evaluate.generic.sort.e, an element on whose text to sort;
and,
o user.evaluate.generic.sort.a, an attribute on whose value to sort;
Of course, only one of the user.evaluate.generic.sort.* options may
be specified for a given evaluation script.
Rose & Gazzetta Expires September 7, 2000 [Page 17]
Internet-Draft Blocks eXtensible eXchange Service March 2000
5.2.2 Publication Scripts
5.2.2.1 publish.doc.edgar.spacescript and publish.doc.spacescript20
These scripts specify use of SpaceScript as server-side blocks data
publication language. SpaceScript itself is described in a separate
document[7].
Options to be specified when using SpaceScript are:
o user.publish.spacescript.url, the location of the template that
contains SpaceScript code; and,
o user.publish.page.nav.url, the location of a template to be used
as page navigation tool.
5.2.2.2 publish.debug.1
This script displays the contents of the retrieved blocks without
further processing.
Rose & Gazzetta Expires September 7, 2000 [Page 18]
Internet-Draft Blocks eXtensible eXchange Service March 2000
6. The BXXS DTD
<!--
DTD for Blocks eXtensible eXchange Service, as of 2000-03-03
Copyright 1999, 2000 Invisible Worlds, Inc.
This document is a DTD and is in full conformance with all
provisions of Section 10 of RFC2026 except that the right to
produce derivative works is not granted.
Refer to this DTD as:
<!ENTITY % BXXS PUBLIC "-//Blocks//DTD BXXS//EN"
"http://xml.resource.org/blocks/bxxs.dtd">
%BXXS;
-->
<!--
Contents
External Entity definitions
Entities
Commonly-used Properties
Blocks about
Scripts
-->
<!--
External Entity definitions
Caller should already have included the SEP datastore DTD.
-->
<!ENTITY % BXXS.BLOCK "xscript">
Rose & Gazzetta Expires September 7, 2000 [Page 19]
Internet-Draft Blocks eXtensible eXchange Service March 2000
<!--
Entities
-->
<!ENTITY % generic.content
"title?,description?,image*,organization?,address?">
<!--
Commonly-used Properties
-->
<!ELEMENT title (%CTEXT;)>
<!ELEMENT description (%TEXT;)*>
<!ELEMENT image EMPTY>
<!ATTLIST image
src %URI; #REQUIRED
alt %ATEXT; ""
height %UINT16; #IMPLIED
width %UINT16; #IMPLIED>
<!ELEMENT organization
(%CTEXT;)>
<!ATTLIST organization
abbrev %ATEXT; #IMPLIED>
<!ELEMENT address (postal?,phone?,facsimile?,email?,uri?)>
<!-- at most one of each the city, region, code, and country
elements may be present -->
<!ELEMENT postal (street+,(city|region|code|country)*)>
<!ELEMENT street (%CTEXT;)>
<!ELEMENT city (%CTEXT;)>
<!ELEMENT region (%CTEXT;)>
<!ELEMENT code (%CTEXT;)>
<!ELEMENT country (%CTEXT;)>
<!ELEMENT phone (%CTEXT;)>
<!ELEMENT facsimile (%CTEXT;)>
<!ELEMENT email (%CTEXT;)>
<!ELEMENT uri (%CTEXT;)>
Rose & Gazzetta Expires September 7, 2000 [Page 20]
Internet-Draft Blocks eXtensible eXchange Service March 2000
<!--
Blocks about Scripts
-->
<!ELEMENT xscript (remote.props,%generic.content;)>
<!ATTLIST xscript
%block.attrs;>
<!ELEMENT remote.props
(property*,title?,description?)>
<!ATTLIST remote.props
uri %URI; #REQUIRED
language %ATEXT; "html">
Rose & Gazzetta Expires September 7, 2000 [Page 21]
Internet-Draft Blocks eXtensible eXchange Service March 2000
References
[1] Rose, M.T. and C. Malamud, "Blocks: Architectural Precepts",
draft-mrose-blocks-architecture-01 (work in progress), March
2000.
[2] Rose, M.T., "The Blocks Simple Exchange Profile",
draft-mrose-blocks-exchange-01 (work in progress), March 2000.
[3] World Wide Web Consortium, "Extensible Markup Language (XML)
1.0", W3C XML, February 1998,
<http://www.w3.org/TR/1998/REC-xml-19980210>.
[4] Berners-Lee, T., Fielding, R.T. and L. Masinter, "Uniform
Resource Identifiers (URI): Generic Syntax", RFC 2396, August
1998.
[5] Crocker, D., "Standard for the format of ARPA Internet text
messages", RFC 822, STD 11, Aug 1982.
[6] Rose, M.T., "The Blocks eXtensible eXchange Protocol",
draft-mrose-blocks-protocol-01 (work in progress), March 2000.
[7] Gazzetta, M.R., "SpaceScript 2.0", Draft Memo, January 2000.
[8] Ousterhout, J., "Tcl and the Tk Toolkit", ISBN 020163337X, May
1994, <http://www.amazon.com/exec/obidos/ASIN/020163337X>.
[9] mailto:blocks-request@invisible.net
[10] http://mappa.mundi.net/
[11] mailto:banana@invisible.net
[12] mailto:top-banana@invisible.net
[13] http://xml.resource.org/blocks/
[14] http://xml.resource.org/blocks/doc/edgar/
Rose & Gazzetta Expires September 7, 2000 [Page 22]
Internet-Draft Blocks eXtensible eXchange Service March 2000
Authors' Addresses
Marshall T. Rose
Invisible Worlds, Inc.
1179 North McDowell Boulevard
Petaluma, CA 94954-6559
US
Phone: +1 707 789 3700
EMail: mrose@invisible.net
URI: http://invisible.net/
Marco R. Gazzetta
Invisible Worlds, Inc.
1179 North McDowell Boulevard
Petaluma, CA 94954-6559
US
Phone: +1 707 789 3700
EMail: marcog@invisible.net
URI: http://invisible.net/
Rose & Gazzetta Expires September 7, 2000 [Page 23]
Internet-Draft Blocks eXtensible eXchange Service March 2000
Appendix A. The RFC space DTD
<!--
DTD for RFC blocks, as of 2000-03-03
Copyright 1999, 2000 Invisible Worlds, Inc.
This document is a DTD and is in full conformance with all
provisions of Section 10 of RFC2026 except that the right to
produce derivative works is not granted.
Refer to this DTD as:
<!ENTITY % RFCSPACE PUBLIC "-//Blocks//DTD RFCSPACE//EN"
"http://xml.resource.org/blocks/doc/rfc/rfcspace.dtd">
%RFCSPACE;
-->
<!--
Contents
DTD data types
External Entity definitions
Blocks about
RFC documents
-->
<!--
DTD data types:
entity syntax/reference example
====== ================ =======
DAY 1*2DIGIT 1
MONTH "January".."December" January
YEAR 4DIGIT 1999
-->
<!ENTITY % DAY "CDATA">
<!ENTITY % MONTH "CDATA">
<!ENTITY % YEAR "CDATA">
Rose & Gazzetta Expires September 7, 2000 [Page 24]
Internet-Draft Blocks eXtensible eXchange Service March 2000
<!--
External Entity definitions
Caller should already have included the BXXS DTD.
-->
<!ENTITY % RFCSPACE.BLOCK "rfc">
<!--
Blocks about RFC documents
-->
<!ELEMENT rfc (rfc.props,doc.props,remote.props+,
%generic.content;)>
<!ATTLIST rfc
%block.attrs;>
<!ELEMENT rfc.props EMPTY>
<!ATTLIST rfc.props
number %UINT32; #REQUIRED
category (std|bcp|info|exp|historic)
"info"
seriesNo %URI; #IMPLIED
relativeSize
%UINT32; #IMPLIED>
<!ELEMENT doc.props (doc.front,doc.extras?,doc.links?)>
<!ELEMENT doc.front (doc.title,doc.author+,doc.date,
doc.area*,doc.workgroup*,doc.keyword*)>
<!ELEMENT doc.title (%CTEXT;)>
<!ATTLIST doc.title
abbrev %ATEXT; #IMPLIED>
<!ELEMENT doc.author (organization,address?)>
<!ATTLIST doc.author
initials %ATEXT; #IMPLIED
surname %ATEXT; #IMPLIED
fullname %ATEXT; #IMPLIED>
<!ELEMENT doc.date EMPTY>
<!ATTLIST doc.date
day %DAY; #IMPLIED
month %MONTH; #REQUIRED
year %YEAR; #REQUIRED>
Rose & Gazzetta Expires September 7, 2000 [Page 25]
Internet-Draft Blocks eXtensible eXchange Service March 2000
<!ELEMENT doc.area (%CTEXT;)>
<!ELEMENT doc.workgroup
(%CTEXT;)>
<!ELEMENT doc.keyword (%CTEXT;)>
<!ELEMENT doc.extras EMPTY>
<!ATTLIST doc.extras
abstract (true|false) "false"
note (true|false) "false">
<!ELEMENT doc.links (doc.obsoletes*,doc.updates*,doc.references*)>
<!ELEMENT doc.obsoletes
EMPTY>
<!ATTLIST doc.obsoletes
target %URI; #REQUIRED>
<!ELEMENT doc.updates EMPTY>
<!ATTLIST doc.updates
target %URI; #REQUIRED>
<!ELEMENT doc.references
EMPTY>
<!ATTLIST doc.references
target %URI; #REQUIRED>
Rose & Gazzetta Expires September 7, 2000 [Page 26]
Internet-Draft Blocks eXtensible eXchange Service March 2000
Appendix B. Reference Blocks Structure Specification
Each element of the blocks array is a list. The first item of the
list is the name of the element. The second item of the list are any
attributes (represented as a serialized array). The remaining items,
three through N, of the list are the element's children. Each child
is stored in the same list format. If the element contains text,
then it has exactly one child and the name of that child is
".pcdata".
For example:
<outer name1="value1" name2="value2">
<middle>some text</middle>
<middle><inner /></middle>
</outer>
is represented as:
{ outer { name1 value1 name2 value2 }
{ middle {} {.pcdata {} "some text"} }
{ middle {} {inner {} } } }
Later versions of the builder store the blocks data in separate
form. To gain access to it, evaluate and publish scripts have to use
a set of API functions called BuilderAPI. This approach provides a
powerful way of separating data storage from data usage and allows
the retrieve step to be fully independent of the subsequent evaluate
and publish steps.
Rose & Gazzetta Expires September 7, 2000 [Page 27]
Internet-Draft Blocks eXtensible eXchange Service March 2000
Appendix C. The BANANA DTD
<!--
DTD for BANANA operations, as of 2000-03-03
Copyright 1999, 2000 Invisible Worlds, Inc.
This document is a DTD and is in full conformance with all
provisions of Section 10 of RFC2026 except that the right to
produce derivative works is not granted.
Refer to this DTD as:
<!ENTITY % BANANA PUBLIC "-//Blocks//DTD BANANA//EN"
"http://xml.resource.org/banana/banana.dtd">
%BANANA;
-->
<!--
Contents
Overview
External Entity Definitions
Operations
soa.request
-->
<!--
Overview
Requests for Delegation of Blocks Namespace
All soa.requests should be sent to mailto:banana@invisible.net
with a MIME attachment of type "text/xml" containing a
well-formed, valid instance of "soa.request".
Human beings may be reached at mailto:top-banana@invisible.net
-->
Rose & Gazzetta Expires September 7, 2000 [Page 28]
Internet-Draft Blocks eXtensible eXchange Service March 2000
<!--
External Entity definitions
Caller should already have included the BXXS DTD.
-->
<!--
Operations
soa.request - request a delegation in the Blocks namespace
the "prefix" attribute identifies the portion of the
namespace being requested, e.g., "doc.edgar", whilst the
"serial" attribute is a monotonically-increasing number.
the "requestor" element identifies the entity requesting the
delegation.
the "description" element describes the proposed use for the
namespace. if available, specify a URI to a DTD ("dtd-info")
that describes the objects contained in the namespace.
similarly, if available, specify a URI to a service
("space-info") that provides access to the namespace.
finally, a concise textual name ("space-name") is required.
the "allocation" element describes the proposed allocation
mechanism for the namespace: "manual" allocation indicates
that human intervention is required to map resources to block
names; "mapped" inicates that an existing namespace can be
used; and, "automatic" indicates that the allocation is
algorithmic in nature.
the "service" element identifies systems that offer SEP
access to the namespace.
-->
<!ELEMENT soa.request (requestor, description,
allocation.policy, blocks.service)>
<!ATTLIST soa.request
prefix %NAME; #REQUIRED
serial %ATEXT; #REQUIRED>
Rose & Gazzetta Expires September 7, 2000 [Page 29]
Internet-Draft Blocks eXtensible eXchange Service March 2000
<!ELEMENT requestor (name, organization, address)>
<!ELEMENT name EMPTY>
<!ATTLIST name
initials %ATEXT; #IMPLIED
surname %ATEXT; #IMPLIED
fullname %ATEXT; #IMPLIED>
<!ELEMENT description (%CTEXT;)>
<!ATTLIST description
dtd-info %URI; #IMPLIED
space-info %URI; #IMPLIED
space-name %ATEXT; #REQUIRED
xml:space (default|preserve) "preserve">
<!ELEMENT allocation (%CTEXT;)>
<!ATTLIST allocation
type (manual|mapped|automatic)
"manual"
xml:space (default|preserve) "preserve">
<!ELEMENT service (entrypoint+)>
<!ELEMENT entrypoint EMPTY>
<!ATTLIST entrypoint
domain %ATEXT; #REQUIRED
port %ATEXT; "10288">
Rose & Gazzetta Expires September 7, 2000 [Page 30]
Internet-Draft Blocks eXtensible eXchange Service March 2000
Appendix D. An Example of a Delegation Request
<!DOCTYPE soa.request PUBLIC
"http://xml.resource.org/banana/banana.dtd">
<soa.request prefix="doc.edgar" serial="2000011801">
<requestor>
<name initials="C." surname="Malamud"
fullname="Carl Malamud" />
<organization>Invisible Worlds, Inc.</organization>
<address>
<postal>
<street>1179 North MacDowell Boulevard</street>
<city>Petaluma</city>
<region>CA</region>
<code>94954-6559</code>
<country>US</country>
</postal>
<phone>+1 707 789 3700</phone>
<facsimile>+1 707 389 3710</facsimile>
<email>carl@invisible.net</email>
<uri>http://invisible.net/</uri>
</address>
</requestor>
<description
dtd-info="http://xml.resource.org/blocks/doc/edgar/edgarspace.dtd"
space-info="http://mappa.mundi.net/cartography/EDGAR/"
space-name="EDGARspace">
EDGARspace consists of a structured set of metadata extracted from
the flow of filings to the U.S. Securities and Exchange Commission.
Raw filings are converted to XML, metadata for the space is extracted
from the underlying XML file, from lookup tables (e.g., CIK to ticker
and home page mapping), through derived remote pointers, and through
calculations on other metadata sets. The collections are maintained
by Invisible Worlds.
</description>
Rose & Gazzetta Expires September 7, 2000 [Page 31]
Internet-Draft Blocks eXtensible eXchange Service March 2000
<allocation.policy type="mapped">
Block names in doc.edgar are based on accession numbers, a unique
identification for each underlying document in the SEC filing stream
which is created through a combination of the CIK identifier for
the filer, the date, and a sequence number.
For an SEC accession number of 0000950123-99-000456, this is
transformed into a Block name by flipping the position of the date
and making it Y2K compliant, adding the CIK of the filer stripped of
leading zeros, and then adding the sequence number stripped of
leading zeros to get:
doc.edgar.1999.950123.456
</allocation.policy>
<service>
<!--
Note: edgar.space.invisible.net is a load-balanced
set of underlying DNS names and IP addresses.
-->
<entrypoint domain="edgar.space.invisible.net" />
</service>
</soa.request>
Rose & Gazzetta Expires September 7, 2000 [Page 32]
Internet-Draft Blocks eXtensible eXchange Service March 2000
Appendix E. Changes from draft-mrose-blocks-service-00
o In Section 5.1.1.1.5, the "retrieve.port parameter was added.
o In Section 6, the correct URI is used to reflect the location of
the DTD.
o In Section 6, the "property*" content was added to the
"remote.props" element.
Rose & Gazzetta Expires September 7, 2000 [Page 33]
Internet-Draft Blocks eXtensible eXchange Service March 2000
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.
Rose & Gazzetta Expires September 7, 2000 [Page 34]
Internet-Draft Blocks eXtensible eXchange Service March 2000
Acknowledgement
Funding for the RFC editor function is currently provided by the
Internet Society.
Rose & Gazzetta Expires September 7, 2000 [Page 35]