XML documents that use DTDs

A document type document (DTD) is a data model for XML documents that provides a special syntax to describe the XML document's template, called a schema. This DTD is a file with the .dtd extension. The business object definitions that represent the schema of an XML document use information in the DTD to preserve and record the document's structure. This section provides the following information about deriving structure information for a business object definition from a DTD:

Requirements for business object definitions based on DTDs

To ensure that business object definitions that correspond to DTDs conform to the requirements of the XML data handler, use the guidelines in this section, which involve:

A properly-constructed business object definition ensures that the data handler can correctly convert a business object to an XML document and an XML document to a business object. For information on how to create business objects for the XML data handler, see XML documents that use schema documents.

Business object structure for DTDs

To represent a DTD requires at least the two business object definitions described in Business object structure. For a DTD, these business object definitions have the following additional requirements:

A business object that is processed by the XML data handler using business object definitions based on DTDs must also follow these rules:

Note:
For a list of general business object requirements, see Requirements for business object definitions.

An example DTD for an XML document is shown below. The DTD is named Order, and it contains elements that correspond to an application Order entity.

<!--Order -->
<!-- Element Declarations -->
<!ELEMENT Order (Unit+)>
<!ELEMENT Unit (PartNumber?, Quantity, Price, Accessory*)>
<!ELEMENT PartNumber (#PCDATA)>
<!ELEMENT Quantity (#PCDATA)>
<!ELEMENT Price (#PCDATA)>
<!ELEMENT Accessory (Quantity, Type)>
<!ATTLIST Accessory
     Name CDATA >
<!ELEMENT Type (#PCDATA)>

Figure 13 shows the structure of a business object that might be created to correspond to an XML document associated with the Order DTD. Note that each XML element and element attribute in the Order DTD has a corresponding business object attribute. The top-level business object contains attributes for the XML declaration, the DOCTYPE, and the top-level Order element. Note also that the element attribute Name is the first attribute in the Accessory business object.

Figure 13. Example business object for XML document using the Order DTD


Business object attribute properties for DTDs

When the business object definitions for an XML document are based on DTDs, the business object attribute properties have the restrictions discussed in Business object attribute properties. In addition, the DTD syntax can determine the "required-ness" of a business object attribute. The "required-ness" is a combination of factors, including cardinality and whether the attribute is a key, that determines whether the XML data handler requires the attribute. If an attribute is required, its Required attribute property must be set to true.

The setting of the Required attribute property depends on the XML element and attribute specifications, as well as the settings of the Cardinality, Key, and Foreign Key attribute properties, as follows:

Application-specific information for XML components in DTDs

This section provides the following information on the application-specific information format for business object definitions based on DTDs:

Business-object-level application-specific information

The XML data handler uses the following types of business objects to represent different kinds of XML elements generated from a DTD:

These types of business objects are distinguished by the application-specific information at the business object level.

Regular business object definitions based on DTDs

A regular business object represents an XML element. In this type of business object, the application-specific information at the business object level identifies the name of the XML element that the business object represents. For example, suppose the XML element is defined as:

<!ELEMENT Unit(...)> 

The application-specific information at the business object level for the associated business object definition is:

[BusinessObjectDefinition]
Name = MyApp_Unit
AppSpecificInfo = elem_name=Unit
[Attribute]
...

Mixed business object definitions based on DTDs

A mixed business object represents a mixed XML element, one that contains mixed content of character data (#PCDATA ) and other subelements. The DTD representation of a mixed-type XML element looks like the following:

<!ELEMENT (#PCDATA | CONTAINED_ELEMENT1 | CONTAINED_ELEMENTN)*>

For example, suppose the Cust XML element is defined in the DTD as follows:

<!ELEMENT Cust(#PCDATA | Address | Phone)*>

To represent a mixed-type XML element, use a mixed-type business object definition. For a mixed business object definition, its business-object-level application-specific information consists of the following components:

For the business object definition, MyApp_Cust, which represents the Cust element, the application-specific information at the business object level is as follows:

[BusinessObjectDefinition]
Name = MyApp_Cust
AppSpecificInfo = Cust;type=MIXED;

Wrapper business object definitions based on DTDs

A wrapper business object represents a repeating choice list. This type of business object definition is needed when an XML element has children that can appear in any order and be of any cardinality. A wrapper business object preserves the order and cardinality of the child elements in the XML document.

For a choice-list XML element, the DTD definition looks like this:

(CONTAINEDELEMENT1 | ... | CONTAINEDELEMENTN)*

As an example, the choice-list XML element definition in a DTD might be:

<!ELEMENT CUST( U | I | B )* )> 

This element contains three subelements that are optional and that can appear in any order. Each subelement is a simple element. Figure 14 shows an XML document of this type.

Figure 14. XML document content for a repeating choice list

<CUST>
   <U>.....
   </U>
   <B>.....
   </B>
   <I>.....
   </I>
   <B>.....
   </B>
   <U>.....
   </U>
...

To represent a choice-list XML element defined in a DTD, the business object definition is hierarchical. It includes the following business object definitions:

Figure 15 shows an illustration of the hierarchy of the business object definitions for a choice-list XML element. At runtime, each child business object is an instance of a wrapper business object and has only one attribute populated with data. As an example, a business object for the XML content in Figure 14 would have five children, each with the appropriate attribute populated.

Figure 15. Hierarchical business object definition for choice-list XML element


Figure 16 shows the parent business object definition, MyApp_Cust, with its application-specific information.

Figure 16. Parent business object definition for a choice-list element

[BusinessObjectDefinition]
Name = MyApp_Cust
AppSpecificInfo = 
 
   [Attribute]
   Name = CustWrapper
   Type = MyApp_CustWrapper
   Cardinality = N
   AppSpecificInfo = attr_name=CustWrapper;(U|I|B)
[End]

The wrapper business object definition, MyApp_CustWrapper, has three attributes, one for each choice element. Because each choice element contains character data, the application-specific information for each attribute specifies:

Note:
For more information on attributes for character data, see For an XML element with only PCDATA.

Figure 17 shows the wrapper business object definition for this XML document.

Figure 17. Wrapper business object definition for a choice-list element

[BusinessObjectDefinition]
Name = MyApp_CustWrapper
AppSpecificInfo =
 
   [Attribute]
   Name = DataU
   Type = String
   AppSpecificInfo = attr_name=U;type=pcdata;
   [End]
 
   [Attribute]
   Name = DataI
   Type = String
   AppSpecificInfo = attr_name=I;type=pcdata;
   [End]
 
   [Attribute]
   Name = DataB
   Type = String
   AppSpecificInfo = attr_name=B;type=pcdata;
   [End]

Array attribute application-specific information

If a business object attribute represents an XML element that contains other elements, the application-specific information must contain the name of the element. For example, if an attribute named DeliveryDate has a business object type and represents an element named DATETIME, the application-specific information contains the name of the element:

Name = DeliveryDate
Relationship = Containment
Cardinality = n
AppSpecificInfo = DATETIME

Attribute application-specific information

The attribute of a business object definition can represent the following XML components:

Table 27 shows the tags for attribute-level application-specific information for these different XML components along with the sections in this manual that describe these tags in more detail.

Table 17. Tags for attribute application-specific information

Representation of business object attribute Application-specific information For more information
An XML element

elem_name=name of XML element

For XML elements
An XML element with only PCDATA

elem_name=name of XML element;type=pcdata

For an XML element with only PCDATA
An attribute for an XML element

attr_name=name of XML attribute

type=attribute

For an XML attribute
An XML element that contains character data and attributes

type=pcdata;notag

For an XML element with character data and attributes
An XML element or attribute whose content includes special characters

escape=true

For an XML element or attribute that contains special characters
For a DOCTYPE declaration

type=doctype

For an XML DOCTYPE declaration
For a CDATA section

type=cdata

For a CDATA section
A comment to be added to the XML document type=comment For an XML comment
A processing instruction type=pi For XML processing instructions

Note:
Attribute application-specific information can also include a tag of the form
( a | b | c ) to specify a multiple-cardinality attribute that represents a repeating choice. For more information, see Wrapper business object definitions based on DTDs.

For XML elements

Every simple (String) business object attribute that represents an XML element must include the elem_name tag in its application-specific information to identify the associated element:

elem_name=name of XML element

For example, if a business object attribute CustLName represents a simple XML attribute, its application-specific information is:

Name = CustLName
AppSpecificInfo = elem_name=CustLName;

XML element names can contain special characters (such as periods and hyphens). However, the names of business object attributes cannot contain these special characters. Therefore, the name of the XML element must be specified in the elem_name tag. To name the business object attribute, the XML ODA removes any special characters in the XML element's name, replacing them with an underscore (_) character.

In the following example, the application-specific information for the XML element specifies a different from the actual XML element's name because the attribute contains a special character:

Name = Phone_Tag
AppSpecificInfo = elem_name=Phone#Tag;

The actual name of the XML element contains a pound sign (#), which is invalid in the names of business-object attributes. Therefore, the elem_name tag in the application-specific information specifies the actual XML element name. In the name of the associated business-object attribute, the pound sign is replaced with an underscore.

For an XML element with only PCDATA

XML elements that contain only character data are mixed elements, which contain only the PCDATA element content specifier. A business object attribute that represents an XML element with only PCDATA must have the following type tag in the application-specific information:

type=pcdata

In this case, the element name is the first field in the application-specific information, and the type parameter is the second field.

For example, an element named PartNumber that contains only PCDATA would have the following definition in the DTD:

<!ELEMENT PartNumber (#PCDATA)>

The corresponding attribute in the business object definition would have the following application-specific information:

Name = PartNumber
AppSpecificInfo = elem_name=PartNumber;type=pcdata;

If the application-specific information also contains the text notag, the XML data handler does not generate XML markup. It adds only the value of the attribute itself to the XML document. For more information, see For an XML element with character data and attributes.

For an XML attribute

If a business object attribute represents an attribute of an XML element, its application-specific information must include the following tags:

Note:
As described in Business object structure, all business object attributes that represent XML attributes must occur within the business object definition before any business object attributes that represent XML elements.

For example, if a business object attribute named ID represents an XML attribute named ID, its application-specific information is:

Name = ID
AppSpecificInfo = attr_name=ID;type=attribute;

For another example that uses the type=attribute tag, see For an XML element with character data and attributes.

For an XML element with character data and attributes

If an XML element contains only PCDATA or CDATA and has one or more XML attributes, its business object definition must include the following attributes:

For example, suppose an XML element named Price has an attribute named Currency and requires data for Price:

<!ELEMENT Price (#PCDATA)>
<!ATTLIST Price Currency NMTOKEN #IMPLIED>

Because the Price element has an XML attribute, in its business object definition a business-object attribute must created for Currency. In addition, another attribute must exist to hold the Price data. The attribute for the Price data must specify notag in its application-specific information to prevent the data handler from creating a start and end tag for this attribute.

The Price child business object might look like this:

[BusinessObjectDefinition]
Name = Price
AppSpecificInfo = Price

   [Attribute]
   Name = Currency
   Type = String
   AppSpecificInfo = attr_name=Currency;type=attribute;
   ...
   [End]

   [Attribute]
   Name = Price
   Type = String
   AppSpecificInfo = Price;type=pcdata;notag
   ...
   [End]

In this case, the data handler does not generate a new XML element for the Price data but simply adds the data to the parent element.

For an XML element or attribute that contains special characters

Business object attributes representing XML elements or XML attributes with content that require escape processing must include the following tag in their application-specific information:

escape=true

An attribute requires escape processing if the attribute represents an XML element whose value contains any of the following special characters:

An attribute will not be escape-processed unless it contains the escape=true tag in its application-specific information. This tag must be placed at the end of any existing application-specific information. For example:

[Attribute]
Name=Data
Type=String
AppSpecificInfo=Price;type=pcdata;escape=true
[End]

If the attribute's application-specific information does not include the escape tag, the XML data handler checks the value of the DefaultEscapeBehavior property to determine whether to perform escape processing:

For an XML DOCTYPE declaration

If a business object attribute represents a document type declaration in the prolog, the application-specific information must include the following type tag:

type=doctype

For example, if a business object attribute named DocType represents a DOCTYPE element, its application-specific information is:

Name = DocType
AppSpecificInfo = type=doctype;

If the DocType attribute has the value:

DOCTYPE CUSTOMER "customer.dtd"

then the data handler generates the following XML:

<!DOCTYPE CUSTOMER "customer.dtd">

This application-specific information may also be used to include general entity declarations in the XML document. However, there is no explicit support for the inclusion of an internal DTD or parameter entity declarations. These can be included in the document by putting the entire text into the value of an attribute that has type=doctype in the application-specific information.

For a CDATA section

If a business object attribute represents a CDATA section within an XML document, the application-specific information must include the following type tag:

type=cdata

For example, if a business object attribute UserArea represents a CDATA section, its application-specific information is:

Name = UserArea
AppSpecificInfo = type=cdata;

For an XML comment

When the XML data handler converts a business object to an XML document, you can specify that it add comments to the XML document. To enable the data handler to add comments, take the following steps:

For example, if a business object attribute named Comment represents an XML comment that the data handler should add to an XML document, the Comment attribute would appear as follows:

Name = Comment
AppSpecificInfo = type=comment;

If this attribute has the value "Customer information update from application A", the following XML is generated:

<!--Customer information update from application A-->

For XML processing instructions

If a business object attribute represents a processing instruction, the application-specific information must include the following type tag:

type=pi

For example, if a business object attribute named XMLDeclaration represents the XML declaration in the prolog, the application-specific information is:

Name = XMLDeclaration
AppSpecificInfo = type=pi;

If the attribute has the value:

xml version = "1.0" 

then the XML data handler generates the following XML:

<?xml version="1.0"?> 

Creating business object definitions from DTDs

A DTD describes the format of an XML document. Therefore, the DTD is very useful for obtaining information needed for the business object definition. To translate the structure information in the DTD to a business object definition, you can use the XML Object Discovery Agent (ODA). For information on XML ODA, see Using an XML ODA to create business object definitions.

Note:
Previous versions of the XML data handler included two tools to create business object definitions from DTDs: Edifecs SpecBuilder and the deprecated XMLBorgen utility. The XML ODA replaces both these tools have been replaced in functionality.

Supported DTD structures

The XML ODA supports structures of a DTD including:

Unsupported DTD structures

The XML ODA is capable of processing most DTDs. However, it does not support the following DTD structures:

Copyright IBM Corp. 1997, 2004