XML for Visio Schema

This document, dated 17-March-2001, is for design reference only and is subject to change. This material is to be used for reference only and is intended only to enable prototyping and not for production use.

© Copyright Microsoft Corporation, 2001. All rights reserved. Microsoft Confidential

Contents

Contents
Introduction and Goals
Features of the XML for Visio file format
Structure of the XML for Visio schema
        VisioDocument Structure
                VisioDocument Tag Hierarchy
        ShapeSheet Structure
                ShapeSheet Tag Hierarchy
                Inheritance
Technical Notes
        Namespaces
        Versioning
        XML for Visio Integrity Check
        Extensibility by Solutions
        Style 0
        Round-tripping Issues
VisioDocument Tag Hierarchy
ShapeSheet Tag Hierarchy
Tag Reference
Appendixes
        Unit of Measure Table

Introduction and Goals

This specification describes a new file format for native data in Microsoft Visio. This new format, called XML for Visio, is based on XML (eXtensible Markup Language) syntax, is capable of describing Visio data with as much fidelity as VSD format, and is intended to provide open access to data in Visio and to enable more open exchange of Visio data with other applications. 

In addition, by using the Save as Web Page feature, users can publish Visio drawings to the Web and at the same time generate a XML for Visio file that will permit round-tripping-re-opening the file in Visio without loss of data.

Features of the XML for Visio file format

The following list provides a brief summary of some of the most important features of the XML for Visio format:

  • Full Fidelity  The XML for Visio format offers full-fidelity: that is to say, it is possible to write any Visio document as a XML for Visio file and read it back in to the same version of Visio without data loss.
  • Understandable by developers  In order to offer full fidelity, the XML for Visio format requires considerable complexity. However, developers who have a knowledge of Visio (the Automation and ShapeSheet models in particular) will have no trouble understanding the format and, with a reasonable amount of effort, writing software that uses it.
  • Represents complete documents or individual shapes or other data  The XML for Visio schema is organized so that individual shapes and masters can be represented without requiring the complete document structure. In practice, this means that Visio can both emit individual objects as XML for Visio data and read in and merge such objects.
  • Extensible with SolutionXML  XML is an increasingly important format for storing all types of data. Visio solutions can save data in XML format into the XML for Visio stream and access it using standard XML tools externally to Visio, or from within Visio at runtime. (See the Technical Note section.)

Structure of the XML for Visio schema

A XML for Visio file is an XML document that contains all of the components of a binary VSD file. A XML for Visio file, like a VSD file, contains document-level containers and hierarchical containers of other containers. 

VisioDocument Structure

The root element of a XML for Visio document is called VisioDocument. The VisioDocument element may contain several sub-elements. Some sub-elements, such as DocumentProperties, VBProject, DocumentSheet, Colors, and Fonts represent document-level containers. Three special sub-elements -- StyleSheets, Masters and Pages -- represent collections of shapes and ShapeSheets.

The DocumentProperties element contains document properties such as the title, author, and so forth. The VBProject element contains a VBA project. The DocumentSheet contains the document's ShapeSheet. The Colors and Fonts elements contain the document's color and font tables. The StyleSheets element contains the StyleSheet elements.

A XML for Visio file may contain two hierarchical containers. The Masters element contains Master elements, and the Pages element contains Page elements. Each Master and Page may contain a Shapes element which contain Shape elements. Each Shape may in turn have its own Shapes collection, and so on.

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

The order in which the objects appear in the collection has a special meaning. In the Pages collection, the order of the Page elements is the order in which pages appear in the Visio user interface and in the automation collections.

The order in which the Shape elements appear in a Shapes collection determines the display-list order of the shapes. The first Shape in the collection is the shape that has the bottom-most Z-order.

Element Attributes

The Masters, Pages, and Shapes elements contain Shape elements. Shape elements inherit properties and behaviors from associated Master elements and StyleSheet elements. Visio uses special attribute tags on the Shape and the parent elements to determine if a Shape inherits from a Master or a StyleSheet. The following table describes these attributes. Inheritance is described in more detail in the Inheritance section.

Click on the Element name or an attribute name to see a full description.

StyleSheet

Master

Page

Shape

Description

ID

ID

ID

ID

A unique ID within the object's container.

 

UniqueID

 

UniqueID

A globally unique ID (a GUID)

Name

Name

Name

Name

A unique Name within the container.

NameU

NameU

NameU

NameU

A universal Name -- a name that is not localized.

 

BaseID

 

 

A globally unique ID (a GUID) of a master.

 

 

 

Master

The ID of the master that this shape inherits.  Top-level shapes on a page that are instances of a master must have a valid Master attribute.  Mutually exclusive with ShapeInMaster below.

 

 

 

MasterShape

This is the ID of a shape in a Master that this shape inherits.  Establishes a linkage between an instance of a shape and its Master's shape.  Sub-shapes of a master instance group shape must have this attribute.  Mutually exclusive with Master above.

LineStyle

 

 

LineStyle

ID of the Line Style that this shape or style inherits.

FillStyle

 

 

FillStyle

ID of the Fill Style that this shape or style inherits.

TextStyle

 

 

TextStyle

ID of the Text Style that this shape or style inherits.

  

 

 

Del

Del is a boolean attribute.  It is only meaningful if the shape is part of a master instance.  If true (1), then the shape instance is deleted locally.

 

 

 

Type

Type is an enumerated attribute.  It may be one of the following values: Shape, Group, Guide, Foreign.

VisioDocument Tag Hierarchy

The complete structure of the VisioDocument and it's sub-elements are illustrated in the figure below.  Click on any element in the figure to jump to a description of that element.

The child elements of the root element, VisioDocument, must appear in the order shown below.  If a child element of VisioDocument is out of order, Visio will show a warning message when the file is loaded and may ignore the contents of the element.

ShapeSheet Structure

A ShapeSheet is a collection of formulas and values organized in a spreadsheet-like table that defines the appearance and behavior of an object in Visio. These formulas and values are contained in cells. Cells are organized in groups called rows. Rows may in turn be grouped into sections. Cell formulas are expressions that evaluate to numeric or string values. The formula expressions may contain numeric and string constants, ShapeSheet functions (similar to Microsoft Excel functions), and references to the values of other cells.

Four element types defined in the XML for Visio schema are used to represent a Visio ShapeSheet: DocumentSheet, StyleSheet, PageSheet, and Shape. Consider this fragment of the ShapeSheet of a Visio Shape:

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 ShapeSheet fragment shown above will look like this:

<XForm>
    <
PinX Unit="in_f" F=""> 3.75 </PinX>
    <
PinY Unit="in_f" F=""> 6.75 </PinY>
    <
Width Unit="in_f" F=""> 6.5 </Width>
    <
Height Unit="in_f" F="GUARD(Width)"> 6.5 </Height>
</
XForm>

The XForm element represents the Shape Transform row. The sub-elements-PinX, Width, and so forth, represent cells in the row. The V and F elements represent the cells' values and formulas.

Cells

Shapesheet cells contain formulas and values.  Each cell element may have a value which specifies the cell formula's last valid computed value (LVCV).  Each cell also may have an F attribute specifying the formula expression itself.  Another optional attribute is the Err sub-element which is present if the formula evaluates to an error.  The text within the Err attribute represents the last computed value (LCV) which is an error message string.  If a formula evaluates to a constant value, the formula attribute F is null and the LVCV element V contains the constant value.

A cell element may have a single optional attribute, Unit.  Unit specifies a cell's unit of measure.  It determines how Visio will display the cell's value.  The value of the attribute is an enumerated type.  The possible values are listed in the Unit of Measure Table Appendix.

Units that are a measurement of length determine that the values are expressed as a floating point number in inches (Visio internal units).  For example, f a cell has a value of 2 feet, the cell's unit attribute is "FT" for feet, and its V element 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 "12/20/2000 23:00".  See the Unit of Measure Table for a list of the possible value formats.

Rows

Some row types may only appear once in a sheet; other row types may have multiple instances within a sheet.  For instance, a shape's ShapeSheet may contain one and only one XForm row, but it may contain any number of Scratch rows.  

Rows that may appear more than once must be identified within the sheet by special attribute tags. Some multiple rows are identified by index, and other types are identified by name. Indexed row elements must have an IX attribute with an integer value; the first index is 0, the second 1, and so on. Named rows must have a Name attribute with a string value. Rows may appear in any order within a ShapeSheet. When Visio emits a XML for Visio file, rows are reordered in the order of the ShapeSheet Tag Hierarchy diagram below. Within a group of indexed rows, the rows are arranged in IX value order. The order of named rows is arbitrary.

Text Rows

Four types of indexed rows represent runs of text attributes, Char, Para, Tabs, and Field.

Consider the following shape. It has some text that consists of two character runs, one bold and the other in italics.

The portion of the shape's ShapeSheet that describes character text runs is called the Characters section. The Character rows for this shape are as follows:

Notice that the column on the left, indicates the length of each run, 5 characters and 7 characters respectively. The only cells that vary between the two rows are the Style cell values. The Style cell determines if the run is bold, italics, or another style. The XML code for these rows is as follows:

<Char IX="0">
    <
Font F=""> 0 </Font>
    <
Size Unit="pt" F=""> 12 </Size>
    <
Scale Unit="%" F=""> 1 </Scale>
    <
Spacing Unit="pt" F=""> 0 </Spacing>
    <
Color F=""> 0 </Color>
    <
Style F=""> 1 </Style>
    ...
</
Char>
<
Char IX="1">
    <
Font F=""> 0 </Font>
    <
Size Unit="pt" F=""> 12 </Size>
    <
Scale Unit="%" F=""> 1 </Scale>
    <
Spacing Unit="pt" F=""> 0 </Spacing>
    <
Color F=""> 0 </Color>
    <
Style F=""> 2 </Style>
    ...
</
Char>

<Text><cp ix='0'/>Bold<cp ix='1'/> Italics.</Text>

The two Char elements represent the two Character rows.  Each has an IX (Index) attribute describing the relative order of the rows.  Each Char element contains a sub-element for each cell in the row.  The shape also contains an element called Text.  The Text element contains the characters of the text and special empty elements that mark the end of one run and the beginning of the next.

The <cp ix='1'/> tag indicates that the current character run has ended and the run attributed to Char row 1 has begun.

Four types of run marker elements may appear inside Text.  The <cp/> element marks Char runs, <pp/> marks paragraph runs, <tp/> marks Tabs runs, and <fld/> indicates a field position.

When Visio emits a XML for Visio file, all cp, pp, tp, and fld elements in the text will have ix values that are sequential. In other words, a <cp ix='1'/> will always precede a <cp ix='2'/> and so on. If Visio encounters run markers that are out of order when it reads a XML for Visio file, it will insert duplicates of the text run rows as needed. For example, say Visio reads the following file:

<Char IX="0"> <Style F=""> 0 </Style> </Char>
<
Char IX="1"> <Style F=""> 1 </Style> </Char>
<
Text>Plain <cp ix='1'/>Bold <cp ix='0'/>Plain again</Text>

When Visio re-saves it, it will look like this:

<Char IX="0"> <Style F=""> 0 </Style> </Char>
<
Char IX="1"> <Style F=""> 1 </Style> </Char>
<
Char IX="2"> <Style F=""> 0 </Style> </Char>
<
Text><cp ix='0'/>Plain <cp ix='1'/>Bold <cp ix='2'/>Plain again</Text>

Run marker elements at the very beginning of the text are not required, but are permissible. When Visio rewrites a XML for Visio file, it removes them in the new file.

Text Element

In the Visio engine, a block of text may contain ASCII control characters that represent tabs, line breaks, paragraph breaks, and field positions.

An ASCII 9, ASCII 10, or ASCII 13 character indicating a tab, paragraph break, or line break respectively are emitted as a normal ASCII character into XML for Visio.  These characters are considered legal Unicode characters by all XML parsers.

Any other ASCII control character between ASCII 0 and ASCII 31 (excluding ASCII 9, 10, and 13) are considered illegal Unicode characters by some XML parsers.  Therefore these characters will be translated into special character values in the Unicode Private Use Area.  The Private Use Area begins at 0xE000.  ASCII control characters will be offset by the value 0xE000 when emitted to XML for Visio.  Therefore, if a Visio shape's text contained the character ASCII 11 (Hex 0x0B), it will be emitted as 0xE00B.  

When Visio reads Text elements, it will translate any Unicode characters it encounters in the range 0xE000 to 0xE01F by subtracting 0xE000.

Geometry Sections

In a Visio ShapeSheet, all rows are organized into sections. The XForm row is part of the Object section, Scratch rows are part of the Scratch section, and so on. In the XML for Visio schema, the XForm element simply is in the root of a ShapeSheet element. 

All sections are implied in the XML for Visio file format with the exception of Geometry sections. Geometry row elements-MoveTo, LineTo, and so on- must be grouped within Geometry section elements because unlike other section types, more than one Geometry section may exist in a ShapeSheet. 

Geometry elements must have an IX attribute specifying the index. They may also have a Del='1' attribute which indicates that the section has been deleted locally.

ShapeSheet Tag Hierarchy

The Sheet diagram below describes the basic parts a ShapeSheet. The Cell diagram describes the structure of a single cell element. The ShapeSheet Tag Hierarchy lists all the possible Section, Row, and Cell names and their location within a ShapeSheet. Click an element to see its full description.

Inheritance

Visio ShapeSheets may inherit sections, rows, and cells from parent sheets. A shape on a page may have a master from which it may inherit all of its sections, rows, and cells. A shape or master may also inherit from styles and inherit the style's line, fill, and text attribute rows. A style may inherit from another style. 

The inheritance relationships are established in a XML for Visio file by means of attributes. 

All ShapeShape elements must have an ID tag. The ID is an integer value unique within the elements collection. A Shape that inherits from a document Master has a Master attribute whose value is the ID of the Master. The Shape inherits all of the sections, rows, and cells of the Master. 

Shapes and StyleSheets may inherit from up to three other StyleSheet elements. Three attributes of Shapes and StyleSheets, FillStyle, TextStyle, and LineStyle, may refer to another StyleSheet by ID. When a Shape or StyleSheet inherits from another StyleSheet, it only inherits rows relevant to the attribute. For example, when a Shape inherits a TextStyle attribute, it only inherits rows that effect text, such as TextBlock, Para, Char, Tabs, and so forth.

Local Overrides

A Shape that inherits from a Master is called an instance of the Master. An instance inherits all of the sections, rows and cells of the master. Therefore, the instance in a XML for Visio file does not explicitly express the sections, rows, and cells that it inherits. Consider the following code:

<Master ID='0'>
    <
XForm>
        <
PinX F=""> 1.0 </PinX>
        <
PinY F=""> 2.0 </PinY>
    </
XForm>
</
Master>
...
<
Shape ID='99' Master='0'/>

The Shape 99 inherits all the rows and cells of its Master 0. It does not explicitly express its PinX and PinY cells, but the Shape will behave as if they were present. If a Shape does explicitly express an inherited section, row, or cell, that component is locally overridden in the instance. Consider the following code:

<Master ID='0'>
    <
XForm>
        <
PinX F=""> 1.0 </PinX>
        <
PinY F=""> 2.0 </PinY>
    </
XForm>
</
Master>
...
<
Shape ID='99' Master='0'>
    <
XForm>
        <
PinX F=""> 2.0 </PinX>
    </
XForm>
</
Shape>

In this case, Shape 99 still inherits its Master's PinY cell value, but it has locally overridden the value of PinX to 2.0.

Local Deletion

A Shape may also suppress the appearance of a section, row, or formula in an instance. When an instance suppress a component, the component is locally deleted. Consider this example:

A Master that has three Geom sections.

An Instance of the Master where a Geom section has been locally deleted.

<Master ID='0'>
    ...
    <
Geom IX='0'> ... </Geom>
    <
Geom IX='1'> ... </Geom>
    <
Geom IX='2'> ... </Geom>
    ...
</
Master>

<Shape ID='99' Master='0'>
    ...
    <
Geom IX='2' Del='1'>
    ...
</
Shape>

In this example, the Master contains three Geom sections; suppose that each Geom represents a polygon. The Shape instance inherits from the Master, but it locally deletes the last Geom section. Therefore, the Shape only displays two polygons.

A Master is often composed of several separate Shapes. Furthermore, each Shape may have a collection of sub-Shapes. The IDs of a Master's shapes and sub-shapes are all unique within the Master. In an instance of a master, the master's sub-shapes may be re-expressed for the purposes of local overrides or local deletions. However, those sub-shapes must have their own IDs that are unique within the instance's page. Therefore, in order to maintain a link back to the Master's shapes, overridden shapes must have an separate attribute called ShapeInMaster. The value of this attribute is the ID of the Shape in the Master that this local shape is overriding.

Inheritance States

The following table describes all the possible inheritance states in which the ShapeSheet elements may exist.

State

Section

Row

V (LVCV)

F (Formula)

Err (LCV)

XML Example

1

inherited

inherited

inherited

inherited

inherited

empty

2

locally deleted

none

none

none

none

<Geom ix='1' del='1'/>

3

local

inherited

inherited

inherited

inherited

<Geom ix='1'/>

4

local

locally deleted

none

none

none

<Geom ix='1'> <LineTo ix='2' del='1'/> </Geom>

5

local

local

local

inherited

none

<PinX F="Inh"> 20 </PinX>

6

local

local

local

inherited

local

<PinX F="Inh" Err="#NUM!"> 20 </PinX>

7

local

local

local

locally deleted

none

<PinX F="No Formula"> 20 </PinX>

8

local

local

local

locally generated (constant)

none

<PinX> 20 </PinX>

9

local

local

local

locally explicit

none

<PinX F="Height*2"> 20 </PinX>

10

local

local

local

locally explicit

local

<PinX F="Height/0" Err="#DIV/0!"> 20 </PinX>

State 1 represents full inheritance. If a section, row, or cell inherits its state fully from its parent, the element simply does not appear within the instance. 

In state 2, a section has been locally deleted. This means that the section has been severed locally, blocking inheritance of the section and all its children. 

In state 3, a section is local, but its children are inherited from the master. 

In state 4, a row has been locally deleted. The row has been severed locally, blocking inheritance of the row and its children. 

States 5 and 6 represent cells that have a locally overridden value. 

In state 6, the Error value has also been overridden. The formula is inherited from the parent. 

State 7 is a special case in which the formula has been severed locally. In this state, the F element must contain the special string 'No Formula'. 

State 8 is the most common case. In this state, the formula evaluates to a constant value. The V element contains the constant value and the F element must be empty. 

States 9 and 10 are the next most common cases. In these states, the formula is a complex expression represented by a string that is not empty and not the string 'No Formula'. The V element contains a number, which is the last valid computed value. In state 10, the Err element is also present and contains a string representing the error state.

Technical Notes

Namespaces

Below is the namespace that will be referenced in documents saved in Visio:

Visio namespace:
 xmlns="urn:schemas-microsoft-com:office:visio"

The default namespace will be the XML for Visio schema namespace.

Any SolutionXML data or unknown XML data that appears within a XML for Visio file must also be prefixed with its own namespace. Visio will not attempt to process elements that are not within the default or o: namespace; it will cache those elements and save them back to the XML for Visio file.

Versioning

Future versions of Visio should be able to read Visio 10 XML for Visio with as little special processing as possible and with little or no loss.  Visio 10 should also be able to read XML for Visio output from future versions of Visio, but data loss will almost certainly happen, though some retention may be possible.  Basically we will follow the Office 2000 guidelines in this:  Visio 10 will open Visio 11+ XML for Visio files, but cannot guarantee full fidelity.

Future versions of Visio will add new data to the file format, which means new elements and attributes added to the XML schema.  Visio 10 should be able to read those future file formats with as much fidelity as possible and even roundtrip some of that data.  The XML for Visio parser must adopt a policy of ignoring but preserving unknown elements and attributes during load, and saving them back into the XML for Visio format.  No guarantees shall be made that any particular data will actually survive the roundtrip, and none of the new data will survive save as VSD.  Note that this is closely related to Extensibility by Solutions.  If the file is edited, the validity of the new elements and attributes is also not guaranteed:  for example if new cells are added to a row and they have formulae, values will not be recalculated and after editing the formulae may be invalid (for example by referring to deleted objects).

XML for Visio Integrity Check

XML for Visio files that have been saved by the Visio engine will be "stamped" with a special processing instruction. The processing instruction will contain a hashed key value. When Visio opens the file, it will first pass over the file contents and compute a key value. If the computed key is identical to the key contained in the processing instruction, Visio will recognize the file as a engine-generated XML for Visio file. Engine-generated XML for Visio files will open faster because they won't require the same degree of validation as user-generated XML for Visio files.

The processing instruction will appear immediately after the XML declaration. It will be called integrity and it will have five attributes: app which contains the string 'Visio', version which contains the engine major and minor version number, buildnum which contains the Visio build number, key which contains a 128-bit (64 hexadecimal digit) hash-key value, keystart which contains the offset from the top of the file to the start of the actual XML (skipping the processing instructions), and metric which is a boolean indicating if this document was created on an imperial or metric version of Windows.

<?xml version="1.0" encoding="utf-8" ?>
<?integrity app="Visio" version="10.0" buildnum="2109" metric='0' key="F6FD0A0143F011..." keystart="249"?>
<
VisioDocument 
    xmlns
="urn:schemas-microsoft-com:office:visio">

        ...

</
VisioDocument>

If the file is modified in any way after it is written, the hash key will no longer be valid and the engine will not consider the file trusted. Visio will still open the file, but it will validate the file in a more thorough and time-consuming manner.

Extensibility by Solutions

A developer may store solution XML at the cell level.  Solution XML in a cell is simply a string value stored in a cell that happens to be a chunk of valid XML. The Visio engine will recognize that the string is XML and store the string in an unparsed form. The engine will recognize the cell as a solution XML cell if the cell's string value begins with <SolutionXML> and ends with </SolutionXML>, and if the XML is well-formed.

The following example shows a Scratch user row with solution XML stored in the X cell:

<Scratch>
    <
X Unit="STR">
        <
SolutionXML>
            <
foo>Bar</foo>
        </
SolutionXML>
    </
X>
</
Scratch>

If the cell contains XML, but it is not contained within a <SolutionXML> </SolutionXML> pair, or if the XML is malformed, Visio will output a parsed string value:

<Scratch>
    <
X Unit="STR">
        
&lt;MyXML&gt;&lt;foo&gt;Bar&lt;/foo&gt;&lt;/MyXML&gt;
    </
X>
</
Scratch>

Solution XML stored in a cell will also round-trip in a VSD file, because it is simply a string cell value.

Style 0

When Visio emits a XML for Visio file it will emit the document's complete set of StyleSheets, include the special StyleSheet with ID='0'.  Style 0 is a special read-only style used by Visio to define the default values for all cell types.  In Visio, this style may not be modified.

When Visio reads a XML for Visio file, it will ignore any StyleSheet with ID='0'.  Visio will always use it's built-in Style 0 when re-creating a document from a XML for Visio file.

Round-tripping Issues

XML for Visio files may be created by third party applications. When Visio opens a third-party XML for Visio file and then re-saves the document into another XML for Visio file, the files are not guaranteed to be identical. The following cases illustrate some differences that will occur when a XML for Visio file is round-tripped through Visio:

White Space

White space will not be preserved at all. The user may create a XML for Visio file with any legal white space characters, but the Visio engine will re-write the XML for Visio file so as to use minimal white space. The actual usage of white space will be determined as the code is developed.

Cells

Visio will always emit local cells that have an explicit unit, value, and formula. A third party may omit portions of the cell and Visio will either pick default values or infer correct values for the missing components. Consider a possible fragment emitted from a third party application:

<PinX F="1"/>

Because only a formula was specified, Visio assigns the formula to the PinX cell and then evaluates the formula to determine the value. Because the formula evaluates to a constant, Visio flags the cell as a constant. A unit of measure was not specified, so Visio chooses the internal unit, inches. When the file is re-saved, the fragment above will appear like this:

<PinX Unit="in_f" F=""> 1 </PinX>

Visio always emits a Unit attribute if a value is local. The V element is present with a value of 1, and the F element is present with an empty value. This is the XML for Visio notation for a constant cell value (see Inheritance above).

Rows

A XML for Visio file may contain a series of indexed rows. Consider this file fragment:

<Scratch ix="3">
    <
X F=""> 3 <X/>
</
Scratch>
<
Scratch ix="1">
    <
X F=""> 1 <X/>
</
Scratch>

When Visio reads the file above and re-saves it, it will appear like this:

<Scratch ix="0"/>
<
Scratch ix="1">
    <
X F=""> 1 <X/>
</
Scratch>
<
Scratch ix="2"/>
<
Scratch ix="3">
    <
X F=""> 3 <X/>
</
Scratch>

Visio will always write indexed rows out in index order. If the original sequence of rows were indexed sparsely (there were gaps in the sequence), Visio will implicitly create the missing rows.

Named rows have no specific order. If a XML for Visio file contains a series of named rows, when the file is round-tripped, their order is not guaranteed.

Geometry Sections

Geometry sections round-trip following the same rules as indexed rows. Indexed sections may appear in any order, but when round-tripped they will be written out in index order and the sparse sections will be implicitly created.

Text Blocks

Consider the following code:

<Char IX="0"> <Style F=""> 0 <Style/> </Char>
<
Char IX="1"> <Style F=""> 1 <Style/> </Char>

<
Para IX="0"> <HAlign F=""> 0 <HAlign/> </Char>
<
Para IX="0"> <HAlign F=""> 1 <HAlign/> </Char>

<
Text>The quick <cp ix='1'/>brown fox <pp ix='1'/>jumped <cp ix='0'/>over the lazy dog.</Text>

This code describes a text block that contains three character runs and two paragraph property runs. There is a single paragraph break. The block would render like this:

The quick brown fox

jumped over the lazy dog.

When it is re-saved, it will look like this:

<Char IX="0"> <Style F=""> 0 <Style/> </Char>
<
Char IX="1"> <Style F=""> 1 <Style/> </Char>
<
Char IX="2"> <Style F=""> 0 <Style/> </Char>

<
Para IX="0"> <HAlign F=""> 0 <HAlign/> </Char>
<
Para IX="0"> <HAlign F=""> 1 <HAlign/> </Char>

<
Text><cp ix='0'/>The quick <cp ix='1'/>brown fox <p/><pp ix='1'/>jumped <cp ix='2'/>over the lazy dog.</Text>

When Visio reads a XML for Visio file, it may encounter <cp>, <pp>, <tp>, or <fld> elements with the <text> block in any order. If multiple <p> elements refer to the same Char, Para, Tab, or Field row, Visio duplicates the row. In the example above, the Char row 0 is referenced twice (<cp ix='0'/>). Visio normalizes this by creating a third Char row which is identical to Char row 0.

The initial text run is always assumed to refer to the first row. Although it is not an error to omit the marker for the first run, Visio will emit the initial marker element when the XML for Visio data is round-tripped. Hence the initial <cp ix='0'/> is added in the example above.

The end of a paragraph property run always indicates that a paragraph has ended. In the original XML for Visio file, a <pp ix='1'/> is present in the middle of the text, indicating a new paragraph run. Visio will imply that this also means a paragraph break has occurred. When the file is round-tripped, Visio explicitly writes a <p/> (paragraph break) just before the <pp ix='1'/> (paragraph run marker).

Miscellaneous

A third party may omit a document-level element from a XML for Visio file, such as DocumentProperties, or any of the document level sub-elements, such as Author. However, when the XML for Visio file is round-tripped, Visio will create a document-level element for all non-empty document properties. For example, a XML for Visio file may omit the Version element, but the round-tripped XML for Visio file will contain a Version element that has an appropriate value.