The following target names do not exist: RFC2119, W3C.REC-xml-infoset-20040204, W3C.REC-xml-20060816, schema, W3C.REC-xmlbase-20010627, RFC3986, W3C.REC-xml-20060816, RFC3986, RFC3987, model, RFC2616, W3C.REC-webarch-20041215, RFC2616, collection_resource, memuri, appdocs, appdocs, catdocs
The Neutron 1.0 Protocol
draft-neutron-protocol-0.txt
This stylesheet requires either an XSLT-1.0 processor with node-set() extension function, or an XSLT-2.0 processor. Therefore, parts of the document couldn't be displayed.
The Neutron Protocol is an XML-based application-level protocol for remote content authoring. Neutron provides a generic API to what common Content Management Systems (CMS) support with respect to content authoring.
To provide feedback on this Internet-Draft, join the OSR-101 mailing list (http://wyona.com/cgi-bin/mailman/listinfo/osr-101/).
Neutron 1.0 is an xml-based application level protocol for remote content authoring. Neutron provides a set of methods and configuration directives that allow for:
Neutron has been been started as an effort to provide a generic API to what common Content Management Systems (CMS) support with respect to content authoring. CMS vendors usually implement their own frontend components for content authoring and/or implement a public API for third party component integration. Neutron is ment to be an open standard that leverages integration and reuse of third party components such as editing applications or standalone clients targeted at offline operation. While targeted at large scale content management systems, Neutron can also be used for accessing lightweight content repositories, datastores or remote file systems.
Neutron is typically used over HTTP. However, Neutron can be run on top of any other transport protocol if feasable.
Neutron provides a comprehensive set of instructions for dealing with XML-based resources. Usage of XML-based resources is not required though. Neutron also covers transactions of binary, SGML or other custom formatted data while being extensible enough for integrators to deal with the data formats of their choice.
Compared to other open content authoring standards Neutron is higher-level than WebDAV and lower-level than Atom, to name two prominent examples in that field. While WebDAV operates on Web resources Neutron operates on content servers that might expose their resources to the web. While Atom is targeted at content syndication Neutron provides a generic API to content authoring.
For examples and usage patterns see Appendix B.
The core of the Neutron Protocol consists of the introspection object. The introspection object contains information about one or more resources, in terms of what operations can be performed on those resources, and how.
The same introspection object can be bound to one or multiple resources (i.e. it can be auto-discovered through these resources), and can in turn contain information about one or multiple resources. The introspection object is not required to contain information about the object to which it was bound, but it is recommended to do so.
Note that it might not be possible to bind an introspection object to a specific resource. Namely, it may not be possible to bind it to e.g. an ODT document, and therefore it is not possible to discover the introspection object when processing the ODT document. In such cases, the introspection object should either be bound to a nearby object, or the contents of the introspection object should be merged with the contents of a nearby introspection object.
A client supporting HTML/XHTML (like e.g. Yulup) can discover the introspection object through a Neutron specific "<link>" within the HTML head.
The "<link>" element MUST contain the following attributes:
<html>
<head>
<link rel="neutron-introspection" type="application/neutron+xml" href="introspection-hello-world.xml"/>
<title>Hello World</title>
...
</head>
...
</html>
Figure 1: Introspection Auto-Discovery Example
The mime type of an introspection document which is being returned by the server to the client is "application/xml". Please note that the mime type refered to within this section is independent of the type declaration within the introspection link.
WWW-Authenticate: Neutron-Auth
Neutron: 1.0, 2.0-dev / en
URLs are being resolved relative to the introspection URL. Empty URLs refer to the introspection URL itself.
<?xml version="1.0"?>
<introspection xmlns="http://www.wyona.org/neutron/1.0">
<edit mime-type="application/xhtml+xml" name="Homepage">
<open url="index.xhtml" method="GET"/>
<save url="index.xhtml?yanel.resource.usecase=save" method="POST"/>
</edit>
</introspection>
Figure 2: Example: Opening and Saving of an XHTML document without Locking
<?xml version="1.0"?>
<introspection xmlns="http://www.wyona.org/neutron/1.0">
<edit mime-type="application/xml" name="Calendar">
<open url="calendar.xml" method="GET"/>
<save url="calendar.xml?yanel.resource.usecase=save" method="POST"/>
<styles>
<style href="calendar2xhtml.xsl"/>
</styles>
</edit>
</introspection>
Figure 3: Example: Opening and Saving of an XML document with an XSLT associated without Locking
To open a resource, clients use the URL and METHOD specified within the introspection.
To save a resource, clients use the URL and METHOD specified within the introspection.
The server responds with a status code of 200 and the content which has been saved as a response. Please note that server might change the received content (e.g. last modified date) and hence the client is able to become aware of such changes.
<?xml version="1.0"?>
<introspection xmlns="http://www.wyona.org/neutron/1.0">
<edit mime-type="application/xhtml+xml" name="Homepage">
<checkout url="index.xhtml?yanel.resource.usecase=checkout" method="GET"/>
<checkin url="index.xhtml?yanel.resource.usecase=checkin" method="PUT"/>
</edit>
</introspection>
Figure 4: Opening and Saving with Locking Example
To open a resource, clients use the URL and METHOD specified within the introspection.
The server acquires a lock and responds with the data of the resource.
To save a resource, clients use the URL and METHOD specified within the introspection.
The server releases the previously acquired lock and responds with a status code of 200.
In order to create a resource the server needs to provide a resource navigation, e.g. a sitetree
<?xml version="1.0"?>
<introspection xmlns="http://www.wyona.org/neutron/1.0">
<navigation>
<sitetree href="sitetree.xml" method="GET"/>
<--
<sitetree href="/" method="PROPFIND"/>
-->
<--
<topicmap href="topicmap.xtm" method="GET"/>
-->
</navigation>
</introspection>
Also see http://www.webdav.org/specs/rfc2518.html
<multistatus xmlns="DAV:">
<response>
<href>/yanel/osr-101/amendments/index.html?yanel.webdav=propfind1</href>
<propstat>
<prop>
<displayname>index.html</displayname>
<resourcetype/>
<getcontenttype>application/xhtml+xml</getcontenttype>
<source>
<link>
<src>/yanel/osr-101/amendments/index.html</src>
<dst>/yanel/osr-101/amendments/index.html?yanel.resource.modifiable.source</dst>
</link>
</source>
</prop>
<status>HTTP/1.1 200 OK</status>
</propstat>
</respons>
<response>
<href>/yanel/osr-101/amendments/.svn/</href>
<propstat>
<prop>
<displayname>.svn</displayname>
<resourcetype><collection/></resourcetype>
<getcontenttype>httpd/unix-directory</getcontenttype>
</prop>
<status>HTTP/1.1 200 OK</status>
</propstat>
</response>
</multistatus>
TBD
TBD
If a Neutron-capable client issues a request, the server can respond with exceptions. The following exceptions are defined by the Neutron protocol.
Neutron exceptions have a root element "<exception>" with a "type" attribute, specifying the kind of exception. This element then contains a "<message>" element which can contain a human-readable representation of the exception.
The second element is defined by the exception type (for details, see the various exception types below).
Note that this section is basically the specification of Neutron-Auth, a separate protocol which allows the authentication of clients using arbitrary inputs.
A client supporting Neutron-Auth should always add "WWW-Authenticate: Neutron-Auth" to the HTTP header (beside the version of Neutron, e.g. Neutron: 1.0-dev) such that a server can respond accordingly.
An example of a client-server coversation is as follows:
Client Request: GET http://foo.bar/protected.xhtml HTTP/1.1..WWW-Authenticate: Neutron-Auth..Neutron: 1.0-dev..
Server Response: HTTP/1.1 301 (or 307) https://foo.bar/protected.xhtml
Client Request: GET https://foo.bar/protected.xhtml HTTP/1.1..WWW-Authenticate: Neutron-Auth..Neutron: 1.0-dev..
Server Response: HTTP/1.1 401 Unauthorized..
<?xml version="1.0"?>
<exception xmlns="http://www.wyona.org/neutron/1.0" type="authorization">
<message>Authorization denied for https://foo.bar/protected.xhtml ...</message>
<authentication>
<login url="https://foo.bar/protected.xhtml?action=login-neutron">
<message>Login for realm 'Foo Bar' ...</message>
<form>
<param description="Username" name="username"/>
<param description="Password" name="passwd"/>
</form>
</login>
<logout url="http://foo.bar/?action=logout"/>
</authentication>
</exception>
Client Request: POST https://foo.bar/protected.xhtml?action=login-neutron
<?xml version="1.0"?>
<authentication xmlns="http://www.wyona.org/neutron/1.0">
<param name="username">lenya</param>
<param name="passwd">levi</param>
<original-request url="https://foo.bar/protected.xhtml"/>
</authentication>
(Please note that the above POST request by the client would actually be encrypted since https/SSL is being used, but for illustration plain text is displayed)
Server Response: HTTP/1.1 200 OK.. or Server Response: HTTP/1.1 401 Unauthorized which gives a response body like
<?xml version="1.0"?>
<exception xmlns="http://www.wyona.org/neutron/1.0" type="authentication">
<message>Authentication failed!</message>
<authentication>
<original-request url="http://demo.yulup.org:80/editable-page-with-locking.xhtml?yanel.resource.usecase=checkout"/>
<login url="http://demo.yulup.org:80/editable-page-with-locking.xhtml?yanel.resource.usecase=checkout&yanel.usecase=neutron-auth" method="POST">
<form>
<message>Enter username and password for "Yulup Demo" at "/demo/"</message>
<param description="Username" name="username"/>
<param description="Password" name="password"/>
</form>
</login>
<logout url="http://demo.yulup.org:80/editable-page-with-locking.xhtml?yanel.resource.usecase=checkout&yanel.usecase=logout" realm="Yulup Demo"/>
</authentication>
</exception>
Client Request: GET https://foo.bar/protected.xhtml
<?xml version="1.0"?>
<exception xmlns="http://www.wyona.org/neutron/1.0" type="checkout">
<message>Document has already been checked-out by ...</message>
<checkout url="/hello/world.html">
<locked-by>Jimi Hendrix</locked-by>
<lock-date format="standard">1969.10.03T15:34:26</lock-date>
<!-- Optional. Depending on server implementation -->
<break-lock url="/hello/world.html?yanel.resource.usecase=break-lock"/>
</checkout>
</exception>
How does the server respond to the "break-lock" request?
If the server cannot save the data, then it should return HTTP Status Code 500 and a message.
<?xml version="1.0"?>
<exception xmlns="http://www.wyona.org/neutron/1.0" type="checkin">
<message>Checkin failed, because document has been checked-out by ...</message>
<checkin url="/hello/world.html">
<locked-by>Jimi Hendrix</locked-by>
<lock-date format="standard">1969.10.03T15:34:26</lock-date>
<!-- Optional. Depending on server implementation -->
<break-lock url="/hello/world.html?yanel.resource.usecase=break-lock"/>
</checkin>
</exception>
If the server cannot save the data, then it should return HTTP Status Code 500 and a message.
<?xml version="1.0"?>
<exception xmlns="http://www.wyona.org/neutron/1.0" type="data-not-well-formed">
<message>Received data is not well-formed XML ...</message>
<data-not-well-formed url="/hello/world.html">
<line number="45" message="element not closed"/>
</data-not-well-formed>
</exception>
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 Undefined target: RFC2119[].
Neutron Protocol Document formats are specified in terms of the XML Information Set Undefined target: W3C.REC-xml-infoset-20040204[], serialized as XML 1.0 Undefined target: W3C.REC-xml-20060816[].
The Infoset terms "Element Information Item" and "Attribute Information Item" are shortened to "element" and "attribute" respectively. Therefore, when this specification uses the term "element", it is referring to an Element Information Item, and when it uses the term "attribute", it is referring to an Attribute Information Item.
Some sections of this specification are illustrated with fragments of a non-normative RELAX NG Compact schema [RNC]. However, the text of this specification provides the definition of conformance. Complete schemas appear in Undefined target: schema[].
XML elements defined by this specification MAY have an xml:base attribute Undefined target: W3C.REC-xmlbase-20010627[]. When xml:base is used, it serves the function described in Section 5.1.1 of URI Generic Syntax Undefined target: RFC3986[], by establishing the base URI (or IRI) for resolving relative references found within the scope of the xml:base attribute.
Any element defined by this specification MAY have an xml:lang attribute, whose content indicates the natural language for the element and its descendents. The language context is only significant for elements and attributes declared to be "Language-Sensitive" by this specification. Requirements regarding the content and interpretation of xml:lang are specified in Section 2.12 of XML 1.0 Undefined target: W3C.REC-xml-20060816[].
For convenience, this protocol can be referred to as the "Neutron".
URI/IRI - A Uniform Resource Identifier and Internationalized Resource Identifier. These terms and the distinction between them are defined in Undefined target: RFC3986[] and Undefined target: RFC3987[]. Before an IRI found in a document is used by HTTP, the IRI is first converted to a URI (see Undefined target: model[])
The phrase "the URI of a document" in this specification is shorthand for "a URI which, when dereferenced, is expected to produce that document as a representation".
Resource - A network-accessible data object or service identified by an IRI, as defined in Undefined target: RFC2616[]. See Undefined target: W3C.REC-webarch-20041215[] for further discussion on resources.
Representation - An entity included with a request or response as defined in Undefined target: RFC2616[].
Collection - A resource that contains a set of Member Entries. See Undefined target: collection_resource[].
Member - A resource whose IRI is listed in a Collection by a link element with a relation of "edit" or "edit-media". See Undefined target: memuri[].
Workspace - A group of collections. See Undefined target: appdocs[].
Service Document - A document that describes the location and capabilities of one or more Collections. See Undefined target: appdocs[].
Category Document - A document that describes the categories allowed in a Collection. See Undefined target: catdocs[].
| [RNC] | Clark, J., “RELAX NG Compact Syntax”, December 2001. |
The content and concepts within are a product of the Neutron Working Group.
This stylesheet requires either an XSLT-1.0 processor with node-set() extension function, or an XSLT-2.0 processor. Therefore, parts of the document couldn't be displayed.