Mappa.Mundi Index Go

Network Working GroupM.T. Rose
Internet-DraftM.R. Gazzetta
Expires: September 8, 2000Invisible Worlds, Inc.
 March 10, 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 8, 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; there is also a developers' site.


Go

Table of Contents
Go

1. Introduction

This document describes how to provision a Blocks service.

Service provisioning consists of several activities:


Go

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:

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, The RFC space DTD uses an XML Document Type Definition (DTD) to define the "rfc" object type. The DTD has four parts:

By organizing a DTD in this fashion, object types are systematically described and XML validators may be used during the development process.

2.1 Pre-defined Blocks

The BXXS DTD 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 description of an object which may span multiple lines;
image:
an iconic representation of an object, having several attributes:
src:
a URI[4] reference 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>
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.

When defining a new object type (e.g., "rfc" in The RFC space DTD), the "%generic.content;" entity is included in the content model to allow automatic inclusion of:

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>


Go

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 defines the "soa.request" document type, which should be mailed as an "text/xml" MIME attachment to mailto:banana@invisible.net. As the allocator will be an automated process in the future, requests that require human intervention may be sent to mailto:top-banana@invisible.net.

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 http://xml.resource.org/blocks/ with directories conforming to the Blocks namespace, e.g., if you are looking for relevant DTDs about doc.edgar, go look at http://xml.resource.org/blocks/doc/edgar/.


Go

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.


Go

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

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 the value of the retrieve.tag.r term MUST be the name of a retrieve.tag.v.* term defined for the boolean.

5.1.1.1.3 Text Parameters

If you want to retrieve based on a fulltext searching, use:

The retrieve.text.full parameter may occur multiple times (with results combined according to the value of retrieve.text.merge parameter).

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:

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

Finally, three parameters are set prior to execution of the first evaluation script:

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.

5.1.1.2 Evaluation Parameters

One or more Tcl[8] scripts are executed to evaluate the relationship between the retrieved blocks:

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.

Evaluation Scripts 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 Reference Blocks Structure Specification.

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.

5.1.1.3 Publication Parameters

A Tcl script will be executed to generate output:

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

Publication Scripts 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:

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:

Of course, only one of the user.evaluate.generic.sort.* options may be specified for a given evaluation script.

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:

5.2.2.2 publish.debug.1

This script displays the contents of the retrieved blocks without further processing.


Go

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






<!--
  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;)>












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

Go

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.
[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.
Go

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/
Go

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



<!--
  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>

<!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>


Go

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.


Go

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





<!--
  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>






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

Go

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>







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

Go

Appendix E. Changes from draft-mrose-blocks-service-00
Go

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.
Mappa.Mundi Index Go