PHACTOR - Document Format
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.
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.
<LT href="http://example.org/customers/search" label="Search Customers"> <data name="search-value" /> <data name="country" /> </LT>
All link templates use the
when transfering state to servers. In the above example, if a user enters "Smith" as the value for
and "Canada" as the value for
country, the client will transfer the name-value pairs as
Block and Inline Elements
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 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 - firstname.lastname@example.org - http://example.org/jdoe/index</author> ... </meta>
<document> <content> ... </content> </document>
<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>
<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.
<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.
<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.
<content> <section> ... </section> ... </content>
This element is an OPTIONAL child element of <para> element.
<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.
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.
<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.
<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.
<LE href="http://example.org/images/logo" label="logo" />
<LO href="http://example.org/customers/" label="View Customers" />
<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.
<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.
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.
Major updates to fill out document