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
xsdgen.use.targetnamespace
xsdgen.use.datatypeimport
For example,
sci_ant.sh -Dxsdgen.use.targetnamespace=N
-Dxsdgen.use.datatypeimport=N -f xsdGenerator.xml generate
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.
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>
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:
|
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:
|
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 "".
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.
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.
- 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"
.
- 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 indatatypes.xsd
, run the following command to regenerate thedatatypes.xsd
based on thedatatypes.xml
extensions.- For Windows - run
deployer.cmd -t xapideployer
- For Linux - run
./deployer.sh -t xapideployer
- For Windows - run
- Use the custom datatype, for example
CustomDataType
present indatatypes.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>
- Run the
xsdGenerator.xml
tool to generate XSD for the sample XML. The generated XSD contains the customCustomAttribute
attribute mapped to theCustomDataType
custom datatype.