UserPreferences

PaceServiceDescription


Absract

Replace the draft-06 introspection format

Rationale

The current introspection format is a poor fit for server description. It doesn't allow hierarchy, is extremely over-engineered, and clutters up the protocol document with XML trivia that the document format does not require. APP SDF is an extremely simple format that meets all of the requirements for Atom Protocol.

Implementers are confused and intimidated by the writing style used for the current format, which borrows heavily from the AtomFormat spec. This style is unnessecary for a document that will be authored by people writing APP implementations.

Proposal

Replace Sections 6 and 7 of draft-06 as follows:

APP Service Description Format

Many APP applications require a basic resource layout in order to ease configuration requirements. This section defines the APP Service Description Format, which servers use to convey information about related groups of APP feeds. On a blogging service, for example, each group might represent a distinct blog and associated resources.

Example APP Service Description Document:

<app>
  <service name="My Blog" class="feed" 
   href="http://example.com/entries">
    <service name="Photos" class="media feed" 
     href="http://example.com/photos"/>
    <service name="Drafts" class="feed" 
     href="http://example.com/drafts"/>
  </service>
  <service class="feed" name="Sidebar Blog"
   href="http://example.org/details"/>
</app>
Servers are not required to expose an APP Service Description Document, but experimental deployment experience has shown that a single document which signals some basic information about the server's configuration can greatly simplify client implementations. The simplest useful Service Description Document shows the location of a single resource:

<app>
  <service name="My Blog" class="feed"
   href="http://blog.example.com/app.cgi"/>
</app>

If another service is added, the document can be upgraded to reflect new resources.

<app>
  <service name="My Blog" class="feed"
   href="http://blog.example.com/app.cgi"/>
  <service name="Another Blog" class="feed"
   href="http://another.example.com/app.cgi"/>
</app>

Finally, more extensive services could require some amount of hierarchical grouping.

<app>
  <service name="My Blog" class="feed"
   href="http://blog.example.com/app.cgi">
   <service name="Photos" class="media feed" 
     href="http://example.com/photos"/>
  </service>
  <service name="Other Things">
    <service name="Another Blog" class="feed"
     href="http://another.example.com/app.cgi"/>
    <service name="A Third Blog" class="feed"
     href="http://third.example.com/app.cgi"/>
  </service>
</app>

This example shows that links to APP feeds can appear in <service> elements used to group other resources. The <service> element named "Other Things" does not contain an 'href' attribute, so it functions as a simple named group of the services it contains.

Document Format

APP Service Description Documents MUST be well-formed XML [W3C.REC-xml-20040204].

The root element of an APP Service Description Document is "<app>". This specification does not define any attributes of the <app> element, but the element MAY have any number of attributes.

Zero or more <service> elements MAY appear as child elements of <app>. Also, <service> elements MAY contain zero or more <service> elements. This specification defines three attributes of the <service> element. <service> elements MUST contain at least a 'name' or 'href' attribute. Additional service properties too large or structured to include in attribute values could appear as child elements of the service element.

<app> elements MAY contain any number of elements that are not <service> elements, and <service> elements MAY contain any number of elements that are not <service> elements.

The 'name' Attribute

The 'name' attribute contains a short string describing the service element. Entities such as "&amp;" and "&lt;" represent their corresponding characters ("&" and "<" respectively), not markup.

The 'href' Attribute

The 'href' attribute contains an IRI reference interpreted relative to the in-scope base IRI [RFC3987]. Most protocols require URIs [RFC3986], so IRIs usually need to be converted to URIs before being dereferenced.

The 'class' Attribute

The 'class' attribute contains a space-separated list of strings used to classify the service element. This specification defines two values for the 'class' attribute:

These values correspond to standard feeds and media feeds, respectively [APP]. If the 'class' attribute is not present, the <service> element can be processed as if the attribute were present with a value of 'feed'.

Relax NG Schema

This schema is normative.

start = app

app = element app {
  anyAttribute*,
  (service* & anyElement*) 
}

service = element service {
  (nameAtt | hrefAtt), anyAttribute*,
  (service* & anyElement*) 
}

nameAtt = attribute name { text }
hrefAtt = attribute href { text }       
classAtt = attribute class { text }     

anyElement = element * { (anyAttribute | text | anyElement)* }
anyAttribute = attribute * { text }

Extending Service Description

The APP Service Description Format can be freely extended by adding attributes and elements not defined by this specification.

Valid APP Service Description Document with extensions:

<app foo="bar">
  <blog-userid>42</blog-userid>
  <service name="Baz" qux="hmmm" href="http://example.com">
    <some-other-extension>hmm</some-other-extension>
  </service>
</app>

Additional service properties too large or structured to include in attribute values could appear as child elements of the <service> or <app> elements. <app> elements MAY contain any number of elements that are not <service> elements, and <service> elements MAY contain any number of elements that are not <service> elements.

User Agent Conformance

Foreign markup is markup not defined by this specification.

Software consuming APP Service Description Documents MUST NOT not halt processing when any foreign markup is encountered. Software MAY ignore the markup and process any content of foreign elements as though the surrounding markup were not present. For example, software may process

<app>
  <workspace>
    <service name="My Blog" 
     href="http://example.com/entries">
      <service name="Photos" class="media feed" 
       href="http://example.com/jpgs"/>
      <view title="Archives" seek="...">
        <view title="2005" href="..." />
         ...
      </view>
    </service>     
  </workspace>
</app>

as though the <workspace> and <view> elements were not present.

Software conforming to this specification MAY halt processing when documents that do not conform to the schema below are encountered.


CategoryProposals