Loading files created or edited outside of Visio

  • Article

Loading files created or edited outside of Visio

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.

Third parties can create and edit XML files outside of Visio that follow the Visio schema. When Microsoft Visio opens a VDX file, it checks whether the file is trusted (created by Visio) or untrusted (created or edited outside of Visio). If the file is untrusted and contains a reference to the XML for Visio schema file, Visio validates the file against its schema.

When Visio encounters invalid, ambiguous, or incomplete XML it tries to preserve as much information as possible and continue on. When you are editing or generating your own XML for Visio files, you'll get better performance results if you try to mimic the XML that Visio generates.

Note When a file is untrusted, Visio uses the MSXML Document Object Model (DOM) to validate the file. However, if the file doesn't include an explicit reference to an XDR file, MSXML cannot actually validate the file and can only check for well-formedness. After MSXML validates a file, Visio performs additional validation as it loads the file. If Visio finds errors in the file, it logs them in the warning log. For details about errors and warnings, see Error and warning messages.

This topic explains how you can validate your own files against the XML for Visio schema, along with some of the ways that Visio handles data when loading untrusted VDX data.

It is suggested that you validate your XML files against the XML for Visio schema to ensure that your files comply with the Visio schema and to identify potential schema errors. To validate your XML file against the Visio XDR file, do the following:

  1. Download the visio-schema XDR file from the Microsoft Visio Developer Center.
  1. Include the following namespace declaration in the <VisioDocument> tag:
  xmlns='x-schema:your visio-path\visio-schema.xdr'
  1. Load the file into the MSXML DOM (2.0 or later) and call the validate method.
  • Optionally, you can rename a VDX file with an .xml extension, open the file in Microsoft Internet Explorer (version 5.0 or later), right-click the page, and then click
  • Validate
  • . Internet Explorer uses the DOM to validate the file, and shows any parsing or validation errors at the end of the file.
  • For details about the DOM and its methods, search for "XML DOM reference" on
  • MSDN
  • .

When Visio loads untrusted files, it validates the file against any XDR files that are referenced in a namespace with an "x-schema:" prefix.

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 XML for Visio schema in this reference). Files emitted by Visio always reflect this order. If these elements are not written in the correct order, Visio displays a warning message and ignores the contents of the element.
  • The order of Shape, Page, and Master elements within their parent elements has particular meaning.
  • 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 saved in Visio.

When you write XML for Visio, 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 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 save it in its sparse state using Visio. 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>

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

  <Shape ID='1' Master='0'/>
<Shape ID='4' Master='0'/>
  • Because subshapes within groups have x,y postitions 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 unspecified.
  • 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.

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.
  • 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.
  • If a cell element has an F attribute that contains 'No Formula', Visio must trust the value (because there's nothing to compare it to). If the element also contains a value, that 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.
  • 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.

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:

  1. Replaces the value with '#000000' (black), as if it had been specified as RGB='#000000'.
  1. Logs an error message. For details on errors, see Error and warning messages.
  1. 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 with a COLOR data type unit.

In cases where untrusted XML for Visio 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:

  1. A warning message is logged. For details on errors and warnings, see Error and warning messages.
  1. 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—INV_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.
  <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 XML for Visio 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 coerces the result as appropriate for the element. This is roughly equivalent to assigning a string formula to a numeric cell. No warning is generated.
  <Angle Unit='STR'>bats can fly</Angle>
<Angle F='&quot;bats can fly&quot;'/>

  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.

For information about how Visio handles text when loading an untrusted XML for Visio file, see Working with a shape's text in XML for Visio.