Visio Schema Overview

Microsoft® Office Visio® 2003 provides an XML vocabulary, or schema, that defines all the XML tags for a Visio document's data elements and attributes and their containment relationships. Software tools and programs that handle XML use the schema to validate XML files.

Note In previously published materials, including the Microsoft Office Visio 2003 SDK, the XML schema that is explained in this document was referred to as "XML for Visio." From now on, the schema will be known as DatadiagramML.

A DatadiagramML file, like a Visio drawing (VSD) file, contains document-level containers and hierarchical containers of other containers. Following is a graphical representation of the containment hierarchy of a Visio file.

DatadiagramML tags represent the containment hierarchy. The following tags describe the preceding graphic:

Note In practice, the StyleSheet, Master, Shape, and Page elements require an ID attribute.

The root element of a DatadiagramML document is called VisioDocument, and it contains the child elements described in the following table.

VisioDocument child element	Contains
DocumentProperties	Document properties such as the title, author, and so on
DocumentSettings	Document settings such as glue, snap, and so on
Colors	The document's color table
FaceNames	Information about each of the fonts in the document
StyleSheets	A sheet for each style in the document
DocumentSheet	The document's sheet
Masters	The document's masters
Pages	The document's pages
Windows	Descriptions of windows that open when the document opens
EventList	The document's event items
HeaderFooter	Header and footer properties
VBProjectData	A Microsoft Visual Basic for Applications (VBA) project
EmailRoutingData	E-mail routing information
SolutionXML	Custom XML for your solution

The child elements of VisioDocument must appear in a DatadiagramML file in the order described in the schema (and in the preceding table). All the child elements of VisioDocument do not need to be present in a DatadiagramML file, but if a child element of VisioDocument is out of order, Visio displays a warning message when the file is loaded and ignores the contents of the element.

Two of the immediate children of the VisioDocument element are hierarchical containers— the Masters and Pages elements. The Masters element contains Master elements, and the Pages element contains Page elements. (Also, each Master and Page element can contain a PageSheet element.)

Each Master and Page element can contain a Shapes element, which contains Shape elements. In turn, each Shape can have its own Shapes collection (for example, a group shape contains a Shapes element).

<VisioDocument>
   ...
   <Masters>
      <Master>
         <Shapes>
            <Shape>
            ...
      ...
   <Pages>
      <Page>
         <Shapes>
            <Shape>
            ...
      ...
...

Note In practice, the Master, Shape, and Page elements require an ID attribute.

The order of child elements in the Pages and Shapes elements has special meaning:

In the Pages element, the order in which the Page elements appear determines the order of their appearance in the Visio user interface and in the Automation collections.
In the Shapes element, the order in which the Shape elements appear determines the display-list order of the shapes. The first Shape child element is the shape that has the bottommost z-order.

View the document hierarchy

A sheet is a collection of formulas and values that are organized in a spreadsheet-like table and define the appearance and behavior of objects in Visio. These formulas and values are contained in cells, which are organized in groups called rows, which are in turn organized into groups called sections. In the Visio user interface, these sheets are commonly referred to as ShapeSheet spreadsheets.

Cell formulas are expressions that evaluate to numeric or string values and other data types, such as those listed in Units of Measure. The formula expressions can contain numeric and string constants, ShapeSheet functions (which are similar to Microsoft Office Excel functions), and references to the values of other cells.

Four elements represent sheets in DatadiagramML: DocumentSheet, StyleSheet, PageSheet, and Shape. These elements are shown in the following excerpt from a VDX file:

<VisioDocument>  
      ...
      <DocumentSheet>
      ...
      <StyleSheets>
         <StyleSheet>
         ...
      <Masters>
         <Master>
            <PageSheet>
            <Shapes>
               <Shape>
               ...
         ... 
      <Pages>
         <Page>
            <PageSheet>
            <Shapes>
               <Shape>
               ...
         ...

Note In practice, the Master, Shape, Page, DocumentSheet, StyleSheet, and PageSheet elements require an ID attribute.

Consider this fragment of the sheet for a Visio shape as viewed in the ShapeSheet window.

A fragment of a sheet for a Visio shape (the Shape Transform section in the ShapeSheet window)

The Height cell contains the formula '=GUARD(Width)'. GUARD is a function that protects the formula from being overridden by Visio. The GUARD function takes a single parameter, in this case Width, which is a reference to another cell, the Width cell. Defining the Height cell in this way ensures that the shape's width will always be the same as its height.

In DatadiagramML format, the preceding ShapeSheet fragment looks like the following:

<XForm>
   <PinX>3.75</PinX>
   <PinY>6.75</PinY>
   <Width Unit='IN'>6.5</Width>
   <Height Unit='IN' F='Guard(Width)'>6.5</Height>
   <LocPinX Unit='IN' F='Width*0.5'>3.25</LocPinX>
   <LocPinY Unit='IN' F='Height*0.5'>3.25</LocPinY>
   <Angle>0</Angle>
   <FlipX>0</FlipX>
   <FlipY>0</FlipY>
   <ResizeMode>0</ResizeMode>
</XForm>

The XForm element represents the Shape Transform row, which appears as a section in the ShapeSheet window. The child elements— PinX, Width, and so on, correspond to cells in the row. The F attribute contains the cell's formula. The cell's value is the value of the element.

Elements that represent cells in a sheet contain formulas and values. The element's value specifies the cell formula's last valid computed value. If the last computed value is an error, the element value remains unchanged and an Err attribute is added.

Cell elements can have any of the following four optional attributes:

The F attribute, which specifies the formula expression itself. This attribute can contain one of the following strings: "someFormula" if the formula exists locally, "No Formula" if the formula is locally deleted or blocked, or "Inh" if the formula is inherited.
If a formula is a simple constant and matches the value of the element, the F attribute is optional and may be omitted.
The Err attribute, which is present if the formula evaluates to an error. The text within the Err attribute represents the current value (an error message string); the value of the element is the last valid value, for example: <Width F='Height/0' Err='#DIV/0!'>3</Width>.
For more details on errors than can appear in the Err attribute, see About error values.
The Unit attribute, which specifies the element's unit of measure. This attribute determines how Visio displays the value, and its value is an enumerated type. For possible values for the Unit attribute, see Units of Measure.
Because each DatadiagramML element has a default unit that Visio uses if the Unit attribute is not present, you only need to include a Unit attribute if you want to use a unit other than the default. To find out the default unit of a particular element, see that element's topic in this reference.
The value of a cell element is always expressed in internal units. For example, units that are a measurement of length determine that the values are interpreted as floating point numbers in inches (internal units). If an element has a value of 2 feet, its Unit attribute is 'FT' for feet and its value is the number 24.
Other units, such as date/time, are expressed as formatted strings. In the case of date/time, it is a string like "2000-12-20T23:00:00". For a list of the possible value formats, see Units of Measure.
The V attribute, which indicates a null string (as opposed to an empty string) in elements whose Unit attribute is STR.

In a Visio sheet and in the ShapeSheet window, rows are organized into sections. In the DatadiagramML schema, however, sections are implied (with the exception of Geometry) and rows are immediate children of the root sheet (DocumentSheet, StyleSheet, PageSheet, or Shape). (For details on Geometry sections, see Working with Geometry in DatadiagramML.)

Some elements that represent rows can appear only once in a sheet; others can appear multiple times in a sheet. For instance, a shape's sheet can contain one and only one XForm element, but it can contain any number of Scratch elements.

Those elements that appear more than once must be identified within the sheet by special attribute tags. Some multirow types are identified by index, and other types are identified by name.

Indexed elements can have an IX attribute with an integer value; the first index is 0, the second 1, and so on. (If the IX attribute is not included, Visio automatically assigns the elements in ascending order.)

Note The IX attribute in geometry elements is one-based.
Named row elements can have a Name, NameU, or ID attribute (or any combination of these attributes) with a string value. Named row elements can appear in any order within a sheet. If the row isn't named, Visio outputs the ID by default and fabricates a name from the ID (for example, for ID='1', Visio creates Name='Row_1'). If the Name and NameU string values are identical, Visio outputs only the NameU attribute.

When Visio emits a DatadiagramML file, elements that represent cells are reordered in the order defined in the schema (and reflected in the tag hierarchy in this reference), but the order that Visio emits elements that represent sheet rows and Geometry sections is arbitrary.

View the sheet hierarchy