Designing an XML Data Structure

This section covers some heuristics you can use when making XML design decisions.

Saving Yourself Some Work

Whenever possible, use an existing schema definition. It's usually a lot easier to ignore the things you don't need than to design your own from scratch. In addition, using a standard DTD makes data interchange possible, and may make it possible to use data-aware tools developed by others.

So if an industry standard exists, consider referencing that DTD by using an external parameter entity. One place to look for industry-standard DTDs is at the Web site created by the Organization for the Advancement of Structured Information Standards (OASIS). You can find a list of technical committees at http://www.oasis-open.org/ or check its repository of XML standards at http://www.XML.org.

Attributes and Elements

One of the issues you will encounter frequently when designing an XML structure is whether to model a given data item as a subelement or as an attribute of an existing element. For example, you can model the title of a slide this way:

In some cases, the different characteristics of attributes and elements make it easy to choose. Let's consider those cases first and then move on to the cases where the choice is more ambiguous.

Forced Choices

Sometimes, the choice between an attribute and an element is forced on you by the nature of attributes and elements. Let's look at a few of those considerations:

The data contains substructures: In this case, the data item must be modeled as an element. It can't be modeled as an attribute, because attributes take only simple strings. So if the title can contain emphasized text (The <em>Best</em> Choice) then the title must be an element.

The data contains multiple lines: Here, it also makes sense to use an element. Attributes need to be simple, short strings or else they become unreadable, if not unusable.

Multiple occurrences are possible: Whenever an item can occur multiple times, such as paragraphs in an article, it must be modeled as an element. The element that contains it can have only one attribute of a particular kind, but it can have many subelements of the same type.

The data changes frequently: When the data will be frequently modified with an editor, it may make sense to model it as an element. Many XML-aware editors make it easy to modify element data, whereas attributes can be somewhat harder to get to.

The data is a small, simple string that rarely if ever changes: This is data that can be modeled as an attribute. However, just because you can does not mean that you should. Check the Stylistic Choices section next, to be sure.

The data is confined to a small number of fixed choices: If you are using a DTD, it really makes sense to use an attribute. A DTD can prevent an attribute from taking on any value that is not in the preapproved list, but it cannot similarly restrict an element. (With a schema, on the other hand, both attributes and elements can be restricted, so you could use either element or an attribute.)

Stylistic Choices

As often as not, the choices are not as cut-and-dried as those just shown. When the choice is not forced, you need a sense of "style" to guide your thinking. The question to answer, then, is what makes good XML style, and why.

Defining a sense of style for XML is, unfortunately, as nebulous a business as defining style when it comes to art or music. There are, however, a few ways to approach it. The goal of this section is to give you some useful thoughts on the subject of XML style.

One heuristic for thinking about XML elements and attributes uses the concept of visibility. If the data is intended to be shown--to be displayed to an end user--then it should be modeled as an element. On the other hand, if the information guides XML processing but is never seen by a user, then it may be better to model it as an attribute. For example, in order-entry data for shoes, shoe size would definitely be an element. On the other hand, a manufacturer's code number would be reasonably modeled as an attribute.

Another way of thinking about the visibility heuristic is to ask, who is the consumer and the provider of the information? The shoe size is entered by a human sales clerk, so it's an element. The manufacturer's code number for a given shoe model, on the other hand, may be wired into the application or stored in a database, so that would be an attribute. (If it were entered by the clerk, though, it should perhaps be an element.)

Perhaps the best way of thinking about elements and attributes is to think of an element as a container. To reason by analogy, the contents of the container (water or milk) correspond to XML data modeled as elements. Such data is essentially variable. On the other hand, the characteristics of the container (whether a blue or a white pitcher) can be modeled as attributes. That kind of information tends to be more immutable. Good XML style separates each container's contents from its characteristics in a consistent way.

To show these heuristics at work, in our slide-show example the type of the slide (executive or technical) is best modeled as an attribute. It is a characteristic of the slide that lets it be selected or rejected for a particular audience. The title of the slide, on the other hand, is part of its contents. The visibility heuristic is also satisfied here. When the slide is displayed, the title is shown but the type of the slide isn't. Finally, in this example, the consumer of the title information is the presentation audience, whereas the consumer of the type information is the presentation program.

Normalizing Data

In Saving Yourself Some Work, you saw that it is a good idea to define an external entity that you can reference in an XML document. Such an entity has all the advantages of a modularized routine: changing that one copy affects every document that references it. The process of eliminating redundancies is known as normalizing, and defining entities is one good way to normalize your data.

In an HTML file, the only way to achieve that kind of modularity is to use HTML links, but then the document is fragmented rather than whole. XML entities, on the other hand, suffer no such fragmentation. The entity reference acts like a macro: the entity's contents are expanded in place, producing a whole document rather than a fragmented one. And when the entity is defined in an external file, multiple documents can reference it.

The considerations for defining an entity reference, then, are pretty much the same as those you would apply to modularized program code:

Whenever you find yourself writing the same thing more than once, think entity. That lets you write it in one place and reference it in multiple places.

If the information is likely to change, especially if it is used in more than one place, definitely think in terms of defining an entity. An example is defining productName as an entity so that you can easily change the documents when the product name changes.

If the entity will never be referenced anywhere except in the current file, define it in the local subset of the document's DTD, much as you would define a method or inner class in a program.

If the entity will be referenced from multiple documents, define it as an external entity, in the same way that you would define any generally usable class as an external class.

External entities produce modular XML that is smaller, easier to update, and easier to maintain. They can also make the resulting document somewhat more difficult to visualize, much as a good object-oriented design can be easy to change, after you understand it, but harder to wrap your head around at first.

You can also go overboard with entities. At an extreme, you could make an entity reference for the word the. It wouldn't buy you much, but you could do it.

Note: The larger an entity is, the more likely it is that changing it will have the expected effect. For example, when you define an external entity that covers a whole section of a document, such as installation instructions, then any changes you make will likely work out fine wherever that section is used. But small inline substitutions can be more problematic. For example, if productName is defined as an entity and if the name changes to a different part of speech, the results can be unfortunate. Suppose the product name is something like HtmlEdit. That's a verb. So you write a sentence like, "You can HtmlEdit your file...", using the productName entity. That sentence works, because a verb fits in that context. But if the name is eventually changed to "HtmlEditor", the sentence becomes "You can HtmlEditor your file...", which clearly doesn't work. Still, even if such simple substitutions can sometimes get you into trouble, they also have the potential to save a lot of time. (One way to avoid the problem would be to set up entities named productNoun, productVerb, productAdj, and productAdverb.)

Normalizing DTDs

Just as you can normalize your XML document, you can also normalize your DTD declarations by factoring out common pieces and referencing them with a parameter entity. Factoring out the DTDs (also known as modularizing) gives the same advantages and disadvantages as normalized XML--easier to change, somewhat more difficult to follow.

You can also set up conditionalized DTDs. If the number and size of the conditional sections are small relative to the size of the DTD as a whole, conditionalizing can let you single-source the same DTD for multiple purposes. If the number of conditional sections gets large, though, the result can be a complex document that is difficult to edit.

Summary

Congratulations! You have now created a number of XML files that you can use for testing purposes. Table 2-5 describes the files you have constructed.

Table 2-5 Listing of Sample XML Files
File	Contents
slideSample01.xml	A basic file containing a few elements and attributes as well as comments.
slideSample02.xml	Includes a processing instruction.
SlideSampleBad1.xml	A file that is not well formed.
slideSample03.xml	Includes a simple entity reference (`<`).
slideSample04.xml	Contains a `CDATA` section.
slideSample05.xml	References either a simple external DTD for elements (`slideshow1a.dtd`) for use with a nonvalidating parser, or else a DTD that defines attributes (`slideshow1b.dtd`) for use with a validating parser.
slideSample06.xml	Defines two entities locally (`product` and `products`) and references `slideshow1b.dtd`.
slideSample07.xml	References an external entity defined locally (`copyright.xml`) and references `slideshow1b.dtd`.
slideSample08.xml	References `xhtml.dtd` using a parameter entity in `slideshow2.dtd`, producing a naming conflict because `title` is declared in both.
slideSample09.xml	Changes the `title` element to `slide-title` so that it can reference `xhtml.dtd` using a parameter entity in `slideshow3.dtd` without conflict.