Share via

Visio Schema Overview

  • Article

Microsoft® Visio® 2010 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." The schema is now 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.

XML_01_ZA07645865.gif" alt="Graphical representation of the containment hierarchy of a Visio file"

[Caption] Representation of containment hierarchy of a DatadiagramML file

DatadiagramML 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 DatadiagramML 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 2010 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 a DatadiagramML file, there are four elements that represent sheets—the DocumentSheet, PageSheet, Shape, and StyleSheet elements.

    Sheets contain cells, each of which has a formula. The cells are organized into rows, and the rows into sections. Most of the elements in the sheet structure correspond to the sections, rows, and cells defined in the Microsoft Visio 2010 ShapeSheet Reference.

    Note

    Although the DatadiagramML schema allows any type of sheet data in any type of sheet, we recommend that you restrict data to that allowed by the ShapeSheet and Automation interfaces. For instance, the schema allows geometry in a style, but Automation does not. If you supply nonstandard data in an XML file, it might not be fully supported by Visio even if it loads successfully.

VisioDocument structure

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

DataConnections

The DataConnection elements for the document

DataRecordsets

All the DataRecordset elements in the document

RibbonX

The Ribbon XML string that is passed to the document to customize the ribbon user interface

UserCustomUI

The Ribbon XML string that is passed to the document to customize the Quick Access toolbar or the ribbon

Validation

Information about diagram validation for the document.

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

Sheet structure

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

XML_10_ZA07645878.gif" alt="A fragment of a sheet for a Visio shape (the Shape Transform section in the ShapeSheet window)">

The Height Cell (Shape Transform Section) 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 sheet cells

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:

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

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

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

    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.

  4. The V attribute, which indicates a null string (as opposed to an empty string) in elements whose Unit attribute is STR.

Elements that represent sheet rows and sections

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 multi-row types are identified by index, and other types are identified by name.

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

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