Skip to main content
Previous section   Next section

Controlling the Projection to XML Schemas

This chapter discusses how to control the projection of InterSystems IRIS classes to XML schemas.

The XML examples in this chapter are in literal format.

Class and Property Parameters Discussed in This Chapter
  • CONTENT
  • DISPLAYLIST
  • VALUELIST
  • ESCAPE
  • MAXLEN
  • MINLEN
  • MINVAL
  • XMLFractionDigits
  • XMLTotalDigits
  • XMLLISTPARAMETER
  • XSDTYPE
  • XMLTYPE
  • SUPPRESSTYPEPREFIX

Viewing the Schema for an XML-Enabled Class

When you enable an InterSystems IRIS class for XML, you are implicitly creating an XML schema for that class, which you can view. To see the schema for a given XML-enabled class, you have two options:

  • You can use %XML.Schema and %XML.Writer to generate complete schema documents. For details, see “Generating XML Schemas from Classes” in Using XML Tools.

  • You can use the XMLSchema() class method of your XML-enabled class, which writes the XML schema for this class to the current device. This method does not write the XML declaration and ignores namespaces and thus has limited use. This method can be helpful, however, if you are interested only in the XML types.

This chapter primarily uses the XMLSchema() class method, because using it requires only a single line of code.

Example

For example, consider the following class definitions:

Class GXML.Person Extends (%Persistent, %Populate, %XML.Adaptor) 
{
Property Name As %Name;
Property DOB As %Date(FORMAT = 5, MAXVAL = "+$h");
Property GroupID As %String (XMLPROJECTION="ATTRIBUTE");
Property OtherID As %String(XMLPROJECTION = "NONE");
Property Address As GXML.Address;
Property Doctors As list Of GXML.Doctor;
}
Copy code to clipboard

The GXML.Address class is as follows:

Class GXML.Address Extends (%Persistent, %Populate, %XML.Adaptor) 
{
Property Street As %String;
Property City As %String;
Property State As %String(MAXLEN = 2, PATTERN = "2u");
Property Zip As %String(MAXLEN = 10, PATTERN = "5n.1(1""-""4n)");
}
Copy code to clipboard

And the GXML.Doctor class is as follows:

Class GXML.Doctor Extends (%Persistent, %Populate, %XML.Adaptor) 
{
Property Name As %Name;
}
Copy code to clipboard

To see the schema for the GXML.Person class, enter the following command in the Terminal:

 do ##class(GXML.Person).XMLSchema()
Copy code to clipboard

You then see the following:

<s:complexType name="Person">
    <s:sequence>
        <s:element name="Name" type="s:string" minOccurs="0" />
        <s:element name="DOB" type="s:date" minOccurs="0" />
        <s:element name="Address" type="s_Address" minOccurs="0" />
        <s:element name="Doctors" type="ArrayOfDoctorDoctor" minOccurs="0" />
    </s:sequence>
    <s:attribute name="GroupID" type="s:string" />
</s:complexType>
<s:complexType name="s_Address">
    <s:sequence>
        <s:element name="City" type="s:string" minOccurs="0" />
        <s:element name="Zip" type="s:string" minOccurs="0" />
    </s:sequence>
</s:complexType>
<s:complexType name="ArrayOfDoctorDoctor">
    <s:sequence>
        <s:element name="Doctor" type="Doctor" 
minOccurs="0" maxOccurs="unbounded" nillable="true" />
    </s:sequence>
</s:complexType>
<s:complexType name="Doctor">
    <s:sequence>
        <s:element name="Name" type="s:string" minOccurs="0" />
    </s:sequence>
</s:complexType>
Copy code to clipboard

Notice the following:

  • The schemas for the <Person>, <Address>, and <Doctor> types are based directly on the corresponding class definitions.

  • The schema consists of only the properties that are projected.

  • The schema recognizes whether each property is projected as an element or as an attribute. For example, GroupID is an attribute and Name is an element.

  • Other parameters of the properties can affect the schema.

  • In this example, the class properties are of type string, which is one of the basic XSD types (see https://www.w3.org/TR/xmlschema-2/).

Projection of Literal Properties to XML Schemas

This section discusses how literal (non-collection) properties are projected to XML types, as well as options that affect the XML schema. It discusses the following:

Default XSD Types for InterSystems IRIS Data Type Classes

If a class or a class property is based on one of the common InterSystems IRIS data type classes, the XML type is set automatically, according to the following table. Classes in the %xsd package map directly to the XML types, as shown in the table.

XML Types for InterSystems IRIS Data Types in the %Library and %xsd Packages
InterSystems IRIS Class in the %xsd Package InterSystems IRIS Class in the %Library Package XSD Type Used in Projections to XML
%xsd.anyURI   anyURI
%xsd.base64Binary base64Binary
%xsd.boolean %Boolean boolean
%xsd.byte %TinyInt byte
%xsd.date %Date date
%xsd.dateTime dateTime
%xsd.decimal decimal
%xsd.double double
%xsd.float   float
%xsd.hexBinary   hexBinary
%xsd.int   int
%xsd.integer   integer
%xsd.long long
%xsd.negativeInteger   negativeInteger
%xsd.nonNegativeInteger   nonNegativeInteger
%xsd.nonPositiveInteger   nonPositiveInteger
%xsd.positiveInteger   positiveInteger
%xsd.short %SmallInt short
%xsd.string string
%xsd.time %Time time
%xsd.unsignedByte   unsignedByte
%xsd.unsignedInt   unsignedInt
%xsd.unsignedLong   unsignedLong
%xsd.unsignedShort   unsignedShort

For information on the XML data types, see https://www.w3.org/TR/xmlschema-2/.

For example, consider the following class:

Class Schema.DataTypesDemo Extends (%RegisteredObject, %XML.Adaptor)
{

Parameter XMLTYPENAMESPACE="mytypes";

Property binaryprop As %xsd.base64Binary;

Property booleanprop As %Boolean;

Property dateprop As %Date;

Property datetimeprop As %TimeStamp;

Property decimalprop As %Numeric;

Property integerprop As %Integer;

Property stringprop As %String;

Property timeprop As %Time;

}
Copy code to clipboard

The schema for this class is as follows:

<?xml version="1.0" encoding="UTF-8"?>
<schema xmlns="http://www.w3.org/2001/XMLSchema" xmlns:s="http://www.w3.org/2001/XMLSchema" 
elementFormDefault="qualified" targetNamespace="mytypes">
  <complexType name="DataTypesDemo">
    <sequence>
      <element minOccurs="0" name="binaryprop" type="s:base64Binary"/>
      <element minOccurs="0" name="booleanprop" type="s:boolean"/>
      <element minOccurs="0" name="dateprop" type="s:date"/>
      <element minOccurs="0" name="datetimeprop" type="s:dateTime"/>
      <element minOccurs="0" name="decimalprop" type="s:decimal"/>
      <element minOccurs="0" name="integerprop" type="s:long"/>
      <element minOccurs="0" name="stringprop" type="s:string"/>
      <element minOccurs="0" name="timeprop" type="s:time"/>
    </sequence>
  </complexType>
</schema>
Copy code to clipboard

Compiler Keywords That Affect the Schema

The Required keyword affects the XML schema, by removing the minOccurs="0" attribute. For example, consider the following class:

Class Schema.PropKeywords Extends (%RegisteredObject, %XML.Adaptor)
{

Parameter XMLTYPENAMESPACE="mytypes";

Property Property1 As %String;

Property Property2 As %String [ Required ];

}
Copy code to clipboard

If we generate a schema for the namespace used here, we see the following:

<?xml version="1.0" encoding="UTF-8"?>
<schema xmlns="http://www.w3.org/2001/XMLSchema" xmlns:s="http://www.w3.org/2001/XMLSchema" 
elementFormDefault="qualified" targetNamespace="test">
  <complexType name="PropKeywords">
    <sequence>
      <element minOccurs="0" name="Property1" type="s:string"/>
      <element name="Property2" type="s:string"/>
    </sequence>
  </complexType>
</schema>
Copy code to clipboard

Note that the default for minOccurs is 1; that is, Property2 is required.

Note:

For compatibility reasons, %XML.Reader does not check for required properties by default, but you can cause it to do so; see “Checking for Required Elements and Attributes” in Using XML Tools. Also by default, an InterSystems IRIS web service does not check for required properties, but you can cause it to do so; see “Checking for Required Elements and Attributes” in Creating Web Services and Web Clients.

No other property keywords affect the schema for data type classes.

Parameters That Affect XML Schemas

The InterSystems IRIS data type classes use many parameters. (For a table that lists the parameters supported in each data type class, see “Data Types” in Defining and Using Classes.) In most cases, you can also specify these as property parameters.

The parameters that affect XML schemas are as follows:

CONTENT

Influences how the property values are escaped; see “Handling Special XML Characters,” earlier in this book.

The "MIXED" value causes a change in the schema, as compared to the other possible values. Consider the following class:

Class Schema.CONTENT Extends (%RegisteredObject, %XML.Adaptor)
{

Parameter XMLTYPENAMESPACE = "mytypes";

Property Property1 As %String;

Property Property2 As %String(CONTENT = "STRING");

Property Property3 As %String(CONTENT = "ESCAPE");

Property Property4 As %String(CONTENT = "MIXED");

}
Copy code to clipboard

If we generate a schema for the namespace used here, we see the following:

<?xml version="1.0" encoding="UTF-8"?>
<schema xmlns="http://www.w3.org/2001/XMLSchema" xmlns:s="http://www.w3.org/2001/XMLSchema" 
elementFormDefault="qualified" targetNamespace="mytypes">
  <complexType name="CONTENT">
    <sequence>
      <element minOccurs="0" name="Property1" type="s:string"/>
      <element minOccurs="0" name="Property2" type="s:string"/>
      <element minOccurs="0" name="Property3" type="s:string"/>
      <element name="Property4">
        <complexType mixed="true">
          <choice maxOccurs="unbounded" minOccurs="0">
            <any processContents="lax"/>
          </choice>
        </complexType>
      </element>
    </sequence>
  </complexType>
</schema>
Copy code to clipboard

Notice that the three of these properties have the same type information, because XML treats them in the same way. InterSystems IRIS, however, treats the properties differently as described in “Handling Special XML Characters,” later in this book.

If you use the object as input or output for a web method, and SoapBodyUse is encoded for that method, then InterSystems IRIS treats mixed content like string content, the default. That is, if you specify CONTENT as "MIXED", that value is ignored.

DISPLAYLIST

Affects the schema if VALUELIST is also specified and if XMLLISTPARAMETER equal to "DISPLAYLIST". See the discussions for those two parameters.

MAXLEN

Controls the maxLength attribute, which is a facet or restriction. Facets define acceptable values for XML types. The following example shows several of them. Consider the following class:

Class Schema.BasicFacets Extends (%RegisteredObject, %XML.Adaptor)
{

Parameter XMLTYPENAMESPACE = "mytypes";

Property Property1 As %Integer (MINVAL=10, MAXVAL=1000);

Property Property2 As %String (MINLEN=20, MAXLEN=100);

}
Copy code to clipboard

If we generate a schema for the namespace used here, we see the following:

<?xml version="1.0" encoding="UTF-8"?>
<schema xmlns="http://www.w3.org/2001/XMLSchema" 
xmlns:s="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" targetNamespace="mytypes">
  <complexType name="BasicFacets">
    <sequence>
      <element minOccurs="0" name="Property1">
        <simpleType>
          <restriction base="s:long">
            <maxInclusive value="1000"/>
            <minInclusive value="10"/>
          </restriction>
        </simpleType>
      </element>
      <element minOccurs="0" name="Property2">
        <simpleType>
          <restriction base="s:string">
            <maxLength value="100"/>
            <minLength value="20"/>
          </restriction>
        </simpleType>
      </element>
    </sequence>
  </complexType>
</schema>
Copy code to clipboard

When the SOAP Wizard or the XML Schema Wizard finds a maxLength restriction in a schema, it sets the MAXLEN property parameter as appropriate in the generated class.

MAXVAL

Controls the maxInclusive attribute. See the example in MAXLEN.

MINLEN

Controls the minLength attribute. See the example in MAXLEN.

When the SOAP Wizard or the XML Schema Wizard finds a minLength restriction in a schema, it sets the MINLEN property parameter as appropriate in the generated class.

MINVAL

Controls the minInclusive attribute. See the example in MAXLEN.

VALUELLIST

Adds an <enumeration> restriction to the type. Consider the following class:

Class Schema.VALUELIST Extends (%RegisteredObject, %XML.Adaptor)
{

Parameter XMLTYPENAMESPACE = "mytypes";

Property Property1 As %String;

Property Property2 As %String (VALUELIST = ",r,g,b");

}
Copy code to clipboard

The following shows the schema for this class:

<?xml version="1.0" encoding="UTF-8"?>
<schema xmlns="http://www.w3.org/2001/XMLSchema" xmlns:s="http://www.w3.org/2001/XMLSchema" 
elementFormDefault="qualified" targetNamespace="mytypes">
  <complexType name="VALUELIST">
    <sequence>
      <element minOccurs="0" name="Property1" type="s:string"/>
      <element minOccurs="0" name="Property2">
        <simpleType>
          <restriction base="s:string">
            <enumeration value="r"/>
            <enumeration value="g"/>
            <enumeration value="b"/>
          </restriction>
        </simpleType>
      </element>
    </sequence>
  </complexType>
</schema>
Copy code to clipboard
XMLFractionDigits

Applicable to a %Numeric property. This parameter corresponds to the <fractionDigits> facet, as shown in the following fragment:

<element minOccurs="0" name="Property2">
  <simpleType>
    <restriction base="s:decimal">
      <fractionDigits value="2"/>
      <totalDigits value="5"/>
    </restriction>
  </simpleType>
</element>
Copy code to clipboard
XMLTotalDigits

Applicable to a %Numeric property or an %Integer property. This parameter corresponds to the <totalDigits> facet, as shown in the following fragment:

<element minOccurs="0" name="Property2">
  <simpleType>
    <restriction base="s:decimal">
      <fractionDigits value="2"/>
      <totalDigits value="5"/>
    </restriction>
  </simpleType>
</element>
Copy code to clipboard
XMLLISTPARAMETER

Applicable to a %String property that specifies the VALUELIST parameter. Specifies the name of the parameter that contains the list of values to project to XML, instead of the values contained in the object. In most cases, you also specify the standard DISPLAYLIST parameter, and you set XMLLISTPARAMETER equal to "DISPLAYLIST".

The XMLLISTPARAMETER parameter controls the value attribute used in the <enumeration> restriction.

You cannot specify this as a property parameter.

XMLPATTERN

Controls the pattern restriction. Consider the following class:

Class Schema.Pattern Extends (%RegisteredObject, %XML.Adaptor)
{

Parameter XMLTYPENAMESPACE = "mytypes";

Property Property1 As %String;

Property Property2 As %String(XMLPATTERN = "[A-Z]");

}
Copy code to clipboard

The schema for this class is as follows:

<?xml version="1.0" encoding="UTF-8"?>
<schema xmlns="http://www.w3.org/2001/XMLSchema" xmlns:s="http://www.w3.org/2001/XMLSchema" 
elementFormDefault="qualified" targetNamespace="mytypes">
  <complexType name="Pattern">
    <sequence>
      <element minOccurs="0" name="Property1" type="s:string"/>
      <element minOccurs="0" name="Property2">
        <simpleType>
          <restriction base="s:string">
            <pattern value="[A-Z]"/>
          </restriction>
        </simpleType>
      </element>
    </sequence>
  </complexType>
</schema>
Copy code to clipboard

If multiple patterns appear in a simple type, then InterSystems IRIS combines the patterns according to https://www.w3.org/TR/xmlschema-2 (see section 4.3.4.3, “Constraints on XML Representation of pattern”). The patterns are combined as separate branches in the same pattern (separated by a vertical bar) in the XMLPATTERN parameter.

XSDTYPE

Declares the XSD type used when projecting to XML. This parameter is set appropriately in all InterSystems IRIS data type classes. The InterSystems IRIS XML tools use this parameter when generating schemas. This parameter does not directly affect the input and output transformations, although it should be consistent with them.

Projection of Stream Classes to XML Types

If a class or a property is based on an InterSystems IRIS stream, it is projected to an XML type as shown in the following table:

XML Types for InterSystems IRIS Streams

For example, consider the following class:

Class Schema.StreamPropDemo Extends (%Persistent, %XML.Adaptor)
{

Parameter XMLTYPENAMESPACE="mytypes";

Property BinStream As %Library.GlobalBinaryStream;

Property CharStream As %Library.GlobalCharacterStream;

}
Copy code to clipboard

The schema for this class is as follows:

<?xml version="1.0" encoding="UTF-8"?>
<schema xmlns="http://www.w3.org/2001/XMLSchema" xmlns:s="http://www.w3.org/2001/XMLSchema" 
elementFormDefault="qualified" targetNamespace="mytypes">
  <complexType name="StreamPropDemo">
    <sequence>
      <element minOccurs="0" name="BinStream" type="s:base64Binary"/>
      <element minOccurs="0" name="CharStream" type="s:string"/>
    </sequence>
  </complexType>
</schema>
Copy code to clipboard

Projection of Collection Properties to XML Schemas

This section describes how collection properties are projected to XML schemas, for XML-enabled classes. This section discusses the following:

Projection of Collection Properties to XML Schemas

For most kinds of properties, the class definition contains enough information to specify the complete XML projection — both to project objects as XML documents and to define a complete XML schema for validation purposes. For collection properties, however, InterSystems IRIS supports some forms of definitions that do not provide enough information for a complete XML schema. If you are using the XML projections in a context where the schema is needed (such as in web services and clients), it is necessary to have a complete XML schema; otherwise validation against the schema will fail. If you are not validating against a schema, this consideration does not apply. The following table lists the scenarios:

Forms of Collection Properties and Their XML Projection Details
Form of Property Definition XML Is Usable? XML Schema Is Usable?
Property PropName As List of classname or Property PropName As Array of classname Yes Yes
Property PropName As %ListOfDataTypes or Property PropName As %ArrayOfDataTypes Yes Yes (but the default type for the collection item is string, which might not be appropriate)
Property PropName As %ListOfObjects or Property PropName As %ArrayOfObjects Yes No (the schema does not specify the type for the collection item)

The following subsections show the XML schemas for these scenarios.

List of Classname

This section shows the part of an XML schema that is generated from an XML-enabled class, when that class includes a property that is defined as List of Classname. For example, consider the following property definition:

Property PropName As list Of %Integer(XMLITEMNAME = "MyXmlItemName");
Copy code to clipboard

If this property is in an XML-enabled class named Test.DemoList1, the XML schema for this class contains the following:

<schema xmlns="http://www.w3.org/2001/XMLSchema" xmlns:s="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" 
targetNamespace="mytypes">
  <complexType name="DemoList1">
    <sequence>
      <element minOccurs="0" name="PropName" type="s01:ArrayOfMyXmlItemNameLong" xmlns:s01="mytypes"/>
    </sequence>
  </complexType>
  <complexType name="ArrayOfMyXmlItemNameLong">
    <sequence>
      <element maxOccurs="unbounded" minOccurs="0" name="MyXmlItemName" nillable="true" type="s:long"/>
    </sequence>
  </complexType>
...
</schema>
Copy code to clipboard

The following rules govern the names of the types:

  • For the PropName property, the corresponding type is named ArrayOfXMLItemNameType, where:

    • XMLItemName is the name of items in the collection as described as in “Controlling the Element and Attribute Names for List-Type Properties.” For a data type property, the default item name is the property name with Item appended to the end. (For a object property, the default item name is the short class name.)

    • Type is the XML type to which the property class is projected.

    <element minOccurs="0" name="PropName" type="s01:ArrayOfMyXmlItemNameLong" xmlns:s01="mytypes"/>
    Copy code to clipboard
    Note:

    If XMLItemName is identical to Type, then for the PropName property, the corresponding type is named ArrayOfXMLItemName. That is, the redundant array item is removed from the type name. To cause the type name to include the redundant name, specify the AllowRedundantArrayName property (of your instance of %XML.Schema) as 1. Similarly, in a web service class, to include the redundant array item name in the type in the WSDL, specify the ALLOWREDUNDANTARRAYNAME parameter (of the web service class) as 1.

  • The type ArrayOfXMLItemNameType is defined as a <sequence> of another type, named XMLItemName:

      <complexType name="ArrayOfMyXmlItemNameLong">
        <sequence>
          <element maxOccurs="unbounded" minOccurs="0" name="MyXmlItemName" nillable="true" type="s:long"/>
        </sequence>
      </complexType>
    Copy code to clipboard
  • The element XMLItemName is based on the XSD type corresponding to the data type class:

    <element maxOccurs="unbounded" minOccurs="0" name="MyXmlItemName" nillable="true" type="s:long"/>
    Copy code to clipboard

The same rules apply when Classname refers to an object class. For example, consider the following property definition:

Property PropName As list Of SimpleObject(XMLITEMNAME = "MyXmlItemName");
Copy code to clipboard

Where Simple.Object contains two properties, MyProp and AnotherProp. If this property is in an XML-enabled class named Test.DemoObjList, the XML schema for this class contains the following:

<schema xmlns="http://www.w3.org/2001/XMLSchema" xmlns:s="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" 
targetNamespace="mytypes">
  <complexType name="DemoObjList">
    <sequence>
      <element minOccurs="0" name="PropName" type="s01:ArrayOfMyXmlItemNameSimpleObject" xmlns:s01="mytypes"/>
    </sequence>
  </complexType>
  <complexType name="ArrayOfMyXmlItemNameSimpleObject">
    <sequence>
      <element maxOccurs="unbounded" minOccurs="0" name="MyXmlItemName" nillable="true" type="s01:SimpleObject" xmlns:s01="mytypes"/>
    </sequence>
  </complexType>
  <complexType name="SimpleObject">
    <sequence>
      <element minOccurs="0" name="MyProp" type="s:string"/>
      <element minOccurs="0" name="AnotherProp" type="s:string"/>
    </sequence>
  </complexType>
...
</schema>
Copy code to clipboard

Array of Classname

This section shows the part of an XML schema that is generated from an XML-enabled class, when that class includes a property that is defined as Array of Classname. For example, consider the following property definition:

Property PropName As array Of %Integer(XMLITEMNAME = "MyXmlItemName", XMLKEYNAME = "MyXmlKeyName");
Copy code to clipboard

If this property is in an XML-enabled class named Test.DemoArray1, the XML schema for this class contains the following:

<schema xmlns="http://www.w3.org/2001/XMLSchema" xmlns:s="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" targetNamespace="mytypes">
  <complexType name="DemoArray1">
    <sequence>
      <element minOccurs="0" name="PropName" type="s01:ArrayOfMyXmlItemNamePairOfMyXmlKeyNameLong" xmlns:s01="mytypes"/>
    </sequence>
  </complexType>
  <complexType name="ArrayOfMyXmlItemNamePairOfMyXmlKeyNameLong">
    <sequence>
      <element maxOccurs="unbounded" minOccurs="0" name="MyXmlItemName" nillable="true" type="s01:PairOfMyXmlKeyNameLong" xmlns:s01="mytypes"/>
    </sequence>
  </complexType>
  <complexType name="PairOfMyXmlKeyNameLong">
    <simpleContent>
      <extension base="s:long">
        <attribute name="MyXmlKeyName" type="s:string" use="required"/>
      </extension>
    </simpleContent>
  </complexType>
...
</schema>
Copy code to clipboard

The following rules govern the names of the types:

  • For the PropName property, the corresponding type is named ArrayOfXMLItemNamePairOfXMLKeyNameType, where:

    <element minOccurs="0" name="PropName" type="s01:ArrayOfMyXmlItemNamePairOfMyXmlKeyNameLong" xmlns:s01="mytypes"/>
    Copy code to clipboard
    Note:

    If XMLKeyName is identical to Type, then for the PropName property, the corresponding type is named ArrayOfXMLItemNamePairOfXMLKeyName. That is, the redundant array item is removed from the type name. To cause the type name to include the redundant name, specify the AllowRedundantArrayName property (of your instance of %XML.Schema) as 1. Similarly, in a web service class, to include the redundant array item name in the type in the WSDL, specify the ALLOWREDUNDANTARRAYNAME parameter (of the web service class) as 1.

  • The type ArrayOfXMLItemNamePairOfXMLKeyNameType is defined as a <sequence> of another type, named PairOfXMLKeyNameType:

     <complexType name="ArrayOfMyXmlItemNamePairOfMyXmlKeyNameLong">
        <sequence>
          <element maxOccurs="unbounded" minOccurs="0" name="MyXmlItemName" nillable="true" type="s01:PairOfMyXmlKeyNameLong" xmlns:s01="mytypes"/>
        </sequence>
      </complexType>
    
    Copy code to clipboard
  • The type PairOfXMLKeyNameType is an extension of the given XSD type. This extension adds an attribute named XMLKeyName:

      <complexType name="PairOfMyXmlKeyNameLong">
        <simpleContent>
          <extension base="s:long">
            <attribute name="MyXmlKeyName" type="s:string" use="required"/>
          </extension>
        </simpleContent>
      </complexType>
    Copy code to clipboard

The same rules apply when Classname refers to an object class. For example, consider the following property definition:

Property PropName As %ArrayOfObjects(XMLITEMNAME = "MyXmlItemName", XMLKEYNAME = "MyXmlKeyName");
Copy code to clipboard

Where Simple.Object contains two properties, MyProp and AnotherProp. If this property is in an XML-enabled class named Test.DemoObjArray, the XML schema for this class contains the following:

<schema xmlns="http://www.w3.org/2001/XMLSchema" xmlns:s="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" 
targetNamespace="mytypes">
  <complexType name="DemoObjArray">
    <sequence>
      <element minOccurs="0" name="PropName" type="s01:ArrayOfMyXmlItemNamePairOfMyXmlKeyNameSimpleObject" xmlns:s01="mytypes"/>
    </sequence>
  </complexType>
  <complexType name="ArrayOfMyXmlItemNamePairOfMyXmlKeyNameSimpleObject">
    <sequence>
      <element maxOccurs="unbounded" minOccurs="0" name="MyXmlItemName" nillable="true" type="s01:PairOfMyXmlKeyNameSimpleObject" xmlns:s01="mytypes"/>
    </sequence>
  </complexType>
  <complexType name="PairOfMyXmlKeyNameSimpleObject">
    <complexContent>
      <extension base="s01:SimpleObject" xmlns:s01="mytypes">
        <attribute name="MyXmlKeyName" type="s:string" use="required"/>
      </extension>
    </complexContent>
  </complexType>
  <complexType name="SimpleObject">
    <sequence>
      <element minOccurs="0" name="MyProp" type="s:string"/>
      <element minOccurs="0" name="AnotherProp" type="s:string"/>
    </sequence>
  </complexType>
</schema>
Copy code to clipboard

%ListOfDataTypes

This section shows the part of an XML schema that is generated from an XML-enabled class, when that class includes a property that is defined as %ListOfDataTypes. For example, consider the following property definition:

Property PropName As %ListOfDataTypes(XMLITEMNAME = "MyXmlItemName");
Copy code to clipboard

If this property is in an XML-enabled class named Test.DemoList, the XML schema for this class contains the following:

<schema xmlns="http://www.w3.org/2001/XMLSchema" xmlns:s="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" targetNamespace="mytypes">
  <complexType name="DemoList">
    <sequence>
      <element minOccurs="0" name="PropName" type="s01:ArrayOfMyXmlItemNameString" xmlns:s01="mytypes"/>
    </sequence>
  </complexType>
  <complexType name="ArrayOfMyXmlItemNameString">
    <sequence>
      <element maxOccurs="unbounded" minOccurs="0" name="MyXmlItemName" nillable="true" type="s:string"/>
    </sequence>
  </complexType>
</schema>
Copy code to clipboard

For the rules for the names of the types, see “List of Classname,” earlier in this section. Note that the collection item (PropNameItem in this example) is based on the XSD string type:

<element maxOccurs="unbounded" minOccurs="0" name="MyXmlItemName" nillable="true" type="s:string"/>
Copy code to clipboard

That is, the collection item is assumed to be a string. Also see “Options for Using Collection Classes,” later in this chapter.

%ArrayOfDataTypes

This section shows the part of an XML schema that is generated from an XML-enabled class, when that class includes a property that is defined as %ArrayOfDataTypes. For example, consider the following property definition:

Property PropName As %ArrayOfDataTypes(XMLITEMNAME = "MyXmlItemName", XMLKEYNAME = "MyXmlKeyName"); 
Copy code to clipboard

If this property is in an XML-enabled class named Test.DemoArray, the XML schema for this class contains the following:

<schema xmlns="http://www.w3.org/2001/XMLSchema" xmlns:s="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" 
targetNamespace="mytypes">
  <complexType name="DemoArray">
    <sequence>
      <element minOccurs="0" name="PropName" type="s01:ArrayOfMyXmlItemNamePairOfMyXmlKeyNameString" xmlns:s01="mytypes"/>
    </sequence>
  </complexType>
  <complexType name="ArrayOfMyXmlItemNamePairOfMyXmlKeyNameString">
    <sequence>
      <element maxOccurs="unbounded" minOccurs="0" name="MyXmlItemName" nillable="true" type="s01:PairOfMyXmlKeyNameString" xmlns:s01="mytypes"/>
    </sequence>
  </complexType>
  <complexType name="PairOfMyXmlKeyNameString">
    <simpleContent>
      <extension base="s:string">
        <attribute name="MyXmlKeyName" type="s:string" use="required"/>
      </extension>
    </simpleContent>
  </complexType>
...
</schema>
Copy code to clipboard

For the rules for the names of the types, see “Array of Classname,” earlier in this section. Note that the collection item (PairOfMyXmlKeyNameString in this example) is based on the XSD string type:

  <complexType name="PairOfMyXmlKeyNameString">
    <simpleContent>
      <extension base="s:string">
        <attribute name="MyXmlKeyName" type="s:string" use="required"/>
      </extension>
    </simpleContent>
  </complexType>
Copy code to clipboard

That is, the collection item is assumed to be a string. Also see “Options for Using Collection Classes,” later in this chapter.

%ListOfObjects

This section shows the part of an XML schema that is generated from an XML-enabled class, when that class includes a property that is defined as %ListOfObjects. For example, consider the following property definition:

Property PropName As list Of %Integer(XMLITEMNAME = "MyXmlItemName");
Copy code to clipboard

If this property is in an XML-enabled class named Test.DemoObjList1, the XML schema for this class contains the following:

<schema xmlns="http://www.w3.org/2001/XMLSchema" xmlns:s="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" 
targetNamespace="mytypes">
  <complexType name="DemoObjList1">
    <sequence>
      <element minOccurs="0" name="PropName" type="s01:ArrayOfMyXmlItemNameRegisteredObject" xmlns:s01="mytypes"/>
    </sequence>
  </complexType>
  <complexType name="ArrayOfMyXmlItemNameRegisteredObject">
    <sequence>
      <element maxOccurs="unbounded" minOccurs="0" name="MyXmlItemName" nillable="true" type="s01:RegisteredObject" xmlns:s01="mytypes"/>
    </sequence>
  </complexType>
...
</schema>
Copy code to clipboard

For the rules for the names of the types, see “List of Classname,” earlier in this section. Note that the collection item type is RegisteredObject, which is not defined:

<element maxOccurs="unbounded" minOccurs="0" name="MyXmlItemName" nillable="true" type="s01:RegisteredObject" xmlns:s01="mytypes"/>
Copy code to clipboard

As a result, this schema is unusable. See “Options for Using Collection Classes,” later in this chapter.

%ArrayOfObjects

This section shows the part of an XML schema that is generated from an XML-enabled class, when that class includes a property that is defined as %ArrayOfObjects. For example, consider the following property definition:

Property PropName As %ArrayOfObjects(XMLITEMNAME = "MyXmlItemName", XMLKEYNAME = "MyXmlKeyName");
Copy code to clipboard

If this property is in an XML-enabled class named Test.DemoObjArray1, the XML schema for this class contains the following:

<schema xmlns="http://www.w3.org/2001/XMLSchema" xmlns:s="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" targetNamespace="mytypes">
  <complexType name="DemoObjArray1">
    <sequence>
      <element minOccurs="0" name="PropName" type="s01:ArrayOfMyXmlItemNamePairOfMyXmlKeyNameRegisteredObject" xmlns:s01="mytypes"/>
    </sequence>
  </complexType>
  <complexType name="ArrayOfMyXmlItemNamePairOfMyXmlKeyNameRegisteredObject">
    <sequence>
      <element maxOccurs="unbounded" minOccurs="0" name="MyXmlItemName" nillable="true" type="s01:PairOfMyXmlKeyNameRegisteredObject" xmlns:s01="mytypes"/>
    </sequence>
  </complexType>
  <complexType name="PairOfMyXmlKeyNameRegisteredObject">
    <complexContent>
      <extension base="s01:RegisteredObject" xmlns:s01="mytypes">
        <attribute name="MyXmlKeyName" type="s:string" use="required"/>
      </extension>
    </complexContent>
  </complexType>
...
</schema>
Copy code to clipboard

For the rules for the names of the types, see “List of Classname,” earlier in this section. Note that the collection item type is based on RegisteredObject, which is not defined:

  <complexType name="PairOfMyXmlKeyNameRegisteredObject">
    <complexContent>
      <extension base="s01:RegisteredObject" xmlns:s01="mytypes">
        <attribute name="MyXmlKeyName" type="s:string" use="required"/>
      </extension>
    </complexContent>
  </complexType>
Copy code to clipboard

As a result, this schema is unusable. See “Options for Using Collection Classes,” later in this chapter.

Options for Using Collection Classes

Within an XML-enabled class, tor each property of type %ListOfDataTypes or %ArrayOfDataTypes, the collection item is assumed to be a string; this assumption may or may not be suitable for your needs. Similarly, for each property of type %ListOfObjects or %ArrayOfObjects, the collection item type is RegisteredObject, and InterSystems IRIS does not include an XML projection for the type RegisteredObject, so the XML schema is not usable. (See the previous subsections for examples.)

In these scenarios, you can do either of the following:

  • Modify the property definition to have the form List of Classname or Array of Classname, where Classname is a suitable class. If Classname is an object class, XML-enable the class.

  • Create a custom subclass of the collection class (%ListOfDataTypes, %ArrayOfDataTypes, %ListOfObjects, %ArrayOfObjects). In the subclass, specify the ELEMENTTYPE class parameter. For example:

    Class MyApp.MyIntegerCollection Extends %ListOfDataTypes
    {
    Parameter ELEMENTTYPE="%Library.Integer";
    
    }
    Copy code to clipboard

    For ELEMENTTYPE, specify the complete package and class name of the class used in the collection. If you subclass %ListOfDataTypes or %ArrayOfDataTypes, specify a data type class. Then the type for the collection element is controlled by the XSDTYPE parameter for that class.

    If you subclass %ListOfObjects or %ArrayOfObjects, specify an XML-enabled class. For example

    Class MyApp.MyObjectCollection Extends %ListOfObjects
    {
    Parameter ELEMENTTYPE="MyApp.SimpleObject";
    
    }
    Copy code to clipboard

    Then use your custom collection class in your property definition. For example:

    Property MyProp as MyApp.MyIntegerCollection;
    Copy code to clipboard

Projection of Other XML-Enabled Classes to XML Types

For an XML-enabled class or a property that is based on an XML-enabled class, the XML type is determined as follows: If the class has a value for the XMLTYPE parameter, that is used as the type name. Otherwise, the short class name is taken as the XML type name.

For example, consider the following class definitions:

Class GXML.PersonWithAddress Extends (%Persistent, %XML.Adaptor) 
{
Parameter XMLTYPE = "PersonType";

Property Name As %Name;

Property DOB As %Date(FORMAT = 5, MAXVAL = "+$h");

Property HomeAddress As GXML.Address;

}
Copy code to clipboard

For an instance of this class, the XML type is PersonType, which is taken from the XMLTYPE parameter.

Suppose that the GXML.Address class does not include the XMLTYPE parameter. In this case, for the <HomeAddress> element, the XML type is Address, which is the short class name.

Specifying the Namespaces for Types

The previous sections discussed how to assign elements to namespaces. This section discusses the namespaces of the types.

XML types are assigned to namespaces as follows:

  1. If the corresponding class definition defines the XSDTYPE class parameter, the type is in the following W3 namespace:

    http://www.w3.org/2001/XMLSchema
    Copy code to clipboard

    You specify XSDTYPE only within data type classes.

    Note:

    A data type class does not inherit the XSDTYPE class parameter. That is, if you subclass an existing data type class, you must specify this parameter, if the class should be mapped to one of the XSD types.

  2. If the class definition does not define XSDTYPE but does define NAMESPACE, the type is in the namespace specified by NAMESPACE.

  3. Otherwise the type is not in any namespace.

    You can, however, specify a namespace when you generate a schema. See “Generating XML Schemas from Classes” in Using XML Tools.

To see the namespaces to which the types are assigned, you must use %XML.Schema and %XML.Writer. For details, see “Generating XML Schemas from Classes” in Using XML Tools.

Suppressing the Namespace Prefix for the Type QName

As described in Using XML Tools, when you generate output with %XML.Writer, you can include the XML type attribute; to do so, you specify the writer’s OutputTypeAttribute property as 1.

By default, the type attribute is written as a QName (qualified name), which indicates both the name of the type as well as the namespace to which the type belongs. For example:

<TeamA xmlns:s01="http://mynamespace" xsi:type="s01:TeamA">
Copy code to clipboard

You can define the corresponding InterSystems IRIS class definition so that the namespace prefix is suppressed. For example:

<TeamB xsi:type="TeamB">
Copy code to clipboard

For example, consider the following class definition:

Class STP.TeamA Extends (%RegisteredObject, %XML.Adaptor)
{

Parameter NAMESPACE = "http://mynamespace";

Property Member1 as %String;

Property Member2 as %String;

}
Copy code to clipboard

The class STP.TeamB, which is not shown, has the same definition but also specifies SUPPRESSTYPEPREFIX as 1.

Both classes are used as properties in a third class:

Class STP.Container Extends (%RegisteredObject, %XML.Adaptor)
{

Parameter NAMESPACE = "http://mynamespace";

Property TeamA As STP.TeamA;

Property TeamB As STP.TeamB;

}
Copy code to clipboard

When we generate output for an instance of STP.Container (and we enable output of the XML type attribute), we see something like this:

<?xml version="1.0" encoding="UTF-8"?>
<Container xmlns="http://mynamespace" 
           xmlns:s="http://www.w3.org/2001/XMLSchema" 
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <TeamA xmlns:s01="http://mynamespace" xsi:type="s01:TeamA">
    <Member1 xsi:type="s:string">Jack O'Neill</Member1>
    <Member2 xsi:type="s:string">Samantha Carter</Member2>
  </TeamA>
  <TeamB xsi:type="TeamB">
    <Member1 xsi:type="s:string">Jasper O'Nelson</Member1>
    <Member2 xsi:type="s:string">Sandra Chartres</Member2>
  </TeamB>
</Container>
Copy code to clipboard

Notice that the <TeamA> element includes the xsi:type attribute, which equals "s01:TeamA". The namespace declaration in this element indicates that the s01 prefix refers to the namespace http://mynamespace.

The <TeamB> element, however, does not include a prefix within the xsi:type attribute.

Note:

The SUPPRESSTYPEPREFIX does not affect the namespace to which the XML type belongs. It just suppresses the writing of the type prefix.