XML Fragment Interchange

1 Overview

The XML standard supports logical documents composed of possibly several entities. It may be desirable to view or edit one or more of the entities or parts of entities while having no interest, need, or ability to view or edit the entire document. The problem, then, is how to provide to a recipient of such a fragment the appropriate information about the context that fragment had in the larger document that is not available to the recipient.

In the case of many XML documents, it is suboptimal to have to receive and parse the entire document when only a fragment of it is desired. If the user asked to look at chapter 20, one shouldn't need to parse 19 whole chapters before getting to the part of interest. The goal of this activity is to define a way to enable processing of small parts of an XML document without having to process everything up to the part in question. This can be done regardless of whether the parts are entities or not, and the parts can either be viewed immediately or accumulated for later use, assembly, or other processing.

Conceptually, the holder of the complete source document considers a fragment of that document and, using the notation to be defined by this activity, constructs a fragment context specification. The object representing the fragment removed from its source document is called the fragment body. The fragment context specification and the fragment body are transmitted to the recipient. The storage object in which the fragment body is transmitted is call the fragment entity. (In some packaging schemes, the fragment context specification may also be embedded in the fragment entity.) The recipient processes the fragment context specification to determine the proper parser state for the context at the beginning of the fragment and uses that information to enable the XML parser to parse the fragment body. (The terms “sender,” “recipient,” “transmit,” are used throughout this document to describe the process of fragment interchange. It should be noted, however, that there are many feasible and useful scenarios for fragment interchange, and in some cases, the “sender” and “recipient” may be on the same machine, node, system, or network, and may even be the same tool in different guises.)

The challenge is that an isolated element from an XML document may not contain quite enough information to be parsed correctly. The goal of this activity is to enable senders to provide the remaining information required so that systems can interchange any XML elements they choose, from books or chapters all the way down to paragraphs, tables, footnotes, book titles, and so on, without having to manage each as a separate entity or having to risk incorrect parsing due to loss of context.

To accomplish these ends, this Recommendation defines:

• exact constraints on what portions of an XML document may constitute fragments to be supported by this Recommendation;

• the set of information (fragment context information) that allows for successful parsing as well as for viewing or editing of a fragment in a useful and important set of cases;

• the notation (i.e., language) in which this information will be described (the fragment context specification);

• some mechanisms for associating this information with a fragment.

2 Scope

This Recommendation enables interchanging portions of XML documents while retaining the ability to parse them correctly (that is, as they would be parsed in their originating document context), and, as far as practical, to be formatted, edited, and otherwise processed in useful ways.

The goal of this activity is to define a way to send fragments of an XML document—regardless of whether the fragments are predetermined entities or not—without having to send all of the containing document up to the part in question. The delivered parts can either be viewed or edited immediately or accumulated for later use, assembly, or other processing; what the receiving application does with the information—and issues involved with the possible “return” of such a fragment to the original sender—is beyond the scope of this activity. While implementations of this Recommendation may serve as part of a larger system that allows for “fragment reuse,” the many important issues about reuse of XML text and “concurrent multiple author environments” are beyond the scope of this Recommendation.

The point of the fragment context information is to provide information that is not available in the fragment body itself but that would be available from the complete XML document. Specifically, any information not available from the XML document (which may include an external subset) as a whole (plus knowledge of the location of the fragment body within the document) is out of scope for inclusion in the fragment context information. Such information may well be useful and important metadata in a variety of applications, but there are (or need to be) other mechanisms for handling this information.

This Recommendation considers fragments of XML as defined by [XML 1.0] and [XML Namespaces]. It is explicitly noted that this version of this Recommendation does not take into account work such as that taking place in the XML Schema Working Group; insofar as such work by other currently active working groups places new requirements on a fragment interchange solution, those requirements would be input to a new version of the fragment interchange specification that may become a chartered activity at a later date.

It is also explicitly noted that this Recommendation does not consider interchange of information that is not well-formed XML; in particular, issues specific to the interchange of fragments of SGML (including HTML)—other than such SGML that is, in fact, also well-formed XML—are not within scope of this Recommendation.

3 Terminology

This list is sorted “logically” as opposed to alphabetically. In an entry, phrases in parentheses are “optional” modifiers; whether they are used explicitly or not, we are still talking about the same thing for the purposed of this Recommendation.

(well-formed) XML document

defined in [XML 1.0], Well-formed XML documents

(well-formed) (external) (parsed) entity

defined in [XML 1.0], production [78] extParsedEnt

(well-)balanced

A region (consecutive sequence of characters) of an XML document is said to be (well-)balanced if it matches production [43] content of [XML 1.0]. Informally this means that, if the region includes any part of the markup of any construct, it contains all of the markup of that construct (e.g., in the case of elements, all of both the start and end tag).

fragment

A general term to refer to part of an XML document, plus possibly some extra information, that may be useful to use and interchange in the absence of the rest of the XML document. See the rest of the fragment-related terms when a more precise definition is required.

fragment interchange

The process of receiving and/or parsing of a fragment by a fragment-aware application.

fragment body

A well-balanced region of an XML document being considered as (logically and/or physically) separate from the rest of the document for the purposes of defining it as a fragment. Also, that part of a fragment entity that consists solely of the well-balanced region from the complete XML document. When it is important to indicate that a reference is specifically to the version of the fragment body still physically part of the originating (parent) document, this document will use the term “fragment body in situ.”

context information

The abstract set of information—divorced from any particular language/syntax/notation—that constitutes the “parser state” at the point when a parser processing the complete XML document encounters (but has not yet processed) the first character of (what would be) the fragment body.

(fragment) context (information)

(sometimes abbreviated fci) The subset of the context information that we decide will be expressible in any fragment context specification language. Also the abstract set of information represented by a particular fragment context specification.

fragment context specification

(sometimes abbreviated fcs) A valid string in the language (notation) that this Recommendation defines that describes a set of fragment context information. Also the particular string in a fragment entity or fragment package that describes the fragment's context information.

package [verb]

To associate in some specified way a fragment body with a fragment context specification. This may include some way of combining both into a single XML-encoded object; combining both in some multipart MIME or archiving encoding; or linking the two via some sort of referencing, co-referencing, or third-party referencing scheme.

fragment entity

The storage object in which the fragment body is stored and/or transmitted during the process of fragment interchange.

(fragment) package [noun]

The object actually transmitted during the process of fragment interchange. Though one might expect this is the same thing as a fragment entity, the terms may or may not be synonyms in all cases; one could define a packaging mechanism whereby the fragment context specification is transmitted without the fragment body (which presumably gets retrieved later) in which case the fragment package is the fragment context specification, and the fragment entity gets retrieved later.

fragment context specification document

As defined in this Recommendation, a valid fragment context specification (fcs) is a well-formed XML document. Therefore, when considered as a document, an fcs is sometimes referred to as a fragment context specification document (or fcs document). A fragment context specification document may also be a fragment package (i.e., it may be the actual object transmitted to effect fragment interchange).

send/receive (and sender/recipient)

In the context of this Recommendation, words such as send/receive (and sender/recipient) are used to described the general process of fragment interchange. There are many feasible and useful scenarios for fragment interchange, and in some cases, the “sender” and “recipient” may be on the same machine, node, system, or network, and may even be the same tool in different guises. The only constant assumption is that the sender has access to and knowledge of the entire (parental) document from which the fragment comes, and the recipient is in possession only of the fragment package (though nothing in this Recommendation precludes the possibility of the recipient using the information in the fragment package, if available, to attempt to fetch more information from the sender).

4 Fragment context information set

In this section, numbers in brackets refer to productions in [XML 1.0]. The following information shall constitute the complete fragment context information (fci) set:

1. A reference to the external subset (extSubset [30]), by specifying an ExternalID [75] for it.

2. Internal subset information using some or all of the following:

   1. A reference to an “externalized copy” of the internal subset (presumably generated by placing the internal declarations into a storage object such as extSubset [30]), presumably by specifying an ExternalID [75] for it.

   2. Some or all of markupdecl [29] and/or PEReference [69] allowed in an XML document's internal subset; note that PEReference implies expansion of what could be more external entities; also note that markupdecl includes comments, processing instructions, and declarations for elements, attribute lists, entities, and notations.

3. Ancestor information for the fragment body.

4. Sibling information for the fragment body.

5. Sibling information for any of the ancestors.

6. Element content (aka descendant) information for any of the ancestors or siblings.

7. Attribute information (attribute name and value) for:

   1. any of the ancestors;

   2. any of the siblings of the fragment body;

   3. any of the siblings of any of the ancestors;

   4. any of the descendants of any of the ancestors or siblings.

8. A reference to the original/parental document by specifying an ExternalID [75] for it.

9. A reference to the fragment body within the original/parental document by specifying an ExternalID [75].

From the above list, the following items affect proper (validating) parsing of the fragment:

• External subset

• Internal subset

• (Preceding) Siblings of the fragment body

The following items, while they cannot affect proper parsing, are usually considered part of the basic, structural XML parse tree:

• Ancestors

• (Preceding) Siblings of ancestors

• Following siblings of the fragment body and its ancestors

• Ancestor and sibling descendants

• Attributes

The following items, while not usually considered part of the basic, structural XML parse tree, are clearly definable pieces of information known or computable by any XML processor that is processing the parent document:

• XML declaration information of the parent document. Note that we have defined a fragment package to be an XML document. That is, the fragment package would contain its own XMLDecl-like information as necessary, so the fci itself need not include that information.

• A reference to the parent document.

• A reference to the fragment body in situ.

5 Fragment context specification notation

  xmlns:f="http://www.w3.org/2001/02/xml-fragment"
  xmlns="http://www.oasis-open.org/docbook/DocbookSchema"

  <f:fcs xmlns:f="http://www.w3.org/2001/02/xml-fragment"
         extref="http://www.oasis-open.org/docbook/docbook/3.0/docbook.dtd"
         parentref="http://www.acme.com/~me/mydocs/mybook.xml"
         xmlns="http://www.oasis-open.org/docbook/DocbookSchema">
    <book>
      <part>
        <chapter>
          <sect1/>
          <sect1>
            <orderedlist numeration="arabic">
              <listitem/>
              <f:fragbody/>
            </orderedlist>
          </sect1>
        </chapter>
      </part>
    </book>
  </f:fcs>

<?xml version="1.0"?>
<!DOCTYPE book SYSTEM "http://www.oasis-open.org/docbook/docbook/3.0/docbook.dtd">
<book xmlns="http://www.oasis-open.org/docbook/DocbookSchema">
  <part>
    <chapter><title>The title for chapter one</title>
      <sect1><title>The title for section one in chapter one</title>
        <p>The first paragraph....</p>
        <p>....</p>
      </sect1>
      <sect1><title>The title for section two in chapter one</title>
        <p>An introductory paragraph preceding an ordered list.</p>
        <orderedlist numeration="arabic">
          <listitem><para>This is the first listitem in this ordered 
          list.</para></listitem>
          <listitem><para>This is the second listitem within the
          second sect1 of the first chapter within the first part
          of a Docbook <quote>book</quote> document.</para></listitem>
          <listitem><para>And this is the next listitem.</para></listitem>
          <listitem><para>This is the fourth and last listitem.</para></listitem>
        </orderedlist>

        <p>Another paragraph....</p>
      </sect1>
    </chapter>
    <chapter><title>More content</title>
      <p>More chapters, sections, paragraphs, and such....</p>
    </chapter>
  </part>
</book>

          <listitem><para>This is the second listitem within the
          second sect1 of the first chapter within the first part
          of a Docbook <quote>book</quote> document.</para></listitem>
          <listitem><para>And this is the next listitem.</para></listitem>

  <f:fcs xmlns:f="http://www.w3.org/2001/02/xml-fragment"
         extref="http://www.oasis-open.org/docbook/docbook/3.0/docbook.dtd"
         parentref="http://www.acme.com/~me/mydocs/mybook.xml"
         xmlns="http://www.oasis-open.org/docbook/DocbookSchema">
    <book>
      <part>
        <chapter>
          <sect1/>
          <sect1>
            <orderedlist numeration="arabic">
              <listitem/>
              <f:fragbody fragbodyref="http://www.acme.com/~me/mydocs/myfrag.xml"/>
            </orderedlist>
          </sect1>
        </chapter>
      </part>
    </book>
  </f:fcs>

6 Conformance

A fragment conforms to this XML Fragment Interchange Recommendation if it adheres to all syntactic requirements defined in this Recommendation. A fragment is syntactically correct if all of the requirements specified in Section 5.2 are met.

Application software acting as recipient conforms to the XML Fragment Interchange Recommendation if it interprets all conforming XML fragments (as defined above) according to all required semantics prescribed by this Recommendation, and, for any optional semantics it chooses to support, supports them in the way prescribed. Specifically, conforming application software must be able to parse all conforming valid fragment context specification information whether it chooses to support its semantics or not. Application software acting as sender conforms to the XML Fragment Interchange Recommendation if it creates conforming XML fragments (as defined above) and, if including fragment context information, includes conforming fragment context information according to the requirements in section 4.

If fragment context information is included with a transmitted fragment, then it should conform according to the requirements in section 4.