Creating and using an XML Schema

Why do I need a schema

A schema is a formal description of your data. It is good practice to have an XML schema to describe any XML data that you intend to share, be that with another company, or with the guy sitting next to you.

Without one your just building up problems for the future, and as we all know problems that are fixed early cost less in time, money and hair.

So what does it actually give you.

• A formal definition of your data - not a woolly document, which can be interpreted, this is a rock solid description.
  If you've ever sent a specification off to a 3rd party, then tried to reconcile their interpretation with what you were expecting, then you'll understand. You'll get additional data creeping in because they wanted to add stuff, things are missing because they didn't understand bits.
  If you have a schema then there is none of that. If it's not valid against the schema then we are not interested in it, you can then put the onus back on them to make it correct.
• Validation - You can take an XML document, and check that it complies with your schema. In fact, validators are now so fast that many companies will not allow data into there process flows unless it's valid against the schema. This entry point validation ensures that all data moving through the system is valid, and massively lowers the overhead caused by invalid messages.
• Less Error Handling – If you validate your XML before making use of it, then you can make more assumptions about it, which reduces the amount of error handling/checking you have to do. This is not to say you can write sloppy code, but you don’t have to re-invent the wheel and effectively hard code the validation performed by the XSD Validator.
• Centralises Documentation – Your documentation for the schema can be placed within the schema itself. There are <annotation> tags which allow you to add human and machine readable comments into the schema. There are a number of tools for editing these annotations, including XML Studio.
• Machine readable – Because your schema is machine readable, it can be used by a number of different tools.
  You can produce pretty documentation from it, complete with diagrams and the documentation you painstakingly added.
  You can generate code from it. Code that will read and write your XML documents making it even easier to work with.
  XML Editors can use the schema to provide intellisense when your editing your XML (even making use of the embedded documentation).

So you can either, create some XML, put a woolly document together that describes it, manually adding some hand drawn diagrams to show its structure. Then re-code all the validation rules you described in your document, before you even start to use the XML.

Or

You can write an XML Schema, add documentation into it as you go, generate some pretty documentation from it which you can put on the internet/intranet. When it comes to coding, you just run your XML through the Validator before your code even looks at it, if it isn’t valid, just send it back.

Putting the cart before the horse

Its good practice to think about your data before you design your schema, but things normally happen the other way around, we have some data, and we want to retro fit a schema to it.
So let's look at some data.

<?xml version="1.0" encoding="utf-8"?>
<!-- Created with Liquid XML Studio (https://www.liquid-technologies.com) -->
<SalesCatalogue>
 <Product>
  <Name>Transformers T-Shirt</Name>
  <Description>
    This Transformers Autobot T-shirt is black and made from 100% cotton.
    The distressed image featured on the front of this t-shirt is of the Transformers Autobot.
  </Description>
  <Price>17.95</Price>
  <ProductCode>52-2436556</ProductCode>
  <Size>XL</Size>
 </Product>
</SalesCatalogue>

 <?xml version="1.0" encoding="utf-8" ?>
<!--Created with Liquid XML Studio (https://www.liquid-technologies.com)-->
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" >
    <xs:element name="SalesCatalogue">
        <xs:complexType>
            <xs:sequence>
                <xs:element minOccurs="0" maxOccurs="unbounded" name="Product">
                    <xs:complexType>
                        <xs:sequence>
                            <xs:element name="Name" type="xs:string"/>
                            <xs:element name="Description" type="xs:string"/>
                            <xs:element name="Price" type="xs:string"/>
                            <xs:element name="ProductCode" type="xs:string"/>
                            <xs:element name="Size">
                                <xs:simpleType>
                                    <xs:restriction base="xs:string">
                                        <xs:enumeration value="XXXL"/>
                                        <xs:enumeration value="XXL"/>
                                        <xs:enumeration value="XL"/>
                                        <xs:enumeration value="L"/>
                                        <xs:enumeration value="M"/>
                                        <xs:enumeration value="S"/>
                                    </xs:restriction>
                                </xs:simpleType>
                            </xs:element>
                        </xs:sequence>
                    </xs:complexType>
                </xs:element>
            </xs:sequence>
        </xs:complexType>
    </xs:element>
</xs:schema>

We'll start by just building a schema for the XML above.

Step 1: One Liquid XML Studio

Step 2: Create a new Schema.

Menu (New->File...)

Select 'W3C XML Schema'.

Step 3: Add an element to the schema.

Right click on the "Schema Root" node, Menu (Add Child->Element)

A new element node should appear, set the name in the focused text box ("SalesCatalogue").

Step 4: Add a sequence to the 'SalesCatalogue' node

Right click on the 'SalesCatalogue' node and select the menu (Add Child->Sequence).
A Sequence is a container for other child elements, there are 2 other containers choice and all.

Step 5: Add an element to the sequence

Right click on the sequence and select the menu (Add Child->Element).

Give the element the name 'Product'.

Step 6: Change the Cardinality

We want to allow lots of product elements to be present in the SalesCatalogue. To do this we can change the cardinality.

Right click on the 'product' node and select the menu (Cardinality->0..unbounded).

Step 7: Add a sequence to 'Product'

Repeat step 4 for the 'Product' node

Step 8: Add a name element to products sequence

Add a new element to the sequence attached to product, name it "Name" (see step 3).

The previous elements we have created have been containers for other child elements (i.e. 'SalesCatalogue' contains 0 or more 'Product' elements). We are now defining an element that can only contain data, in this case text.

Select the type portion of the node, on the right (contains the text '<None>'), and select from the list (or type in) 'string'.

There are a number of different built in data types which you can use, you can also define your own (See Simple Types)

Short cut, when editing the elements name, you can press 'Tab' to move to the type list.

Step 9: Add more data elements

Add the following elements in the same way as step 8.

• 'Description' of type 'string'
• 'Price' of type 'double'
• 'ProductCode' of type 'string'
• 'Size' of type 'string'

Step 10: Restrict the values for 'Size'

We may want tot element 'Size' to have a limited range of values. We can do this by setting the enumeration property.

Select the 'Size' node.

Go to the properties window (it may be hidden or closed, use the Menu (View->Properties), or F4 to make it visible).

Select the 'Enumeration' entry, and click the '...' button that appears

Add all the allowable values (one per line).

Step 11: Save your schema

Select the menu item (File->Save) or Ctrl-S. Name the schema 'SalesCatalogue.xsd'

Using your Schema

You can now make use of your schema to validate your XML document.

Step 1: Create an XML document.

Step 2: Create your XML Document

Cut and paste the xml code at the beginning of the page into the editor.

Step 3: Performing validation.

The editor will automatically validate the document. However, as the editor does not know about the schema, it can not check that the data is correct (only well formed; all tag are paired and closed).

You can see that the editor has not associated a schema with the properties in the tool bar

Step 4: Associating a schema with the document

You can set the schema that is associated with this XML document using the Validation Options Button ().

Find your schema in the list (if it is not there use the 'Add' button). Then change the Use property to 'Use this Schema' ().

Now when you return to the editor you can see that your schema is associated with the document.

The validation rules for a given XML file are recorded, so when the XML file is re-loaded its associations are kept.

Step 4: Validating

Now when the validation is performed, the editor can also validate against the schema. As this document is valid you will see no errors.

Let's change things a little so it becomes invalid.

Change the value of Size from 'XL' to 'Big'.

Because the 'Size' element has a restriction on it (it can only be one of the enumerated values specified), the value 'Big' will make it invalid.

Now you should see a validation error appear in the Errors Tool Window (Press Ctrl-E, if it is not visible).

Note: double clicking on the error in the Error list will take you to the problem in the XML.

Step 5: Intellisense

Another advantage of associating a schema with your XML is you can now make use of intellisense. You will now get presented with the valid options when you start creating and element or attribute.