BizTalk Server: Deep Dive in Schema Design
Introduction
A Schema is a definition of a document which describes the structure of that particular document. In BizTalk, there are two common types of structures which mainly deal with XML-based and Flat Files. This article intends to explain bits and bytes of designing BizTalk Schema (XML).
The Example used in article
<?xml version="1.0" encoding="utf-16"? >
-<xs:schema xmlns="http://testingschemas.incomingorder/" xmlns:b="http://schemas.microsoft.com/BizTalk/2003" targetNamespace="http://testingschemas.incomingorder/" xmlns:xs="http://www.w3.org/2001/XMLSchema">
- <xs:simpleType name="eMailType">
- <xs:restriction base="xs:string">
<xs:pattern value="\w+([-+.']\w+)*@\w+([-.]\w+)*\.\w+([-.]\w+)*" />
</xs:restriction>
</xs:simpleType>
- <xs:element name="Order">
- <xs:annotation>
- <xs:appinfo>
- <b:properties>
<b:property distinguished="true" xpath="/*[local-name()='Order' and namespace-uri()='http://testingschemas.incomingorder/']/*[local-name()='Header' and namespace-uri()='']/*[local-name()='OrderId' and namespace-uri()='']" />
<b:property distinguished="true" xpath="/*[local-name()='Order' and namespace-uri()='http://testingschemas.incomingorder/']/*[local-name()='Header' and namespace-uri()='']/*[local-name()='OrderDate' and namespace-uri()='']" />
</b:properties>
</xs:appinfo>
</xs:annotation>
- <xs:complexType>
- <xs:sequence>
- <xs:element name="Header">
- <xs:complexType>
- <xs:sequence>
<xs:element name="OrderId" type="xs:string" />
<xs:element name="OrderDate" type="xs:string" />
<xs:element name="Currency" type="xs:string" />
- <xs:element minOccurs="0" maxOccurs="1" name="ShipTo">
- <xs:complexType>
- <xs:sequence>
<xs:element name="ID" type="xs:string" />
<xs:element name="Name" type="xs:string" />
<xs:element name="AddressLine1" type="xs:string" />
<xs:element name="AddressLine2" type="xs:string" />
<xs:element name="City" type="xs:string" />
<xs:element name="State" type="xs:string" />
<xs:element name="PostalCode" type="xs:string" />
<xs:element name="Country" type="xs:string" />
<xs:element name="TelephoneNumber" type="xs:string" />
<xs:element name="EmailAddress" type="eMailType" />
</xs:sequence>
</xs:complexType>
</xs:element>
- <xs:element minOccurs="0" maxOccurs="1" name="BillTo">
- <xs:complexType>
- <xs:sequence>
<xs:element name="ID" type="xs:string" />
<xs:element name="Name" type="xs:string" />
<xs:element name="AddressLine1" type="xs:string" />
<xs:element name="AddressLine2" type="xs:string" />
<xs:element name="City" type="xs:string" />
<xs:element name="State" type="xs:string" />
<xs:element name="PostalCode" type="xs:string" />
<xs:element name="Country" type="xs:string" />
<xs:element name="TelephoneNumber" type="xs:string" />
<xs:element name="EmailAddress" type="eMailType" />
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="HeaderComment" type="xs:string" />
</xs:sequence>
</xs:complexType>
</xs:element>
- <xs:element name="Details">
- <xs:complexType>
- <xs:sequence>
- <xs:element minOccurs="1" maxOccurs="unbounded" name="Item">
- <xs:complexType>
- <xs:sequence>
<xs:element name="ItemId" type="xs:string" />
<xs:element name="ItemDescription" type="xs:string" />
<xs:element name="Quantity" type="xs:string" />
<xs:element name="UnitPrice" type="xs:string" />
<xs:element name="LineNumber" type="xs:string" />
<xs:element name="UOM" type="xs:string" />
<xs:element name="RequestedDeliveryDate" type="xs:string" />
<xs:element name="LineComment" type="xs:string" />
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
Code Block 1. Sample schema
Building blocks of BizTalk schema
The Schema is created with the help of following components:
- BizTalk Schema Editor.
- Version and Encoding.
- Namespace.
- Properties.
- Root Node and properties associated with it.
- Record Node and properties associated with it.
- Element and properties associated with it.
- Attributes and properties associated with it.
- Properties associated with Schema.
BizTalk Schema Editor
The BizTalk Editor shows the schema in two sections, the first section on the left shows the tree view and the second section shows the XSD code.
Properties window can be found at the right bottom of the screen, which is used to set properties of the nodes.
Note: XSD code can only be viewed and cannot be edited.
Figure 1. BizTalk Schema Editor.
Version and Encoding
Both are used as a Processing Instruction.
xml version: It tells as to which XML output conforms to.
encoding: It tells as to which encoding standard is used for displaying the characters in XML.
Below are few encoding standards:
- "us-ascii"
- "windows-1252"
- "ISO-8859-1"
- "UTF-8"
- "UTF-16"
BizTalk always uses UTF-16 encoding for their schemas.
<?xml version="1.0" encoding="utf-16"? >
See forum question.
Namespace
By default, the BizTalk Editor will set the namespace of a schema to
- **http://ProjectName.SchemaName. **
Note: http://schemas.microsoft.com/BizTalk/2003 and http://www.w3.org/2001/XMLSchema are also added by BizTalk and are implicit. Basically, both are references to definitions, annotations defined by BizTalk and W3.org, it is the reason why we are able to build schema.
<xs:schema xmlns="http://testingschemas.incomingorder/" xmlns:b="http://schemas.microsoft.com/BizTalk/2003" targetNamespace="http://testingschemas.incomingorder/" xmlns:xs="http://www.w3.org/2001/XMLSchema">
See this question on the forum.
Common Properties across Root Node,Record Node,Element Field,Attribute Field
Properties |
Description |
Available For |
Base Data Type |
Determines the name of the type definition that the current node type is based upon. |
Root Node, Record Node, Element Field, Attribute Field |
Block |
The Block property is used to prevent specific types of derivation to be used in place of this Node. The default value is ’None’. |
Root Node, Record Node |
Content Type |
Content model of the complex type (either of ComplexContent, SimpleContent,None).The default is ‘None’. |
Root Node, Record Node |
Data Structure Type |
Indicates the structure type of the record. Usually is a global complex type or named a reference to a global element. |
Root Node, Record Node |
Group Max Occurs |
Maximum Occurrences of the underlying group content of this Node. Its value should always be greater than or equal to Group Min Occurs. The default value is ‘1’. |
Root Node, Record Node |
Group Min Occurs |
Minimum Occurrences of the underlying group content of this Node. Its value should always be less than or equal to Group Max Occurs. The default value is ‘1’. |
Root Node, Record Node |
Group Order Type |
Determines the type of group ordering for children nodes under the current context. Available options are Sequence, Choice, All. |
Root Node, Record Node |
Mixed |
Determines whether the sub-elements in the current context can be intermingled with text content. The default value is ‘False’. |
Root Node, Record Node |
Nillable |
Determines whether this node can be null in the instance document. The default value is ‘False’. |
Root Node, Record Node, Element Field |
Node Name |
Name of the Node. |
Root Node, Record Node, Element Field, Attribute Field |
Notes |
This property is used to access a dialog for entry of what are effectively business level comments about the node with focus. |
Root Node, Record Node, Element Field, Attribute Field |
Max Occurs |
Maximum Occurrences of this node. Its value should always be greater than or equal to minOccurs of this node. Use ‘unbounded’ or ‘*’ to indicate unlimited occurrences. The default value is ‘1’. |
Record Node, Element Field |
Min Occurs |
Minimum occurrences of this node. Its value should always be less than or equal to MaxOccurs for this node. The default value is ‘1’. |
Record Node, Element Field |
Data Type |
Data Type of the Node |
Element Field, Attribute Field |
Default Value |
Default value of this node.This can be used in a scenario where you can get no value in the instance but it can't be left blank, thus, assign a value (so if no value then the default value is considered). |
Element Field, Attribute Field |
Derived By |
Indicates how the underlying Simple Type of the Field is derived from its base data type. Options available are Restriction, List and Union. |
Element Field, Attribute Field |
Fixed |
The fixed attribute is used to ensure that the field is set to particular fixed value.This can be used in a scenario where value has to be static. |
Element Field, Attribute Field |
Form |
During instance validation, determines whether the items in the current context must be qualified with a namespace. Options are Qualified and Unqualified. |
Element Field, Attribute Field |
Table 1. Listing of common properties,description and available for.
Root Node and properties associated with it
Root node is a special type of Record Node which has at least one child and no parent. Whenever you create a schema in BizTalk schema editor a Root node will be added automatically with the name as "Root". It can be renamed, and its best practice to name it after the purpose, say "Order" if it is for the order.
User have no control over certain properties:
There are few properties which are disabled (BizTalk has control) like Body XPath, Derived By, Form, Instance Path, Min Occurs, Max Occurs and Namespace.
**Note : **When the Envelope property of the Schema node is set to Yes its only then Body XPath property can be set.
Body XPath property is used to specify the XPath of the node which is root of the body which is wrapped using Envelope.
Figure 2. Properties available for Root Node.
Record Node and properties associated with it
Whenever Record node is added, it's Content-Type is preset as complexType and whenever a child element field is added under it , the Group Order Type gets set as a sequence.
There are indicators as to how the elements should appear under Record.
- xs:Choice
- xs:Sequence
- xs:All
When we use xs:choice group then only one of its child elements to appear, when xs:sequence is used then it is expected to have elements as in the schema as per the sequence and when xs:all is used, it allow their child elements to appear zero (0) or one (1) time and in any order.
See forum question.
- <xs:element name="Header">
- <xs:complexType>
- <xs:sequence>
<xs:element name="OrderId" type="xs:string" />
<xs:element name="OrderDate" type="xs:string" />
<xs:element name="Currency" type="xs:string" />
Four properties which puzzles a lot:
The properties associated with occurrences** are Group Max Occurs,Group Min Occurs,Max Occurs and Min Occurs**.
Group Max Occurs and Group Min Occurs: This property tells about the number of times the group of elements (either of type sequence, group) which are under that particular Record can occur and by Default, it is "1".
Max Occurs and Min Occurs: This property tells about the number of times that particular Record can occur and by Default, it is "1".
See forum question.
Figure 3. Properties available for Record Node.
Element and properties associated with it
Whenever an element is added its Data Type is set to xs:string, it can/should be changed as per requirement, and to do it click the Text field in front of Data Type property and select from the options which serves your purpose. If the requirement is to have some restrictions or pattern to be implemented then Base Data Type is to be used along with the Derived By property.
- <xs:simpleType name="eMailType">
- <xs:restriction base="xs:string">
<xs:pattern value="\w+([-+.']\w+)*@\w+([-.]\w+)*\.\w+([-.]\w+)*" />
</xs:restriction>
</xs:simpleType>
See How to create custom data type
Form is a special property as it is used only in the scenario where that particular element/attribute needs to qualify to the namespace. Default is unqualified.
There are situations where the elements need to have a default value, this can be done by Using Default Value property and setting value against it.
See forum question.
Note: Even if Max Occurs and** Min Occurs** appear blank in Properties tab, it is implicitly considered as "1".
See forum question.
< xs:element name="OrderId" type="xs:string" />
<xs:element name="OrderDate" type="xs:string" />
<xs:element name="Currency" type="xs:string" />
Figure 4. Properties available for Element Field.
Attributes and properties associated with it
Whenever an attribute is added its Data type is set to xs:string, it can/should be changed as per requirement, and to do it click the Text field in front of** Data Type** property and select from the options which serves your purpose.
**Note: **Max Occurs and Min Occurs property are not available .
<xs:attribute name="ForDemo" type="xs:string" />
Figure 5. Properties available for Attributes.
Properties associated with Schema
The most important property is Target Namespace. Target Namespace is to schema what a namespace is to .Net Object. It is used in the creation of MessageType and plays an important role to resolve schema references.
Note: Target Namespace can be empty.
Envelope is a BizTalk specific property which indicates whether the schema is an envelope schema (wrapper to some document schema). By default values is 'No'. It can/should be changed when creating Envelope schema and value should be 'Yes'.
CodeList Database : Specifies the database (*.mdb file) to be used to indicate code list property(enumeration values) on fields.
Attributes FormDefault: Describes how the attributes will appear in the instance. Default value is 'Unqualified'. If set to qualified then the instance will have all attribute field marked with namespaces.
Element FormDefault: Describes how the elements will appear in the instance. Default value is 'Unqualified'. If set to qualified then the instance will have all element field marked with namespaces.
Property which raises questions:
Imports property which helps in using already existing schemas gives three options to choose from as per the requirement.
- XSD Import – Accessing types and using them, deriving new types from them of another schema.
- XSD Include – Accessing types and using them of another schema within the same namespace (or blank), deriving new types from them.
- XSD Redefine – Accessing types and using them of another schema within the same namespace (or blank) ,deriving new types from them and also type modifications are allowed, thus the name Redefine.
See forum question.
Figure 6. Properties available for Schema.
Author
**Maheshkumar S Tiwari **| User Page
http://tech-findings.blogspot.com/
See Also
Read suggested related topic:
Another important place to find a huge amount of BizTalk related articles is the TechNet Wiki itself. The best entry point is BizTalk Server Resources on the TechNet Wiki.
Another important place to find a huge amount of TechNet Wiki related articles is Wiki: List of Articles for TechNet Wiki
This article participates in the TechNet Guru for September competition