Design issues in XML formats

Size: px

Start display at page:

Download "Design issues in XML formats"

Ilene Peters
5 years ago
Views:

1 Design issues in XML formats David Mertz, Ph.D. Gesticulator, Gnosis Software, Inc. 1 November 2001 In this tip, developerworks columnist David Mertz advises when to use tag attributes and when to use subelement contents to represent data. Learn what considerations go into designing a DTD, Schema, or just an ad hoc XML format. You'll also learn when attributes and contents are interchangeable, and when they aren't. Code samples show the options. An odd thing about XML is that it provides two almost, but not quite, equivalent ways of spelling "this is the data." One way to indicate a data value is to put it inside a subelement; another way is to put it in attribute values. Because there usually isn't an obvious answer for when of each of the two approaches is appropriate, XML is not entirely orthogonal (which is computer science speak for "each construct does one thing, and no other construct does the same thing"). This tip offers some guidance for when to use subelements and when to use attributes. One time when you do not need to decide what data goes where is when you are handed an XML dialect specification to follow -- given to you as a DTD or as a W3C XML Schema, or described informally or by example. If you are not making the choices, don't worry about the suggestions in this tip. Often, though, developers need to design the exact XML dialect to use for a process. If that's your case, read on. One thing to keep in mind is the difference between XML documents that merely need to be well formed, and those that need to be valid relative to some DTD/Schema. Validity is much more rigorous; it allows you to insist that certain data be present and be structured in a certain way. For the very same reason, it is much more work to make sure a given document production process conforms with validity requirements. Both approaches have advantages; imposing a DTD adds complexity to the element/attribute issue, but there are tradeoffs in both cases. These tradeoffs are discussed below. Is data order important? If you want to use a DTD, subelements are strictly ordered, while attributes are unordered. In well-formed-only XML documents, you are free to play with order; after all, in this case any tag can go inside any other tag, at any depth. In both cases, attributes are usually better for unordered data. For XML documents with a DTD, however, use of attributes is almost required for this type of data For example, you might have a list of contacts, each of whom must have a name, age, and telephone number. But there is no logical sense in which age precedes telephone 1

2 number. The attributes are thus unordered. In this case, attributes are more intuitive. Compare the brief XML documents in listings 1 and 2: Listing 1. Attribute data for contacts <?xml version="1.0"?> <!DOCTYPE contacts SYSTEM "attrs.dtd" > <contacts> <contact name="jane Doe" age="74" telephone=" " /> <contact name="chieu Win" telephone=" " age="44" /> </contacts> Listing 2. Subelement data for contacts <?xml version="1.0"?> <!DOCTYPE contacts SYSTEM "subelem.dtd" > <contacts> <contact> <name>jane Doe</name> <age>74</age> <telephone> </telephone> </contact> <contact> <name>chieu Win</name> <telephone> </telephone> <age>44</age> </contact> </contacts> Imagine the DTD that is implied by each XML format. For the attribute-oriented form in Listing 1, it might look like Listing 3. Listing 3. Attribute DTD for contacts document <!ELEMENT contacts (contact*)> <!ELEMENT contact EMPTY> <!ATTLIST contact name CDATA #REQUIRED age CDATA #REQUIRED telephone CDATA #REQUIRED > A subelement-oriented DTD to do the same thing could look like Listing 4. 2

3 Listing 4. Subelement DTD for contacts document <!ELEMENT contacts (contact*)> <!ELEMENT contact (name,age,telephone)> <!ELEMENT name (#PCDATA)> <!ELEMENT age (#PCDATA)> <!ELEMENT telephone (#PCDATA)> The obvious problem with the DTD in Listing 4 is that the simple example in Listing 2 is invalid under the DTD (even though it has the data we want). The subelements are out of order. The sidebar shows how you can use unordered subelements with a DTD, but unless there is a different compelling reason, it is better to use the attribute-style for unordered data. Does multiple data occur at the same level? If the same type of data occurs many times within an object, subelements win, hands down. For example, in the contact list scenario, a contacts object contains many contact objects. In this case, it is clear that each contact should be described within a child element of the contacts element. In real life, however, developers often creep away from this design principle in the course of making revisions. Here is how it happens: First, you find that each Flazbar has a flizbam attached to it (and a flizbam is described by a datum). Good enough, it seems like an obvious choice to save the extra verbosity of a subelement and create a flizbam attribute for the Flazbar tag. A while down the road -- after you have written wonderful production code for handling Flazbars -- you discover that in some situations a Flazbar can have two flizbams. Not a problem: with very little change to your installed code, you just change the DTD to contain: <!ATTLIST Flazbar flizbam CDATA #REQUIRED flizbam2 CDATA #IMPLIED> With the amended code, your old XML documents are still valid, but new ones work also. After a while you discover the third flizbam... It's hard to avoid being tempted into this design pitfall. Data and objects evolve over time, and singular things frequently become dual or multiple. Some XML programmers eschew attributes altogether for this reason, but I think that goes too far. My advice is to think carefully at the design stage about whether a singular datum might have siblings later on. If there is a reasonable probability of multiple siblings in the future, use subelements from the start. If you can be reasonably confident that a data object will remain unique, stick with attributes. 3

4 Is whitespace preservation required? After normalization of attributes, you can count on every token in an attribute being separated from its neighbors by whitespace. But that's all you can count on. For readability by developers, you can add vertical and horizontal whitespace to long attribute values without any problem (in fact, you should do this). But once those readable attributes go through an XML parser, the layout of the attribute will probably be somewhat different than in the source XML. If whitespace is important, subelements are a better choice. For instance, if you are representing something like source code or poetry, where exact spacing matters, stick to element contents. Does readability count? Ideally, XML should be a format computers read, not one humans read. But, fortunately or unfortunately, programmers are humans too; and for the foreseeable future, we are going to spend a lot of time reading, writing, and debugging XML files. It is positively painful to read XML that is formatted with only machines in mind (no whitespace, or nonsensical whitespace). Personally, I find it much easier to read and write attributeoriented XML formats than subelement-oriented ones. Look again at Listing 1 and Listing 2 above to see what I mean. Neither is horrible to read, but the attribute version in Listing 2 is easier -- and better still to write, because you do not need to worry about capricious subelement ordering. Conclusion I have pointed to some cases where subelements or attributes are more desirable. Keeping in mind the principles addressed can lead to clearer and cleaner XML document formats. Unfortunately, sometimes the real situation falls into multiple cases (pointing in opposite directions). And a lot of times, data designs change enough to invalidate previous motivations. Use the rules given in this tip where possible, but above all "use (informed) common sense." Resources Simulating unordered subelements You could create a DTD that makes the XML document in Listing 2 valid by including the definition, as in this listing. A DTD that defines contact list subelements very flexibly However, the DTD above allows far too much flexibility. You could have contact elements with no name, and ones with several ages -- neither of which meets the semantic requirements. To get what we really want would require the extremely cumbersome definition below. A cumbersome but accurate DTD for contact list elements This DTD is ugly, and it gets uglier at a factorial rate with more data points. Plus, making a DTD stricter than is semantically necessary for data producers is also undesirable (for example, imposing the first subelement DTD). Everything you really need to know about XML is in the Extensible Markup Language (XML) 1.0 W3C Recommendation. Of course, understanding exactly what this signifies requires some subtlety. The XML Cover Pages has some tips on Using elements and attributes. That page also contain pointers to a number of articles, each giving contrary advice about what criteria to use in deciding between attributes and elements. That is 4

5 why we programmers get paid the big bucks! One way to view the distinction between attributes and elements is in terms of "Document-Centric" vs. "Data-Centric" documents. Check out other XML tips published in the developerworks XML zone. About the author David Mertz uses a wholly unstructured brain to write about structured document formats. David may be reached at mertz@gnosis.cx; his life pored over at 5

Introduction Syntax and Usage XML Databases Java Tutorial XML. November 5, 2008 XML

Introduction Syntax and Usage Databases Java Tutorial November 5, 2008 Introduction Syntax and Usage Databases Java Tutorial Outline 1 Introduction 2 Syntax and Usage Syntax Well Formed and Valid Displaying