Controlling the Projection to XML Schemas
For any XML-enabled class, there is an implicit XML schema for that class, which you can view. InterSystems IRIS® data platform provides ways to modify that schema.
The XML examples in this topic are in literal format.
Class and Property Parameters Discussed on This Page |
---|
|
Viewing the Schema for an XML-Enabled Class
To see the schema for a given XML-enabled class, you have two options:
-
You can use %XML.SchemaOpens in a new tab and %XML.WriterOpens in a new tab to generate complete schema documents. For details, see Generating XML Schemas from Classes.
-
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 topic 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;
}
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)");
}
And the GXML.Doctor class is as follows:
Class GXML.Doctor Extends (%Persistent, %Populate, %XML.Adaptor)
{
Property Name As %Name;
}
To see the schema for the GXML.Person class, enter the following command in the Terminal:
do ##class(GXML.Person).XMLSchema()
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>
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 tab).
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.
For information on the XML data types, see https://www.w3.org/TR/xmlschema-2/Opens in a new tab.
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;
}
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>
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 ];
}
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>
Note that the default for minOccurs is 1; that is, Property2 is required.
For compatibility reasons, %XML.ReaderOpens in a new tab does not check for required properties by default, but you can cause it to do so; see Checking for Required Elements and Attributes. 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.
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 most cases, you can also specify these as property parameters.
The parameters that affect XML schemas are as follows:
Influences how the property values are escaped; see Handling Special XML Characters.
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");
}
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>
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.
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.
Affects the schema if VALUELIST is also specified and if XMLLISTPARAMETER equal to "DISPLAYLIST". See the discussions for those two parameters.
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);
}
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>
Controls the maxInclusive attribute. See the example in MAXLEN.
Controls the minLength attribute. See the example in MAXLEN.
Controls the minInclusive attribute. See the example in MAXLEN.
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");
}
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>
Applicable to a %NumericOpens in a new tab 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>
Applicable to a %NumericOpens in a new tab property or an %IntegerOpens in a new tab 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>
Applicable to a %StringOpens in a new tab 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.
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]");
}
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>
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 tab (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.
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:
InterSystems IRIS Stream Type | XSD Type Used in Projections to XML |
---|---|
%Library.GlobalCharacterStreamOpens in a new tab, %Library.FileCharacterStreamOpens in a new tab, %Stream.FileCharacterOpens in a new tab, and %Stream.GlobalCharacterOpens in a new tab | string |
%Library.GlobalBinaryStreamOpens in a new tab, %Library.FileBinaryStreamOpens in a new tab, %Stream.FileBinaryOpens in a new tab, and %Stream.GlobalBinaryOpens in a new tab | base64Binary |
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;
}
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>
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:
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");
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>
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"/>
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 tab) 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>
-
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"/>
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");
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>
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");
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>
The following rules govern the names of the types:
-
For the PropName property, the corresponding type is named ArrayOfXMLItemNamePairOfXMLKeyNameType, where:
-
XMLItemName is the name of items in the collection as described as in Controlling the Element and Attribute Names for Array-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.)
-
XMLKeyName is the name of the key for the collection as described in Controlling the Element and Attribute Names for Array-Type Properties. The default is the property name with Key concatenated to the end
-
Type is the XML type to which the property class is projected.
<element minOccurs="0" name="PropName" type="s01:ArrayOfMyXmlItemNamePairOfMyXmlKeyNameLong" xmlns:s01="mytypes"/>
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 tab) 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>
-
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>
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");
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>
%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 tab. For example, consider the following property definition:
Property PropName As %ListOfDataTypes(XMLITEMNAME = "MyXmlItemName");
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>
For the rules for the names of the types, see List of Classname. 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"/>
That is, the collection item is assumed to be a string. Also see Options for Using Collection Classes.
%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 tab. For example, consider the following property definition:
Property PropName As %ArrayOfDataTypes(XMLITEMNAME = "MyXmlItemName", XMLKEYNAME = "MyXmlKeyName");
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>
For the rules for the names of the types, see Array of Classname. 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>
That is, the collection item is assumed to be a string. Also see Options for Using Collection Classes.
%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 tab. For example, consider the following property definition:
Property PropName As list Of %Integer(XMLITEMNAME = "MyXmlItemName");
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>
For the rules for the names of the types, see List of Classname. 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"/>
As a result, this schema is unusable. See Options for Using Collection Classes. .
%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 tab. For example, consider the following property definition:
Property PropName As %ArrayOfObjects(XMLITEMNAME = "MyXmlItemName", XMLKEYNAME = "MyXmlKeyName");
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>
For the rules for the names of the types, see List of Classname. 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>
As a result, this schema is unusable. See Options for Using Collection Classes.
Options for Using Collection Classes
Within an XML-enabled class, tor each property of type %ListOfDataTypesOpens in a new tab or %ArrayOfDataTypesOpens in a new tab, 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 tab or %ArrayOfObjectsOpens in a new tab, 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.
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 (%ListOfDataTypesOpens in a new tab, %ArrayOfDataTypesOpens in a new tab, %ListOfObjectsOpens in a new tab, %ArrayOfObjectsOpens in a new tab). In the subclass, specify the ELEMENTTYPE class parameter. For example:
Class MyApp.MyIntegerCollection Extends %ListOfDataTypes { Parameter ELEMENTTYPE="%Library.Integer"; }
For ELEMENTTYPE, specify the complete package and class name of the class used in the collection. If you subclass %ListOfDataTypesOpens in a new tab or %ArrayOfDataTypesOpens in a new tab, specify a data type class. Then the type for the collection element is controlled by the XSDTYPE parameter for that class.
If you subclass %ListOfObjectsOpens in a new tab or %ArrayOfObjectsOpens in a new tab, specify an XML-enabled class. For example
Class MyApp.MyObjectCollection Extends %ListOfObjects { Parameter ELEMENTTYPE="MyApp.SimpleObject"; }
Then use your custom collection class in your property definition. For example:
Property MyProp as MyApp.MyIntegerCollection;
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;
}
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
XML types are assigned to namespaces as follows:
-
If the corresponding class definition defines the XSDTYPE class parameter, the type is in the following W3 namespace:
http://www.w3.org/2001/XMLSchema
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.
-
If the class definition does not define XSDTYPE but does define NAMESPACE, the type is in the namespace specified by NAMESPACE.
-
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.
To see the namespaces to which the types are assigned, you must use %XML.SchemaOpens in a new tab and %XML.WriterOpens in a new tab. For details, see Generating XML Schemas from Classes.
Suppressing the Namespace Prefix for the Type QName
As described in Using XML Tools, when you generate output with %XML.WriterOpens in a new tab, 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">
You can define the corresponding InterSystems IRIS class definition so that the namespace prefix is suppressed. For example:
<TeamB xsi:type="TeamB">
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;
}
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;
}
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>
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.
The SUPPRESSTYPEPREFIX does not affect the namespace to which the XML type belongs. It just suppresses the writing of the type prefix.