Media Types

Maze+XML - Format

Description

  1. Elements
  2. Attributes
  3. Link Relations
  4. Data Types
  5. Extensibility
NOTE:
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

1.

Elements

Below is a "map" of the Maze+XML media type. This map shows all the possible elements, attributes, link relations, and data types.

It should be noted that the media-type map below does not neccesarily represent a valid instance of a Maze+XML document. It is only useful as a map to explore the various features of the media type. You can find a list of valid instances of Maze+XML documents in the Examples section of this documentation.

Consider using RELAX NG Compact instead of the document map. [ngarthl]

<maze version="1.0">
  <collection href="URI">
    <link href="URIrel="maze" />
    <link href="URIrel="maze" />
    ...
  </collection>
  <item href="URI" >
    <link href="URIrel="start" />
    <debug>CDATA</debug>
  </item>  
  <cell href="URIdebug="TEXT" total="NUMBER" side="NUMBER">
    <link href="URIrel="current" debug="TEXT" total="NUMBER" side="NUMBER" /> <!-- alternate 'current' link -->
    <link href="URIrel="north" />
    <link href="URIrel="south" />
    <link href="URIrel="east" />
    <link href="URIrel="west" />
    <link href="URIrel="exit" />
  </cell>
  <error href="URI">
    <title>TEXT</title>
    <code>TEXT</code>
    <message>CDATA</message>
  </error>
</maze>         
          

1.1.

<cell>

The <cell> element represents a single "cell" or "block" in the maze.

The <cell> element SHOULD have two attributes: href and rel. The href attribute MUST contain a valid URI. The rel attribute SHOULD be set to "current".

The <cell> element MAY have one or more of the following attributes: debug, total, and size.

The <cell> element MAY have one or more <link> child elements.

1.2.

<code>

The <code> element is a child element of the <error> element. It can be used to provide a human-friendly error code for the error being reported.

It SHOULD contain valid TEXT data.

It is an OPTIONAL element.

1.3.

<collection>

The <collection> element represents the list of available "mazes" in this collection.

The <collection> element SHOULD have an href attribute with a URI value which points to this resource. If present, this URI MAY be used with the HTTP POST method to create a new "maze" or "game" as a child resource of the collection URI.

The <collection> element MAY have one or more <link> child elements. Each of these child elements SHOULD have a rel attribute with a value of "maze". This indicates the associated href of the link element has a URI which points to the the starting point of a maze or game.

1.4.

<debug>

This element is a child of the <item>. It contains additional information that can be used to help debug or inspect the state of the maze or game. This data is defined by and supplied by the server.

This element SHOULD contain only valid CDATA.

This is an OPTIONAL element.

Consider moving this to an extension. [ngarthl]

1.5.

<error>

The <error> element is an OPTIONAL element. It MAY contain one or more child elements. The list of valid child elements is: <title>, <code>, <message>, and <link>.

Each of the above child elements MUST appear no more than once within the <error> element.

If the <error> element appears in the document, it SHOULD be the only child element of the <maze> element.

1.6.

<item>

The <item> element represents a complete "maze" or "game."

The <item> element SHOULD have an href attribute. The href attribute MUST contain a valid URI. The <item> element SHOULD have a <link> child element whose attributes SHOULD point to the start of a maze or game. The <item> element MAY have a <debug> child element.

1.7.

<link>

The <link> element MUST have two attributes: href, and rel. The href attribute MUST contain a valid URI. The rel attribute SHOULD contain one of the valid Link Relation values.

The <link> MAY appear as the child element of the <collection>, <item>, and <error> elements.

NOTE: If the <link> element has a rel attribute set to current it MAY also have the following addition attributes: debug, size, and total.

Consider adding @name or @id to links to help w/ identification in a collection [ngarthl].

1.8.

<maze>

A valid Maze+XML document MUST have a root element of <maze>. It MAY have one or more of the following child elements: <collection>, <item>, <cell>, and <error>.

Each of these child elements MUST NOT appear more than once within the document. If the <error>element appears, it SHOULD be the only child element of the document.

1.9.

<message>

The <message> element is a child element of the <error> element. It holds additional information about the error that is represented by the <error> element.

It SHOULD contain only valid CDATA chacters.

It is an OPTIONAL element.

1.10.

<title>

The <title> element is a child element of the <error> element. It can be used to provide a human-friendly title for the error being reported.

It SHOULD contain valid TEXT data.

It is an OPTIONAL element.

2.

Attributes

Below is a list of all the attributes used in the Maze+XML media type:

2.1.

debug

This attribute contains text data that represents debugging information supplied by the server. It's value MUST be TEXT

This is an OPTIONAL attribute. If present, it MUST only appear on the <cell> element.

2.2.

href

This attribute specifies the location of a Maze+XML resource, thus defining a link between the current resource and the destination resource defined by this attribute.

The value of the attribute MUST always be a valid URI.

This is an OPTIONAL attribute for the following elements: <collection>, <item>, <cell>, and <error>. This is a REQUIRED attribute for the <link> element.

2.3.

rel

This attribute describes the relationship from the current representation to the URI specified by the href attribute. The value of this attribute SHOULD be one of the values listed in the Attributes section of this document.

This is a REQUIRED attribute for the <link> element.

2.4.

side

This attribute indicates the number of cells on a single side of the maze represented by this document. The value of this attribute MUST be a valid NUMBER.

This is an OPTIONAL attribute. If it is present, it MUST only appear on the <cell> element.

2.5.

total

This attribute indicates the total number of cells in the maze represented by this document. The value of this attribute MUST be a valid NUMBER.

This is an OPTIONAL attribute. If it is present,it MUST only appear on the <cell> element.

2.6.

version

Indicates the version of this Maze+XML media-type document. The value of this attribute MUST be set to "1.0" for this version of the documentation.

This is an OPTIONAL attribute. If it is present, it MUST only appear on the <maze> element.

3.

Link Relations

Below is a list of all the valid link relation values for the rel attribute of the Maze+XML document.

Consider using full URI|IRI or possibly URNs for link relation values. [ngarthl]

3.1.

collection

Refers to a resource that returns a list of the target document/entities, etc. Logged with the Microformats Existing Rel Values.

When used in the Maze+XML media type, the associated URI returns the available collection of mazes.

3.2.

current

Refers to a resource containing the most recent item(s) in a collection of resources. Registered through IANA Link Relations.

When used in the Maze+XML media type, the associated URI returns the client's current position in the active maze.

3.3.

east

Refers to a resource to the "east" of the current resource. Logged with the Microformats Existing Rel Values.

When used in the Maze+XML media type, the associatd URI points to a neighboring cell resource to the east in the active maze.

3.4.

exit

Refers to a resource that represents the exit or end of the current client actvity or process. Logged with the Microformats Existing Rel Values.

When used in the Maze+XML media type, the associated URI points to the final exit resource of the active maze.

3.5.

maze

Refers to a single maze/game document.

When used in the Maze+XML media type, the associated URI points to an existing resource that represents a maze.

3.6.

north

Refers to a resource that is "north" of the current resource. Logged with the Microformats Existing Rel Values.

When used in the Maze+XML media type, the associatd URI points to a neighboring cell resource to the north in the active maze.

3.7.

south

Refers to a resource that is "south" of the current resource. Logged with the Microformats Existing Rel Values.

When used in the Maze+XML media type, the associatd URI points to a neighboring cell resource to the south in the active maze.

3.8.

start

Refers to the first resource in a collection of resources. Registered through IANA Link Relations.

When used in the Maze+XML media type, the associated URI refers to the starting cell resource within a maze.

3.9.

west

Refers to a resource that is "west" of the current resource. Logged with the Microformats Existing Rel Values.

When used in the Maze+XML media type, the associatd URI points to a neighboring cell resource to the west in the active maze.

4.

Data Types

Below are the data types used in Maze+XML documents. The reference for most of the data type definitions below is the SGML basic types section of the HTML 4.01 Specification.

4.1.

CDATA

CDATA is a sequence of characters from the document character set and may include character entities.

4.2.

NUMBER

Numbers MUST contain at least one digit ([0-9]). The characters ".", "-", and "+" MAY also appear.

4.3.

TEXT

Text is meant to be "human readable".

4.4.

URI

URI is defined by RFC 3986

5.

Extensibility

added 2010-12-08 per [ngarthl] suggestion.

This document describes the Maze+XML markup vocabulary. Markup from other vocabularies ("foreign markup") can be used in a Maze+XML document. Any extensions to the Maze+XML vocabulary MUST not redefine any elements, attributes, link relations, or data types defined in this document. Clients that do not recognize extensions to the Maze+XML vocabulary SHOULD ignore them.

The details of designing and implementing Maze+XML is beyond the scope of this document.

NOTE: It is possible that future forward-compatible modifications to this specification will include new elements, attributes, link-relations, and data types. Extension designers should take care to prevent future modifications from breaking or redefining those extensions. The safest way to do this is to use a unique XML Namespace for each extension.

Update History

2010-12-06
Updated Maze+XML
2010-11-27
Initial post