One document matched: draft-snell-atompub-feature-12.xml

<?xml version="1.0"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
    <!ENTITY rfc2119 PUBLIC "" 
      "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
    <!ENTITY rfc4287 PUBLIC "" 
      "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4287.xml">
    <!ENTITY rfc5023 PUBLIC "" 
      "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5023.xml">      
    <!ENTITY rfc3986 PUBLIC ""
      "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3986.xml">
    <!ENTITY rfc3987 PUBLIC ""
      "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3987.xml">
    <!ENTITY rfc4288 PUBLIC ""
      "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4288.xml">
    <!ENTITY rfc3023 PUBLIC ""
      "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3023.xml">
    <!ENTITY infoset PUBLIC ""
      "http://xml.resource.org/public/rfc/bibxml4/reference.W3C.REC-xml-infoset-20040204.xml">
    <!ENTITY xmlnames PUBLIC ""
      "http://xml.resource.org/public/rfc/bibxml4/reference.W3C.REC-xml-names-20060816.xml">
    <!ENTITY xmlbase PUBLIC ""
      "http://xml.resource.org/public/rfc/bibxml4/reference.W3C.REC-xmlbase-20010627.xml">
    <!ENTITY xml PUBLIC ""
      "http://xml.resource.org/public/rfc/bibxml4/reference.W3C.REC-xml-20060816.xml">
]>

<rfc category="exp" ipr="full3978" docName="draft-snell-atompub-feature-12.txt">
<?rfc toc="yes" ?>
<?rfc symrefs="yes" ?>
<?rfc sortrefs="yes"?>
<?rfc strict="yes" ?>
<?rfc toc="yes"?>
<?rfc compact="yes"?>
<front>
<title abbrev="Atompub Features">Atom Publishing Protocol Feature Discovery</title>
<author initials="J.M." surname="Snell" fullname="James M Snell">
<organization></organization>
<address>
<postal>
<street></street>
<city></city> <region></region> <code></code>
<country></country>
</postal>
<phone></phone>
<email>jasnell@gmail.com</email>
<uri>http://snellspace.com</uri>
</address>
</author>
<date month="October" year="2007" />
<area>General</area>
<keyword>I-D</keyword>
<keyword>Internet-Draft</keyword>
<keyword>XML</keyword>
<keyword>Extensible Markup Language</keyword>
<keyword>Atom</keyword>
<keyword>Syndication</keyword>
<abstract><t>This document introduces extensions to the Atom Publishing Protocol
Service Document format for expressing metadata about the behaviors, functions and 
capabilities supported by an Atom Publishing Protocol collection.</t></abstract>
</front>
<middle>

<section title="Introduction">

<t>This document introduces an extension to the Atom Publishing Protocol (Atompub)
service document <xref target="RFC5023" /> format that allows for
the documentation and discovery of behaviors, functions or capabilities supported 
by an Atompub collection.  Examples of such capabilities can include the 
preservation of certain kinds of content, support for draft entries, support for the 
scheduled publication of entries, use of a particular set of Atom format extensions, 
and so on.</t>

<t>Describing features using the mechanisms defined in this specification is 
currently considered to be largely experimental.  While there are examples of 
such mechanisms being put to practical use in deployed applications, there is 
currently not enough collective implementation experience to determine whether
the mechanism defined here is sufficient to fully address the general needs of
Atom Publishing Protocol client and server implementations. Implementations and 
feedback are encouraged.</t>

</section>

<section title="Notational Conventions">

<t>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 BCP 14, <xref target="RFC2119" />.</t>

<t>This specification uses XML Namespaces 
<xref target="W3C.REC-xml-names-20060816" /> to uniquely identify XML element 
names.  It uses the following namespace prefix for the indicated namespace 
URI;</t>

<figure><artwork><![CDATA[
  "f": "http://purl.org/atompub/features/1.0"
]]></artwork></figure>

<t>This specification uses terms from the XML Infoset 
<xref target="W3C.REC-xml-infoset-20040204" />.  However, this specification 
uses a shorthand; the phrase "Information Item" is omitted when naming Element 
Information Items.  Therefore, when this specification uses the terms "element" 
and "attribute" it is referring, respectively, to the Element and Attribute 
Information Items in Infoset terms.</t>

<t>This specification uses the terms "atomUri" and "atomCommonAttributes" from 
the non-normative RELAX NG Compact schema included in <xref target="RFC4287" />.
Where used, these serve the same purpose and have the same meaning as their use
in <xref target="RFC4287" />.</t>

<t>Atom allows the use of IRIs <xref target="RFC3987"/>.  Every 
URI <xref target="RFC3986"/> is also an IRI, so a URI may be used wherever below 
an IRI is named.  There are two special considerations: (1) when an IRI that is 
not also a URI is given for dereferencing, it MUST be mapped to a URI using the 
steps in Section 3.1 of <xref target="RFC3987"/> and (2) when an IRI is serving 
as an identifier, it MUST NOT be so mapped.</t>

<t>Any element defined by this specification MAY have an xml:base attribute 
<xref target="W3C.REC-xmlbase-20010627"/>.  When xml:base is used, it 
serves the function described in section 5.1.1 of <xref target="RFC3986"/>, 
establishing the base URI (or IRI) for resolving any relative references found 
within the effective scope of the xml:base attribute.</t>

<t>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".  Requirements regarding the content and interpretation 
of xml:lang are specified in XML 1.0 <xref target="W3C.REC-xml-20060816" />, 
Section 2.12.</t>

</section>

<section title="The f:features Element">

<t>The f:features element is used in an app:collection element or as the root
element of a Features Document as a container for zero or more f:feature elements.</t>

<t>An f:features element MAY contain any number of f:feature elements but 
MUST NOT contain more than one with the same ref attribute value. The order 
in which f:feature elements appear within the f:features element is insignificant.</t>

<t>An app:collection element MUST NOT contain more than one f:features element.</t>

<figure><artwork>
  inlineFeatures =
    element f:features {
      (feature*,
       undefinedContent)
    }

  outOfLineFeatures =
    element f:features {
      attribute href { atomURI }
    }

  features = inlineFeatures | outOfLineFeatures
</artwork></figure>

<t>When used within an app:collection element, the f:features element MAY contain
an "href" attribute, whose value MUST be an IRI reference identifying a Features 
Document. If the "href" attribute is provided, the f:features element MUST be 
empty.</t> 

</section>

<section title="The f:feature element">

<t>The f:feature element is used within an f:features element to declare a 
collection's support for a feature.</t>

<figure><artwork><![CDATA[
  feature = element f:feature {
    atomCommonAttributes,
    attribute ref    { atomUri },
    attribute href   { atomUri }?,
    attribute label  { text }?,
    (anyElement)*
  }
  
  anyElement = element * - f:feature {
    (attribute * { text }
      | text
      | anyElement)*
  }
]]></artwork></figure>

<t>The ref attribute specifies a globally unique IRI identifying a feature. 
The value of the ref attribute MUST be compared on a case-sensitive, 
character-by-character basis. Relative references MUST NOT be used. The IRI
is used strictly for identification and cannot be assumed to be dereferenceable.</t>

<t>An optional href attribute MAY be used to specify a dereferenceable IRI of a 
human-readable description of the feature. Relative references MAY be used.</t>

<t>The optional label attribute MAY be used to specify a human-readable 
label for the feature.  The value of the label attribute is Language-Sensitive
as defined by Section 2 of <xref target="RFC4287" />.</t>

<t>The f:feature element MAY contain a mix of text and any number of child elements and 
attributes from any XML namespace, with the exception of the f:feature element 
itself.  Such markup is considered to be metadata applicable to the feature 
identified. Software agents MUST NOT stop processing or signal an error or change 
their behavior as a result of encountering such markup.</t>

<t>The presence of a f:feature element is an indication that the collection
supports the feature identified.  The lack of a f:feature element identifying a 
particular feature indicates that support for that feature is unspecified.  This 
does not mean that the feature is not supported, only that the server has not 
explicitly declared support.  There are no means by which a server can indicate 
that a given feature is unsupported.</t>

<section title="Example">

<figure><preamble>The following is an example of a collection using the f:feature
element to indicate its support for the app:draft element as defined
by <xref target="RFC5023" />.</preamble>
<artwork><![CDATA[
  <service 
    xmlns="http://www.w3.org/2007/app" 
    xmlns:atom="http://www.w3.org/2005/Atom"
    xmlns:f="http://purl.org/atompub/features/1.0">
    <workspace>
      <atom:title>My Workspace</atom:title>
      <collection href="...">
        <atom:title>My Atom Collection</atom:title>
        <accept>application/atom+xml;type=entry</accept>
        <f:features>
          <f:feature 
            ref="http://purl.org/atompub/features/1.0/supportsDraft" />
        </f:features>
      </collection>
    </workspace>
  </service>
]]></artwork></figure>

</section>

</section>

<section title="Feature Documents">

<t>A Feature Document contains a listing of f:feature elements that can be referenced
by multiple app:collection elements.  Separating the list of f:features out into
a separate document enables and promotes the reuse of features across multiple
collections.</t>

<t>The root of a Feature Document is the f:features element. The f:features element MUST NOT
contain an href atribute. Feature documents are identified with the "application/atomfeature+xml" 
media type (see Section 9.1).</t>

<section title="Example">

<figure><artwork><![CDATA[
  <?xml version="1.0?>
  <features xmlns="http://purl.org/atompub/features/1.0">
    <feature ref="http://purl.org/atompub/features/1.0/supportsDraft" />
    <feature ref="http://example.org/foo/supportsFoo" />    
  </features>
]]></artwork></figure>

<t>This Feature Document indicates support for the app:draft publishing 
control and a hypothetical extension.</t>

<figure><preamble>The following is an example of a collection using the
f:features element to reference a Feature Document.</preamble>
<artwork><![CDATA[
  <service 
    xmlns="http://www.w3.org/2007/app" 
    xmlns:atom="http://www.w3.org/2005/Atom"
    xmlns:f="http://purl.org/atompub/features/1.0">
    <workspace>
      <atom:title>My Workspace</atom:title>
      <collection href="...">
        <atom:title>My Atom Collection</atom:title>
        <accept>application/atom+xml;type=entry</accept>
        <f:features href="http://example.org/features.xml" />
      </collection>
    </workspace>
  </service>
]]></artwork></figure>

</section>

</section>

<section anchor="supportsdrafts" title="The "supportsDraft" Feature">

<t>The "supportsDraft" feature is used to indicate that a collection supports the
use of the app:draft control element as defined by Section 13.1.1 
of <xref target="RFC5023" />. The IRI of the "supportsDraft" feature is:</t>

<figure><artwork>  http://purl.org/atompub/features/1.0/supportsDraft</artwork></figure>

</section>

<section anchor="ignoresdrafts" title="The "ignoresDraft" Feature">

<t>The "ignoresDraft" feature is used to indicate that a collection will ignore the
use of the app:draft control element as defined by Section 13.1.1 
of <xref target="RFC5023" />. The IRI of the "ignoresDraft" feature is:</t>

<figure><artwork>  http://purl.org/atompub/features/1.0/ignoresDraft</artwork></figure>

<t>A server MUST NOT declare support for both the "supportsDraft" and "ignoresDraft"
features within the a single app:collection element.</t>

</section>

<section anchor="security" title="Security Considerations">

<t>Specific features supported by a collection may introduce 
security considerations and concerns beyond those discussed by the Atom 
Publishing Protocol and Atom Syndication Format specifications.  Implementors
must refer to the specifications and description of each feature 
to determine the security considerations relevant to each.</t>

<t>Implementations of this specification handle URIs and IRIs.  See
Section 7 of <xref target="RFC3986"/> and Section 8 of <xref target="RFC3987"/> for security
considerations related to their handling and use.</t>

</section>


<section title="IANA Considerations">

<t>This specification uses a new media type that conforms to the registry 
mechanism described in <xref target="RFC4288"/>.</t>

<section title="Content-type registration for 'application/atomfeature+xml'">

<t>A Feature Document, when serialized as XML 1.0, can be identified with the 
following media type:</t>

<t>
  <list style="hanging">
    <t hangText="MIME media type name:"> application</t>
    <t hangText="MIME subtype name:"> atomfeature+xml</t>
    <t hangText="Mandatory parameters:"> None.</t>
    <t hangText="Optional parameters:">
      <list style="hanging">
        <t hangText='"charset":'> This parameter has identical
        semantics to the charset parameter of the "application/xml" media type 
        as specified in <xref target="RFC3023" pageno="false" format="default"></xref>.</t>
      </list>
    </t>
    <t hangText="Encoding considerations:"> Identical to those of
    "application/xml" as described in <xref target="RFC3023" pageno="false" format="default"></xref>, 
    section 3.2.</t>
    <t hangText="Security considerations:"> As defined in this specification. <cref>update upon publication</cref></t>
    <t>In addition, as this media type uses the "+xml" convention, it shares the 
    same security considerations as described in
    <xref target="RFC3023" pageno="false" format="default"></xref>, section 10.</t>
    <t hangText="Interoperability considerations:"> There are no known interoperability issues.</t>
    <t hangText="Published specification:"> This specification. <cref>update upon publication</cref></t>
    <t hangText="Applications that use this media type:"> No known applications currently use this media type.</t>
  </list>
</t>

<t>Additional information:</t>

<t>
  <list style="hanging">
    <t hangText="Magic number(s):"> As specified for
    "application/xml" in <xref target="RFC3023" pageno="false" format="default"></xref>, section 3.2.</t>
    <t hangText="File extension:"> .atomfeature</t>
    <t hangText="Fragment identifiers:"> As specified for "application/xml" in 
    <xref target="RFC3023" pageno="false" format="default"></xref>, section 5.</t>
    <t hangText="Base URI:"> As specified in <xref target="RFC3023" pageno="false" format="default"></xref>, section 6.</t>
    <t hangText="Macintosh File Type code:"> TEXT</t>
    <t hangText="Person and email address to contact for further information:"> James Snell <jasnell@gmail.com></t>
    <t hangText="Intended usage:">COMMON</t> 
    <t hangText="Author/Change controller:">IETF (iesg@ietf.org) Internet Engineering Task Force</t>
  </list>
</t>
</section>
</section>

</middle>
<back>
<references title="Normative References">
  &rfc2119;
  &rfc4287;
  &rfc5023;
  &rfc3986;
  &rfc3987;
  &rfc4288;
  &rfc3023;
  &infoset;
  &xmlnames;
  &xmlbase;
  &xml;
</references>
<section title="Acknowledgements">
<t>The author acknowledges the feedback from the other members of the 
IETF Atom Publishing working group during the development of this 
specification.</t>
</section>
</back>
</rfc>