About the XML for Visio schema

About the XML for Visio schema

This content is no longer actively maintained. It is provided as is, for anyone who may still be using these technologies, with no warranties or claims of accuracy with regard to the most recent product version or service release.

Microsoft Visio 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.

An XML for Visio 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.

Representation of containment hierarchy of an XML for Visio file

XML for Visio tags represent the containment hierarchy. The following tags describe the preceding graphic:

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

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

The XML for Visio hierarchy contains two major structures:

• The VisioDocument structure The root element of the document structure, VisioDocument, and its immediate child elements specify properties of the document as a whole. Many of the elements at this level of the hierarchy correspond to objects and properties exposed in the Visio object model and described in the Microsoft Visio Automation Reference.

• The sheet structure In a Visio file, certain containers represent sheets. A sheet is a collection of cells that specifies properties of the object represented by the sheet. These sheets are commonly referred to in the application as ShapeSheet spreadsheets. In an XML for Visio file, there are four elements that represent sheets—the DocumentSheet, PageSheet, Shape, and StyleSheet elements.

The root element of an XML for Visio document is called VisioDocument, and contains the child elements described in the following table.

The child elements of VisioDocument must appear in an XML for Visio 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 an XML for Visio 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 (similar to Microsoft Excel functions), and references to the values of other cells.

Four elements represent sheets in XML for Visio: 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.

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 XML for Visio 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 three optional attributes:

• The F attribute specifying the formula expression itself. This attribute can contain the string "someFormula" if the formula exists locally, "No Formula" if the formula doesn't exist, 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 specifying 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 XML for Visio 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.

In a Visio sheet and in the ShapeSheet window, rows are organized into sections. In the XML for Visio 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 XML for Visio.)

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.)

• 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 an XML for Visio 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