Skip to main content

Overview of XML Virtual Property Paths

This topic provides an overview of XML virtual property paths (property paths in XML virtual documents).

The next two topics describe in detail how to create XML virtual property paths.

Note:

The code examples in this topic are fragments from data transformations, because data transformations generally use a richer set of property paths than do rule sets and search tables. Also, the emphasis is on DOM-style paths, because those are the paths that you must create manually. (In contrast, when you specify a schema to use, InterSystems IRIS® data platform displays the structure of the document and automatically generates schema-dependent paths when you drag and drop or when you use auto-completion.)

Orientation to Virtual Property Paths for XML Virtual Documents

This section briefly introduces virtual property paths for XML virtual documents.

As noted earlier, you can use schema-dependent paths only if you have loaded the corresponding XML schema. You can always use DOM-style paths, even when no schema is available.

Basic Syntax for Schema-dependent Paths

For XML virtual documents, a schema-dependent path consists of a set of path units separated by periods, as in the following example:

unit1.unit2.unit3

Where unit1 is the name of a child XML element in the document, unit2 is the name of a child element within unit1, and so on. The leaf unit is the name of either a child XML element or an XML attribute.

For example:

HomeAddress.City

For complete information, see Specifying Schema-dependent Paths.

Basic Syntax for DOM-style Paths

A DOM-style path always starts with a slash and has the basic structure shown in the following example:

/root_unit/unit1/unit2/unit3

Each path unit has the following form.

namespace_identifier:name

Where namespace_identifier represents the XML namespace; this is a token that InterSystems IRIS replaces with the actual namespace URI, as discussed in a later subsection. This token is needed only if the element or attribute is in a namespace.

name is the name of an XML element or attribute.

For example:

/$2:Patient/$2:HomeAddress/$2:City

For complete information, see Specifying DOM-style Paths.

XML Namespace Tokens

When you load a schema into InterSystems IRIS, it establishes a set of tokens for the namespaces used in that schema, for use in any DOM-style paths.

The token $1 is used for first namespace that is declared in the schema; this usually corresponds to the XML schema namespace (http://www.w3.org/2001/XMLSchema). The token $2 is used for the next namespace that is declared in the schema, $3 is used for the third, and so on.

InterSystems IRIS assigns namespace tokens for all namespaces declared in the schema, whether or not those namespaces are actually used. Therefore, InterSystems IRIS might use $3 or a higher value rather than $2 for the items of interest to you, if additional namespaces are declared in the schema. It is practical to use the Management Portal to view the individual path units, as discussed in the next section, to be sure that you are using the correct token for a specific path unit.

You can use namespace tokens if you have also loaded the corresponding schema (and have configured the applicable business host to use that schema). Otherwise, you must use the namespace prefixes exactly as given in the XML document.

Viewing Path Units for XML Virtual Documents

Until you are familiar with property paths for XML virtual documents, it is useful to use the Management Portal to view the individual path units. You can do this if you have loaded the corresponding schema.

To view the path units for the elements and attributes in a schema:

  1. Load the schema as described previously.

    For example, consider the following XML schema, shown here for reference, for the benefit of readers who are familiar with XML schemas:

    <?xml version="1.0" encoding="UTF-8"?>
    <schema xmlns="http://www.w3.org/2001/XMLSchema" 
                elementFormDefault="qualified" targetNamespace="http://myapp.com"     xmlns:myapp="http://myapp.com">
      <element name="Patient" type="myapp:Patient"/>
      <complexType name="Patient">
        <sequence>
          <element minOccurs="0" name="Name" type="string"/>
          <element minOccurs="0" name="FavoriteColors" 
                       type="myapp:ArrayOfFavoriteColorString" />
          <element minOccurs="0" name="Address" type="myapp:Address" />
          <element minOccurs="0" name="Doctor" type="myapp:Doctor" />
        </sequence>
        <attribute name="MRN" type="string"/>
        <attribute name="DL" type="string"/>
      </complexType>
      <complexType name="ArrayOfFavoriteColorString">
        <sequence>
          <element maxOccurs="unbounded" minOccurs="0" name="FavoriteColor" 
                       nillable="true" type="string"/>
        </sequence>
      </complexType>
      <complexType name="Address">
        <sequence>
          <element minOccurs="0" name="Street" type="string"/>
          <element minOccurs="0" name="City" type="string"/>
          <element minOccurs="0" name="State" type="string"/>
          <element minOccurs="0" name="ZIP" type="string"/>
        </sequence>
      </complexType>
      <complexType name="Doctor">
        <sequence>
          <element minOccurs="0" name="Name" type="string"/>
        </sequence>
      </complexType>
    </schema>

    The following shows an example XML document that obeys the schema shown in this section:

    <?xml version="1.0" ?>
    <Patient MRN='000111222' xmlns='http://myapp.com'>
        <Name>Georgina Hampton</Name>
        <FavoriteColors>
            <FavoriteColor>Red</FavoriteColor>
            <FavoriteColor>Green</FavoriteColor>
        </FavoriteColors>
        <Address>
            <Street>86 Bateson Way</Street>
            <City>Fall River</City>
        </Address>
        <Doctor>
            <Name>Dr. Randolph</Name>
        </Doctor>
    </Patient>
  2. Select the Interoperability > Interoperate > XML > XML Schema Structures page. The left column lists XML schemas loaded into this namespace.

  3. Select Category link in the row corresponding to the XML schema of interest.

    If we do this for the XML schema shown previously, InterSystems IRIS then displays this:

    List of the XML DocType structures in the MyApp Category

  4. Select the link for the document type of interest.

    If we select Patient, InterSystems IRIS then displays this:

    Document structure of the MyApp:Patient document type, which includes six elements

    On this page:

    • Above the table, the value in large font displays the DocType value for this XML element. In this case, DocType is MyApp:Patient.

    • The Name column shows path units in the format needed for schema-dependent paths.

      In this case, this page tells us that we can use Name, FavoriteColors, Address, Doctor, MRN, and DL as path units in schema-dependent paths.

    • The Element column shows path units in the format needed for DOM-style property paths.

      In this case, this page tells us that we can use $3:Name, $2:FavoriteColors/$2:FavoriteColor, $2:Address, $2:Doctor/$2:Name, @MRN, and @DL as path units in DOM-style paths. Notice that @MRN and @DL do not have a namespace prefix; these attributes are not in any namespace.

  5. Click additional sub-items as wanted.

    If we click Address in the Name column, InterSystems IRIS displays this:

    Structure of the MyApp:Address Complex Type, which includes four elements

    This page displays any additional path units within Address.

    In this case, this page tells us that we can use these additional path units in combination with the path unit that we used to get to this page, for example:

    Path Type Example
    Schema-dependent path (partial) ...Address.Street
    DOM-style path (partial) /.../$2:Address/$2:Street

The following sections note specific variations due to schema variations.

Redundant Inner Elements for Schema-dependent Paths

For schema-dependent paths, InterSystems IRIS collapses redundant inner elements. This is best explained by example:

  • The <FavoriteColors> element contains a sequence of multiple <FavoriteColor> elements. On the schema viewer page, <FavoriteColors> is shown simply as FavoriteColors() in the Name column (which shows the path unit for schema-dependent paths). This column is displayed in blue in the following figure.

    Structure of the MyApp:Patient document type

    In contrast, the same element is shown as $2:FavoriteColors/$2:FavoriteColorsItem in the Element column on the right. This column shows the path unit for DOM-style paths.

    For a sequence of multiple items of the same type, the schema-dependent path does not use the name of the inner element. (In contrast, the DOM-style path uses all the element names.) More generally, any redundant inner levels found in a schema are ignored in schema-dependent paths; the following item shows another example.

  • The <Doctor> element includes a single <Name> element. On the schema viewer page, the <Doctor> item is shown as Doctor in the Name column, as shown in the previous figure.

    Notice that the schema-dependent path to the data inside <Doctor> does not use the name of the inner element.

    In contrast, the same item is shown as $3:Doctor/$3:Name in the Element column on the right. This column shows the path unit for DOM-style paths.

Note:

If there is a single, non-repeating outer element it will be collapsed. This shortens the property path to only use the inner element. If the outer element is repeating, the path will not be shortened, so that you can access all inner elements.

One restriction to this is that the path will be shortened if the outer element’s type is defined by reference. In this case, you won’t be able to access any inner elements beyond the first node of the outer element using a schema-dependent path. You will still be able to access all inner elements using the DOM-style path. To prevent this, you should not define the outer element’s type by reference when it is repeating and the only outer element.

Repeating Fields

If a given element can occur multiple times, the Name column displays parentheses () at the end of the element name. For example, see the FavoriteColors() row in the preceding figure.

The Type and Element columns indicate the number of times the element can be repeated. In this case, the element can be repeated five times. If there is no number displayed in parentheses in the Type column, the element can be repeated any number of times.

Repeating Sequences

XML schemas can include repeating sequences that occur within the structure but do not have an element name to distinguish them from surrounding elements. This results in sequence(rep) appearing in VDoc property paths, but having no equivalent in the DOM path. In these cases, the property path can be used to get the value of an entire repetition of a sequence (for example, People(1).sequence(2)) or a value within the sequence (for example, People(1).sequence(2).Color.Tint). The property path can also be used to set the value of an element within a sequence.

Be aware that setting a value into the entire sequence is not supported. For example, the following returns an error and does not change any values:

SetValueAt("<Color><ColorName>pink</ColorName><Tint>bright</Tint></Color><Value>001</Value>","People(1).sequence(4)") 

Duplicate Names

If an XML schema has multiple elements at the same level that have the same name but different types, then InterSystems IRIS appends _2, _3, and so on, as needed to create unique names at that level. This procedure applies only to the schema-dependent paths. For example, consider a schema that defines the <Person> element to include two elements named <Contact>. One is of type <Phone> and the other is of type <Assistant>. InterSystems IRIS displays the schema for the <Person> element as follows:

Structure of a complex type with an element named Contact and an elementnamed Contact_2

Similarly, if the schema has multiple elements at the same level but in different namespaces, then InterSystems IRIS appends _2, _3, and so on, as needed to create unique names at that level. This procedure applies only to the schema-dependent paths.

Choice Structures

Some schemas include <choice> structures, like the following example:

<xsd:choice>
  <xsd:element name="OptionA"  type="my:OptionType"/>
  <xsd:element name="OptionB"  type="my:OptionType"/>
  <xsd:element name="OptionC"  type="my:OptionType"/>
</xsd:choice>

InterSystems IRIS represents this structure differently for the two kinds of paths. The following shows an example:

Structure of a complex type that includes choice as the first item listed in the structure

For schema-dependent paths, the Name displays a generic name for the <choice> structure, and the Type column displays a numeric placeholder. The Element column does not display anything.

If we click choice, InterSystems IRIS then displays the following:

List of three elements in the choice structure

In this case, these pages tell us that we can use the following paths to access OptionB:

Path Type Example
Schema-dependent path (partial) ...Parent.choice.OptionB
DOM-style path (partial) /.../Parent/OptionB

Groups Included by Reference

A schema can include a <group> that is included via the ref attribute. For example:

<s01:complexType name="Patient">
   <s01:sequence>
      <s01:element name="Name" type="s01:string" minOccurs="0"/>
      <s01:element name="Gender" type="s01:string" minOccurs="0"/>
      <s01:element name="BirthDate" type="s01:date" minOccurs="0"/>
      <s01:element name="HomeAddress" type="s02:Address" minOccurs="0"/>
      <s01:element name="FavoriteColors"
        type="s02:ArrayOfFavoriteColorsItemString" minOccurs="0"/>
      <s01:element name="Container" type="s02:ContainerType" minOccurs="0"/>
      <s01:element name="LatestImmunization" type="s02:Immunization" minOccurs="0"/>
      <s01:element ref="s02:Insurance" minOccurs="0"/>
      <s01:group ref="s02:BoilerPlate" minOccurs="1" maxOccurs="1"/>
   </s01:sequence>
...
<s01:group name="BoilerPlate">
   <s01:sequence>
      <s01:element name="One" type="s01:string"/>
      <s01:element name="Two" type="s01:string"/>
      <s01:element name="Three" type="s01:string"/>
   </s01:sequence>
</s01:group>

InterSystems IRIS represents this structure differently for the two kinds of paths. The following shows an example:

Structure of a complex type where the element included by reference looks like other elements and you can drill down for deta

For schema-dependent paths, the Name displays the name of the group, and the Type column displays a numeric placeholder. The Element column also displays the name of the group.

If we click BoilerPlate, InterSystems IRIS then displays the following:

List of three elements named one, two, and three

In this case, these pages tell us that we can use the following paths to access Two:

Path Type Example
Schema-dependent path (partial) ...Patient.BoilerPlate.Two
DOM-style path (partial) /.../$2:Patient/$2:Two

See Also

FeedbackOpens in a new tab