XMLBuilderDiagram XML Schema Definition

The XML builder works from XML files. The purpose of this topic is to describe how these XML files must be built so that they can be correctly decoded by the XML builder.

About XML and XSD files

Extensible Markup Language (XML) is similar to Hypertext Markup Language (HTML). An HTML file contains both data and information about how it's presented. An XML file contains data only.

XML data is embedded within tags that add meaning. For example, <price>24</price> declares the numeral 24 to be a price. In XML terms, this price is referred to as an element. Other elements might be product names, quantities, or totals. While a person can look at the XML tag and determine that 24 is a price, it's more important that software can extract price elements from the file; this isn't possible with the HTML file.

An XML file is based on an XML Schema Definition (XSD). An XSD file provides the syntax and defines the way in which elements and attributes can be represented in an XML document; it defines a type of XML document in terms of constraints on what elements and attributes may appear and their relationship to each other, what types of data may be in them, and other things.

XMLBuilderDiagram XSD file in details

The XMLBuilderDiagram XML schema definition is the XML schema that provides the syntax for the XML files that can be decoded by the ArcGIS Schematics XML Builder. This XSD file is installed by default in \ArcGIS\Schematics\XMLSchema.

Any XML file that is compatible with the XML Builder starts and ends with the Diagrams tag:

Elements within <Diagrams> tags

<?xml version="1.0" encoding="utf-8"?>
<sch:Diagrams xmlns:sch = 'http://www.esri.com/schemas/ArcGIS/10/Schematics'
              xmlns:xsi = 'http://www.w3.org/2001/XMLSchema-instance'
              xsi:schemaLocation='http://www.esri.com/schemas/ArcGIS/10/Schematics XMLBuilderDiagram.xsd'>
...
 </Diagrams>

Several diagrams can be stored in an XML file; the definition of each starts with the Diagram tag:

Elements within <Diagram> tags

<?xml version="1.0" encoding="utf-8"?>
<sch:Diagrams xmlns:sch = 'http://www.esri.com/schemas/ArcGIS/10/Schematics'
              xmlns:xsi = 'http://www.w3.org/2001/XMLSchema-instance'
              xsi:schemaLocation='http://www.esri.com/schemas/ArcGIS/10/Schematics XMLBuilderDiagram.xsd'>
  <Diagram DiagramTemplateName="All" DiagramName="All" EnforceDiagramTemplateName="false" EnforceDiagramName="false">
   ...
  </Diagram>                
 </Diagrams>

DiagramTemplateName and DiagramName are optional parameters. When the EnforceDiagramTemplateName or EnforceDiagramName parameter are False, the diagram template name and diagram name need to be redefined on the New Schematic Diagram dialog box.

The following sections are then expected for each diagram:

• The first possible tag for a diagram is PropertySet, which can be used to define property values related to the diagram. This section is optional:

  Elements within <PropertySet> tags

  <Diagram EnforceDiagramTemplateName="false" EnforceDiagramName="false">
    <PropertySet>
      <PropertyArray>
        ...
      </PropertyArray>
    </PropertySet>      
    ...
  </Diagram>

  Each property value related to a PropertySet starts with the PropertySetProperty tag, inside of which the Key and Value items are weighted. Several PropertySetProperty items can be specified:

  Elements within <PropertySetProperty> tags

  <PropertySet>
    <PropertyArray>
      <PropertySetProperty>
        <Key>Country</Key>
        <Value>CALIFORNIA</Value>
      </PropertySetProperty>
      <PropertySetProperty>
        ...
      </PropertySetProperty>
    </PropertyArray>  
  </PropertySet>

  The Key tag defines the name of the property and the Value tag, which is its value.
• The second possible tag for a diagram is Datasources, which details all the data sources that can be related to the diagram and its content.

  Elements within <Datasources> tags

  <Diagram EnforceDiagramTemplateName="false" EnforceDiagramName="false">
    ...
    <Datasources>
       ...
    </Datasources>
    ...
  </Diagram>

  Each Datasource definition is based on two required items: NameString and WorkSpaceInfo; NameString being the data source name and WorkSpaceInfo regrouping parameters that define the data source type and connection properties (PathName, BrowseName, WorkspaceFactoryProgID, WorkspaceType, ConnectionProperties).

  Elements within <Datasource> tags

  <Datasources>
    ...
    <Datasource>
      <NameString>XMLDataSource</NameString>
      <WorkSpaceInfo>
        <WorkspaceFactoryProgID>esriDataSourcesGDB.AccessWorkspaceFactory</WorkspaceFactoryProgID>
        <PathName>C:\ArcGIS\ArcTutor\Schematics\DatasetEditor\XMLDataAssociatedFeatureClasses.mdb</PathName>
      </WorkSpaceInfo>          
    </Datasource>
    ...
  </Datasources>

• The last expected section is Features, which details all the schematic features contained in the diagram.

  Because four kinds of schematic features can be displayed in schematic diagrams (node, link, node on link, and sublink), four kinds of tags can be defined in this section: NodeFeature, LinkFeature, NodeOnLinkFeature, and SubLinkFeature:

  Elements within <Features> tags

  <Diagram EnforceDiagramTemplateName="false" EnforceDiagramName="false">
    ...
    <Features>
      <NodeFeature>
        ...
      </NodeFeature>
      ...
      <LinkFeature>
        ...
      </LinkFeature>
      ...
          <NodeOnLinkFeature>
        ...
      </NodeOnLinkFeature>
      ...
      <SubLinkFeature>
        ...
      </SubLinkFeature>
      ...
    </Features>
  </Diagram>

  • Two specific attributes are mandatory for a feature element, regardless of its type: FeatureClassName, which references the name of the schematic feature class that implements this schematic feature in the schematic diagram, and ExternalUniqueID, which corresponds to the schematic feature identifier.
  • Then, several optional parameters can be found for a feature element such as: DatasourceName, UCID, UOID, and USID (the ClassID, ObjectID, and subtype ID of the associated GIS feature/object in the DatasourceName database when a GIS feature/object is related to the schematic feature); RelatedContainerID (the ID of the schematic feature's container); and PropertySet (that details all the property values related to the schematic feature).
  • Specific attributes can or must be defined for schematic features, depending on their type:
    • For a NodeFeature type, the InitialX and InitialY optional attributes can also be set to specify the x- and y-coordinates of the schematic feature:

      Following is a sample of a NodeFeature element:

      Elements within <NodeFeature> tags

      <NodeFeature>
              <FeatureClassName>Stations</FeatureClassName>
              <ExternalUniqueID>Station-1</ExternalUniqueID>
              <DatasourceName>XMLDataSource</DatasourceName>
              <UCID>1</UCID>
              <UOID>1</UOID>
              <RelatedContainerID>Container-1</RelatedContainerID>
              <InitialX>-4462</InitialX>
              <InitialY>2828</InitialY>
              <PropertySet>
                <PropertyArray>
                  <PropertySetProperty>
                    <Key>Feeder</Key>
                    <Value>1</Value>
                  </PropertySetProperty>
                  <PropertySetProperty>
                    <Key>Name</Key>
                    <Value>WABY</Value>
                  </PropertySetProperty>
                  <PropertySetProperty>
                    <Key>Capacity</Key>
                    <Value>1</Value>
                  </PropertySetProperty>
                <PropertySetProperty>
                  <Key>Type</Key>
                  <Value>A</Value>
                </PropertySetProperty>
                </PropertyArray>  
              </PropertySet>      
            </NodeFeature> 

    • For a LinkFeature type, the FromNode and ToNode attributes are mandatory. They must reference the NodeFeature identifiers related to the origin and extremity nodes. The Vertices tag can also be found to specify the set of Vertex that can be displayed along the link, each vertex being displayed at the x- and y-coordinates.

      Following is a sample of a LinkFeature element:

      Elements within <LinkFeature> tags

      <LinkFeature>
              <FeatureClassName>LV_Lines</FeatureClassName>
              <ExternalUniqueID>LVLine-52</ExternalUniqueID>
              <DatasourceName>XMLDataSource</DatasourceName>
              <UCID>5</UCID>
              <UOID>52</UOID>
              <FromNode>Station-33</FromNode>
              <ToNode>Station-45</ToNode>
              <PropertySet>
                <PropertyArray>
                  <PropertySetProperty>
                    <Key>Rate</Key>
                    <Value>452456</Value>
                  </PropertySetProperty>
                  <PropertySetProperty>
                    <Key>Category</Key>
                    <Value>S</Value>
                  </PropertySetProperty>
                </PropertyArray>
              </PropertySet>
              <Vertices>
                <Vertex>
                  <X>-562.37451</X>
                  <Y>-2935.90906</Y>
                </Vertex>
                <Vertex>
                  <X>-192.067429999999</X>
                  <Y>-3254.90854</Y>
                </Vertex>
                <Vertex>
                  <X>509.88013</X>
                  <Y>-3298.78026</Y>
                </Vertex>
              </Vertices>
            </LinkFeature>

    • For a NodeOnLinkFeature type, the ReferenceLink and InitialPosition mandatory attributes are expected. The ReferenceLink specifies the LinkFeature identifier the node on link is related to, and the InitialPosition is used to specify the absolute or relative position of the node on link on its related link.

      Following is a sample of a NodeOnLinkFeature element:

      Elements within <NodeOnLinkFeature> tags

      <NodeOnLinkFeature>
              <FeatureClassName>NOL</FeatureClassName>
              <ExternalUniqueID>N1</ExternalUniqueID>
              <DatasourceName>myDS</DatasourceName>
              <InitialPosition>0.5</InitialPosition>
              <ReferenceLink>L1</ReferenceLink>
            </NodeOnLinkFeature>

    • For a SubLinkFeature type, the ReferenceLink,FromNode, and ToNode mandatory attributes are expected. The ReferenceLink specifies the LinkFeature identifier the sublink is related to, and the FromNode and ToNode reference the NodeFeature identifiers that are related to the origin and extremity nodes of the sublink.

      Following is a sample of a SubLinkFeature element:

      Elements within <NodeOnLinkFeature> tags

      <SubLinkFeature>
              <FeatureClassName>LOL</FeatureClassName>
              <ExternalUniqueID>S1</ExternalUniqueID>
              <DatasourceName>myDS</DatasourceName>
              <FromNode>N1</FromNode>
              <ToNode>R2</ToNode>
              <ReferenceLink>L1</ReferenceLink>
            </SubLinkFeature>

XMLBuilderDiagram data model

The following figure shows the XML Schema Definition of the XMLBuilderDiagram file:

XML file samples based on the XMLBuilderDiagram XSD file

The following figure shows a basic XML file sample that includes a description of one diagram containing a unique node schematic feature:

The following figure shows a sample extraction of an XML file that includes a description of one diagram containing a link schematic feature:

For a more detailed XML file sample based on the XMLBuilderDiagram XML Schema Description file, open the SampleNetworkData.xml file provided with the Tutorial setup. It should be installed in C:\ArcGIS\ArcTutor\Schematics\Schematics_Configuration\XML_Data.