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:
-f xsdGenerator.xml generate
sci_ant.sh -Dxsdgen.use.targetnamespace=N -Dxsdgen.use.datatypeimport=N -f xsdGenerator.xml generate
|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.|
The input XML files should be placed in the <runtime_sandbox>/xapidocs/extn/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.
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>
|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.|
This attribute can contain any of the following values:
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:
|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
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.
| B | C | |" results in valid options of "A", "B", "C", "
", and "".
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.
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.
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.
XSD and DTD files contain query type attributes used in list APIs
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
ComplexQuerySupported="Y" is set.
- 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
- Ensure you have extended the
datatypes.xmlfile 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.xsdbased on the
- For Windows - run
deployer.cmd -t xapideployer
- For Linux - run
./deployer.sh -t xapideployer
- For Windows - run
- Use the custom datatype, for example
datatypes.xsdto define an attribute, for example,
CustomAttributein 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>
- Run the
xsdGenerator.xmltool to generate XSD for the sample XML. The generated XSD contains the custom
CustomAttributeattribute mapped to the