The Neutron 1.0 ProtocolWyonaHardstrasse 219ZurichZurich8005CH+41 44 272 91 61michael.wechner@wyona.comhttp://www.wyona.comWyonaHardstrasse 219ZurichZurich8005CH+41 44 272 91 61awuest@student.ethz.chhttp://www.wyona.comUnicom (University of Zurich)+41 44 634 51 31thomas.comiotto@unicom.unizh.chThe 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:concurrent access to resourcescreating resources based on templatesproviding styling information for resourcesmetadata handlingaccessing revisionscustom authentication schemesand moreNeutron 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
.
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:
The "rel" attribute of the "<link>" element MUST be set to "neutron-introspection".The "type" attribute of the "<link>" element MUST be set to "application/neutron+xml".The "href" attribute MUST contain the URI pointing to the introspection object. If this URI is relative, a client MUST resolve the URI relative to the URI of the document in which the "<link>" element is contained.
<html>
<head>
<link rel="neutron-introspection" type="application/neutron+xml" href="introspection-hello-world.xml"/>
<title>Hello World</title>
...
</head>
...
</html>
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-AuthNeutron: 1.0, 2.0-dev / enURLs 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>
<?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>
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>
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>
TBDTBDIf 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.xhtmlClient 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?Server breaks lock, check-out for new user and returns content.Server breaks lock and returns lock broken successfully, please retry opening again ...Server responds breaking the lock failed for whatever reason.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
.Neutron Protocol Document formats are specified in terms of the XML Information Set
, serialized as XML 1.0
.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
. However, the text of this specification provides the definition of conformance. Complete schemas appear in
. XML elements defined by this specification MAY have an xml:base attribute
. When xml:base is used, it serves the function described in Section 5.1.1 of URI Generic Syntax
, 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
.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
and
. Before an IRI found in a document is used by HTTP, the IRI is first converted to a URI (see
)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
. See
for further discussion on resources.Representation - An entity included with a request or response as defined in
.Collection - A resource that contains a set of Member Entries. See
.Member - A resource whose IRI is listed in a Collection by a link element with a relation of "edit" or "edit-media". See
.Workspace - A group of collections. See
.Service Document - A document that describes the location and capabilities of one or more Collections. See
.Category Document - A document that describes the categories allowed in a Collection. See
.RELAX NG Compact SyntaxThe content and concepts within are a product of the Neutron Working Group.