DTD and XSD generator

Every application API uses standard input, output, and error XMLs. These XMLs conform to the related Document Type Definition (DTD).

For example, consider the following XML:

<?xml version="1.0" encoding="UTF-8"> 
<Order EnterpriseCode="DEFAULT" OrderNo="S100" />

The corresponding DTD for this XML is:

<!ELEMENT Order> 
<!ATTLIST Order OrderNo CDATA #IMPLIED> 
<!ATTLIST Order EnterpriseCode CDATA #REQUIRED>

To create such DTDs for the extended XML, a tool called the xsdGenerator.xml is provided in the <runtime_sandbox>/bin directory. This tool converts a specially-formatted XML file into a DTD and XML schema definition (XSD). The command for running the tool is:

Before you run the following command, ensure that you generate API docs. For more information, see Generating and accessing Javadoc.

sci_ant.sh -f xsdGenerator.xml generate
You can also pass the following properties as command line arguments:
  • xsdgen.use.targetnamespace
  • xsdgen.use.datatypeimport

For example,

sci_ant.sh  -Dxsdgen.use.targetnamespace=N
-Dxsdgen.use.datatypeimport=N -f xsdGenerator.xml generate
The following table contains information about the XSD Generator properties:
Fields Description
xsdgen.use.targetnamespace Optional. The default value is Y. If set to Y, the XSD files are generated with a defined target namespace.
xsdgen.use.datatypeimport Optional. The default value is Y. If set to Y, all the XSD files reference a single common XSD file containing all the common data type definitions. If set to N, each XSD file is created with a copy of the database definitions embedded within it.

Browse to the <runtime_sandbox>/xapidocs/extn/ directory, and create an input folder. Then, place the XML files into the created input directory. The resulting DTD and XSD files are placed in the <runtime_sandbox>/xapidocs/extn/output/dtd and <runtime_sandbox>/xapidocs/extn/output/xsd directories respectively.

Note: When the xsdgen.use.datatypeimport is set to 'Y' it will generate the updated datatypes.xsd file in the <runtime_sandbox>/xapidocs/extn/output/xsd directory based on the merged datatypes.xml including the data type extensions.

Consider the following sample XML that could be placed in the input directory and converted to an XSD and DTD:

<Item yfc:DTDOccurrence="REQUIRED" ItemKey="" ItemID="REQUIRED"
OrganizationCode="REQUIRED" UnitOfMeasure=""> 
   <PrimaryInformation Description="" ItemType="" /> 
   <AdditionalAttributeList> 
        <AdditionalAttribute Name="" Value=""/> 
    </AdditionalAttributeList> 
    <Extn ExtnAttr1="" ExtnRefId=""> 
       <CSTItemDataList yfc:DTDOccurrence="ZeroOrOne"> 
         <CSTItemData yfc:DTDOccurrence="ZeroOrMany" ItemDataKey="" 
Description=""> 
            <CSTItemExtraData yfc:DTDOccurrence="ZeroOrOne" CodeType="" 
DataType="" /> 
            <YFSCommonCode yfc:DTDOccurrence="REQUIRED" CodeName="" 
CodeType="" CodeValue="" />  
         </CSTItemData> 
       </CSTItemDataList> 
    </Extn> 
</Item>
The following table contains descriptions of special attributes for XML:
Fields Description
yfc:QryTypeSupported This attribute determines whether or not the query type functionality is supported for the attributes in this element. If set to Y, it takes effect for all the elements.
yfc:ComplexQuerySupported This attribute specifies whether or not a complex query type is supported. This attribute can only be present in the root element.
yfc:XSDType The name of the type to use for the root element schema definition.
yfc:DTDOccurrence
This attribute can contain any of the following values:
  • REQUIRED - This element must be present if the parent element is present.
  • ZeroOrOne - This element is optional, but may occur only once.
  • ZeroOrMany - This element is optional, but may occur multiple times.
  • OneOrMany - This element is required, and may occur multiple times.
yfc:UseEntityOrdering
This attribute determines whether or not all the first-level children of an element are ordered in the sequence they are found in the entity xmls. This attribute can contain any of the following values:
  • true - All the first-level children of an element are ordered in the sequence they are found in the entity xmls.
  • false - The first-level children of an element are not ordered in the sequence they are found in the entity xmls.
xmlns The namespace to use for the targetNameSpace in the output XSD. This attribute takes effect only if it is present in the root element.

The attributes with values of REQUIRED are generated as required attributes in the DTD and XSD. However, an existing required attribute cannot be marked as optional.

The attribute values can also be specified to supply additional constraints. A list of options is separated by a vertical bar (|). The value of the attribute must be one of the given options. This is only supported for data types based on the strings. The values are trimmed of the whitespace character if the value itself is entirely spaces, in which case the enumerated option remains unchanged.

For example, SomeAttr="A | B | C | |" results in valid options of "A", "B", "C", " ", and "".

Note: The DTDs do not support enumerated values containing only whitespace characters. Therefore, restrictions of this type cannot be represented in the DTD.

The default input and output XMLs that can act as a base for your custom XML are located in the <runtime_sandbox>/xapidocs/xmlstruct/ directory. Also note that the DTDOccurrence and REQUIRED data provided for the standard tables are inferred from the base file in the xmlstruct directory and do not need to be supplied. If they are provided, the existing information is overridden by any new information present in the custom XMLs. Any required datatype and relationship information are obtained from the entity XMLs.

Note: Do not put your custom XMLs in the xmlstruct directory.

Therefore, when the tool is run these base XML files serve as a default to your custom XML files, which need only contain the changes made by you such as the extended elements and attributes. This allows future upgrades to safely modify the XML files in the xmlstruct directory. Re-running the XSD generation tool automatically picks up these updates.

The appropriate XML file in the xmlstruct directory associated with your custom XML is identified by the file name. Your custom XML may start with an optional prefix followed by an underscore and the base file name. For example, a custom XML file named Custom_File_YFS_getOrderDetails_input.xml refers to the YFS_getOrderDetails_input.xml file in the xmlstruct directory.

However, the naming convention is optional. For example, you can also name your custom XML sampleCustomApi.xml but no base file is used. In this case, the tool outputs an informational message to indicate that no base XML is found.

Note: If you want to use our base XML file for conversion, the naming convention of your custom XML must be suffixed appropriately. For example, Custom_File_YFS_getOrderDetails_input.xml would use the base file named YFS_getOrderDetails_input.xml.

The generated XSD specifies the target namespace as shown below:

<xsd:schema attributeFormDefault="unqualified" 
elementFormDefault="qualified"
targetNamespace="http://www.sterlingcommerce.com/documentation" 
xmlns:xsd=http://www.w3.org/2001/XMLSchema
xmlns:yfc="http://www.sterlingcommerce.com/documentation">

This namespace is picked up from the xmlns attribute on the root element of the input XML and defaults to http://www.sterlingcommerce.com/documentation.

The XSD and DTD files contain query type attributes used in list APIs when QryTypeSupported="Y" is set in the root element of the input XML. Similarly, the complex query types defined for getItemList() and getOrganizationList() APIs are represented in the XSD and DTD files when ComplexQuerySupported="Y" is set.

However, in APIs the following exceptions are exhibited in the DTDs since these constraints cannot be represented in a pure DTD, XSD or both:
  • If an XML contains multiple Extn attributes, the generated DTD-only (not generated XSD) defines a single Extn element which appears as the union of all possible Extn elements.
  • Conditionally required attributes. For example, you need to specify a group of attributes or another group of attributes such as OrderHeaderKey or EnterpriseCode/OrderNo.
  • Mandatory condition of a node depends on some attribute value. For example in the createOrder() API, the OrderLine node is required if the DraftOrderFlag="N".
To define a custom datatype for an attribute in the generated XSD, do the following steps:
  1. Ensure you have extended the datatypes.xml file and the new custom datatype is present in the <runtime_sandbox>/xapidocs/api_javadocs/XSD/datatypes.xsddirectory. If the new datatype is not present in datatypes.xsd, run the following command to regenerate the datatypes.xsd based on the datatypes.xml extensions.
    • For Windows - run deployer.cmd -t xapideployer
    • For Linux - run ./deployer.sh -t xapideployer
  2. Use the custom datatype, for example CustomDataType present in datatypes.xsd to define an attribute, for example, CustomAttribute in your input XML present in the <runtime_sandbox>/xapidocs/extn/input directory.

    The following is a sample XML file.

    <Item yfc:DTDOccurrence="REQUIRED" ItemKey="" ItemID="REQUIRED"
    OrganizationCode="REQUIRED" UnitOfMeasure="">
       <PrimaryInformation Description="" ItemType="" CustomAttribute="">
         <yfc:doc>
           <Attributes>
             <Attribute DataType="CustomDataType" Name="CustomAttribute"/>
           </Attributes>
         </yfc:doc>
       <PrimaryInformation/>
    </Item>
  3. Run the xsdGenerator.xml tool to generate XSD for the sample XML. The generated XSD contains the custom CustomAttribute attribute mapped to the CustomDataType custom datatype.