Media Types

This section contains general concepts that apply to all PHACTOR documents.

All PHACTOR documents transfer state from clients to servers using link templates. All link templates have an href attribute. This is the target of the state transfer. Some link templates MAY have one or more <data> child elements. These child elements represent the names and values that will be sent to the server for processing.

There are three link templates in PHACTOR documents. They are:
• <LI>
• <LN>
• and <LT>.

<LT href="http://example.org/customers/search" label="Search Customers">
<data name="search-value" />
<data name="country" /> 
</LT>

All link templates use the application/x-www-form-urlencoded content-type when transfering state to servers. In the above example, if a user enters "Smith" as the value for search-value and "Canada" as the value for country, the client will transfer the name-value pairs as search-value=smith&country=Canada.

Some elements in PHACTOR documents can only contain child elements; no text nodes. These are referred to in this documentation as container elements.

The following are container elements:
• <document>
• <meta>
• <content>
• <section>
• <para>
• <LI>
• <LN>
• <LT>

Some elements in PHACTOR documents can only contain text; no child elements. These are referred to in this documentation as text elements.

The following are text elements:
• <title>
• <author>
• <update>
• <text>
• <data>

Some elements in PHACTOR documents have no child elements and no text nodes. These are referred to in this documentation as empty elements.

The following are empty elements:
• <eol />
• <LE />
• <LO />

Some elements in PHACTOR documents are "block" elements and others are "inline" elements. By default, block elements are formatted differently than inline elements. Generally, block elements begin on new lines, inline elements do not.

The following are block elements:
• <section>
• <para>
• <title>
• <author>
• <update>
• <LI>
• <LN>
• <LO>

The following are inline elements:
• <text>
• <eol />
• <data />
• <LE />
• <LO />

The value of the element represents the author of the document. It's data type is CDATA.

This element is an OPTIONAL child element of the <meta> element.

<meta>
<author>J. Doe - jdoe@example.org - http://example.org/jdoe/index</author>
...
</meta>

This element represents the main body of a PHACTOR document. It is a container element.

The <content> element is a REQUIRED child element of the <document> element.

This element MAY have the following child elements:
• <section>
• <LE />
• <LI>
• <LN>
• <LO />
• <LT>

<document>
<content>
...
</content>
</document>

This element is a container for data that will be sent to the server when a link template is submitted. It MUST have a name attribute. It MAY have a label attribute.

This element is a child element of the the following elements:
• <LI>
• <LN>
• <LT>

<LN href="http://example.com/comments/">
<data name="email" label="Your Email:" />
<data name="full-name" label="Your Name:" />
<data name="comments" label="Your Comments:" />
</LN>
              

This element represents the root of all PHACTOR documents. It MUST be the first element in all PHACTOR documents.

This element MAY have the following child elements:
• <meta>
• <content>

<document>
<meta>
...
</meta>
<content>
...
</content>
</document>

This element represents the "end-of-line" for a block of text. It should be interpreted as a "line-feed" character. This is an empty element. It has no valid child elements, and no valid attributes.

This element is an OPTIONAL child element of the <para]> element.

<para>
<text>This is line one of some text.</text>
<text>This text will also appear on line one.</text>
<eol />
<text>This text will appear on line two.</text>
</para>

This element contains child elements that represent the meta-data for the current representation.

This element is an OPTIONAL child element of the <document> element.

This element MAY have the following child elements:
• <title>
• <author>
• <updated>

<document>
<meta>
...
</meta>
...
</document>

The element represents a block of text in the docment. It is a container element.

This element is an OPTIONAL child element of the <section> element.

This element MAY have the following child elements:
• <eol />
• <LE />
• <LI>
• <LN>
• <LO />
• <LT>

<section>
<para>
...
</para>
<para>
...
</para>
</section>

This element represents a section of the document. It is a container element.

This element is an OPTIONAL child element of the <content> element.

The <section> element MAY have the following child elements:
• <para>
• <LE />
• <LI>
• <LN>
• <LO />
• <LT>

<content>
<section>
...
</section>
...
</content>

This element contains text; it is a text element. It's value data type is CDATA.

This element is an OPTIONAL child element of <para> element.

This element MAY have the following child elements:
• <EOL />
• <LE />
• <LI>
• <LN>
• <LO>
• <LT>

<text>This is some text.</text>

The value of this element represents the title of the document or section of the document. The value of this element SHOULD be the data-type CDATA.

This element is an OPTIONAL child of the following elements:
• <meta>
• <section>

When this element is a child element of the <meta> element, the value of this element represents the title of the document.

<meta>
<title>Customer List</title>
...
</meta>

When this element is a child of the <section> element, the value of this element represents the title of the current section.

<section>
<title>Introduction</title>
...
</section>
<section>
<title>Chapter 1</title>
...

</section>

The value of this element represents the date the document was last updated. It SHOULD be of the data type DATE.

This is an OPTIONAL child element of the <meta> element.

<meta>
<updated>2012-01-31</updated>
...
</meta>

This attribute describes the relationship from the current document to the anchor specified by the href attribute. The value of this attribute MUST be a space-separated list of one or more ID data-types.

This is a REQUIRED attribute for the following elements:
• <LE />
• <LI>
• <LN>
• <LO />
• <LT>

<LO href="http://example.org/customers/" CL="customer-list" />

This attribute specifies which transfer method will be used to submit the link tempate data set.

This is an OPTIONAL attribute for the <LI> element. Possible (case-insensitive) values for the HTTP protocol are "put" (the default) and "delete." Possible (case-insensitive) values for the FTP protocol are "stor" (the default) and "dele."

<LI href="http://example.org/customers/cust-001" CM="delete" />

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

The value of the attribute MUST be a valid URI.

This is a REQUIRED attribute for the following elements:
• <LE />
• <LI>
• <LN>
• <LO />
• <LT>

<LE href="http://example.org/images/logo" />

This attribute represents text associated with the element. The value of this attribute MUST be of the data-type TEXT.

This is an OPTIONAL attribute for the following elements:
• <data>
• <LE />
• <LI>
• <LN>
• <LO />
• <LT>

When applied to <LE /> elements, this attribute specifies alternate text For user agents that cannot display the resource representation indicated by the associated href attribute.

<LE href="http://example.org/images/logo" label="logo" />

When applied to <LO /> elements, this attribute specifies the link text that describes the resource representation indicated by the associated href attribute.

<LO href="http://example.org/customers/" label="View Customers" />

When applied to <LI>, <LI>, or <LT> elements, this attribute specifies the text of the activating control (i.e. button or link) for the template.

<LT href="http://example.org/customers/search" label="Search Customers">
<data name="search-value" />
</LT>

When applied to <data> elements, this attribute specifies that element's prompt text.

<LN href="http://example.org/customers/" >
<data name="customer-name" label="Name:"/>
<data name="shipping-address" label="Address:"/>
<data name="country" label="Country:"/>
</LN>

This attribute assigns the "control name" for the associated <data> element. When a link template is submitted for processing, <data>> elements have their name paired with their current value and these pairs are submitted with the template.

The value of this attribute MUST be of the data-type ID.

This is a REQUIRED attribute for <data> elements.

This is an OPTIONAL attribute for the following elements:
• <LI>
• <LN>
• <LT>

<LT href="http://example.org/customers/search" label="Search" >
<data name="search-value"/>
</LT>

The PHACTOR media type does not have any pre-defined link relation values. Authors are free to use any of the IANA registered link relation values when crafting resource representations. Authors may also wish to create their own unique link relation values using the standards outlined in RFC5988.

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.

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

DATE values must be valid per RFC3339.

ID tokens must begin with a letter ([A-Za-z]) and may be followed by any number of letters, digits ([0-9]), hyphens ("-"), underscores ("_"), colons (":"), and periods (".").

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

Text is meant to be "human readable".

URI is defined by RFC 3986

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

The details of designing and implementing PHACTOR extensions 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.