XML Primer

From MTConnect® User's Portal
Revision as of 14:25, 30 July 2013 by Tjones25 (Talk | contribs)

Jump to: navigation, search



XML consists of a hierarchy of elements. The elements can contain sub-elements, CDATA, or both. For this specification, however, an element never contains mixed content or both sub-elements and CDATA. Attributes are additional information associated with an element. The textual representation of an element is referred to as a tag. See the following example:

1. <Foo name=”bob”>Ack!</Foo>

An XML element consists of a named opening and closing tag. In the above example, <Foo...> is referred to as the opening tag and </Foo> is referred to as the closing tag. The text Ack! in between the opening and closing tags is called the CDATA. CDATA can be restricted to certain formats, patterns, or words. In the document when it refers to an element having CDATA, it indicates that the element has no sub-elements and only contains data.

When one looks at an XML Document there are two parts. The first part is typically referred to as an XML declaration and is only a single line. It looks something like this:

2. <?xml version="1.0" encoding="UTF-8"?>

This line indicates the XML version being used and the character encoding. Though it is possible to leave this line off, it is usually considered good form to include this line in the beginning of the document.

Every XML Document contains one and only one root element. In the case of MTConnect, it is the MTConnectDevices, MTConnectStreams, MTConnectAssets, or MTConnectError element. When these root elements are used in the examples, you will sometimes notice that it is prefixed with mt as in mt:MTConnectDevices.

The mt is what is referred to as a namespace alias and it refers to the urn urn:mtconnect.org:MTConnectDevices:1.2 in the case of an MTConnectDevices document. The urn is the important part and MUST be consistent between the schema and the XML document. The namespace alias will be included as an attribute of the XML element as in:

1.	<MTConnectDevices 
2.	  xmlns:m="urn:mtconnect.org:MTConnectDevices:1.2" 
3.	  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
4.	  xmlns="urn:mtconnect.org:MTConnectDevices:1.2"
5.	  xsi:schemaLocation="urn:mtconnect.org:MTConnectDevices:1.2

In the above example, the alias m refers to the MTConnectDevices urn. This document also contains a default namespace on line 4 which is specified with an xmlns attribute without an alias. There is an additional namespace that is always included in all XML documents and usually assigned the alias xsi. This namespace is used to refer to all the standard XML data types prescribed by the W3C. An example of this is the xsi:schemaLocation attribute that tells the XML parser where the schema can be found.

In XML, to allow for multiple XML Schemas to be used within the same XML Document, a namespace will indicate which XML Schema is in effect for this section of the document. This convention allows for multiple XML Schemas to be used within the same XML Document, even if they have the same element names. The namespace is optional and is only required if multiple schemas are required.

An attribute is additional data that can be included in each element. For example, in the following MTConnect® DataItem, there are several attributes describing the DataItem:

3. <DataItem name=”Xpos” type=”POSITION” subType=”ACTUAL” category=”SAMPLE” />

The name, type, subType, and category are attributes of the element. Each attribute can only occur once within an element declaration, and it can either be required or optional.

An element can have any number of sub-elements. The XML Schema specifies which sub-elements and how many times a given sub-element can occur. Here’s an example:

4.	<TopLevel>
5.	  <FirstLevel>
6.	    <SecondLevel>
7.	      <ThirdLevel name=”first”></ThirdLevel>
8.	      <ThirdLevel name=”second”></ThirdLevel>
9.	    </SecondLevel>
10.	  </FirstLevel>
11.	</TopLevel>

In the above example, the FirstLevel has an sub-element SecondLevel which in turn has two sub-elements, ThirdLevel, with different names. Each level is an element and its children are its sub-elements and so forth.

In XML we sometimes use elements to organize parts of the document. A few examples in MTConnect® are Streams, DataItems, and Components. These elements have no attributes or data of their own; they only provide structure to the document and allow for various parts to be addressed easily.

In the following example DataItems and Components are only used to contain certain types of elements and provide structure to the documents. These elements will be referred to as Containters in the standard.

1.	…
2.	<Device id=”d” name=”Device”>
3.	  <DataItems>
4.	    <DataItem/>
5.	    …
6.	  </DataItems>
7.	  <Components>
8.	    <Axes></Axes>
9.	  </Components>
10.	</Device>

An XML Document can be validated. The most basic check is to make sure it is well-formed, meaning that each element has a closing tag, as in <foo>...</foo> and the document does not contain any illegal characters (<>) when not specifying a tag. If the closing </foo> was left off or an extra > was in the document, the document would not be well-formed and may be rejected by the receiver. The document can also be validated against a schema to ensure it is valid. This second level of analysis checks to make sure that required elements and attributes are present and only occur the correct number of times. A valid document must be well-formed.

All MTConnect® documents must be valid and conform to the XML Schema provided along with this specification. The schema will be versioned along with this specification. The greatest possible care will be taken to make sure that the schema is backward compatible.

For more information, visit the w3c website for the XML Standards documentation: http://www.w3.org/XML/

Markup Conventions

MTConnect® follows industry conventions on tag format and notations when developing the XMLschema. The general guidelines are as follows:

  1. All tag names will be specified in Pascal case (first letter of each word is capitalized). For example: <ComponentEvents />
  2. Attribute names will also be camel case, similar to Pascal case, but the first letter will be lower case. For example: <MyElement attributeName=”bob”/>
  3. All values that are part of a limited or controlled vocabulary will be in upper case with an _ (underscore) separating words. For example: ON, OFF, ACTUAL, COUNTER_CLOCKWISE, etc…
  4. Dates and times will follow the W3C ISO 8601 format with arbitrary decimal fractions of a second allowed. Refer to the following specification for details: http://www.w3.org/TR/NOTE-datetime The format will be YYYY-MM-DDThh:mm:ss.ffff, for example 2007-09-13T13:01.213415. The accuracy and number of decimal fractional digits of the timestamp is determined by the capabilities of the device collecting the data. All times will be given in UTC (GMT).
  5. XML element names will be spelled-out and abbreviations will be avoided. The one exception is the word identifier that will be abbreviated Id. For example: SequenceNumber will be used instead of SeqNum.

Reply XML Document Structure

At the top level of all MTConnect® XML Documents there MUST be one of the following XML elements: MTConnectDevices, MTConnectStreams, or MTConnectError. This element will be the root for all MTConnect® responses and contains all sub-elements for the protocol.

All MTConnect® XML Documents are broken down into two parts. The first XML element is the Header that provides protocol related information like next sequence number and creation date and the second section provides the content for Devices, Streams, or Errors.

The top level XML elements MUST contain references to the XML schema URN and the schema location. These are the standard XML schema attributes:

1.	<MTConnectStreams xmlns:m="urn:mtconnect.com:MTConnectStreams:1.1"
2.	   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
3.	   xmlns="urn:mtconnect.com:MTConnectStreams:1.1"
4.	   xsi:schemaLocation="urn:mtconnect.com:MTConnectStreams:1.1 http://www.mtconnect.org/schemas/MTConnectStreams.xsd">


MTConnectDevices provides the descriptive information about each device served by this Agent and specifies the data items that are available. In an MTConnectDevices XML Document, there MUST be a Header and it MUST be followed by Devices section.

Figure 1: MTConnect Devices Structure

MTConnectDevices XML Document MUST have the following structure:

5.	<MTConnectDevices xmlns:m="urn:mtconnect.com:MTConnectDevices:1.1"
6.	   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
7.	   xmlns="urn:mtconnect.com:MTConnectDevices:1.1"	
8.	   xsi:schemaLocation="urn:mtconnect.com:MTConnectDevices:1.1 
9.	  <Header/>
10.	  <Devices></Devices>
11.	</MTConnectDevices>

An MTConnectDevices element MUST include the Header for all documents and the Devices element.

Figure 2: MTConnectDevices Elements


MTConnectStreams contains a timeseries of Samples, Events, and Condition from devices and their components. In an MTConnectStreams XML Document, there MUST be a Header and it MUST be followed by a Streams section.

Figure 3: MTConnectStreams Structure

An MTConnectStreams XML Document will have the following structure:

12.	<MTConnectStreams xmlns:m="urn:mtconnect.com:MTConnectStreams:1.1"
13.	   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
14.	   xmlns="urn:mtconnect.com:MTConnectStreams:1.1"	
15.	   xsi:schemaLocation="urn:mtconnect.com:MTConnectStreams:1.1 http://www.mtconnect.org/schemas/MTConnectStreams.xsd">
16.	  <Header/>
17.	  <Streams></Streams>
18.	</MTConnectStreams>

An MTConnectStreams document MUST include a Header and a Streams element.

Figure 4: MTConnectStreams Elements


An MTConnect asset document contains information pertaining to a machine tool asset, something that is not a direct component of the machine and can be relocated to another device during its lifecycle. The Asset will contain transactional data that will be changed as a unit, meaning that at any point in time the latest version of the complete state for this asset will be given by this device.

Figure 5: MTConnectAssets Structure

Each device may have a different set of information about this asset and it is the responsibility of the application to collect and determine the best data and keep histories if necessary. MTConnect will allow any application or other device request this information. MTConnect makes no guarantees that this will be the best information across the entire set of devices, only that from this devices perspective, it is the latest and most accurate information it has supplied.

MTConnect allows any application to request information about an asset by its assetId. This identifier MUST be unique for all assets. The uniqueness is defined within the domain used by the implementation, meaning, if MTConnect will be used within a shop, the assetId MUST be unique within that shop. And conversely, if MTConnect will be used throughout an enterprise, it is advisable to make the assetId unique throughout the enterprise.

1.	<?xml version="1.0" encoding="UTF-8"?>
2.	<MTConnectAssets xsi:schemaLocation="urn:mtconnect.org:MTConnectAssets:1.2 ../MTConnectAssets_1.2.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="urn:mtconnect.org:MTConnectAssets:1.2" xmlns:mt="urn:mtconnect.org:MTConnectAssets:1.2">
3.		<Header creationTime="2001-12-17T09:30:47Z" sender="localhost" version="1.2" bufferSize="131000" instanceId="1" />
4.		<Assets>
5.			<CuttingTool serialNumber="1234" timestamp="2001-12-17T09:30:47Z" assetId="1234-112233">
6.				<Description>Cutting Tool</Description>
7.				<ToolDefinition></ToolDefinition>
8.				<ToolLifeCycle deviceUuid="1222" toolId="1234">…
9.				</ToolLifeCycle>
10.			</CuttingTool>
11.		</Assets>
12.	</MTConnectAssets>

The document is broken down into two sections, the tool definition (line 7) and the tool life cycle (lines 8-9).


Figure 6: MTConnectErrorn Structure

An MTConnectError document contains information about an error that occurred in processing the request. In an MTConnectError XML Document, there MUST be a Header and it must be followed by an Errors container that can contain a series of Error elements:

1.	<?xml version="1.0" encoding="UTF-8"?>
2.	<MTConnectError xmlns="urn:mtconnect.org:MTConnectError:1.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:mtconnect.org:MTConnectError:1.1 http://www.mtconnect.org/schemas/MTConnectError_1.1.xsd">
3.	  <Header creationTime="2010-03-12T12:33:01" sender="localhost" version="1.1" bufferSize="131072" instanceId="1268463594" />
4.	  <Errors>
5.	    <Error errorCode="OUT_OF_RANGE" >Argument was out of range</Error>
6.	    <Error errorCode="INVALID_XPATH" >Bad path</Error>
7.	  </Errors>
8.	</MTConnectError>
</source lang="xml">
For purposes of backward compatibility, a single ''error'' can have a single Error element.
<source lang="xml">
1.	<?xml version="1.0" encoding="UTF-8"?>
2.	<MTConnectError xmlns="urn:mtconnect.org:MTConnectError:1.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:mtconnect.org:MTConnectError:1.1 http://www.mtconnect.org/schemas/MTConnectError_1.1.xsd">
3.	  <Header creationTime="2010-03-12T12:33:01" sender="localhost" version="1.1" bufferSize="131072" instanceId="1268463594" />
4.	  <Error errorCode="OUT_OF_RANGE" >Argument was out of range</Error>
5.	</MTConnectError>

An MTConnect® document MUST include the Header for all documents and one Error element.

Figure 7: MTConnectError Elements

Header Attributes

Figure 7: Header Attributes

The nextSequence, firstSequence, and lastSequence number MUST be included in sample and current responses. These values MAY be used by the client application to determine if the sequence values are within range. The testIndicator MAY be provided as needed.

Details on the meaning of various fields and how they relate to the protocol are described on the protocol page. The standard specifies how the protocol MUST be implemented to provide consistent MTConnect® Agent behavior.

The instanceId MAY be implemented using any unique information that will be guaranteed to be different each time the sequence number counter is reset. This will usually happen when the MTConnect® Agent is restarted. If the Agent is implemented with the ability to recover the event stream and the next sequence number when it is restarted, then it MUST use the same instanceId when it restarts.

The instanceId allows the MTConnect® Agents to forgo persistence of Events, Condition, and Samples and restart clean each time. Persistence is a decision for each implementation to be determined. This is further discussed on the fault tolerance page.

The sender MUST be included in the header to indicate the identity of the Agent sending the response. The sender MUST be in the following format: http://<address>[:port]/. The port MUST only be specified if it is NOT the default HTTP port 80.

The bufferSize MUST contain the maximum number of results that can be stored in the Agent at any one instant. This number can be used by the application to determine how frequently it needs to sample and if it can recover in case of failure. It is the decision of the implementer to determine how large the buffer should be.

As a general rule, the buffer SHOULD be sufficiently large to contain at least five minutes’ worth of Events, Condition, and Samples. Larger buffers are more desirable since they allow longer application recovery cycles. If the buffer is too small, data can be lost. The Agent SHOULD NOT be designed so it becomes burdensome to the device and could cause any interruption to normal operation.