Controlling the XML Element and Attribute Names

Default XML Element and Attribute Names

The default correspondence between InterSystems IRIS names and XML element and attribute name is as follows:

• For a class, the corresponding XML element or attribute name is the same as the short class name.

• For a property in this class, the corresponding XML element or attribute name is the same as the property name.

  (Note that the property definition determines whether it is projected as an XML element or attribute. See Controlling the Projection for Simple Properties.

  If the property name includes quotes, the quote marks are not included in the XML element or attribute name. For example, consider the following property:

  Property "Quoted Property" As %String;
  

  

  This property is projected as the element <Quoted Property> or the attribute Quoted Property, depending on how this property is mapped.

• If the property is a list or an array, it automatically consists of subelements, each of which is one item in that list or array. By default, the name of the subelement is the property name with Item appended to it.

• If a property is an array, the subelement also has an attribute to indicate the corresponding key. By default, the name of that attribute is the property name with Key appended to it.

Controlling the Name of the Element or Attribute for an Object Projected as a Top-Level Element

When you project a class instance as a top-level element, its XML name is determined as follows:

For information on XMLTYPE, see Controlling the Projection to XML Schemas.

For example, if you export objects of the Sample.Address class, each of those objects would be shown something like the following, by default:

<Address>
  <Street>5064 Elm Street</Street>
  <City>Jackson</City>
  <State>PA</State>
  <Zip>27621</Zip>
</Address>

Suppose that you specify the XMLNAME parameter of the Sample.Address class. For example:

Parameter XMLNAME = "HomeAddress";

In this case, the output would be as follows instead:

<HomeAddress>
  <Street>5064 Elm Street</Street>
  <City>Jackson</City>
  <State>PA</State>
  <Zip>27621</Zip>
</HomeAddress>

You can override these parameters when you export objects to XML, as described in Using XML Tools.

Controlling the Tags for Simple Properties

In an XML-enabled object, each simple property is projected as an XML element or attribute, depending on how it is mapped. In either case, by default, the InterSystems IRIS property name is used as the XML element or attribute name. To provide a different XML name for a property, you specify the XMLNAME parameter of that property.

For example:

Property Zip As %String (XMLNAME = "PostalCode");

The output for the previous example would be as follows instead:

<HomeAddress>
  <Street>5064 Elm Street</Street>
  <City>Jackson</City>
  <State>PA</State>
  <PostalCode>27621</PostalCode>
</HomeAddress>

Note that if a property is in turn another InterSystems IRIS object class, the XML projection ignores the class name and the XMLNAME parameter of that class. For example, suppose that the Person class has a property named Address which is a reference to the Address class. The projection for a Person object would look something like the following:

<Person>
 <Name>Zevon,Juanita Q.</Name>
 <DOB>1986-08-18</DOB>
 <Address>
   <Street>5064 Elm Street</Street>
   <City>Jackson</City>
   <State>PA</State>
   <Zip>27621</Zip>
 </Address>
</Person>

The name of the <Address> element is determined by the name of the corresponding property in the Person object. This is because the address object is a property of the object that is being imported or exported (instead of being an object that is being imported or exported directly).

As with any other property, you can override this name by specifying theXMLNAME parameter for the property. For example:

Property Address As MyApp.Address (XMLNAME = "EmployeeAddress");

The output for the previous example would be as follows instead:

<Person>
 <Name>Zevon,Juanita Q.</Name>
 <DOB>1986-08-18</DOB>
 <EmployeeAddress>
   <Street>5064 Elm Street</Street>
   <City>Jackson</City>
   <State>PA</State>
   <Zip>27621</Zip>
 </EmployeeAddress>
</Person>

Controlling the Element and Attribute Names for List-Type Properties

In an XML-enabled object, a list-type property is projected to an element with subelements, each of which is one item in that list. Suppose that an InterSystems IRIS object property named ColorOptions equals a list of three strings: "Red", "Green", "Blue". By default, this property corresponds to the following XML fragment:

<ColorOptions>
  <ColorOptionsItem>Red</ColorOptionsItem>
  <ColorOptionsItem>Green</ColorOptionsItem>
  <ColorOptionsItem>Blue</ColorOptionsItem>
</ColorOptions>

This shows the ColorOptionsItem subelement, which corresponds to an item in the list. The name for this subelement is determined as follows:

The same logic applies to the items of an array. The keys of an array are treated separately.

Controlling the Element and Attribute Names for Array-Type Properties

In an XML-enabled object, an array-type property is projected to an element with subelements, each of which is one item in that array, in the same basic way that a list property is projected; see the previous section.

Each subelement has an additional attribute that indicates the key associated with the item. You can control the name of this attribute.

Consider the following example property:

Property Tools As %ArrayOfDataTypes;

For example, suppose that (for some object instance) this property consists of an array as follows:

• The value Hammer is stored with the key 845.

• The value Monkey wrench is stored with the key 1009.

• The value Screwdriver is stored with the key 3762.

By default, this property corresponds to the following XML fragment:

<Tools>
  <ToolsItem ToolsKey="845">Hammer</ToolsItem>
  <ToolsItem ToolsKey="1009">Monkey Wrench</ToolsItem>
  <ToolsItem ToolsKey="3762">Screwdriver</ToolsItem>
</Tools>

This shows the ToolsKey attribute, which corresponds to the key of an array. The name of this attribute is determined as follows:

Notice that the XMLITEMNAME property parameter does not affect the attribute name; this parameter is discussed in the previous section.

For example, suppose you do not set XMLKEYNAME and you set XMLNAME equal to MyXMLName, as follows:

Property Tools As %ArrayOfDataTypes(XMLNAME = "MyXMLName");

Then the same property would correspond to the following XML fragment:

<MyXMLName>
  <MyXMLNameItem MyXMLNameKey="845">Hammer</MyXMLNameItem>
  <MyXMLNameItem MyXMLNameKey="1009">Monkey Wrench</MyXMLNameItem>
  <MyXMLNameItem MyXMLNameKey="3762">Screwdriver</MyXMLNameItem>
</MyXMLName>