Biztalk 0.8 Tag Specification

[This local archive copy is from the official and canonical URL, http://www.biztalk.org/Biztalk%20Design%20Guide%20Final.htm; please refer to the canonical source document if possible.]

BizTalk™ Framework Document Design Guide

Creating XML document schemas and instances from data contained within your existing systems, or that meet your application needs is complicated, in part due to the number of different ways of expressing the same things. Furthermore, inconsistency in the way messages are constructed will make the process of integration more difficult. The purpose of this document is to provide a set of design guidelines for BizTalk Framework documents that can be easily implemented by application developers.

The BizTalk Framework is an XML framework for application integration and e-commerce. It includes a design framework for implementing an XML schema and a set of XML tags used in messages sent between applications. Microsoft, other software companies, and industry standards bodies will use the Biztalk Framework to produce XML schemas in a consistent manner.

Microsoft hereby grants to all users of this BizTalk (tm) Framework specification, version 0.8 (the "Specification"), a perpetual, nonexclusive, royalty-free, world-wide right and license under any Microsoft copyrights in the Specification to copy, publish and distribute the Specification. Microsoft further agrees to grant to users a royalty-free license under applicable Microsoft intellectual property rights to implement and use the BizTalk XML tags and schema guidelines included in the Specification for the purpose of creating computer programs that adhere to such guidelines --one condition of this license shall be the party's agreement not to assert patent rights against Microsoft and other companies for their implementation of the Specification. Microsoft expressly reserves all other rights it may have in the material and subject matter of this Specification. Microsoft expressly disclaims any and all warranties regarding this Specification including any warranty that this Specification or implementations thereof does not violate the rights of others.

Information in this document is subject to change without notice.

Microsoft and BizTalk are either registered trademarks or trademarks of Microsoft Corporation in the U.S.A. and/or other countries.

Mandatory Requirements Tags

There are three essential rules for the creation of BizTalk Framework documents and messages: define your schemas using XML-Data, use BizTalk Framework Tags, and document your schemas so they can be automatically catalogued.

Define your schemas using XML-Data.

Business message documents are described by schemas, meaning a listing of which elements and attributes may appear in the message and in which combinations. There are several formats available for writing a schema. The BizTalk Framework requires a specific format: XML-Data.

Briefly, XML-Data is a vocabulary (schema) of XML elements and attributes designed for describing other classes of XML documents. It describes what elements may be used in a document, what attributes may appear, and what combinations of elements and attributes are valid. To this degree, it performs the same function as the XML standard format known as "DTD." However, XML-Data goes beyond DTD in four important respects: it describes datatypes (number, date, etc.); it supports the XML Namespaces specification; it allows open content models and it is itself extensible, being written in XML.

Defining which elements in a document are numbers, which are dates and so forth is important to improving the reliability, automatic validation, and programmatic access of business messages. If you use datatypes, you will find that you must format numbers and dates in certain restricted ways based on international standards. These are documented more fully at http://msdn.microsoft.com/xml/xmlguide/schema-datatypes.asp and also at http://msdn.microsoft.com/xml/reference/schema/datatypes.asp.

Supporting the namespaces specification allows you to compose messages using parts drawn from several schemas. Namespaces give universally-recognizable identifiers to elements, and so are fundamental to interoperability of Web documents. The BizTalk Framwork requires the documentation of messages using XML-Data, and use of the features of datatypes and namespaces.

Full details on XML-Data are available from http://msdn.microsoft.com/xml.

Use BizTalk Framework Tags

Certain information, such as routing numbers, from and to addresses and so forth constitute protocol level information common to all business messages. The BizTalk Framework defines a set of standard tags for this purpose which are mandatory in every BizTalk Framework document. These are defined in the BizTalk Framework Tags specification document available on http://www.biztalk.org/.

Document and Classify your schema.

BizTalk provides a set of standard elements for you to use to document and classify your schemas. With these, you can indicate the owner, author, intended use and various other categorizations of your schema, as well as providing keywords and other taxonomic classifiers to make it easier for other businesses to discover and use your schema.

Style Guidelines

Names and Cases

Names should use the style called "CamelCase" . If an element reflects a thing (an object, a class or a table name) use UpperCamelCase and if it is a property, a reference etc, use lowerCamelCase.

UpperCamelCase Example:

lowerCamelCase Examples:

Use meaningful names

People sometimes become over-economical in the letters they are willing to spend on a tag name, perhaps omitting vowels and other expendable parts. This made good sense in the days when a few letters consumed a significant fraction of the space available on a computer or a phone line. However, XML compresses very well. Computers are getting relentlessly cheaper; humans are not. Keep the few extra letters to make sure that humans can read messages more easily.

<shp2> Don’t do this.

<shipTo> Write it this way.

Name by function, not location

Do not name elements by their location. In addition to the resulting illegibility, this practice is unreliable because the variations in messages tend to shift element positions, and also because it encourages overloading the same element name to hold different information items at different times.

<field_34> Don’t do this.

<shipTo> Write it this way.

Don’t use Private Encodings

When practical, use distinct elements to separate parts of data. If you have a data item that has internal structure, if you separate the parts with tags the XML parser will do the work of distinguishing them for you, saving you the cost of writing a custom parser. Additionally, you will have made the structure publicly readable and thereby available to standard tools such as XSL style sheets and query languages. If something has more than one part, it is likely that it will gain still more parts in the future, and using tags up-front means easier extension later.

<price>12.5AUS</price> Don’t do this.

<price> Write it this way.

</price>

Practical Applications

The message body of a BizTalk Framework document contains the real data of the interchange, the information that the receiving application will consume, rather than the BizTalk Framework infrastructure. This section provides practical examples of how to design the structure of a BizTalk Framework message body from an application developers perspective.

Expressing Data

All simple data - trees, columns, rows, objects, properties, etc. should be expressed as elements and sub-elements, not attributes. The XML Canonical Form Document available from http://www.biztalk.org/ defines the approach for expressing more complex data structures and relationships.

For example the simplified BizTalk Framework message shown below represents a purchase order:

<BizTalk xmlns="urn:schemas-biztalk-org:biztalk-0.8.xml">

	<Route>
		. . . see above . . .

	</Route>
	<Body>
		<PurchaseOrder>
		<POHeader> 
			<PONumber>12345</PONumber>
			<PaymentType>INVOICE</PaymentType> 
			<POShipTo>
				<street1>Your Street 1</street1>
				<street2>Your Street 2</street2> 
				<city>Your City</city>
			</POShipTo >	
			<POBillTo>
				<street1>Your Street 1</street1>
				<street2>Your Street 2</street2> 
				<city>Your City</city>
			</POBillTo >
		</POHeader>
		<POLines>
			<Item>
				<partno>ikypop1</partno>
				<quantity>1</quantity>
				<unitPrice>14.00</unitPrice>
			</Item>

		</POLines>
	</PurchaseOrder>
	</Body>	
</BizTalk>

Since this will not generally be the way the data is actually stored on any system it needs to be mapped from the native form to the BizTalk Framework form.

Mapping From Database Tables

Records should be represented as an element containing sub-elements for each field. Where a field is a foreign key, that element will be a container for the sub-elements representing the foreign record.

For example the source database tables for the above example might have the following schema:

PURCHASE_ORDERS

    po_number (primary key)

    payment_type

    ship_to (foreign key -> DEPARTMENTS)

    bill_to (foreign key -> DEPARTMENTS)

DEPARTMENTS

    department_id (primary key)

    street1

    street2

    city

LINE_ITEMS
    po_number

    part_number

    quantity
    unit_price

Mapping From Objects

Objects should be represented as elements containing a nested element for each property. Where a property is a reference to another object the nesting is extended to include the properties of the referenced object.

For example the XML above might be derived from a set of objects with the following classes:

		PurchaseOrder

			.OrderID

			.PaymentType

			.ShipTo

			.BillTo

			.Items()

		Department

			.DepartmentName

			.Street

			.City

			.PostalCode

		Item

			.PartNumber

			.Quantity

			.UnitPrice