1. 1 Implementing Variable Content Containers XML Schemas: Best Practices A set of guidelines for designing XML Schemas Created by discussions on xml-dev

2. 2 Issue What are the methods for designing an element which is to be comprised of variable content? - variable content section - or or... Catalogue is called a variable content container

3. 3 4 Methods There are 4 methods for implementing variable content containers: –Method 1: use an abstract element and element substitution –Method 2: use a element –Method 3: use an abstract type and type substitution –-Method 4: use a dangling type In the following slides each method will be described, along with its advantages and disadvantages

4. 4 Method 1 - use an Abstract Element and Element Substitution - variable content section Publication (abstract) substitutionGroup "substitutable for"

5. 5 Method 1 - use an Abstract Element and Element Substitution In the Schema: –Declare Catalogue to be comprised of Publication, where Publication is declared abstract –Declare Book and Magazine to be in a substitutionGroup with Publication In an Instance Document: –The contents of can be any element that is in the substitutionGroup

6. 6 Method 1 - use an Abstract Element and Element Substitution

7. 7 PublicationType BookTypeMagazineType In order for Book and Magazine to be in a substitutionGroup with Publication, their type (BookType and MagazineType, respectively) must be the same as, or derived from Publication's type (PublicationType)

8. 8

9. 9 <Catalogue xmlns="http://www.catalogue.org" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation= "http://www.catalogue.org Catalogue.xsd"> Illusions The Adventures of a Reluctant Messiah Richard Bach 1977 0-440-34319-4 Dell Publishing Co. Natural Health 1999 The First and Last Freedom J. Krishnamurti 1954 0-06-064831-7 Harper & Row Do Lab1

10. 10 Method 1 Advantages - Extensibility Extensible: other schemas can extend the set of elements that may occur in the variable content container CD.xsd Now the variable content container may contain or

11. 11 Method 1 Advantages - Extensibility Note how the CD schema extended the Catalogue schema, without modifying it! Oftentimes you would like to extend a schema, but it is read-only (under someone else's control). With this technique you are able to extend a read-only schema!

12. 12 <Catalogue xmlns="http://www.catalogue.org" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation= "http://www.catalogue.org CD.xsd"> Illusions The Adventures of a Reluctant Messiah Richard Bach 1977 0-440-34319-4 Dell Publishing Co. Timeless Serenity Dyveke Spino 1984 Dyveke Spino Productions Natural Health 1999 The First and Last Freedom J. Krishnamurti 1954 0-06-064831-7 Harper & Row

13. 13 Method 1 Advantages - Semantic Cohesion All the elements that may occur in the variable content container must have a type that derives from the abstract element's type. Thus, the elements have a type hierarchy to bind them together, to provide structural (and, by implication, semantic) coherence among the elements.

14. 14 Method 1 Disadvantages - No Independent Elements The variable content container cannot contain elements whose type does not derive from the abstract element's type, or is not in a substitutionGroup with the abstract element - as would typically be the case with independently developed elements.

15. 15 Method 1 Disadvantages - Limited Structural Variability Over time a schema will evolve, and the kinds of elements which may occur in the variable content container will typically grow. There is no way to know in what direction it will grow. The new elements may be conceptually related but structurally vastly different from the original set of elements. The abstract element's type (e.g., PublicationType) may have been a good base type for the original set of elements which were all structurally related, but may not be a good base type for the new elements which have vastly different structures. So you are faced with a tradeoff - –create a simple base type to support lots of different structures (but then you can make less assumptions about the structure of the members), or –create a rich base type to support strong data type checking (but then you reduce the ability to add elements with radically different types)

16. 16 Method 1 Disadvantages - Nonscalable Processing Suppose that Catalogue is declared to contain two abstract elements - Publication and Retailer, and there can be multiple occurrences of each. Here's a sample instance document: … How would you write, say, a stylesheet to process all the Publication elements?

17. 17 Method 1 Disadvantages - Nonscalable Processing Answer: you would need to write special-case code: - process Book - process Magazine This is not scalable. Each time a new element is added to Publication's substitutionGroup (e.g., CD), the stylesheet breaks (i.e., needs to be updated)

18. 18 Method 1 Disadvantages - No Control over Namespace Exposure A requirement of using substitutionGroup is that all elements in a substitutionGroup must be declared globally. As a consequence, there is no way to hide (localize) the namespaces of the elements in the variable content container. This fails the Best Practice guideline which states that you should design your schema to be able to turn namespace exposure on/off using elementFormDefault as a namespace switch.

19. 19 Method 2 - use a Element - variable content section

20. 20 Method 2 - use a Element Do Lab2

21. 21 Method 2 Advantages - Independent Elements The elements in the variable content container do not need a common type ancestry. Thus, the variable content container can contain dissimilar, independent, loosely coupled elements.

22. 22 Method 2 Disadvantages - Nonextensible This method requires that the contents of the element be modified to include additional elements. However, the schema may be outside your control (read- only), so you may not be able to get it extended to include your additional elements. Thus, this method has serious extensibility restrictions!

23. 23 Method 2 Disadvantages - No Semantic Coherence The element allows you to group together dissimilar elements. The elements in the variable choice container have no type hierarchy to bind them together, to provide structural (and, by implication, semantic) coherence among the elements. Thus, you can make no assumptions about the structure of the elements.

24. 24 Method 3 - use an Abstract Type and Type Substitution - variable content section PublicationType (abstract) BookType MagazineType

25. 25 Method 3 - use an Abstract Type and Type Substitution In the Schema: –Declare Catalogue to be comprised of Publication, where Publication is declared to be of type PublicationType, which is abstract –Declare BookType and MagazineType to derive from PublicationType In an Instance Document: –The contents of will be, and its content can be any type that derives from PublicationType

26. 26......... <xsd:element name="Publication" type="PublicationType" maxOccurs="unbounded"/>

27. 27 <Catalogue xmlns="http://www.catalogue.org" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation= "http://www.catalogue.org Catalogue.xsd"> Illusions The Adventures of a Reluctant Messiah Richard Bach 1977 0-440-34319-4 Dell Publishing Co. Natural Health 1999 The First and Last Freedom J. Krishnamurti 1954 0-06-064831-7 Harper & Row Do Lab3

28. 28 Method 3 Advantages - Extensibility Extensible: other schemas can extend the set of elements that may occur in the variable content container CD.xsd Now the content of may be BookType, or MagazineType, or CDType

29. 29 <Catalogue xmlns="http://www.catalogue.org" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation= "http://www.catalogue.org CD.xsd"> Illusions The Adventures of a Reluctant Messiah Richard Bach 1977 0-440-34319-4 Dell Publishing Co. Timeless Serenity Dyveke Spino 1984 Dyveke Spino Productions Natural Health 1999 The First and Last Freedom J. Krishnamurti 1954 0-06-064831-7 Harper & Row

30. 30 Method 3 Advantages - Minimal Dependencies In Method 1 to extend the variable content container you need access to both the abstract element (Publication) and its type (PublicationType). With method 3 you only need access to the abstract type. Thus, to extend a schema there are fewer dependencies

31. 31 Method 3 Advantages - Uniform, Scalable Processing With this method instance documents will look different than we saw with the other two methods. Namely, will not contain variable content. Instead, it will always contain the same element (Publication). However, that element will contain variable content:... The contents of Catalogue can be uniformly processed, even as new types (e.g, CDType) are added. For example, a stylesheet could process each Publication element as follows: -- do something --

32. 32 Method 3 Advantages - Semantic Cohesion All the elements that may occur in the variable content container must have types that derive from the abstract type. Thus, the elements have a type hierarchy to bind them together, to provide structural (and, by implication, semantic) coherence among the elements.

33. 33 Method 3 Advantages - Control over Namespace Exposure Recall that the key to controlling namespace exposure is to embed the elements within type definitions. That's exactly what this method does. Consequently, we can control exposure of the namespace of the elements using elementFormDefault. This is consistent with the Best Practice design recommendation we issued for hide (localize) versus expose namespaces.

34. 34 Method 3 Disadvantages - No Independent Elements The variable content container cannot contain elements whose type does not derive from the abstract type - as would typically be the case with independently developed elements.

35. 35 Method 3 Disadvantages - Limited Structural Variability Over time the kinds of elements which may occur in the variable content container will typically grow. There is no way to know in what direction it will grow. The new elements may be conceptually related but structurally vastly different from the original set of elements. The abstract type (e.g., PublicationType) may have been a good base type for the original set of elements which were all structurally related, but may not be a good base type for the new elements which have vastly different structures. So you are faced with a tradeoff: –create a simple base type to support lots of different structures (but then you can make less assumptions about the structure of the members), or –create a rich base type to support strong data type checking (but then you reduce the ability to add elements with radically different types)

36. 36 Method 4 - Motivation Thus far our variable content container has always contained complex content (i.e., child elements). Suppose that we want to create a variable content container to hold simple content? None of the previous methods can be used. We need a method that allows us to create simpleType variable content containers.

37. 37 Method 4 - Motivation Problem: Suppose that we have an element, sensor, which contains the name of a weather station sensor. For example: Barometric Pressure Several things to note: 1. This element holds a simpleType. 2. Each weather station may have sensors that are unique to it. Consequently, we must design our schema so that the sensor element can be customized by each weather station.

38. 38 Method 4 - use a Dangling Type Here's the method - when you create sensor, declare it to be of a type from another namespace. Then, for the element don't provide a schemaLocation (schemaLocation is optional with the import element). Thus, the element is declared to be of a type, for which no particular schema is identified, i.e., we have a dangling type definition!

39. 39 Method 4 - use a Dangling Type In your schema, declare the sensor element: Note that I declared the sensor element to have a type "sensor_type", which is in a different namespace - the sensor namespace: xmlns:s="http://www.sensor.org" Now here's the key - when you this namespace, don't provide a value for schemaLocation! For example:

40. 40 Method 4 - use a Dangling Type The instance document must then identify a schema that implements sensor_type. Thus, at run time (validation time) we are matching up the reference to sensor_type with the implementation of sensor_type. For example, an instance document may have this: xsi:schemaLocation= "http://www.weather-station.org weather-station.xsd http://www.sensor.org boston-sensors.xsd" In this instance document schemaLocation is identifying a schema, boston-sensors.xsd, which provides an implementation of sensor_type.

41. 41 <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" targetNamespace="http://www.weather-station.org" xmlns="http://www.weather-station.org" xmlns:s="http://www.sensor.org" elementFormDefault="qualified"> <xsd:element name="sensor" type="s:sensor_type" maxOccurs="unbounded"/> weather-station.xsd An import with no schemaLocation! sensor is the variable content container. It contains a sensor_type for which no schema has been indicated! It is a dangling type!

42. 42 <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" targetNamespace="http://www.sensor.org" xmlns="http://www.sensor.org" elementFormDefault="qualified"> boston-sensors.xsd This schema provides an implementation for the dangling type, sensor_type.

43. 43 <weather-station xmlns="http://www.weather-station.org" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation= "http://www.weather-station.org weather-station.xsd http://www.sensor.org boston-sensors.xsd"> thermometer barometer anenometer boston-weather-station.xml In the instance document we provide a schema which implements the dangling type.

44. 44 <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" targetNamespace="http://www.sensor.org" xmlns="http://www.sensor.org" elementFormDefault="qualified"> london-sensors.xsd This schema provides a different implementation for the dangling type, sensor_type.

45. 45 <weather-station xmlns="http://www.weather-station.org" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation= "http://www.weather-station.org weather-station.xsd http://www.sensor.org london-sensors.xsd"> thermometer barometer hygrometer anenometer london-weather-station.xml The London weather station is able to customize the content of by using london-sensors.xsd, which defines sensor_type appropriately for the London weather station. Wow!

46. 46 Method 4 - Summary Summary: The key to this design pattern is: 1. When you declare the variable content container element give it a type that is in another namespace, e.g., s:sensor_type 2. When you that namespace don't provide a value for schemaLocation, e.g., 3. Create any number of implementations of the type: - boston-sensors.xsd - london-sensors.xsd 4. In instance documents identify the schema that shall be used to implement the type, e.g., xsi:schemaLocation= "http://www.weather-station.org weather-station.xsd ----> http://www.sensor.org london-sensors.xsd"

47. 47 Method 4 - Note In the previous example the implementation of the dangling type (sensor_type) was a simpleType. It need not be a simpleType. It could be a complexType. Thus, this method can be used to create variable content containers which are either complex or simple.

48. 48 Method 4 Advantages - Dynamic A schema which contains a dangling type is very dynamic. It does not statically hard- code the identity of a schema to implement the type. Rather, it empowers the instance document author to identify a schema that implements the dangling type. Thus, at instance-document-creation the dangling type implementation is provided (rather than at schema-document-creation)

49. 49 Method 4 Advantages - Both for Simple and Complex Variable Content Containers A dangling type can be implemented using either a simpleType or a complexType. The other methods are only applicable to creating variable content containers with a complex type.

50. 50 Method 4 Disadvantages - Must be in Another Namespace The implementation of the dangling type must be in another namespace. It cannot be in the same namespace as the variable content container element. None of the schema validators implement dangling types (yet). The best that you can do today is "fake it" with anyType (see next slides)

51. 51 <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" targetNamespace="http://www.weather-station.org" xmlns="http://www.weather-station.org" xmlns:s="http://www.sensor.org" elementFormDefault="qualified"> <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" targetNamespace="http://www.weather-station.org" xmlns="http://www.weather-station.org" xmlns:s="http://www.sensor.org" elementFormDefault="qualified"> Instead of these... Use this. Cont. -->

52. 52 Do Lab4 <weather-station xmlns="http://www.weather-station.org" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation= "http://www.weather-station.org weather-station.xsd http://www.sensor.org boston-sensors.xsd"> thermometer barometer anenometer <weather-station xmlns="http://www.weather-station.org" xmlns:s="http://www.sensor.org" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation= "http://www.weather-station.org weather-station-using-anyType.xsd http://www.sensor.org boston-sensors.xsd"> thermometer barometer anenometer Instead of this... Use this (specify the type explicitly)

53. 53 Best Practice If you have a hard requirement for independent, dissimilar elements then you have no choice but to use Method 2 ( element) If you have a hard requirement for a variable content container which contains simple content then you have no choice but to use Method 4 (dangling types) In all other cases, the combination of method 4 and method 3 (that is, use a dangling type, but provide an implementation of the dangling type which uses method 3) provides the most flexibility.