Extending the Schema

From MTConnect® User's Portal
Revision as of 05:31, 28 February 2014 by Will (Talk | contribs)

Jump to: navigation, search

MTConnect was designed with various extension points that are created as substitution groups. These extension points allow for new elements to be created that have certain properties that must be inherited from the parent to provide consistency for an application. There are three places where the MTConnect schema can be extended using an additional namespace: 1. New components can be added, 2. new data item types can be added, and 3. new asset types or measurements can be added. Each requires extending one of the three main XSD schema file. The XSD can be extended using a separate namespace in a separate XSD file and importing the base MTConnect XSD or you can use the schema generator to create the file for you.

Adding a new Component

Adding a new Data Item Type

The header must look something like the following:

  1. <xs:schema xmlns:xs='http://www.w3.org/2001/XMLSchema' xmlns='urn:example.com:ExampleStreams:1.2' 
  2.    xmlns:e='urn:example.com:ExampleStreams:1.2'
  3.   targetNamespace='urn:example.com:ExampleStreams:1.2' elementFormDefault='qualified' 
  4.   attributeFormDefault='unqualified' xmlns:mt='urn:mtconnect.org:MTConnectStreams:1.2'>
  5.   <xs:import namespace='urn:mtconnect.org:MTConnectStreams:1.2' 
  6.                     schemaLocation='/schema/MTConnectStreams_1.2.xsd'/>

The header needs to be modified slightly to include the new namespace e and MTConnect must remain the default namespace. The statements on lines 2 and 3 show how this is done. The MTConnect namespace m should always be assigned to MTConnect, this will make sure the agent operates correctly when generating XML.

The schema locations should also point to the local storage for these XSD files. It is best to have the agent serve the files up directly so there are no version issues when you deploy the files. I will cover agent configuration later in the document.

Line #5 contains the import statement for the MTConnect schema. This will include the base schema into the extended schema and resolve all the references. Specifying it as in the header will work with all validation tools with the C++ Reference MTConnect agent.

Next we are going to add a new data item called CommonVariable. The first thing we need to add is a type signature for the common variable. This is going to be a floating point value or UNAVAILABLE. The value can be anything you like, the only caveat is that Samples MUST be floating point numbers and Events are just text.

  1.   <xs:complexType name='CommonVariableType'>
  2.     <xs:annotation>
  3.       <xs:documentation>
  4.         A variable value
  5.       </xs:documentation>
  6.     </xs:annotation>
  7.     <xs:simpleContent>
  8.       <xs:restriction base='mt:EventType'>
  9.         <xs:pattern value='[+-]?\d+(\.\d+)?(E[+-]?\d+)?|UNAVAILABLE'/>
  10.       </xs:restriction>
  11.     </xs:simpleContent>
  12.   </xs:complexType>
  13.   <xs:element name='CommonVariable' type='CommonVariableType' substitutionGroup='mt:Event'>
  14.     <xs:annotation>
  15.       <xs:documentation>
  16.         A variable value
  17.       </xs:documentation>
  18.     </xs:annotation>
  19.   </xs:element>

We need to first create the CommonVariableType to show how to and we specify the content as simpleContent meaning there is no structure, just some data and we need to extend the mt:EventType which is the type for the substitutionGroup mt:Event. mt is the namespace for the MTConnect schema. The pattern we are going to use is a floating point number of UNAVAILABLE, this is a restriction on the base xs:string type in Event.

The next piece declares the element with the name "CommonVariable" and make it a member of the substitution group mt:Event. This allows us to use this within the <Events>...</Events> area of the component stream. The new entity can now be used by placing the following line in the Devices.xml:

   <DataItem type="x:COMMON_VARIABLE" category="EVENT" id="cv1" name="reg_1" />

There is no need to extend the Devices schema since the pattern for the type includes the ability to use a namespace prefix as a way to indicate that we are now in an extended space.

Once you have your XSD file completed, you will need to configure the MTConnect agent to include this schema as the default when it serves the XML documents. The following lines should be added to the agent configuration:

  1. StreamsNamespaces {
  2.   x {
  3.     Urn = urn:example.com:ExampleStreams:1.2
  4.     Location = /schemas/ExampleStreams_1.2.xsd
  5.     Path = ./Schemas/ExampleStreams_1.2.xsd
  6.   }
  7. }
  9. Files {
  10.   schemas { 
  11.     Location = /schemas/
  12.     Path = ./Schemas/
  13.   }
  14. }

The first section declares that there is a new namespace (we're calling it x (it does not have to match the e above). The URN needs to match URN as declared at the top of the previous xsd (xmlns='urn:example.com:ExampleStreams:1.2' ) and the location will tell it where the file lives when referenced in the XML document. The Actual path of the file is in the Schema subdirectory.

The next Files section tells the agent that it should look for the standard MTConnect schema files in the Schemas directory and prefix them with the location /schema/. That allows it to serve these file correctly if the they are request when referenced by the import above.