Loading Files that were Created or Edited Outside of Visio

Third parties can create and edit XML files outside Microsoft® Office Visio® that follow the Visio schema. When Visio opens a VDX file, it checks whether the file is trusted (created by Visio) or untrusted (created or edited outside Visio). If the file is untrusted and contains third-party schema references, Visio attempts to validate the file against the appropriate schema. If an untrusted file fails to pass validation, it will be rejected, and the document will not be loaded into Visio. In all cases Visio will validate the file against the Visio schema.

Visio will not load any XML that fails validation, either against the Visio schema or a third-party schema. If an XML file passes schema validation, Visio will load the file even if it contains recoverable errors. When Visio encounters any such XML that is ambiguous or incomplete, it tries to preserve as much information as possible and continues loading the file.

If Visio is unable to load a file, or if it finds errors in the file, it logs the errors it finds in the error or warning log. For details about errors and warnings, see Error and Warning Messages.

Beginning with Microsoft Office Visio 2003, you can test the validity of changes you make to SolutionXML elements without having to reopen the file in Visio by turning on the XMLValidateOnSave registry key. For more information, see Embedding Custom XML in a DatadiagramML file.

Visio follows certain rules for handling untrusted data; these rules are explained in the following sections.

Following are the requirements for the order of elements in an untrusted file:

The elements that are direct children of the VisioDocument element must be ordered according to the schema (this order is reflected in the DatadiagramML Schema in this reference). Files emitted by Visio always reflect this order. If these elements are not written in the correct order, the file will fail validation and Visio will not load it.
The order of Shape, Page, and Master elements within their parent elements has particular meaning.
Page elements appear in the order in which pages appear in the Visio user interface and in the Automation collections.
The order of the Shape elements determines the display-list order of the shapes— the first Shape element is the shape that has the bottommost z-order.
The order of Master elements determines how they are arranged on the stencil.
Cell elements are ordered according to the schema (this order is reflected in the tag hierarchy) whenever Visio emits a file. Third parties can write them in any order, but files are reordered if they are saved in Visio.

When you write DatadiagramML, the only element that is absolutely required is the VisioDocument element; Visio will automatically write out everything else required for a Visio document using default units and values. This functionality makes it possible for you to create the minimal XML for a VDX file, and Visio will fill in all the other details that are required for a complete document. You can supply only the elements that you are interested in defining, provided they are properly nested under the VisioDocument element and all IDs are accounted for (for example, elements such as Master, Shape, Page, StyleSheet, and PageSheet require an ID attribute).

Be aware that this also means an XML file that is initially "sparse" can grow in size after you load it in Visio and then save it as a VDX file in Visio. While you can initially write a sparse XML file, you can't actually use Visio to save it in its sparse state. Visio always fills in any missing element information when it saves or emits the file.

A sparse XML file includes only the elements that the developer is interested in declaring. A sparse instance is a shape instance (such as for a master that is a group) that does not have all of its child elements specified. Creating a sparse instance of a shape means specifying the top-level shape in the instance without listing its subshapes.

The following guidelines apply to how Visio handles sparse instances when loading untrusted files:

Instances can be contained in other instances, and any combination of the instances may be sparse.
When Visio creates an instance from a sparse instance in XML, it fills in all the IDs for omitted sheets. For example, if the master is:

<Master ID='0'>
   <Shapes>
      <Shape ID='5'>
         <Shapes>
            <Shape ID='6'/>
            <Shape ID='7'/>
         </Shapes>
      </Shape>
   </Shapes>
</Master>

The following XML would be incorrect and would produce a warning indicating duplicate elements:

<Shape ID='1' Master='0'/>
<Shape ID='2' Master='0'/>

The following XML is correct because it takes into account the additional IDs that will be used for the other shape instances:

<Shape ID='1' Master='0'/>
<Shape ID='4' Master='0'/>

Because subshapes within groups have x,y coordinates that are relative to the parent's (group) coordinates, not the page coordinates, the coordinate information for subshapes is not required.
Elements that are locally deleted must be explicitly listed with the attribute Del='1'. These elements do not get created, their content is ignored, and any child elements are also treated as deleted (even if the children don't have the Del attribute, or if they have Del='0'). No warnings are generated.
The order of child Shape elements in an instance shape is the same as the order of child Shape elements in the master. To alter the order of any combination of child Shape elements, you must include all the child Shape elements in the instance. If only a subset of the child Shape elements is listed, the results are unpredictable.
If an element is listed for the purpose of a local override, all Shape elements between that element and the top-level instance must also be listed. This means if you want to change one shape in a group, you must specify all the shapes between that shape and its top-level Group element.
If the Master has multiple immediate child elements within a Page, Visio automatically creates a "synthetic" group to contain the child elements when an instance of the master is created.

Note Well-constructed masters have exactly one immediate child element in a page— either a shape or a group. There may be multiple shapes, but they all have a single common parent in the page. Masters that have more than one immediate child element in the page require Visio to generate a group to contain these children when the master is instanced.

When loading untrusted files, Visio enforces internal consistency between a cell element's formula and its value. For most cases where the formula and the value don't match, Visio automatically recalculates the formula to re-create the value and does not generate a warning message.

Following are some Visio behaviors:

When an evaluated formula result differs from the supplied cell value, the formula result is assumed to be the correct choice, and it replaces the cell value. No warnings are generated.
If a cell element's formula evaluates to an error (for example, F='5/0') and the element also contains a value, the value is assigned to the cell, but Visio generates a warning message.
If a cell element has an F attribute that contains 'No Formula', but if the element contains a value, Visio must trust the value (because there's nothing to compare it to). In that case, the value is assigned to the cell with appropriate type conversion if needed. If there is no element value, Visio uses the default value for that cell type (typically zero). The cell element is not recalculated.

Note To examine the value in a cell that contains 'No Formula', you must either use Automation or examine it indirectly in the ShapeSheet by referencing it from another cell.
If a cell element has an F attribute that contains 'Inh', the element's value is recalculated in the local context to guarantee that the local result is consistent with the inherited value.

A valid value format for the RGB attribute is #RRGGBB, where RR, GG, and BB represent the 00 to FF color component hexadecimal values. If Visio detects an invalid RGB attribute, it does the following:

Replaces the value with '#000000' (black), as if it had been specified as RGB='#000000'.
Logs an error message. For details on errors, see Error and Warning Messages.
Continues to load the document, using the substituted value.

Note RGB data is an attribute for the ColorEntry element in the color table and can also be the element value for a cell that has a COLOR data type unit.

In cases where untrusted DatadiagramML files have invalid style-linkage attributes, these linkages cannot be verified by schema-level validation and must be detected and repaired by Visio to keep the model in memory consistent.

The attributes LineStyle, FillStyle, and TextStyle are style-linkage attributes. Their data is a number that specifies the ID of the style to be inherited from.

When Visio detects an invalid style-linkage attribute, the following occurs:

A warning message is logged. For details on errors and warnings, see Error and Warning Messages.
The linkage is reset to No Style (Style 0), as if the attribute had been ='0'.

A style-linkage attribute is considered invalid if any of the following are true:

The ID is non-numeric.
The ID is -1 or 4294967295 (signalling an invalid ID).
The ID refers to a nonexistent object.
The ID refers to an object that is not a style.

The ID causes a cycle (circular reference) in the inheritance chain.

For example:

<StyleSheet ID='5' LineStyle='6' FillStyle='6' TextStyle='6'/>
<StyleSheet ID='6' LineStyle='5' FillStyle='5' TextStyle='5'/>

Visio enables third parties to easily create and edit DatadiagramML cell elements by providing default Unit attributes for cell elements that are of a known unit type and logging informative error messages when unexpected data is encountered.

Most cell elements have known and dedicated result types, such as boolean, color, distance, angle, and so on. These cells are termed non-void cells. Other cells have no intrinsic result type and are intended to hold any type of result— these are termed void cells. Examples of void cells are: elements A through D in Scratch elements, and Value elements in User and Prop elements.

Note To find out the default unit of a particular element, see that element's topic in this reference.

Following are some of the ways that Visio handles unexpected data when verifying the Unit attribute associated with a cell element:

If a non-void cell element's Unit attribute is missing or invalid, Visio automatically supplies the appropriate unit for the cell. No warning is generated.
If a void cell element's Unit attribute is missing or invalid, Visio assumes Unit='NUM' and does not attempt to deduce the unit from the format of the element's value. No warning is generated.
If a cell element's Unit attribute has an unrecognized value (for example, Unit='qxz'), Visio acts as if no Unit attribute was specified and logs a warning message.
If a non-void cell element has a Unit attribute that is inconsistent with its default unit, Visio uses the specified unit to parse the element value and expresses the result as appropriately as possible for the element. This is roughly equivalent to assigning a string formula to a numeric cell. No warning is generated.
For example, the following two XML snippets produce identical results and no warnings. (The default unit for the Angle element is DA, default angle units.):
```
<Angle Unit='STR'>bats can fly</Angle>

<Angle F='&quot;bats can fly&quot;'/>
```
In both cases, the internal result is:
```
formula = 'bats can fly'
   value = 0 deg. 
   error = #VALUE!
```

Visio emits Unit attributes only when they are different than the default unit for that particular element.