Skip to main content
Previous sectionNext 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.SchemaOpens in a new window and %XML.WriterOpens in a new window 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/Opens in a new window).

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.anyURIOpens in a new window   anyURI
%xsd.base64BinaryOpens in a new window base64Binary
%xsd.booleanOpens in a new window %BooleanOpens in a new window boolean
%xsd.byteOpens in a new window %TinyIntOpens in a new window byte
%xsd.dateOpens in a new window %DateOpens in a new window date
%xsd.dateTimeOpens in a new window dateTime
%xsd.decimalOpens in a new window decimal
%xsd.doubleOpens in a new window double
%xsd.floatOpens in a new window   float
%xsd.hexBinaryOpens in a new window   hexBinary
%xsd.intOpens in a new window   int
%xsd.integerOpens in a new window   integer
%xsd.longOpens in a new window long
%xsd.negativeIntegerOpens in a new window   negativeInteger
%xsd.nonNegativeIntegerOpens in a new window   nonNegativeInteger
%xsd.nonPositiveIntegerOpens in a new window   nonPositiveInteger
%xsd.positiveIntegerOpens in a new window   positiveInteger
%xsd.shortOpens in a new window %SmallIntOpens in a new window short
%xsd.stringOpens in a new window string
%xsd.timeOpens in a new window %TimeOpens in a new window time
%xsd.unsignedByteOpens in a new window   unsignedByte
%xsd.unsignedIntOpens in a new window   unsignedInt
%xsd.unsignedLongOpens in a new window   unsignedLong
%xsd.unsignedShortOpens in a new window   unsignedShort

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

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.ReaderOpens in a new window 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 %NumericOpens in a new window 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 %NumericOpens in a new window property or an %IntegerOpens in a new window 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 %StringOpens in a new window 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-2Opens in a new window (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.SchemaOpens in a new window) 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.SchemaOpens in a new window) 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 %ListOfDataTypesOpens in a new window. 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 %ArrayOfDataTypesOpens in a new window. 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 %ListOfObjectsOpens in a new window. 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 %ArrayOfObjectsOpens in a new window. 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 %ListOfDataTypesOpens in a new window or %ArrayOfDataTypesOpens in a new window, 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 %ListOfObjectsOpens in a new window or %ArrayOfObjectsOpens in a new window, 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:

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.SchemaOpens in a new window and %XML.WriterOpens in a new window. 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.WriterOpens in a new window, 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.

FeedbackOpens in a new window