Extending XML Schemas XML Schemas: Best Practices A set of guidelines for designing XML Schemas Created by discussions on xml-dev

Not “All Powerful” XML Schemas is very powerful However, it is not "all powerful". There are many constraints that it cannot express. Here are some examples: –Ensure that the value of the aircraft element is greater than the value of the obstacle element. –Ensure that: if the value of the attribute, mode, is "air", then the value of the element,, is either airplane or hot-air balloon if mode="water" then is either boat or hovercraft if mode="ground" then is either car or bicycle. –Ensure that the value of the is equal to the value of, where these elements are in separate documents! To check all our constraints we will need to supplement XML Schemas with another tool. In this tutorial we will cover each of these examples and show how the constraints may be implemented using either XSLT/XPath or Schematron. At the end we will examine the pros and cons of each approach.

Two Approaches to Extending XML Schemas XSLT/XPath –The first approach is to supplement the XSD document with a stylesheet Schematron –The second approach is to embed the additional constraints within elements in the XSD document. Then, a tool (Schematron) will extract and process those constraints.

Enhancing XML Schemas using XSLT/XPath Your XML data Schema Validator XML Schema XSL Processor XSLT Stylesheet containing code to check additional constraints valid Now you know your XML data is valid!

Enhancing XML Schemas using Schematron Your XML data Schema Validator XML Schema valid Now you know your XML data is valid! Schematron valid

<Demo xmlns=" xmlns:xsi=" xsi:schemaLocation=" demo.xsd"> First Example: Verify that A > B Constraints which must be implemented: 1. contains a sequence of elements: then 2. contains an integer; contains an integer 3. The value of element is greater than the value of element Note: an XML Schema document can implement the first two constraints, but not the last.

<xsd:schema xmlns:xsd=" targetNamespace=" xmlns=" elementFormDefault="qualified"> Demo.xsd Note that this schema implements constraints 1 and 2.

<xsl:stylesheet xmlns:xsl=" xmlns:d=" version="1.0"> Error! A is less than B A = B = Instance document is valid Demo.xsl (see example01/xslt) This stylesheet implements constraint 3!

Output Here is the output that results when the stylesheet is run against demo.xml: Error! A is less than B A = 10 B = 20

Introduction to Schematron Schematron enables you to embed assertions (which are expressed using XPath syntax) within elements. XML Schema Schematron Extract assertions from elements XML Data Valid/invalid

Introduction to Schematron (cont.) State a constraint using an element A is comprised of one or more elements …

The Element Use the assert element to state a constraint A should be greater than B XPath expressionText description of the constraint In the element you express a constraint using an XPath expression. Additionally, you state the constraint in natural language. The later helps to make your schemas self-documenting.

The Element Use this element to specify the context for the elements. A should be greater than B "Within the context of the Demo element, we assert that the A element should be greater than the B element." The value of the context attribute is an XPath expression.

The Element You can associate an element with a element. Use the element for printing error messages when the XML data fails the assertion. –In the element you can use: Literal strings The element (from XSLT) to print out the value of elements The elements are embedded within a element. The diagnostics go after a element.

A should be greater than B Error! A is less than B A = B =

Schematron Schema Recall that Schematron extracts the assertions, rules, etc out of the elements. It builds a Schematron schema from the stuff that it extracts. XML Schema Extract assertions, rules, etc from the elements Schematron Schema Schematron XML Data Valid/invalid Demo.xsd Demo.xml_sch Demo.xml

Schematron Schema (cont.) Schematron requires all the Schematron elements (e.g.,,, etc) to be qualified with the namespace prefix sch: –This is how the Schematron engine identifies the Schematron elements.

A should be greater than B Error! A is less than B A = B =

Need to Inform Schematron of the Namespace of the XML Data You need to inform Schematron of the namespace of the XML data. Also, you need to tell it the namespace prefix that you are using in the section to identify the XML data elements. Use the element to do this.

<xsd:schema xmlns:xsd=" targetNamespace=" xmlns=" xmlns:sch=" elementFormDefault="qualified"> Schematron validation A should be greater than B Error! A is less than B. A = B = See example01 Do Lab1

Example 2 Constraint: Ensure that an Aircraft’s Elevation is greater than the Height of all Obstacles <Flight xmlns=" xmlns:xsi=" xsi:schemaLocation= " Aircraft.xsd"> Aircraft.xml (see example02) Check that the aircraft is higher than all obstacles. In this example it isn’t, so we want to catch this (kind of an important check, don’t you agree?)

<xsl:stylesheet xmlns:xsl=" xmlns:a=" version="1.0"> Danger! The aircraft is about to collide with a ! aircraft elevation = height = Instance document is valid XSLT Implementation of Checking the Constraint Aircraft.xsl (see example02)

Output Here is the output that results when the stylesheet is run against Aircraft.xml: Danger! The aircraft is about to collide with a mountain! aircraft elevation = 3300 mountain height = 26000

The Aircraft Elevation should be greater than Obstacle Height. Danger! The aircraft is about to collide with a... aircraft elevation =... height = Schematron Implementation of Checking the Constraint (This annotation is embedded within Aircraft.xsd) Do Lab2

Example 3 Constraint: Ensure that the value of the element is appropriate for the value specified by the mode attribute (see table below) mode Transportation air airplane, hot-air balloon water boat, hovercraft ground car, bicycle

<JourneyToTibet xmlns=" xmlns:xsi=" xsi:schemaLocation= " journeyToTibet.xsd"> boat boat car hovercraft hot-air balloon journeyToTibet.xml (see example03) Need to check each Trip element to ensure that the Transportation element has a legal value for the given mode. In this example the first Trip (segment) is illegal and the remaining segments are legal.

<xsl:when and (not((j:Transportation='airplane') or (j:Transportation='hot-air balloon')))"> Error! When the mode is 'air' then Transportation must be either airplane or hot-air balloon segment = mode = Transportation = <xsl:when and (not((j:Transportation='boat') or (j:Transportation='hovercraft')))"> Error! When the mode is 'water' then Transportation must be either boat or hovercraft segment = mode = Transportation = XSLT Implementation of Checking the Constraint Cont. -->

<xsl:when and (not((j:Transportation='car') or (j:Transportation='bicycle')))"> Error! When the mode is 'ground' then Transportation must be either car or bicycle segment = mode = Transportation = segment is valid. journeyToTibet.xsl (see example03)

Output Here is the output that results when the stylesheet is run against journeyToTibet.xml: Error! When the mode is 'air' then Transportation must be either airplane or hot-air balloon segment = 1 mode = air Transportation = boat segment 2 is valid. segment 3 is valid. segment 4 is valid. segment 5 is valid.

<sch:assert and (j:Transportation='airplane')) or and (j:Transportation='hot-air balloon')) or and (j:Transportation='boat')) or and (j:Transportation='hovercraft')) or and (j:Transportation='car')) or and (j:Transportation='bicycle'))" diagnostics="wrongTransportationForTheMode"> If the mode is air then Transportation should be either airplane or hot-air balloon. If the mode is water then Transportation should be either boat or hovercraft. If the mode is ground then Transportation should be either car or bicycle. Error! Transportation does not have a legal value for the given mode. segment = mode = Transportation = (This annotation is embedded within journeyToTibet.xsd) Schematron Implementation of Checking the Constraint

<sch:assert test="(j:Transportation='airplane') or (j:Transportation='hot-air balloon')" diagnostics="wrongTransportationForTheMode"> If the mode is air then Transportation should be either airplane or hot-air balloon. <sch:assert test="(j:Transportation='boat') or (j:Transportation='hovercraft')" diagnostics=" wrongTransportationForTheMode "> If the mode is water then Transportation should be either boat or hovercraft. <sch:assert test="(j:Transportation='car') or (j:Transportation='bicycle')" diagnostics=" wrongTransportationForTheMode "> If the mode is ground then Transportation should be either car or bicycle. Error! Transportation does not have a legal value for the given mode. segment =. mode =. Transportation =. Alternate Schematron Implementation (see journeyToTibet_v2.xsd in example03)

Observation In this last example there is a definite difference in the complexity of implementations. Schematron provides a much simpler way of expressing the constraints than XSLT. Do Lab3

Example 4 Constraint: Ensure that the value of the equals the value of, where these two elements are in different documents. Invoice.xml … CheckingAccount.xml … Check that these are equal.

<Invoice xmlns=" xmlns:xsi=" xsi:schemaLocation= " Invoice.xsd"> Invoice.xml (see example04) <CheckingAccount xmlns=" xmlns:xsi=" xsi:schemaLocation= " CheckingAccount.xsd"> CheckingAccount.xml (see example04)

Payment due is NOT equal to payment received! Payment due = Payment received = Instance document is valid XSLT Implementation of Checking the Constraint CheckDocuments.xsl (see example04)

Output Here is the output that results when the stylesheet is run against Invoice.xml and CheckingAccount.xml : Payment due is NOT equal to payment received! Payment due = Payment received = 79.00

<sch:assert test="i:PaymentDue = document('file://.../CheckingAccount.xml')/c:CheckingAccount/c:PaymentReceived" diagnostics="amountsDiffer"> Payment due should equal payment received. Payment due is NOT equal to payment received!... Payment due =... Payment received = Schematron Implementation of Checking the Constraint (This appinfo is embedded within Invoice.xsd)

Advantages of using XSLT/XPath to Implement Additional Constraints –Application Specific Constraint Checking: Each application can create its own stylesheet to check constraints that are unique to the application. Thus, each application can enhance the schema without touching it! –Core Technology: XSLT/XPath is a "core technology" which is well supported, well understood, and with lots of material written on it. –Expressive Power: XSLT/XPath is a very powerful language. Most, if not every, constraint that you might ever need to express can be expressed using XSLT/XPath. Thus you don't have to learn multiple schema languages to express your additional constraints – Long Term Support: XSLT/XPath is well supported, and will be around for a long time.

Disadvantages of using XSLT/XPath to Implement Additional Constraints –Separate Documents: With this approach you write your XML Schema document, then you write a separate XSLT/XPath document to express additional constraints. Keeping the two documents in synch needs to be carefully managed –Overkill? On the previous slide it was stated that an advantage of using XSLT/XPath is that it a very rich, expressive language. As a language for expressing constraints perhaps it is too much. As we have seen with these examples, only a few XSLT/XPath elements were needed to express all the contraints. So XSLT/XPath gives a lot of unnecessary overhead.

Advantages of using Schematron to Implement Additional Constraints –Collocated Constraints: We saw how Schematron could be used to express additional constraints. We saw that you embed the Schematron directives within the XML Schema document. There is something very appealing about having all the constraints expressed within one document rather than being dispersed over multiple documents. –Application Specific Constraint Checking: In all of our examples we showed the Schematron elements embedded within the XSD document. However, that is not necessary. Alternatively, you can create a standalone Schematron schema. With this later approach applications can then create a Schematron schema to express their unique constraints. –Simpler: The Schematron vocabulary is very simple, comprised of a handful of elements. As we have seen, with this handful of elements we are able to express all the desired assertions.

Disadvantages of using Schematron to Implement Additional Constraints –Multiple Schema Languages may be Required: From the examples shown in this tutorial it appears that Schematron is sufficiently powerful to express any additional constraints that you might have. It is possible, however, that there are constraints that it cannot express, or cannot express easily. Consequently, you may need to supplement Schematron with another language to express all the additional constraints.

Inside Schematron The “Schematron engine” is actually just an XSL stylesheet! XML Schema Extract assertions, rules, etc from the elements Schematron Schema validate.xsl XML Data valid/invalid Demo.xsd Demo.xml_sch Demo.xml XSD2Schtrn.xsl Convert to a stylesheet Schematron-basic.xsl skeleton1-5.xsl XSL Processor