Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
branch: develop
Fetching contributors…

Cannot retrieve contributors at this time

6584 lines (6578 sloc) 353.871 kb
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html
SYSTEM "about:legacy-compat">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>XML Design Patterns</title>
<link rel="stylesheet" type="text/css" href="index.css"/>
<meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/>
</head>
<body>
<div class="book" title="XML Design Patterns" id="d55e2">
<div class="titlepage">
<div>
<div>
<h1 class="title">XML Design Patterns</h1>
</div>
<div>
<div class="author">
<h3 class="author">
<span class="firstname">Toivo</span>
<span class="surname">Lainevool</span>
</h3>
<code class="email">&lt;<a class="email" href="mailto:info@xmlpatterns.com">info@xmlpatterns.com</a>&gt;</code>
</div>
</div>
</div>
<hr/>
</div>
<nav>
<dl class="toc">
<dt>Table of Contents</dt>
<dd>
<ol class="book">
<li class="part">
<a href="#d55e33">Home</a>
<ol>
<li class="article">
<a href="#d55e36">XML Design Patterns</a>
</li>
</ol>
</li>
<li class="part">
<a href="#d55e59">Introduction</a>
<ol>
<li class="article">
<a href="#d55e62">Introductory Material</a>
</li>
<li class="article">
<a href="#d55e67">Pattern</a>
</li>
<li class="article">
<a href="#d55e83">History</a>
</li>
<li class="article">
<a href="#d55e96">Pattern Forms</a>
<ol>
<li class="glossary">
<a href="#d55e114">Glossary</a>
</li>
</ol>
</li>
<li class="article">
<a href="#d55e175">Good Design</a>
</li>
<li class="article">
<a href="#d55e222">Journey</a>
</li>
</ol>
</li>
<li class="part">
<a href="#d55e243">Patterns</a>
<ol>
<li class="chapter">
<a href="#d55e247">Document Roots</a>
<ol>
<li class="section">
<a href="#d55e255">Multi Root Document Types</a>
</li>
<li class="section">
<a href="#d55e314">Multiple Document Types</a>
</li>
<li class="section">
<a href="#d55e376">Universal Root</a>
</li>
</ol>
</li>
<li class="chapter">
<a href="#d55e437">Metadata</a>
<ol>
<li class="section">
<a href="#d55e445">Head-Body</a>
</li>
<li class="section">
<a href="#d55e525">Metadata First</a>
</li>
<li class="section">
<a href="#d55e584">Metadata in Separate Document</a>
</li>
<li class="section">
<a href="#d55e659">Separate Metadata and Data</a>
</li>
</ol>
</li>
<li class="chapter">
<a href="#d55e724">Abstraction</a>
<ol>
<li class="section">
<a href="#d55e732">Choice Reducing Container</a>
</li>
<li class="section">
<a href="#d55e801">Collection Element</a>
</li>
<li class="section">
<a href="#d55e871">Container Element</a>
</li>
<li class="section">
<a href="#d55e942">Domain Element</a>
</li>
<li class="section">
<a href="#d55e998">Optional Container Element</a>
</li>
</ol>
</li>
<li class="chapter">
<a href="#d55e1067">Organization</a>
<ol>
<li class="section">
<a href="#d55e1075">Declare Before First Use</a>
</li>
<li class="section">
<a href="#d55e1129">Envelope</a>
</li>
<li class="section">
<a href="#d55e1215">Flyweight</a>
</li>
<li class="section">
<a href="#d55e1316">Marketplace</a>
</li>
<li class="section">
<a href="#d55e1377">Referenced Note</a>
</li>
</ol>
</li>
<li class="chapter">
<a href="#d55e1454">Flexibility</a>
<ol>
<li class="section">
<a href="#d55e1462">Catch-All Element</a>
</li>
<li class="section">
<a href="#d55e1534">Extensible Content Model</a>
</li>
<li class="section">
<a href="#d55e1642">Generic Element</a>
</li>
<li class="section">
<a href="#d55e1700">Role Attribute</a>
</li>
</ol>
</li>
<li class="chapter">
<a href="#d55e1765">Consistency</a>
<ol>
<li class="section">
<a href="#d55e1773">Common Attributes</a>
</li>
<li class="section">
<a href="#d55e1859">Consistent Element Set</a>
</li>
<li class="section">
<a href="#d55e1921">Parallel Design</a>
</li>
</ol>
</li>
<li class="chapter">
<a href="#d55e1983">Miscellaneous</a>
<ol>
<li class="section">
<a href="#d55e1991">Content Type Label</a>
</li>
<li class="section">
<a href="#d55e2057">Reuse Document Types</a>
</li>
<li class="section">
<a href="#d55e2140">Short Understandable Names</a>
</li>
<li class="section">
<a href="#d55e2194">Use XML</a>
</li>
</ol>
</li>
</ol>
</li>
<li class="part">
<a href="#d55e2323">Books</a>
<ol>
<li class="chapter">
<a href="#d55e2326">XML Structure</a>
</li>
<li class="chapter">
<a href="#d55e2331">Patterns</a>
</li>
<li class="chapter">
<a href="#d55e2336">Software Design Patterns</a>
</li>
</ol>
</li>
<li class="part">
<a href="#d55e2344">Links</a>
<ol>
<li class="article">
<a href="#d55e2347">Links</a>
<ol>
<li class="section">
<a href="#d55e2352">XML Design Patterns</a>
</li>
<li class="section">
<a href="#d55e2406">Other Patterns</a>
</li>
<li class="section">
<a href="#d55e2430">XML Design</a>
</li>
<li class="section">
<a href="#d55e2448">Schema Repositories</a>
</li>
</ol>
</li>
<li class="article">
<a href="#d55e2472">Other XML Links</a>
<ol>
<li class="section">
<a href="#d55e2477">General XML</a>
</li>
<li class="section">
<a href="#d55e2507">XSLT</a>
</li>
</ol>
</li>
</ol>
</li>
<li class="article">
<a href="#d55e2532">About</a>
<ol>
<li class="section">
<a href="#d55e2537">Contacts</a>
</li>
<li class="section">
<a href="#d55e2552">What They Are Saying About Us</a>
</li>
<li class="section">
<a href="#d55e2561">Privacy Statement</a>
</li>
<li class="section">
<a href="#d55e2568">Log Files</a>
</li>
<li class="section">
<a href="#d55e2573">Cookies and Web Beacons</a>
</li>
<li class="section">
<a href="#d55e2580">DoubleClick DART cookies</a>
</li>
</ol>
</li>
</ol>
</dd>
</dl>
</nav>
<nav class="list-of-examples">
<p>
<strong>List of Examples</strong>
</p>
<ol>
<li>1.1 <a href="#d55e346">Employees.dtd:</a>
</li>
<li>1.2 <a href="#d55e351">HoursWorked.dtd:</a>
</li>
<li>2.1 <a href="#d55e620">File: <code class="filename">author-info.xml</code>
</a>
</li>
<li>2.2 <a href="#d55e627">File: <code class="filename">document.xml</code>
</a>
</li>
<li>3.1 <a href="#d55e762">Example</a>
</li>
<li>3.2 <a href="#d55e769">Example</a>
</li>
<li>3.3 <a href="#d55e831">Simple Collection Element</a>
</li>
<li>3.4 <a href="#d55e836">Container Element With Metadata</a>
</li>
<li>3.5 <a href="#d55e841">Multiple Categories of Same Collection</a>
</li>
<li>4.1 <a href="#d55e1267">XML Entities</a>
</li>
<li>4.2 <a href="#d55e1274">XLink</a>
</li>
<li>4.3 <a href="#d55e1281">ID and IDREF</a>
</li>
<li>5.1 <a href="#d55e1494">Example</a>
</li>
<li>5.2 <a href="#d55e1501">Example</a>
</li>
<li>5.3 <a href="#d55e1564">Using DTDs</a>
</li>
<li>5.4 <a href="#d55e1571">purchase_order.dtd</a>
</li>
<li>5.5 <a href="#d55e1580">mydoc.xml</a>
</li>
<li>5.6 <a href="#d55e1585">Using XML Schemas</a>
</li>
<li>5.7 <a href="#d55e1590">PurchaseOrder.xsd</a>
</li>
<li>5.8 <a href="#d55e1597">US-Address.xsd</a>
</li>
<li>5.9 <a href="#d55e1604">mydoc.xml</a>
</li>
<li>6.1 <a href="#d55e1803">Common Attributes in DTDs</a>
</li>
<li>6.2 <a href="#d55e1813">Common Attributes in XML Schemas</a>
</li>
<li>6.3 <a href="#d55e1889">Example</a>
</li>
<li>6.4 <a href="#d55e1896">Example</a>
</li>
</ol>
</nav>
<div class="part" title="Part I. Home" id="d55e33">
<div class="titlepage">
<div>
<div>
<h1 class="title">Part I. Home</h1>
</div>
</div>
</div>
<nav>
<dl class="toc">
<dt>Table of Contents</dt>
<dd>
<ol class="part">
<li class="article">
<a href="#d55e36">XML Design Patterns</a>
</li>
</ol>
</dd>
</dl>
</nav>
<div class="article" title="XML Design Patterns" id="d55e36">
<header class="titlepage">
<div>
<h2 class="title">XML Design Patterns</h2>
</div>
</header>
<p>Welcome to XMLPatterns.com, the site about designing good XML structure with patterns.</p>
<p>There are 28 <a class="link" href="patterns/patterns.part.xml">XML Design Patterns</a>. If you are new to software design patterns, a good place to start is the <a class="link" href="intro/introduction.part.xml">Introductory Material</a>.</p>
<p>In the years since XMLPatterns.com was launched, XML has moved from being a relatively obscure technology to being a part of the everyday technologies that software developers use. Since XML design patterns are an excellent way to pass knowledge on from the experts to XML newcomers, they have become more important then ever. Designing good XML structure using DTDs, W3C XML Schema or RelaxNG does not always come easily, and hopefully the patterns on this site will be able to help out.</p>
<p>Please feel free to <a class="link" href="mailto:info@xmlpatterns.com">email</a> feedback about this site.</p>
<p>Thanks for visiting!</p>
</div>
</div>
<div class="part" title="Part II. Introduction" id="d55e59">
<div class="titlepage">
<div>
<div>
<h1 class="title">Part II. Introduction</h1>
</div>
</div>
</div>
<nav>
<dl class="toc">
<dt>Table of Contents</dt>
<dd>
<ol class="part">
<li class="article">
<a href="#d55e62">Introductory Material</a>
</li>
<li class="article">
<a href="#d55e67">Pattern</a>
</li>
<li class="article">
<a href="#d55e83">History</a>
</li>
<li class="article">
<a href="#d55e96">Pattern Forms</a>
<ol>
<li class="glossary">
<a href="#d55e114">Glossary</a>
</li>
</ol>
</li>
<li class="article">
<a href="#d55e175">Good Design</a>
</li>
<li class="article">
<a href="#d55e222">Journey</a>
</li>
</ol>
</dd>
</dl>
</nav>
<div class="article" title="Introductory Material" id="d55e62">
<header class="titlepage">
<div>
<h2 class="title">Introductory Material</h2>
</div>
</header>
<p>Follow the links below for some background material that might be useful as an introduction into the world of XML Design Patterns.</p>
</div>
<div class="article" title="Pattern" id="d55e67">
<header class="titlepage">
<div>
<h2 class="title">Pattern</h2>
</div>
</header>
<p>The originator of the pattern, Christopher Alexander, defines a pattern as “a three part rule, which expresses a relation between a certain context, a problem, and a solution” [<a class="link" href="books/books.part.xml#0195024028">Alex79</a>].</p>
<p>A pattern can be thought of as a tried and true way to deal with a problem that appears over and over again. People who are experienced in a particular field of knowledge will have internalized certain solutions to these problems. They recognize a problem to be solved and know which solution to apply in the particular situation. The idea of a pattern is to be able to describe this internalized expert knowledge and to state the problem, context and solution, so that less experienced people can benefit from this knowledge.</p>
<p>Another benefit of having formal, written patterns is that these previously internalized concepts get named. It is much easier to discuss and think about something once it has been named. Discussing concepts that are unnamed is difficult.</p>
<p>A pattern language brings together a number of these patterns in one particular field. It is an attempt to reproduce all of the knowledge needed to create quality items in that field. A pattern language for buildings gives one the power to create building which people will want to live in, a pattern language for software design gives the power to create software which is usable and maintainable. Just as spoken language give people the ability to create an infinite variety of sentences, pattern languages give people the power to create an infinite variety of document types. We just need to create a common vocabulary so we can make useful sentences.</p>
<p>This site is an attempt to start to produce an XML Structural Pattern language. This pattern language gives one the power to create document types for XML, which describe documents that are useful, maintainable, easy to author, and easy to process. This pattern language will be most useful if it is shared across the whole XML community. Because of this, your feedback into this process is very important.</p>
</div>
<div class="article" title="History" id="d55e83">
<header class="titlepage">
<div>
<h2 class="title">History</h2>
</div>
</header>
<p>The concept of patterns was originated by Christopher Alexander. Alexander was an architect. He used patterns to design building and towns. His patterns deal with subjects such as entry ways, gardens and roadways. In the late 1980s people started applying his concept to object oriented software design. The first to do so were Ward Cunningham and Kent Beck, who in 1987 wrote a paper entitled "<a class="link" href="http://c2.com/doc/oopsla87.html">Using Pattern Languages for Object-Oriented Programs</a>", which described five patterns that discussed problems in designing Smalltalk windows.</p>
<p>The object oriented community quickly recognized the power of patterns and started writing patterns that appeared in articles, workshops and books. The breakthrough work was the "<a class="link" href="books/books.part.xml#0201633612">Design Patterns</a>" book, which brought wide scale acceptance of patterns to the object-oriented world. Work has also been done in the areas of analysis patterns, process patterns, and organizational patterns. This site is an attempt to apply the concept of patterns to XML Structural Design.</p>
</div>
<div class="article" title="Pattern Forms" id="d55e96">
<header class="titlepage">
<div>
<h2 class="title">Pattern Forms</h2>
</div>
</header>
<nav>
<dl class="toc">
<dt>Table of Contents</dt>
<dd>
<ol class="article">
<li class="glossary">
<a href="#d55e114">Glossary</a>
</li>
</ol>
</dd>
</dl>
</nav>
<p>There are many different ways to write patterns. Different authors have different way of organizing the ideas presented. Alexander's original patterns were presented in a fairly informal, narrative style. The patterns presented in "<a class="link" href="books/books.part.xml#0201633612">Design Patterns</a>" book were much more fine grained, decomposing each pattern into many sections. The structure used depends on several factors. Each author has his or own preferences. Different subject matters may influence the structure. For example more technical subject areas can call for patterns with more structure. Different audiences may call for different structures as well, novice readers may prefer a more prosy style, while more experienced readers may prefer a more structured approach. The form chosen for this site is a middle of the road one, not as prosy as Alexander's patterns in <a class="link" href="books/books.part.xml#0195019199">A Pattern Language</a>, yet not as structured as "<a class="link" href="books/books.part.xml#0201633612">Design Patterns</a>" book either.</p>
<p>What matters is that there is a consistent structure so patterns are easier to understand and compare.</p>
<p>Most people would agree that there must be at least five elements in every pattern: a name; a problem description; the context of the problem; the solution; and the rational for the solution. This web site uses the following sections for each pattern:</p>
<div class="glossary" title="Glossary" id="d55e114">
<div class="titlepage">
<div>
<div>
<h2 class="title">Glossary</h2>
</div>
</div>
</div>
<dl>
<dt>
<a id="d55e121"/>Abstract</dt>
<dd>
<p>A brief description of the pattern. No more than a few sentences.</p>
</dd>
<dt>
<a id="d55e133"/>Context</dt>
<dd>
<p>The context that the problem appears in. Some problems only arise in certain contexts. Different contexts could require different solutions, leading to different patterns.</p>
</dd>
<dt>
<a id="d55e157"/>Discussion</dt>
<dd>
<p>Includes a rationale for the pattern. Explains why this solution works, and possibly why the solution might not work in certain contexts.</p>
</dd>
<dt>
<a id="d55e151"/>Examples</dt>
<dd>
<p>Sample(s) of how to apply the pattern. Usually a simple, made-up demonstration.</p>
</dd>
<dt>
<a id="d55e139"/>Forces</dt>
<dd>
<p>A description of the elements that influence the problem. These are issues that the effect the solution, and that the solution will try to fix.</p>
</dd>
<dt>
<a id="d55e169"/>Known Uses</dt>
<dd>
<p>Describes existing documents where instances of the pattern exist.</p>
</dd>
<dt>
<a id="d55e115"/>Name</dt>
<dd>
<p>The name of the pattern.</p>
</dd>
<dt>
<a id="d55e127"/>Problem</dt>
<dd>
<p>A description of the problem to be solved.</p>
</dd>
<dt>
<a id="d55e163"/>Related Patterns</dt>
<dd>
<p>A list of patterns which may be similar to, specializations of, or generalizations of this pattern. Will discuss how similar patterns differ.</p>
</dd>
<dt>
<a id="d55e145"/>Solution</dt>
<dd>
<p>The way to fix the problem.</p>
</dd>
</dl>
</div>
</div>
<div class="article" title="Good Design" id="d55e175">
<header class="titlepage">
<div>
<h2 class="title">Good Design</h2>
</div>
</header>
<p>The purpose of XML Structural Patterns are to help create document types that are designed well. The goal of a design can be thought of a balancing of forces. There are many competing forces that the designer of a document type must deal with simultaneously. In non-trivial problems, it is impossible for all of the forces to be eliminated completely, so compromises must be made.</p>
<p>These are some of the forces that the XML document designer must deal with:</p>
<div class="variablelist">
<dl>
<dt>
<span class="term">Document Size</span>
</dt>
<dd>
<p>It is usually better to have short documents. Longer documents take up more disk space, take longer to process by machines and humans, and take longer to transmit across the network.</p>
</dd>
<dt>
<span class="term">Ease of Authoring</span>
</dt>
<dd>
<p>Documents which are authored by people must be understandable to them. Extremely complex documents will cause authors to make mistakes, waste time, and get frustrated.</p>
</dd>
<dt>
<span class="term">Ease of Processing</span>
</dt>
<dd>
<p>XML documents are ultimately processed by software at some point, and the document structure effects how difficult the processing software will be to write.</p>
</dd>
<dt>
<span class="term">Flexibility</span>
</dt>
<dd>
<p>This is an indication of how the document instances written for a particular document type can differ. Some document types, such as HTML were meant to provide for a huge variety of documents to be written using them. For other systems, for examples, a payroll processing system, very strict rules about how the data is to be presented is needed.</p>
</dd>
<dt>
<span class="term">Consistency</span>
</dt>
<dd>
<p>Consistency is important for documents to be usable. Inconsistencies lead to errors and misunderstandings.</p>
</dd>
<dt>
<span class="term">Amount of Abstraction</span>
</dt>
<dd>
<p>The granularity and types of abstraction used in a document type will vary depending on the context. A date could be marked up as
</p>
<pre class="programlisting">
&lt;Date&gt;12-10-2000&lt;/Date&gt;
or
&lt;Date&gt; &lt;Month&gt;Dec&lt;/Month&gt; &lt;Day&gt;10&lt;/Day&gt; &lt;Year&gt;2000&lt;/Year&gt; &lt;/Date&gt;.
</pre>
<p>
Which one is more appropriate depends on the situation where it is used.</p>
</dd>
</dl>
</div>
</div>
<div class="article" title="Journey" id="d55e222">
<header class="titlepage">
<div>
<h2 class="title">Journey</h2>
</div>
</header>
<p>This page provides an overview of the patterns on this site. It is written in a more informal, narrative fashion then other indexes, to provide a gentler introduction to the patterns. This description of the patterns should give a good idea of how the different patterns relate, and roughly in what order they will be used.</p>
<p>When creating a system a data representation must be chosen for information, one possibility is to Use XML. After deciding on XML, investigate existing schemas to see if the project can Reuse Document Types.</p>
<p>Once XML has been chosen as a data representation, it must be determined what the root elements are, or if multiple document types should be used. Multiple Document Types can be used to represent a range of different document types, or if documents are related and have some commonalities, a Multi Root Document Types can be used. If multiple transaction types are needed a Universal Root can be used. To separate concerns such as transport of the data from the data itself, an Envelope can be used.</p>
<p>To create structure in a document, element types which represent abstractions are needed. Name these abstractions using Short Understandable Names These can be based on domain concepts and become Domain Element. To add more structure Container Element can be used. When containers of like element types are needed a Collection Element can be used. To make the documents easier to use for authors, abstraction can be added with Choice Reducing Container and Optional Container Element</p>
<p>When creating these abstractions, some metadata will be needed to be placed in the document. Care should be taken to Separate Metadata and Data. This can be done by placing Metadata in Separate Document or by using a Head-Body. When creating the structure, put Metadata First.</p>
<p>It must be decided how to organize these abstractions. When one abstraction references another one, that is when one abstraction uses information that is declared in another one, Declare Before First Use. When the same information needs to be referenced from many places, use a Flyweight. A Referenced Note can be used when an area of text needs to reference an note in another area of the text. The natural way to structure information in XML is using a hierarchical format, however it is sometimes better to use a more graph-like structure using Marketplace.</p>
<p>Sometimes a document designer will not be able to foresee all of the uses of a document type, in that case a Catch-All Element can be used to easily introduce elements from other DTDs. Role Attribute and Extensible Content Model can be used to make a more flexible document type by adding element that can be introduced by the document author.</p>
<p>To make documents easier to use, consistency is important. Common Attributes and Consistent Element Set can be used to provide this consistency.</p>
</div>
</div>
<div class="part" title="Part III. Patterns" id="d55e243">
<div class="titlepage">
<div>
<div>
<h1 class="title">Part III. Patterns</h1>
</div>
</div>
</div>
<nav>
<dl class="toc">
<dt>Table of Contents</dt>
<dd>
<ol class="part">
<li class="chapter">
<a href="#d55e247">Document Roots</a>
<ol>
<li class="section">
<a href="#d55e255">Multi Root Document Types</a>
<ol>
<li class="section">
<a href="#d55e262">Problem</a>
</li>
<li class="section">
<a href="#d55e267">Context</a>
</li>
<li class="section">
<a href="#d55e272">Forces</a>
</li>
<li class="section">
<a href="#d55e277">Solution</a>
</li>
<li class="section">
<a href="#d55e282">Examples</a>
</li>
<li class="section">
<a href="#d55e293">Discussion</a>
</li>
<li class="section">
<a href="#d55e298">Related Patterns</a>
</li>
<li class="section">
<a href="#d55e308">Known Uses</a>
</li>
</ol>
</li>
<li class="section">
<a href="#d55e314">Multiple Document Types</a>
<ol>
<li class="section">
<a href="#d55e321">Problem</a>
</li>
<li class="section">
<a href="#d55e326">Context</a>
</li>
<li class="section">
<a href="#d55e331">Forces</a>
</li>
<li class="section">
<a href="#d55e336">Solution</a>
</li>
<li class="section">
<a href="#d55e341">Examples</a>
</li>
<li class="section">
<a href="#d55e356">Discussion</a>
</li>
<li class="section">
<a href="#d55e363">Related Patterns</a>
</li>
<li class="section">
<a href="#d55e370">Known Uses</a>
</li>
</ol>
</li>
<li class="section">
<a href="#d55e376">Universal Root</a>
<ol>
<li class="section">
<a href="#d55e383">Problem</a>
</li>
<li class="section">
<a href="#d55e388">Context</a>
</li>
<li class="section">
<a href="#d55e393">Forces</a>
</li>
<li class="section">
<a href="#d55e398">Solution</a>
</li>
<li class="section">
<a href="#d55e403">Examples</a>
</li>
<li class="section">
<a href="#d55e410">Discussion</a>
</li>
<li class="section">
<a href="#d55e421">Related Patterns</a>
</li>
<li class="section">
<a href="#d55e431">Known Uses</a>
</li>
</ol>
</li>
</ol>
</li>
<li class="chapter">
<a href="#d55e437">Metadata</a>
<ol>
<li class="section">
<a href="#d55e445">Head-Body</a>
<ol>
<li class="section">
<a href="#d55e452">Problem</a>
</li>
<li class="section">
<a href="#d55e457">Context</a>
</li>
<li class="section">
<a href="#d55e462">Forces</a>
</li>
<li class="section">
<a href="#d55e467">Solution</a>
</li>
<li class="section">
<a href="#d55e480">Examples</a>
</li>
<li class="section">
<a href="#d55e491">Discussion</a>
</li>
<li class="section">
<a href="#d55e504">Related Patterns</a>
</li>
<li class="section">
<a href="#d55e509">Known Uses</a>
</li>
<li class="section">
<a href="#d55e519">References</a>
</li>
</ol>
</li>
<li class="section">
<a href="#d55e525">Metadata First</a>
<ol>
<li class="section">
<a href="#d55e532">Problem</a>
</li>
<li class="section">
<a href="#d55e537">Context</a>
</li>
<li class="section">
<a href="#d55e542">Forces</a>
</li>
<li class="section">
<a href="#d55e547">Solution</a>
</li>
<li class="section">
<a href="#d55e558">Examples</a>
</li>
<li class="section">
<a href="#d55e565">Discussion</a>
</li>
<li class="section">
<a href="#d55e570">Related Patterns</a>
</li>
<li class="section">
<a href="#d55e578">Known Uses</a>
</li>
</ol>
</li>
<li class="section">
<a href="#d55e584">Metadata in Separate Document</a>
<ol>
<li class="section">
<a href="#d55e591">Problem</a>
</li>
<li class="section">
<a href="#d55e596">Context</a>
</li>
<li class="section">
<a href="#d55e601">Forces</a>
</li>
<li class="section">
<a href="#d55e606">Solution</a>
</li>
<li class="section">
<a href="#d55e615">Examples</a>
</li>
<li class="section">
<a href="#d55e634">Discussion</a>
</li>
<li class="section">
<a href="#d55e643">Related Patterns</a>
</li>
<li class="section">
<a href="#d55e648">Known Uses</a>
</li>
<li class="section">
<a href="#d55e653">References</a>
</li>
</ol>
</li>
<li class="section">
<a href="#d55e659">Separate Metadata and Data</a>
<ol>
<li class="section">
<a href="#d55e666">Problem</a>
</li>
<li class="section">
<a href="#d55e675">Context</a>
</li>
<li class="section">
<a href="#d55e680">Forces</a>
</li>
<li class="section">
<a href="#d55e685">Solution</a>
</li>
<li class="section">
<a href="#d55e690">Examples</a>
</li>
<li class="section">
<a href="#d55e701">Discussion</a>
</li>
<li class="section">
<a href="#d55e706">Related Patterns</a>
</li>
<li class="section">
<a href="#d55e716">Known Uses</a>
</li>
</ol>
</li>
</ol>
</li>
<li class="chapter">
<a href="#d55e724">Abstraction</a>
<ol>
<li class="section">
<a href="#d55e732">Choice Reducing Container</a>
<ol>
<li class="section">
<a href="#d55e739">Problem</a>
</li>
<li class="section">
<a href="#d55e744">Context</a>
</li>
<li class="section">
<a href="#d55e749">Forces</a>
</li>
<li class="section">
<a href="#d55e754">Solution</a>
</li>
<li class="section">
<a href="#d55e759">Examples</a>
</li>
<li class="section">
<a href="#d55e776">Discussion</a>
</li>
<li class="section">
<a href="#d55e783">Related Patterns</a>
</li>
<li class="section">
<a href="#d55e790">Known Uses</a>
</li>
<li class="section">
<a href="#d55e795">References</a>
</li>
</ol>
</li>
<li class="section">
<a href="#d55e801">Collection Element</a>
<ol>
<li class="section">
<a href="#d55e808">Problem</a>
</li>
<li class="section">
<a href="#d55e813">Context</a>
</li>
<li class="section">
<a href="#d55e818">Forces</a>
</li>
<li class="section">
<a href="#d55e823">Solution</a>
</li>
<li class="section">
<a href="#d55e828">Examples</a>
</li>
<li class="section">
<a href="#d55e848">Discussion</a>
</li>
<li class="section">
<a href="#d55e857">Related Patterns</a>
</li>
<li class="section">
<a href="#d55e862">Known Uses</a>
</li>
</ol>
</li>
<li class="section">
<a href="#d55e871">Container Element</a>
<ol>
<li class="section">
<a href="#d55e878">Problem</a>
</li>
<li class="section">
<a href="#d55e883">Context</a>
</li>
<li class="section">
<a href="#d55e888">Forces</a>
</li>
<li class="section">
<a href="#d55e893">Solution</a>
</li>
<li class="section">
<a href="#d55e898">Examples</a>
</li>
<li class="section">
<a href="#d55e909">Discussion</a>
</li>
<li class="section">
<a href="#d55e916">Related Patterns</a>
</li>
<li class="section">
<a href="#d55e931">Known Uses</a>
</li>
<li class="section">
<a href="#d55e936">References</a>
</li>
</ol>
</li>
<li class="section">
<a href="#d55e942">Domain Element</a>
<ol>
<li class="section">
<a href="#d55e949">Problem</a>
</li>
<li class="section">
<a href="#d55e954">Context</a>
</li>
<li class="section">
<a href="#d55e959">Forces</a>
</li>
<li class="section">
<a href="#d55e964">Solution</a>
</li>
<li class="section">
<a href="#d55e969">Examples</a>
</li>
<li class="section">
<a href="#d55e976">Discussion</a>
</li>
<li class="section">
<a href="#d55e983">Related Patterns</a>
</li>
<li class="section">
<a href="#d55e988">Known Uses</a>
</li>
</ol>
</li>
<li class="section">
<a href="#d55e998">Optional Container Element</a>
<ol>
<li class="section">
<a href="#d55e1005">Problem</a>
</li>
<li class="section">
<a href="#d55e1010">Context</a>
</li>
<li class="section">
<a href="#d55e1015">Forces</a>
</li>
<li class="section">
<a href="#d55e1020">Solution</a>
</li>
<li class="section">
<a href="#d55e1025">Examples</a>
</li>
<li class="section">
<a href="#d55e1038">Discussion</a>
</li>
<li class="section">
<a href="#d55e1047">Related Patterns</a>
</li>
<li class="section">
<a href="#d55e1052">Known Uses</a>
</li>
<li class="section">
<a href="#d55e1061">Contributions</a>
</li>
</ol>
</li>
</ol>
</li>
<li class="chapter">
<a href="#d55e1067">Organization</a>
<ol>
<li class="section">
<a href="#d55e1075">Declare Before First Use</a>
<ol>
<li class="section">
<a href="#d55e1082">Problem</a>
</li>
<li class="section">
<a href="#d55e1087">Context</a>
</li>
<li class="section">
<a href="#d55e1092">Forces</a>
</li>
<li class="section">
<a href="#d55e1097">Solution</a>
</li>
<li class="section">
<a href="#d55e1102">Examples</a>
</li>
<li class="section">
<a href="#d55e1107">Discussion</a>
</li>
<li class="section">
<a href="#d55e1112">Related Patterns</a>
</li>
<li class="section">
<a href="#d55e1123">Known Uses</a>
</li>
</ol>
</li>
<li class="section">
<a href="#d55e1129">Envelope</a>
<ol>
<li class="section">
<a href="#d55e1138">Problem</a>
</li>
<li class="section">
<a href="#d55e1143">Context</a>
</li>
<li class="section">
<a href="#d55e1148">Forces</a>
</li>
<li class="section">
<a href="#d55e1155">Solution</a>
</li>
<li class="section">
<a href="#d55e1160">Examples</a>
</li>
<li class="section">
<a href="#d55e1176">Discussion</a>
</li>
<li class="section">
<a href="#d55e1187">Related Patterns</a>
</li>
<li class="section">
<a href="#d55e1201">Known Uses</a>
</li>
<li class="section">
<a href="#d55e1209">References</a>
</li>
</ol>
</li>
<li class="section">
<a href="#d55e1215">Flyweight</a>
<ol>
<li class="section">
<a href="#d55e1222">Problem</a>
</li>
<li class="section">
<a href="#d55e1237">Context</a>
</li>
<li class="section">
<a href="#d55e1242">Forces</a>
</li>
<li class="section">
<a href="#d55e1247">Solution</a>
</li>
<li class="section">
<a href="#d55e1264">Examples</a>
</li>
<li class="section">
<a href="#d55e1288">Discussion</a>
</li>
<li class="section">
<a href="#d55e1297">Related Patterns</a>
</li>
<li class="section">
<a href="#d55e1305">Known Uses</a>
</li>
</ol>
</li>
<li class="section">
<a href="#d55e1316">Marketplace</a>
<ol>
<li class="section">
<a href="#d55e1323">Problem</a>
</li>
<li class="section">
<a href="#d55e1332">Context</a>
</li>
<li class="section">
<a href="#d55e1337">Forces</a>
</li>
<li class="section">
<a href="#d55e1342">Solution</a>
</li>
<li class="section">
<a href="#d55e1347">Examples</a>
</li>
<li class="section">
<a href="#d55e1356">Discussion</a>
</li>
<li class="section">
<a href="#d55e1361">Related Patterns</a>
</li>
<li class="section">
<a href="#d55e1366">Known Uses</a>
</li>
<li class="section">
<a href="#d55e1371">References</a>
</li>
</ol>
</li>
<li class="section">
<a href="#d55e1377">Referenced Note</a>
<ol>
<li class="section">
<a href="#d55e1386">Problem</a>
</li>
<li class="section">
<a href="#d55e1391">Context</a>
</li>
<li class="section">
<a href="#d55e1396">Forces</a>
</li>
<li class="section">
<a href="#d55e1401">Solution</a>
</li>
<li class="section">
<a href="#d55e1417">Examples</a>
</li>
<li class="section">
<a href="#d55e1426">Discussion</a>
</li>
<li class="section">
<a href="#d55e1433">Related Patterns</a>
</li>
<li class="section">
<a href="#d55e1443">Known Uses</a>
</li>
<li class="section">
<a href="#d55e1448">References</a>
</li>
</ol>
</li>
</ol>
</li>
<li class="chapter">
<a href="#d55e1454">Flexibility</a>
<ol>
<li class="section">
<a href="#d55e1462">Catch-All Element</a>
<ol>
<li class="section">
<a href="#d55e1469">Problem</a>
</li>
<li class="section">
<a href="#d55e1474">Context</a>
</li>
<li class="section">
<a href="#d55e1479">Forces</a>
</li>
<li class="section">
<a href="#d55e1486">Solution</a>
</li>
<li class="section">
<a href="#d55e1491">Examples</a>
</li>
<li class="section">
<a href="#d55e1510">Discussion</a>
</li>
<li class="section">
<a href="#d55e1517">Related Patterns</a>
</li>
<li class="section">
<a href="#d55e1528">Known Uses</a>
</li>
</ol>
</li>
<li class="section">
<a href="#d55e1534">Extensible Content Model</a>
<ol>
<li class="section">
<a href="#d55e1541">Problem</a>
</li>
<li class="section">
<a href="#d55e1546">Context</a>
</li>
<li class="section">
<a href="#d55e1551">Forces</a>
</li>
<li class="section">
<a href="#d55e1556">Solution</a>
</li>
<li class="section">
<a href="#d55e1561">Examples</a>
</li>
<li class="section">
<a href="#d55e1609">Discussion</a>
</li>
<li class="section">
<a href="#d55e1616">Related Patterns</a>
</li>
<li class="section">
<a href="#d55e1627">Known Uses</a>
</li>
<li class="section">
<a href="#d55e1636">References</a>
</li>
</ol>
</li>
<li class="section">
<a href="#d55e1642">Generic Element</a>
<ol>
<li class="section">
<a href="#d55e1649">Problem</a>
</li>
<li class="section">
<a href="#d55e1654">Context</a>
</li>
<li class="section">
<a href="#d55e1659">Forces</a>
</li>
<li class="section">
<a href="#d55e1664">Solution</a>
</li>
<li class="section">
<a href="#d55e1669">Examples</a>
</li>
<li class="section">
<a href="#d55e1674">Discussion</a>
</li>
<li class="section">
<a href="#d55e1681">Related Patterns</a>
</li>
<li class="section">
<a href="#d55e1689">Known Uses</a>
</li>
<li class="section">
<a href="#d55e1694">References</a>
</li>
</ol>
</li>
<li class="section">
<a href="#d55e1700">Role Attribute</a>
<ol>
<li class="section">
<a href="#d55e1707">Problem</a>
</li>
<li class="section">
<a href="#d55e1712">Context</a>
</li>
<li class="section">
<a href="#d55e1717">Forces</a>
</li>
<li class="section">
<a href="#d55e1722">Solution</a>
</li>
<li class="section">
<a href="#d55e1727">Examples</a>
</li>
<li class="section">
<a href="#d55e1738">Discussion</a>
</li>
<li class="section">
<a href="#d55e1745">Related Patterns</a>
</li>
<li class="section">
<a href="#d55e1756">Known Uses</a>
</li>
</ol>
</li>
</ol>
</li>
<li class="chapter">
<a href="#d55e1765">Consistency</a>
<ol>
<li class="section">
<a href="#d55e1773">Common Attributes</a>
<ol>
<li class="section">
<a href="#d55e1780">Problem</a>
</li>
<li class="section">
<a href="#d55e1785">Context</a>
</li>
<li class="section">
<a href="#d55e1790">Forces</a>
</li>
<li class="section">
<a href="#d55e1795">Solution</a>
</li>
<li class="section">
<a href="#d55e1800">Examples</a>
</li>
<li class="section">
<a href="#d55e1820">Discussion</a>
</li>
<li class="section">
<a href="#d55e1827">Related Patterns</a>
</li>
<li class="section">
<a href="#d55e1835">Known Uses</a>
</li>
<li class="section">
<a href="#d55e1848">References</a>
</li>
<li class="section">
<a href="#d55e1853">Contributions</a>
</li>
</ol>
</li>
<li class="section">
<a href="#d55e1859">Consistent Element Set</a>
<ol>
<li class="section">
<a href="#d55e1866">Problem</a>
</li>
<li class="section">
<a href="#d55e1871">Context</a>
</li>
<li class="section">
<a href="#d55e1876">Forces</a>
</li>
<li class="section">
<a href="#d55e1881">Solution</a>
</li>
<li class="section">
<a href="#d55e1886">Examples</a>
</li>
<li class="section">
<a href="#d55e1905">Discussion</a>
</li>
<li class="section">
<a href="#d55e1910">Related Patterns</a>
</li>
<li class="section">
<a href="#d55e1915">Known Uses</a>
</li>
</ol>
</li>
<li class="section">
<a href="#d55e1921">Parallel Design</a>
<ol>
<li class="section">
<a href="#d55e1928">Problem</a>
</li>
<li class="section">
<a href="#d55e1933">Context</a>
</li>
<li class="section">
<a href="#d55e1938">Forces</a>
</li>
<li class="section">
<a href="#d55e1943">Solution</a>
</li>
<li class="section">
<a href="#d55e1948">Examples</a>
</li>
<li class="section">
<a href="#d55e1955">Discussion</a>
</li>
<li class="section">
<a href="#d55e1960">Related Patterns</a>
</li>
<li class="section">
<a href="#d55e1968">Known Uses</a>
</li>
<li class="section">
<a href="#d55e1977">References</a>
</li>
</ol>
</li>
</ol>
</li>
<li class="chapter">
<a href="#d55e1983">Miscellaneous</a>
<ol>
<li class="section">
<a href="#d55e1991">Content Type Label</a>
<ol>
<li class="section">
<a href="#d55e1998">Problem</a>
</li>
<li class="section">
<a href="#d55e2003">Context</a>
</li>
<li class="section">
<a href="#d55e2008">Forces</a>
</li>
<li class="section">
<a href="#d55e2013">Solution</a>
</li>
<li class="section">
<a href="#d55e2018">Examples</a>
</li>
<li class="section">
<a href="#d55e2025">Discussion</a>
</li>
<li class="section">
<a href="#d55e2034">Related Patterns</a>
</li>
<li class="section">
<a href="#d55e2042">Known Uses</a>
</li>
<li class="section">
<a href="#d55e2051">References</a>
</li>
</ol>
</li>
<li class="section">
<a href="#d55e2057">Reuse Document Types</a>
<ol>
<li class="section">
<a href="#d55e2064">Problem</a>
</li>
<li class="section">
<a href="#d55e2069">Context</a>
</li>
<li class="section">
<a href="#d55e2074">Forces</a>
</li>
<li class="section">
<a href="#d55e2081">Solution</a>
</li>
<li class="section">
<a href="#d55e2086">Examples</a>
</li>
<li class="section">
<a href="#d55e2091">Discussion</a>
</li>
<li class="section">
<a href="#d55e2124">Related Patterns</a>
</li>
<li class="section">
<a href="#d55e2129">Known Uses</a>
</li>
<li class="section">
<a href="#d55e2134">References</a>
</li>
</ol>
</li>
<li class="section">
<a href="#d55e2140">Short Understandable Names</a>
<ol>
<li class="section">
<a href="#d55e2147">Problem</a>
</li>
<li class="section">
<a href="#d55e2152">Context</a>
</li>
<li class="section">
<a href="#d55e2157">Forces</a>
</li>
<li class="section">
<a href="#d55e2162">Solution</a>
</li>
<li class="section">
<a href="#d55e2167">Examples</a>
</li>
<li class="section">
<a href="#d55e2172">Discussion</a>
</li>
<li class="section">
<a href="#d55e2183">Related Patterns</a>
</li>
<li class="section">
<a href="#d55e2188">Known Uses</a>
</li>
</ol>
</li>
<li class="section">
<a href="#d55e2194">Use XML</a>
<ol>
<li class="section">
<a href="#d55e2201">Problem</a>
</li>
<li class="section">
<a href="#d55e2206">Context</a>
</li>
<li class="section">
<a href="#d55e2233">Forces</a>
</li>
<li class="section">
<a href="#d55e2238">Solution</a>
</li>
<li class="section">
<a href="#d55e2243">Examples</a>
</li>
<li class="section">
<a href="#d55e2248">Discussion</a>
</li>
<li class="section">
<a href="#d55e2253">Related Patterns</a>
</li>
<li class="section">
<a href="#d55e2258">Known Uses</a>
</li>
<li class="section">
<a href="#d55e2310">References</a>
</li>
</ol>
</li>
</ol>
</li>
</ol>
</dd>
</dl>
</nav>
<div class="chapter" title="Chapter 1. Document Roots" id="d55e247">
<div class="titlepage">
<h2 class="title">Chapter 1. Document Roots</h2>
<div>
<div class="abstract" title="Abstract">
<p class="title">
<strong>Abstract</strong>
</p>
<p>Patterns about how to determine what the root element(s) should be.</p>
</div>
</div>
</div>
<nav>
<dl class="toc">
<dt>Table of Contents</dt>
<dd>
<ol class="chapter">
<li class="section">
<a href="#d55e255">Multi Root Document Types</a>
<ol>
<li class="section">
<a href="#d55e262">Problem</a>
</li>
<li class="section">
<a href="#d55e267">Context</a>
</li>
<li class="section">
<a href="#d55e272">Forces</a>
</li>
<li class="section">
<a href="#d55e277">Solution</a>
</li>
<li class="section">
<a href="#d55e282">Examples</a>
</li>
<li class="section">
<a href="#d55e293">Discussion</a>
</li>
<li class="section">
<a href="#d55e298">Related Patterns</a>
</li>
<li class="section">
<a href="#d55e308">Known Uses</a>
</li>
</ol>
</li>
<li class="section">
<a href="#d55e314">Multiple Document Types</a>
<ol>
<li class="section">
<a href="#d55e321">Problem</a>
</li>
<li class="section">
<a href="#d55e326">Context</a>
</li>
<li class="section">
<a href="#d55e331">Forces</a>
</li>
<li class="section">
<a href="#d55e336">Solution</a>
</li>
<li class="section">
<a href="#d55e341">Examples</a>
</li>
<li class="section">
<a href="#d55e356">Discussion</a>
</li>
<li class="section">
<a href="#d55e363">Related Patterns</a>
</li>
<li class="section">
<a href="#d55e370">Known Uses</a>
</li>
</ol>
</li>
<li class="section">
<a href="#d55e376">Universal Root</a>
<ol>
<li class="section">
<a href="#d55e383">Problem</a>
</li>
<li class="section">
<a href="#d55e388">Context</a>
</li>
<li class="section">
<a href="#d55e393">Forces</a>
</li>
<li class="section">
<a href="#d55e398">Solution</a>
</li>
<li class="section">
<a href="#d55e403">Examples</a>
</li>
<li class="section">
<a href="#d55e410">Discussion</a>
</li>
<li class="section">
<a href="#d55e421">Related Patterns</a>
</li>
<li class="section">
<a href="#d55e431">Known Uses</a>
</li>
</ol>
</li>
</ol>
</dd>
</dl>
</nav>
<div class="section" title="Multi Root Document Types">
<div class="titlepage">
<h2 class="title" id="d55e255">Multi Root Document Types</h2>
<div>
<div class="abstract" title="Abstract">
<p class="title">
<strong>Abstract</strong>
</p>
<p>A single document type with multiple root elements is used to handle varying
documents that may exist within a system.</p>
</div>
</div>
</div>
<div class="section" title="Problem">
<div class="titlepage">
<h3 class="title" id="d55e262">Problem</h3>
</div>
<p>A system needs to handle varying types of documents. These are somehow related, yet
each type of document needs a unique identity provided by a document root.</p>
</div>
<div class="section" title="Context">
<div class="titlepage">
<h3 class="title" id="d55e267">Context</h3>
</div>
<p>Systems where varying types of documents need to be processed, but the different
documents are closely related.</p>
</div>
<div class="section" title="Forces">
<div class="titlepage">
<h3 class="title" id="d55e272">Forces</h3>
</div>
<p>Maintainability of the system is effected by how the document types are
organized.</p>
</div>
<div class="section" title="Solution">
<div class="titlepage">
<h3 class="title" id="d55e277">Solution</h3>
</div>
<p>Create a single declaration with multiple root elements for the different document
types.</p>
</div>
<div class="section" title="Examples">
<div class="titlepage">
<h3 class="title" id="d55e282">Examples</h3>
</div>
<p>The two documents below show two different bank transactions, a deposit and a
withdrawal. The document have different root elements, but many other common elements.
Both of these documents use the same DTD, but declare different roots.
</p>
<div class="literallayout">
<p>
<br/>
&lt;!DOCTYPE "Deposit" SYSTEM "bank.dtd"&gt;<br/>
&lt;Deposit&gt;<br/>
&lt;Account id="123"/&gt;<br/>
&lt;Amount currency="USD"&gt;100.00&lt;/Amount&gt;<br/>
&lt;Date&gt;05-10-2000&lt;/Date&gt;<br/>
&lt;/Deposit&gt;<br/>
</p>
</div>
<p>
</p>
<div class="literallayout">
<p>
<br/>
&lt;!DOCTYPE "Withdrawal" SYSTEM "bank.dtd"&gt;<br/>
&lt;Withdrawal&gt;<br/>
&lt;Account id="123"/&gt;<br/>
&lt;Amount currency="USD"&gt;100.00&lt;/Amount&gt;<br/>
&lt;Date&gt;05-10-2000&lt;/Date&gt;<br/>
&lt;/Withdrawal&gt;<br/>
</p>
</div>
<p>
</p>
</div>
<div class="section" title="Discussion">
<div class="titlepage">
<h3 class="title" id="d55e293">Discussion</h3>
</div>
<p>Allows the different document types to easily share structure. Having all of the
related document types declared in a single file can increase maintainability. However,
if revisions need to be made to the different document types separately, it might be
better having separate declarations.</p>
</div>
<div class="section" title="Related Patterns">
<div class="titlepage">
<h3 class="title" id="d55e298">Related Patterns</h3>
</div>
<p>
<a class="link" href="/patterns/doc-roots/universal-root.xml">Universal Root</a> and <a class="link" href="/patterns/doc-roots/multi-doc-types.xml">Multiple Document Types</a> are alternatives.</p>
</div>
<div class="section" title="Known Uses">
<div class="titlepage">
<h3 class="title" id="d55e308">Known Uses</h3>
</div>
<p>In DocBook the root element can be a set or a book element.</p>
</div>
</div>
<div class="section" title="Multiple Document Types">
<div class="titlepage">
<h2 class="title" id="d55e314">Multiple Document Types</h2>
<div>
<div class="abstract" title="Abstract">
<p class="title">
<strong>Abstract</strong>
</p>
<p>When a system needs to represent a range of different document types, each document
type can be represented by a completely separate declarations.</p>
</div>
</div>
</div>
<div class="section" title="Problem">
<div class="titlepage">
<h3 class="title" id="d55e321">Problem</h3>
</div>
<p>A system needs to represent different types of information. This information may be
used at different times, or may be used by different parts of the system.</p>
</div>
<div class="section" title="Context">
<div class="titlepage">
<h3 class="title" id="d55e326">Context</h3>
</div>
<p>Systems which need to represent a variety of information at different times or
places.</p>
</div>
<div class="section" title="Forces">
<div class="titlepage">
<h3 class="title" id="d55e331">Forces</h3>
</div>
<p>Processing and authoring of documents can be simplified if different document types
are used to represent different sets of data.</p>
</div>
<div class="section" title="Solution">
<div class="titlepage">
<h3 class="title" id="d55e336">Solution</h3>
</div>
<p>Use different document types to represent different sets of data within the
system.</p>
</div>
<div class="section" title="Examples">
<div class="titlepage">
<h3 class="title" id="d55e341">Examples</h3>
</div>
<p>In a payroll system, data about the Employees, and data about the hours they work can
be represented by separate documents.</p>
<div class="example">
<a id="d55e346"/>
<p class="title">
<strong>Example 1.1. Employees.dtd:</strong>
</p>
<div class="example-contents">
<div class="literallayout">
<p>
<br/>
&lt;!ELEMENT Employee (Name, HourlyRate)&gt;<br/>
&lt;!ATTLIST Employee id ID #REQUIRED&gt;<br/>
<br/>
&lt;!ELEMENT Name (#PCDATA)&gt;<br/>
<br/>
&lt;!ELEMENT HourlyRate (#PCDATA)&gt;<br/>
</p>
</div>
</div>
</div>
<br class="example-break"/>
<div class="example">
<a id="d55e351"/>
<p class="title">
<strong>Example 1.2. HoursWorked.dtd:</strong>
</p>
<div class="example-contents">
<div class="literallayout">
<p>
<br/>
&lt;!ELEMENT PayPeriod (Employee+)&gt;<br/>
&lt;!ATTLIST PayPeriod<br/>
StartDate #CDATA<br/>
EndDate   #CDATA&gt;<br/>
<br/>
&lt;!ELEMENT Employee (HoursWorked)&gt;<br/>
&lt;!ATTLIST Employee id NMTOKEN&gt;<br/>
<br/>
&lt;!ELEMENT HoursWorked (#PCDATA)&gt;<br/>
</p>
</div>
</div>
</div>
<br class="example-break"/>
</div>
<div class="section" title="Discussion">
<div class="titlepage">
<h3 class="title" id="d55e356">Discussion</h3>
</div>
<p>If different people will authoring the different types of documents it is a good idea
to have completely separate document types, because authors will not need to be exposed
to parts of the document types that are not needed.</p>
<p>Having separate document types allows the different DTDs to be versioned
independently.</p>
</div>
<div class="section" title="Related Patterns">
<div class="titlepage">
<h3 class="title" id="d55e363">Related Patterns</h3>
</div>
<p>
<a class="link" href="/patterns/doc-roots/universal-root.xml">Universal Root</a> allows multiple types of data under one document root. Multi Root
Document Types allows for multiple types of documents to be declared in a single
declaration.</p>
</div>
<div class="section" title="Known Uses">
<div class="titlepage">
<h3 class="title" id="d55e370">Known Uses</h3>
</div>
<p>…</p>
</div>
</div>
<div class="section" title="Universal Root">
<div class="titlepage">
<h2 class="title" id="d55e376">Universal Root</h2>
<div>
<div class="abstract" title="Abstract">
<p class="title">
<strong>Abstract</strong>
</p>
<p>Provide a single root element that contains an option of multiple elements. Often used
for different transaction types within a single document type.</p>
</div>
</div>
</div>
<div class="section" title="Problem">
<div class="titlepage">
<h3 class="title" id="d55e383">Problem</h3>
</div>
<p>There are several different types of document that need to be processed. Providing a
single root element allows for all of the different types of document to be defined by a
single DTD. When a processor receives this document, it will know which type of document
to expect by inspecting the child element of the root element.</p>
</div>
<div class="section" title="Context">
<div class="titlepage">
<h3 class="title" id="d55e388">Context</h3>
</div>
<p>Universal Root is useful when a system has several different, but related, document
types to be processed. A transactional processor would be an example of such a
system.</p>
</div>
<div class="section" title="Forces">
<div class="titlepage">
<h3 class="title" id="d55e393">Forces</h3>
</div>
<p>Having multiple, distinct document types can increase the maintenance burden of a
system. Document types that may be related, but are declared in separate files can start
to stray from commonalities that can be taken advantage of.</p>
</div>
<div class="section" title="Solution">
<div class="titlepage">
<h3 class="title" id="d55e398">Solution</h3>
</div>
<p>Create a document type that has a single root element.</p>
</div>
<div class="section" title="Examples">
<div class="titlepage">
<h3 class="title" id="d55e403">Examples</h3>
</div>
<div class="literallayout">
<p>
<br/>
&lt;!ELEMENT Transaction<br/>
(AddAddress | RemoveAddress | UpdateAddress)&gt;<br/>
<br/>
&lt;!ELEMENT AddAddress<br/>
(AddressBookEntry)&gt;<br/>
<br/>
&lt;!ELEMENT RemoveAddress<br/>
(AddressID)&gt;<br/>
<br/>
&lt;!ELEMENT UpdateAddress<br/>
(AddressID, AddressBookEntry)&gt;<br/>
<br/>
<br/>
&lt;Transaction&gt;<br/>
&lt;AddAddress&gt;<br/>
&lt;AddressBookEntry&gt; ... &lt;/AddressBookEntry&gt;<br/>
&lt;/AddAddress&gt;<br/>
&lt;/Transaction&gt;<br/>
</p>
</div>
<p>In this example an online address book application is being developed. There are
several transactions that can take place, like adding new entries, deleting entries,
updating entries.</p>
</div>
<div class="section" title="Discussion">
<div class="titlepage">
<h3 class="title" id="d55e410">Discussion</h3>
</div>
<p>This allows a way for several related types of documents to be grouped into a single
document type structure. A processing system will always know which DTD to expect, but
can still handle the documents differently based on the first nested element type. This
makes sharing common definitions between the different document easy.</p>
<p>This is also a way that multiple XML document can be gathered into a single larger
document. For example a log file might consist of several fragments, for example:</p>
<div class="literallayout">
<p>
<br/>
&lt;Log&gt;<br/>
&lt;Time&gt;Jan 15, 1999 10:58AM&lt;/Time&gt;<br/>
&lt;Event&gt;Startup&lt;/Event&gt;<br/>
&lt;/Log&gt;<br/>
&lt;Log&gt;<br/>
&lt;Time&gt;Jan 15, 1999 11:02AM&lt;/Time&gt;<br/>
&lt;Event&gt;Message Received from Bob&lt;/Event&gt;<br/>
&lt;/Log&gt;<br/>
…<br/>
</p>
</div>
<p>Since there is no root element in the file it cannot be processed "as is".
To process this, one can prepend a start tag, for example "&lt;LogFile&gt;",
in front of the file, and append the end tag "&lt;/LogFile&gt;" to the end of
the file to be able to process it as a single XML document.</p>
</div>
<div class="section" title="Related Patterns">
<div class="titlepage">
<h3 class="title" id="d55e421">Related Patterns</h3>
</div>
<p>
<a class="link" href="/patterns/doc-roots/multi-root.xml">Multi Root Document Types</a> and <a class="link" href="/patterns/doc-roots/multi-doc-types.xml">Multiple Document Types</a> are alternatives to this
pattern.</p>
</div>
<div class="section" title="Known Uses">
<div class="titlepage">
<h3 class="title" id="d55e431">Known Uses</h3>
</div>
<p>…</p>
</div>
</div>
</div>
<div class="chapter" title="Chapter 2. Metadata" id="d55e437">
<div class="titlepage">
<h2 class="title">Chapter 2. Metadata</h2>
<div>
<div class="abstract" title="Abstract">
<p class="title">
<strong>Abstract</strong>
</p>
<p>How to include metadata in documents.</p>
</div>
</div>
</div>
<nav>
<dl class="toc">
<dt>Table of Contents</dt>
<dd>
<ol class="chapter">
<li class="section">
<a href="#d55e445">Head-Body</a>
<ol>
<li class="section">
<a href="#d55e452">Problem</a>
</li>
<li class="section">
<a href="#d55e457">Context</a>
</li>
<li class="section">
<a href="#d55e462">Forces</a>
</li>
<li class="section">
<a href="#d55e467">Solution</a>
</li>
<li class="section">
<a href="#d55e480">Examples</a>
</li>
<li class="section">
<a href="#d55e491">Discussion</a>
</li>
<li class="section">
<a href="#d55e504">Related Patterns</a>
</li>
<li class="section">
<a href="#d55e509">Known Uses</a>
</li>
<li class="section">
<a href="#d55e519">References</a>
</li>
</ol>
</li>
<li class="section">
<a href="#d55e525">Metadata First</a>
<ol>
<li class="section">
<a href="#d55e532">Problem</a>
</li>
<li class="section">
<a href="#d55e537">Context</a>
</li>
<li class="section">
<a href="#d55e542">Forces</a>
</li>
<li class="section">
<a href="#d55e547">Solution</a>
</li>
<li class="section">
<a href="#d55e558">Examples</a>
</li>
<li class="section">
<a href="#d55e565">Discussion</a>
</li>
<li class="section">
<a href="#d55e570">Related Patterns</a>
</li>
<li class="section">
<a href="#d55e578">Known Uses</a>
</li>
</ol>
</li>
<li class="section">
<a href="#d55e584">Metadata in Separate Document</a>
<ol>
<li class="section">
<a href="#d55e591">Problem</a>
</li>
<li class="section">
<a href="#d55e596">Context</a>
</li>
<li class="section">
<a href="#d55e601">Forces</a>
</li>
<li class="section">
<a href="#d55e606">Solution</a>
</li>
<li class="section">
<a href="#d55e615">Examples</a>
</li>
<li class="section">
<a href="#d55e634">Discussion</a>
</li>
<li class="section">
<a href="#d55e643">Related Patterns</a>
</li>
<li class="section">
<a href="#d55e648">Known Uses</a>
</li>
<li class="section">
<a href="#d55e653">References</a>
</li>
</ol>
</li>
<li class="section">
<a href="#d55e659">Separate Metadata and Data</a>
<ol>
<li class="section">
<a href="#d55e666">Problem</a>
</li>
<li class="section">
<a href="#d55e675">Context</a>
</li>
<li class="section">
<a href="#d55e680">Forces</a>
</li>
<li class="section">
<a href="#d55e685">Solution</a>
</li>
<li class="section">
<a href="#d55e690">Examples</a>
</li>
<li class="section">
<a href="#d55e701">Discussion</a>
</li>
<li class="section">
<a href="#d55e706">Related Patterns</a>
</li>
<li class="section">
<a href="#d55e716">Known Uses</a>
</li>
</ol>
</li>
</ol>
</dd>
</dl>
</nav>
<div class="section" title="Head-Body">
<div class="titlepage">
<h2 class="title" id="d55e445">Head-Body</h2>
<div>
<div class="abstract" title="Abstract">
<p class="title">
<strong>Abstract</strong>
</p>
<p>When a large amount of metadata needs to be included in an element the designer may
create two children for the element, one for the metadata and one for the body of the
document.</p>
</div>
</div>
</div>
<div class="section" title="Problem">
<div class="titlepage">
<h3 class="title" id="d55e452">Problem</h3>
</div>
<p>Sometimes, an element has a large amount of metadata, and this metadata may need to be
structured. In common XML usage, attributes are used for metadata. But with a large
amount of metadata it is difficult for authors to include this information within
attributes, which have limited structure. Including metadata as sibling elements of
content elements leads to the potential to confuse the metadata and the data meant to be
in the body of the element.</p>
</div>
<div class="section" title="Context">
<div class="titlepage">
<h3 class="title" id="d55e457">Context</h3>
</div>
<p>There is a large amount of metadata about some piece of content. For example
information about the title, creation date, and authors of a document should be included
with the document, but this is not really information that belong in the body of the
document.</p>
</div>
<div class="section" title="Forces">
<div class="titlepage">
<h3 class="title" id="d55e462">Forces</h3>
</div>
<p>A clear separation is needed between what is metadata and what is data that forms the
body of the document. This affects ease of authoring and processing of the document
because the context of the data is implied. The metadata needed for an element needs to
structured in such a way that attributes are difficult to use.</p>
</div>
<div class="section" title="Solution">
<div class="titlepage">
<h3 class="title" id="d55e467">Solution</h3>
</div>
<p>Create <code class="sgmltag-element">head</code> and <code class="sgmltag-element">body</code> elements. The element that contains the head and body elements
can be referred to as the skeleton element. The metadata for the document goes into the
head element, and the data for the document itself goes into the body element. The XML
takes the following form:</p>
<div class="literallayout">
<p>
<br/>
&lt;Skeleton&gt;<br/>
&lt;Head&gt;<br/>
... meta information ...<br/>
&lt;/Head&gt;<br/>
&lt;Body&gt;<br/>
... body of document ...<br/>
&lt;/Body&gt;<br/>
&lt;/Skeletion&gt;<br/>
</p>
</div>
</div>
<div class="section" title="Examples">
<div class="titlepage">
<h3 class="title" id="d55e480">Examples</h3>
</div>
<div class="literallayout">
<p>
<br/>
&lt;Document&gt;<br/>
&lt;Head&gt;<br/>
&lt;Author&gt;John Doe&lt;/Author&gt;<br/>
&lt;Author&gt;Frank Black&lt;/Author&gt;<br/>
&lt;CreationDate&gt;June 16, 1999&lt;/CreationDate&gt;<br/>
&lt;/Head&gt;<br/>
&lt;Body&gt;<br/>
This is a document.<br/>
&lt;/Body&gt;<br/>
&lt;/Document&gt;<br/>
</p>
</div>
<p>In this case, the skeleton element is the document root, and the metadata is
structured information about the authors of the document and the creation date of the
document. The Head-Body pattern is often used at the document level, but it can also be
used at levels deeper within a document. For example the pattern could be used inside of
a Table element like this:</p>
<div class="literallayout">
<p>
<br/>
&lt;Document&gt;<br/>
&lt;Table&gt;<br/>
&lt;TableHead&gt;<br/>
&lt;Title&gt;<br/>
&lt;Italic&gt;Sample&lt;Italic&gt; Table<br/>
&lt;/Title&gt;<br/>
&lt;/TableHead&gt;<br/>
&lt;TableBody&gt;<br/>
&lt;Row&gt;Row 1&lt;/Row&gt;<br/>
&lt;Row&gt;Row 2&lt;/Row&gt;<br/>
&lt;/TableBody&gt;<br/>
&lt;/Table&gt;<br/>
&lt;/Document&gt;<br/>
</p>
</div>
<p>In this case the skeleton element is a table, which needs structure for its Title
data.</p>
</div>
<div class="section" title="Discussion">
<div class="titlepage">
<h3 class="title" id="d55e491">Discussion</h3>
</div>
<p>Two new elements are introduced which distinguish the metadata from the body of the
document. This gives processing software context to distinguish these two types of
data.</p>
<p>Because this introduced two additional elements, the resulting documents are larger
than they would be without the application of this pattern</p>
<p>The resulting documents are often easier to understand because of the clear separation
of metadata and the document body itself. The metadata is in the Head element and the
document itself goes in the Body element. Authors and processing software can clearly
distinguish the context of the data they are using.</p>
<p>Documents are also often easier to process because they allow metadata to be
structured, unlike if attributes were use for the metadata of the document.</p>
<p>For an interesting alternative, see Don Park's "Neck" pattern.</p>
</div>
<div class="section" title="Related Patterns">
<div class="titlepage">
<h3 class="title" id="d55e504">Related Patterns</h3>
</div>
<p>The Head-Body pattern consists of two new Container Elements added to the structure of
the document, one for the Head element, and one for the Body. This is a specialization
of the Separate Metadata and Data.</p>
</div>
<div class="section" title="Known Uses">
<div class="titlepage">
<h3 class="title" id="d55e509">Known Uses</h3>
</div>
<p>HEAD and BODY elements in XHTML.</p>
<p>SOAP (Simple Object Access Protocol) uses Header and Body Elements inside an <a class="link" href="/patterns/organization/envelope.xml">Envelope</a>
element.</p>
</div>
<div class="section" title="References">
<div class="titlepage">
<h3 class="title" id="d55e519">References</h3>
</div>
<p>Rick Jelliffe discusses this in a chapter entitled "The Document Shell" in:
The XML &amp; SGML Cookbook: Recipes for Structured Information</p>
</div>
</div>
<div class="section" title="Metadata First">
<div class="titlepage">
<h2 class="title" id="d55e525">Metadata First</h2>
<div>
<div class="abstract" title="Abstract">
<p class="title">
<strong>Abstract</strong>
</p>
<p>Metadata should appear in a document before the data which it is about.</p>
</div>
</div>
</div>
<div class="section" title="Problem">
<div class="titlepage">
<h3 class="title" id="d55e532">Problem</h3>
</div>
<p>Many processors (for example SAX based parsers) are stream based. That is, the
document is processed as it is read in, the whole document is never held in memory at
the same time. If a piece of metadata appears after the data it refers to, the
application software will need to store the data, then read the metadata in order to
know what to do with the data.</p>
</div>
<div class="section" title="Context">
<div class="titlepage">
<h3 class="title" id="d55e537">Context</h3>
</div>
<p>Anywhere in the document that metadata appears.</p>
</div>
<div class="section" title="Forces">
<div class="titlepage">
<h3 class="title" id="d55e542">Forces</h3>
</div>
<p>The ease and speed of processing a document can be effected by the order in which the
structures of the document appear.</p>
</div>
<div class="section" title="Solution">
<div class="titlepage">
<h3 class="title" id="d55e547">Solution</h3>
</div>
<p>Always make sure that metadata appears in a document before the data it refers to.
This can be done whether the metadata is attribute data or element data.</p>
<p>For example, with the following code,</p>
<div class="literallayout">
<p>
<br/>
&lt;Heading&gt;<br/>
This is a new section&lt;Font size="3"/&gt;<br/>
&lt;/Heading&gt;<br/>
</p>
</div>
<p>If the processing software were trying to send this information to a printer, it would
need to save the text of the heading, read in the font size, send the font size command
to the printer, and then send the text to the printer. If the font element appeared
before the text, there would be no need to save the text.</p>
</div>
<div class="section" title="Examples">
<div class="titlepage">
<h3 class="title" id="d55e558">Examples</h3>
</div>
<p>This example shows a table element with the height and width elements appearing before
the actual data of the table. This allows the processing software to start rendering the
table as the data is read in. If the height and width of the table came after the table
data, the processing software would need to read in and save all the data before
starting to display it.</p>
<div class="literallayout">
<p>&lt;Table&gt;<br/>
&lt;height unit="pixels"&gt;100&lt;/height&gt;<br/>
&lt;width unit="pixels"&gt;100&lt;/width&gt;<br/>
&lt;Row&gt;&lt;Col&gt;2&lt;/Col&gt;&lt;Col&gt;3&lt;/Col&gt;&lt;/Row&gt;<br/>
&lt;Row&gt;&lt;Col&gt;8&lt;/Col&gt;&lt;Col&gt;7&lt;/Col&gt;&lt;/Row&gt;<br/>
&lt;/Table&gt;<br/>
</p>
</div>
</div>
<div class="section" title="Discussion">
<div class="titlepage">
<h3 class="title" id="d55e565">Discussion</h3>
</div>
<p>Placing the metadata before the data that it is about will often simplify processing
software. This is also often a natural way for people to think about the data, making
documents easier to read and author.</p>
</div>
<div class="section" title="Related Patterns">
<div class="titlepage">
<h3 class="title" id="d55e570">Related Patterns</h3>
</div>
<p>The ordering of the head and body element in the <a class="link" href="/patterns/metadata/head-body.xml">Head-Body pattern</a> is an application
of this pattern.</p>
</div>
<div class="section" title="Known Uses">
<div class="titlepage">
<h3 class="title" id="d55e578">Known Uses</h3>
</div>
<p>In XHTML The head (which contains metadata) and body (which contains the content) are
always in that order. The table elements contain size and spacing data in the attributes
of the table element, which places it before the data, and the caption and column width
and spacing data appears before the table data itself.</p>
</div>
</div>
<div class="section" title="Metadata in Separate Document">
<div class="titlepage">
<h2 class="title" id="d55e584">Metadata in Separate Document</h2>
<div>
<div class="abstract" title="Abstract">
<p class="title">
<strong>Abstract</strong>
</p>
<p>When there is a large amount of metadata for a document it can make sense to separate
this into a different document altogether, with its own document type.</p>
</div>
</div>
</div>
<div class="section" title="Problem">
<div class="titlepage">
<h3 class="title" id="d55e591">Problem</h3>
</div>
<p>There may a large amount of metadata for a document. If much of this data is required,
it could make the document difficult to author and read.</p>
</div>
<div class="section" title="Context">
<div class="titlepage">
<h3 class="title" id="d55e596">Context</h3>
</div>
<p>There is a large amount of metadata to be associated with the documents. If the
metadata for several documents is the same.</p>
</div>
<div class="section" title="Forces">
<div class="titlepage">
<h3 class="title" id="d55e601">Forces</h3>
</div>
<p>Metadata can add complexity to a document, making it more difficult to author a
document. When processing documents, the metadata may not be needed by some programs.
Having the metadata in the document can increase processing time.</p>
</div>
<div class="section" title="Solution">
<div class="titlepage">
<h3 class="title" id="d55e606">Solution</h3>
</div>
<p>Place the metadata in the separate document. This document should have its own
document type. There is a link placed in the document that refers to the metadata
document.</p>
<p>If the metadata for several documents is the same, this can be a very good pattern to
use. If, for example, a document requires extensive biographical information about its
authors, and several of the documents are by the same author, the single metadata
document can be used to minimize replication and ease maintenance.</p>
<p>External parsed entities parsed entities can be used in a similar way, but the
document type of the original document does not get simplified.</p>
</div>
<div class="section" title="Examples">
<div class="titlepage">
<h3 class="title" id="d55e615">Examples</h3>
</div>
<p>Here is an example that references author information from an external file.</p>
<div class="example">
<a id="d55e620"/>
<p class="title">
<strong>Example 2.1. File: <code class="filename">author-info.xml</code>
</strong>
</p>
<div class="example-contents">
<div class="literallayout">
<p>&lt;Author&gt;<br/>
&lt;Name&gt;Robert Smith&lt;/Name&gt;<br/>
&lt;BirthDate&gt;21-04-1960&lt;/BirthDate&gt;<br/>
&lt;Address&gt;123 Maple Street&lt;/Address&gt;<br/>
&lt;/Author&gt;<br/>
</p>
</div>
</div>
</div>
<br class="example-break"/>
<div class="example">
<a id="d55e627"/>
<p class="title">
<strong>Example 2.2. File: <code class="filename">document.xml</code>
</strong>
</p>
<div class="example-contents">
<div class="literallayout">
<p>
<br/>
&lt;!DOCTYPE DOCUMENT[<br/>
&lt;!ENTITY author-info SYSTEM "author-info.xml"&gt;<br/>
]&gt;<br/>
&lt;Document&gt;<br/>
&lt;Head&gt;<br/>
&amp;author-info;<br/>
&lt;/Head&gt;<br/>
&lt;Body&gt;<br/>
This is the document.<br/>
&lt;/Body&gt;<br/>
&lt;/Document&gt;<br/>
</p>
</div>
</div>
</div>
<br class="example-break"/>
</div>
<div class="section" title="Discussion">
<div class="titlepage">
<h3 class="title" id="d55e634">Discussion</h3>
</div>
<p>This pattern makes the separation between the data and the metadata very clear, very
little confusion can be made between the data and metadata.</p>
<p>The metadata and data can be defined at different times in the development cycle,
allowing for iterative development, or for different authors to work on the data and
metadata at the same time.</p>
<p>By having the metadata in a separate document, many documents can include the metadata
from the same source. In the Example above, if the address of the author had changed,
all of the documents which included this document would be automatically changed as
well.</p>
</div>
<div class="section" title="Related Patterns">
<div class="titlepage">
<h3 class="title" id="d55e643">Related Patterns</h3>
</div>
<p>This is a specialization of both the the Separate Metadata and Data and
patterns.</p>
</div>
<div class="section" title="Known Uses">
<div class="titlepage">
<h3 class="title" id="d55e648">Known Uses</h3>
</div>
<p>…</p>
</div>
<div class="section" title="References">
<div class="titlepage">
<h3 class="title" id="d55e653">References</h3>
</div>
<p>See: The XML &amp; SGML Cookbook page 2–23.</p>
</div>
</div>
<div class="section" title="Separate Metadata and Data">
<div class="titlepage">
<h2 class="title" id="d55e659">Separate Metadata and Data</h2>
<div>
<div class="abstract" title="Abstract">
<p class="title">
<strong>Abstract</strong>
</p>
<p>When documents contain content and data about the content, the two types of data
should be clearly separated.</p>
</div>
</div>
</div>
<div class="section" title="Problem">
<div class="titlepage">
<h3 class="title" id="d55e666">Problem</h3>
</div>
<p>A document contains two distinct types of data, the content of the document, and data
about the content. The data about the content is referred to as metadata. Since a
document contains these two different types of data, it is not always to distinguish
between the two types of data. For example:</p>
<div class="literallayout">
<p>
<br/>
&lt;ArticleSummaries&gt;<br/>
&lt;Author&gt;Phred Smith&lt;/Author&gt;<br/>
&lt;Name&gt;Patterns of Stereo Design&lt;/Name&gt;<br/>
&lt;Author&gt;J.R. Dolby&lt;/Author&gt;<br/>
&lt;Summary&gt;<br/>
Use of patterns to arrange stereo components.<br/>
&lt;/Summary&gt;<br/>
&lt;/ArticleSummary&gt;<br/>
</p>
</div>
<p>Here there are two instances of the Author element, and at first glance it might not
be possible to tell what the first instance of Author represents. Is it the author of
the article being summarized? Is it the author of the article itself? It can be
difficult to distinguish metadata from data.</p>
</div>
<div class="section" title="Context">
<div class="titlepage">
<h3 class="title" id="d55e675">Context</h3>
</div>
<p>Data about the data needs to be included in a document. This could be things like the
author’s name, the creation date, security levels of the data, namespace
information, schema information, or identification attributes for use with cross
references.</p>
</div>
<div class="section" title="Forces">
<div class="titlepage">
<h3 class="title" id="d55e680">Forces</h3>
</div>
<p>A clear separation is needed between what is metadata and what is data that forms the
body of the document. This affects ease of authoring and processing of the document
because the context of the data is clear.</p>
</div>
<div class="section" title="Solution">
<div class="titlepage">
<h3 class="title" id="d55e685">Solution</h3>
</div>
<p>The context of the data and the metadata should be made clear. The metadata should
usually appear before the data that it describes. This makes it clearer what the
metadata is about, and allows processing software to know about the data before it
actually gets the data. For example the size of a table might be considered metadata. If
the processing software gets the size of the table before the actual data, it can layout
the table and then insert the data in the proper place as it encounters it.</p>
</div>
<div class="section" title="Examples">
<div class="titlepage">
<h3 class="title" id="d55e690">Examples</h3>
</div>
<p>See the <a class="link" href="/patterns/metadata/metadata-doc.xml">Metadata in Separate Document</a>, <a class="link" href="/patterns/metadata/head-body.xml">Head-Body pattern</a>s for examples.</p>
</div>
<div class="section" title="Discussion">
<div class="titlepage">
<h3 class="title" id="d55e701">Discussion</h3>
</div>
<p>The resulting context provides structures that clearly identify the metadata as
metadata. Often this pattern introduces new constructs to the document, so the overall
length of the document may be increased. Authors and processing software need to clearly
distinguish between metadata and content. This is not always possible to tell from the
element names or positions. It is better to provide a context that will disambiguate the
types of data. Obviously the first step in using this pattern is to be able to identify
the difference between metadata and data. This is not always an easy task.</p>
</div>
<div class="section" title="Related Patterns">
<div class="titlepage">
<h3 class="title" id="d55e706">Related Patterns</h3>
</div>
<p>
<a class="link" href="/patterns/metadata/metadata-doc.xml">Metadata in Separate Document</a> and <a class="link" href="head-body.xml">Head-Body</a> are specializations of this pattern.</p>
</div>
<div class="section" title="Known Uses">
<div class="titlepage">
<h3 class="title" id="d55e716">Known Uses</h3>
</div>
<p>The W3C Namespace Recommendation includes namespace information in attributes that
make it clearer that this is data about the documents, and not really part of the
document itself.</p>
<p>The XHTML DTD uses Head and Body elements to distinguish the metadata from the
data.</p>
</div>
</div>
</div>
<div class="chapter" title="Chapter 3. Abstraction" id="d55e724">
<div class="titlepage">
<h2 class="title">Chapter 3. Abstraction</h2>
<div>
<div class="abstract" title="Abstract">
<p class="title">
<strong>Abstract</strong>
</p>
<p>What abstractions to create in the document type.</p>
</div>
</div>
</div>
<nav>
<dl class="toc">
<dt>Table of Contents</dt>
<dd>
<ol class="chapter">
<li class="section">
<a href="#d55e732">Choice Reducing Container</a>
<ol>
<li class="section">
<a href="#d55e739">Problem</a>
</li>
<li class="section">
<a href="#d55e744">Context</a>
</li>
<li class="section">
<a href="#d55e749">Forces</a>
</li>
<li class="section">
<a href="#d55e754">Solution</a>
</li>
<li class="section">
<a href="#d55e759">Examples</a>
</li>
<li class="section">
<a href="#d55e776">Discussion</a>
</li>
<li class="section">
<a href="#d55e783">Related Patterns</a>
</li>
<li class="section">
<a href="#d55e790">Known Uses</a>
</li>
<li class="section">
<a href="#d55e795">References</a>
</li>
</ol>
</li>
<li class="section">
<a href="#d55e801">Collection Element</a>
<ol>
<li class="section">
<a href="#d55e808">Problem</a>
</li>
<li class="section">
<a href="#d55e813">Context</a>
</li>
<li class="section">
<a href="#d55e818">Forces</a>
</li>
<li class="section">
<a href="#d55e823">Solution</a>
</li>
<li class="section">
<a href="#d55e828">Examples</a>
</li>
<li class="section">
<a href="#d55e848">Discussion</a>
</li>
<li class="section">
<a href="#d55e857">Related Patterns</a>
</li>
<li class="section">
<a href="#d55e862">Known Uses</a>
</li>
</ol>
</li>
<li class="section">
<a href="#d55e871">Container Element</a>
<ol>
<li class="section">
<a href="#d55e878">Problem</a>
</li>
<li class="section">
<a href="#d55e883">Context</a>
</li>
<li class="section">
<a href="#d55e888">Forces</a>
</li>
<li class="section">
<a href="#d55e893">Solution</a>
</li>
<li class="section">
<a href="#d55e898">Examples</a>
</li>
<li class="section">
<a href="#d55e909">Discussion</a>
</li>
<li class="section">
<a href="#d55e916">Related Patterns</a>
</li>
<li class="section">
<a href="#d55e931">Known Uses</a>
</li>
<li class="section">
<a href="#d55e936">References</a>
</li>
</ol>
</li>
<li class="section">
<a href="#d55e942">Domain Element</a>
<ol>
<li class="section">
<a href="#d55e949">Problem</a>
</li>
<li class="section">
<a href="#d55e954">Context</a>
</li>
<li class="section">
<a href="#d55e959">Forces</a>
</li>
<li class="section">
<a href="#d55e964">Solution</a>
</li>
<li class="section">
<a href="#d55e969">Examples</a>
</li>
<li class="section">
<a href="#d55e976">Discussion</a>
</li>
<li class="section">
<a href="#d55e983">Related Patterns</a>
</li>
<li class="section">
<a href="#d55e988">Known Uses</a>
</li>
</ol>
</li>
<li class="section">
<a href="#d55e998">Optional Container Element</a>
<ol>
<li class="section">
<a href="#d55e1005">Problem</a>
</li>
<li class="section">
<a href="#d55e1010">Context</a>
</li>
<li class="section">
<a href="#d55e1015">Forces</a>
</li>
<li class="section">
<a href="#d55e1020">Solution</a>
</li>
<li class="section">
<a href="#d55e1025">Examples</a>
</li>
<li class="section">
<a href="#d55e1038">Discussion</a>
</li>
<li class="section">
<a href="#d55e1047">Related Patterns</a>
</li>
<li class="section">
<a href="#d55e1052">Known Uses</a>
</li>
<li class="section">
<a href="#d55e1061">Contributions</a>
</li>
</ol>
</li>
</ol>
</dd>
</dl>
</nav>
<div class="section" title="Choice Reducing Container">
<div class="titlepage">
<h2 class="title" id="d55e732">Choice Reducing Container</h2>
<div>
<div class="abstract" title="Abstract">
<p class="title">
<strong>Abstract</strong>
</p>
<p>When creating large DTDs, authors are required to learn a large number of attributes
and elements, and where they can be positioned in order to know how to use the DTD. By
reducing the number of choices that the author has to make at any point in the DTD by
group related elements beneath newly introduced elements, the learning requirements of
the author can be reduced.</p>
</div>
</div>
</div>
<div class="section" title="Problem">
<div class="titlepage">
<h3 class="title" id="d55e739">Problem</h3>
</div>
<p>In a complex DTD with many elements and attributes, a user of a document can be
overwhelmed with the number of choices that have to be made. With many options users
have a difficult time knowing all of the elements available and the order that these
appear in.</p>
</div>
<div class="section" title="Context">
<div class="titlepage">
<h3 class="title" id="d55e744">Context</h3>
</div>
<p>In large, general-purpose DTDs where many logical units are presented, and the
documents are expected to be authored by humans.</p>
</div>
<div class="section" title="Forces">
<div class="titlepage">
<h3 class="title" id="d55e749">Forces</h3>
</div>
<p>When the underlying order of the data to be represented, or to make DTDs applicable in
many situations, large numbers of logical units need to appear in the DTD. However,
presenting large numbers of attributes and elements makes the DTD more difficult to
learn by authors of documents.</p>
</div>
<div class="section" title="Solution">
<div class="titlepage">
<h3 class="title" id="d55e754">Solution</h3>
</div>
<p>Present only a limited number of choices to the author at any point within the
document. If the author has the choice of insert 100 different elements at some point in
the document, it can be difficult to know how to proceed. By grouping elements into
related sets, the number choices to be made at any one point can be reduced. The author
has to choose between only a few higher level groups instead of many more detailed
elements.</p>
</div>
<div class="section" title="Examples">
<div class="titlepage">
<h3 class="title" id="d55e759">Examples</h3>
</div>
<div class="example">
<a id="d55e762"/>
<p class="title">
<strong>Example 3.1. Example</strong>
</p>
<div class="example-contents">
<p>Here is a DTD that presents several choices to the author:</p>
<div class="literallayout">
<p>
<br/>
&lt;!ELEMENT Doc<br/>
( Para<br/>
| OrderedList<br/>
| UnorderedList<br/>
| Figure<br/>
| Artwork )+&gt;</p>
</div>
</div>
</div>
<br class="example-break"/>
<div class="example">
<a id="d55e769"/>
<p class="title">
<strong>Example 3.2. Example</strong>
</p>
<div class="example-contents">
<p>The author here is present with a choice of 5 different elements to choose from
after creating the Doc element. This choice could be limited by introducing new
elements and grouping some of the existing elements together as children of the new
elements like this:</p>
<div class="literallayout">
<p>
<br/>
&lt;!ELEMENT Doc (Para | List | Illustration )+)&gt;<br/>
&lt;!ELEMENT List (OrderedList | UnorderedList )&gt;<br/>
&lt;!ELEMENT Illustration (Figure | Artwork )&gt;<br/>
                </p>
</div>
</div>
</div>
<br class="example-break"/>
</div>
<div class="section" title="Discussion">
<div class="titlepage">
<h3 class="title" id="d55e776">Discussion</h3>
</div>
<p>Once the Choice Reducing Pattern is applied, the learning requirements placed on the
author of documents is reduced. Application of this pattern can however lead to an
increase in the overall number of element types in the DTD. The number of elements in
the above example went from 6 to 8 when the Group Choice pattern was applied. This can
make the overall complexity of the DTD higher. It can also increase the size of
documents.</p>
<p>The Choice Reducing Pattern hides choices from the authors of documents by introducing
new elements that hide the details of a piece of the document that the author might not
care about at that point in time. By introducing a single higher level element, the
number of choices the author needs to make is lower, thereby reducing the learning
requirements of the author.</p>
</div>
<div class="section" title="Related Patterns">
<div class="titlepage">
<h3 class="title" id="d55e783">Related Patterns</h3>
</div>
<p>This Choice Reducing Container is similar to the Optional Container Element in that
they both try to make the DTD easier to use by the author by introducing new element
types. Existing elements are grouped together as children of the new element. One
difference between the two is the context they are used in. The Choice Reducing
Container relates elements that are all choices in a content group while the Optional
Container Element relates optional elements from the content group.</p>
<p>The motivation for the two is also different. In the Choice Reducing Container, the
amount of information at any one point is reduced, but it is not intended to reduce the
overall complexity of the document for a single author. The Optional Container Element
hides parts of the structure permanently from the view of individual authors. It is
likely that some authors will never use certain parts of large DTDs.</p>
</div>
<div class="section" title="Known Uses">
<div class="titlepage">
<h3 class="title" id="d55e790">Known Uses</h3>
</div>
<p>…</p>
</div>
<div class="section" title="References">
<div class="titlepage">
<h3 class="title" id="d55e795">References</h3>
</div>
<p>See Structuring XML Documents, Section 4.2.1 - Limiting Choices.</p>
</div>
</div>
<div class="section" title="Collection Element">
<div class="titlepage">
<h2 class="title" id="d55e801">Collection Element</h2>
<div>
<div class="abstract" title="Abstract">
<p class="title">
<strong>Abstract</strong>
</p>
<p>Create a new element whose content model allows only instances of a single element
type.</p>
</div>
</div>
</div>
<div class="section" title="Problem">
<div class="titlepage">
<h3 class="title" id="d55e808">Problem</h3>
</div>
<p>There is an element that needs to be repeated several times at the same level of a
documents.</p>
</div>
<div class="section" title="Context">
<div class="titlepage">
<h3 class="title" id="d55e813">Context</h3>
</div>
<p>Multiple elements of the same element type need to appear in the document as siblings
of each other. Often metadata about the container needs to be expressed as well. The
Collection Element is a logical place to put this metadata. Sometimes, the elements need
to be grouped into different categories. Multiple Collection Elements can appear in the
document, with each container having elements from one of the sub categories.</p>
</div>
<div class="section" title="Forces">
<div class="titlepage">
<h3 class="title" id="d55e818">Forces</h3>
</div>
<p>Groups of identical repeated elements often need some context established so that
metadata can be associated with the entire group, or to distinguish between different
groups of similar elements.</p>
</div>
<div class="section" title="Solution">
<div class="titlepage">
<h3 class="title" id="d55e823">Solution</h3>
</div>
<p>Create a new element type that contains the multiple elements of the same type. The
Collection Element is often named by putting a descriptive ending on the contained
element name. For example, a Collection Element of authors might be called AuthorList or
AuthorGroup. Another way of naming the Collection Element is to pluralize the contained
element name. For example, a collection of Stock elements would be named Stocks.</p>
</div>
<div class="section" title="Examples">
<div class="titlepage">
<h3 class="title" id="d55e828">Examples</h3>
</div>
<div class="example">
<a id="d55e831"/>
<p class="title">
<strong>Example 3.3. Simple Collection Element</strong>
</p>
<div class="example-contents">
<div class="literallayout">
<p>
<br/>
                    &lt;Portfolio&gt;<br/>
                    &lt;StockList&gt;<br/>
                    &lt;Stock&gt;<br/>
                    &lt;Name&gt;IBM&lt;/Name&gt;<br/>
                    &lt;Price&gt;110.25&lt;/Price&gt;<br/>
                    &lt;/Stock&gt;<br/>
                    &lt;Stock&gt;<br/>
                    &lt;Name&gt;MSFT&lt;/Name&gt;<br/>
                    &lt;Price&gt;89.50&lt;/Price&gt;<br/>
                    &lt;/Stock