Generador de DTD y XSD

Cada API de aplicación utiliza XML de entrada, salida y error estándar. Estos XML se ajustan a la definición de tipo de documento relacionado (DTD).

Por ejemplo, contemple el XML siguiente:

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

La DTD correspondiente para este XML es:

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

Para crear estas DTD para el XML ampliado, se proporciona una herramienta denominada xsdGenerator.xml en el directorio <runtime_sandbox>/bin . Esta herramienta convierte un archivo XML con formato especial en una definición de esquema XML y DTD (XSD). El mandato para ejecutar la herramienta es:

Antes de ejecutar el siguiente comando, asegúrese de generar documentos API. Para más información, consulte Generación y acceso a Javadoc.

sci_ant.sh -f xsdGenerator.xml generate
También puede pasar las propiedades siguientes como argumentos de línea de mandatos:
  • xsdgen.use.targetnamespace
  • xsdgen.use.datatypeimport

Por ejemplo:

sci_ant.sh  -Dxsdgen.use.targetnamespace=N
-Dxsdgen.use.datatypeimport=N -f xsdGenerator.xml generate
La tabla siguiente contiene información sobre las propiedades de XSD Generator:
Campos Descripción
xsdgen.use.targetnamespace Opcional. El valor predeterminado es Y. Si se establece en Y, los archivos XSD se generan con un espacio de nombres de destino definido.
xsdgen.use.datatypeimport Opcional. El valor predeterminado es Y. Si se establece en Y, todos los archivos XSD hacen referencia a un único archivo XSD común que contiene todas las definiciones de tipo de datos comunes. Si se establece en N, cada archivo XSD se crea con una copia de las definiciones de base de datos incluidas.

Vaya al directorio " <runtime_sandbox>/xapidocs/extn/ " y cree una carpeta " input ". A continuación, coloque los archivos XML en el directorio input creado. Los archivos DTD y XSD resultantes se colocan en los directorios <runtime_sandbox>/xapidocs/extn/output/dtd y <runtime_sandbox>/xapidocs/extn/output/xsd respectivamente.

Nota: cuando xsdgen.use.datatypeimport se establece en 'Y', generará el archivo datatypes.xsd actualizado en el directorio <runtime_sandbox>/xapidocs/extn/output/xsd basándose en el datatypes.xml fusionado, incluidas las extensiones de tipo de datos.

Considere el siguiente ejemplo de XML que se podría colocar en el directorio de entrada y convertirse en XSD y 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>
La tabla siguiente contiene descripciones de atributos especiales para XML:
Campos Descripción
yfc:QryTypeSupported Este atributo determina si la funcionalidad de tipo de consulta está soportada para los atributos en este elemento. Si se establece en Y, entra en vigor para todos los elementos.
yfc:ComplexQuerySupported Este atributo especifica si está soportado un tipo de consulta compleja. Este atributo sólo puede estar presente en el elemento raíz.
yfc:XSDType Nombre del tipo que se utilizará para el elemento raíz de la definición de esquema.
yfc:DTDOccurrence
Este atributo puede contener cualquiera de los valores siguientes:
  • REQUIRED - Este elemento debe estar presente si el elemento padre está presente.
  • ZeroOrOne - Este elemento es opcional, pero sólo se puede producir una vez.
  • ZeroOrMany - Este elemento es opcional, pero se puede producir varias veces.
  • OneOrMany - Este elemento es necesario y se puede producir varias veces.
yfc:UseEntityOrdering
Este atributo determina si los hijos de primer nivel de un elemento están ordenados en la secuencia en la que se encuentran en los xmls de entidad. Este atributo puede contener cualquiera de los valores siguientes:
  • true - Todos los hijos de primer nivel están ordenados en la secuencia en la que se han encontrado en los xmls de entidad.
  • false - Los hijos de primer nivel de un elemento no están ordenados en la secuencia en la que se han encontrado en los xmls de entidad.
xmlns El espacio de nombres para targetNameSpace en el XSD de salida. Este atributo sólo entra en vigor si está presente en el elemento raíz.

Los atributos con valores de REQUIRED se generan como atributos necesarios en DTD y XSD. No obstante, un atributo necesario existente no se puede marcar como opcional.

Los valores de atributo también se pueden especificar para proporcionar restricciones adicionales. Una lista de opciones está separada por una barra vertical (|). El valor del atributo debe ser una de las opciones especificadas. Esto sólo está soportado para tipos de datos basados en series. Se quita el carácter de espacio en blanco de los valores si el propio valor es totalmente espacios, en cuyo caso la opción enumerada permanece sin alterar.

Por ejemplo, SomeAttr="A | B | C | |" da como resultado opciones válidas de "A", "B", "C", " " y "".

Nota: Las DTD no dan soporte a valores enumerados que contengan sólo caracteres de espacio en blanco. Por consiguiente, las restricciones de este tipo no se pueden representar en la DTD.

Los XML de entrada y salida predeterminados que pueden actuar como base para el XML personalizado se encuentran en el directorio <runtime_sandbox>/xapidocs/xmlstruct/ . Además, observe que los datos de DTDOccurrence y REQUIRED suministrados para las tablas estándar se deducen del archivo base en el directorio xmlstruct y no necesitan suministrarse. Si se proporcionan, la información existente se sustituye por cualquier información presente en los XML personalizados. Cualquier tipo de datos e información de relación se obtienen de los XML de entidad.

Nota: No coloque los XML personalizados en el directorio xmlstruct.

Por consiguiente, cuando se ejecuta la herramienta, estos archivos XML base sirven de valor predeterminado para los archivos XML personalizados, que sólo necesitan contener los cambios que efectúe como elementos y atributos ampliados. Esto permite a futuras actualizaciones modificar con seguridad los archivos XML en el directorio xmlstruct. Volver a ejecutar la herramienta de generación de XSD recoge automáticamente estas actualizaciones.

El archivo XML adecuado en el directorio xmlstruct asociado con el XML personalizado se identifica mediante el nombre de archivo. El XML personalizado puede empezar por un prefijo opcional seguido de un subrayado y el nombre del archivo base. Por ejemplo, un archivo XML personalizado denominado Custom_File_YFS_getOrderDetails_input.xml hace referencia al archivo YFS_getOrderDetails_input.xml en el directorio xmlstruct.

No obstante, el convenio de denominación es opcional. Por ejemplo, también puede denominar el archivo sampleCustomApi.xml personalizado, pero no se utiliza ningún archivo base. En este caso, la herramienta genera como salida un mensaje informativo para indicar que no se ha encontrado ningún XML base.

Nota: Si desea utilizar nuestro archivo XML base para la conversión, el convenio de denominación del XML personalizado debe tener el sufijo adecuado. Por ejemplo, Custom_File_YFS_getOrderDetails_input.xml utilizará el archivo base denominado YFS_getOrderDetails_input.xml.

El XSD generado especifica el espacio de nombres de destino tal como se muestra a continuación:

<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">

Este espacio de nombres se recoge del atributo xmlns en el elemento raíz del XML de entrada y tiene como valor predeterminado http://www.sterlingcommerce.com/documentation.

Los archivos XSD y DTD contienen atributos de tipo de consulta utilizados en API de lista cuando QryTypeSupported="Y" se establece en el elemento raíz del XML de entrada. Asimismo, los tipos de consultas complejas definidas para las API getItemList() y getOrganizationList() se representan en los archivos XSD y DTD cuando ComplexQuerySupported="Y" está establecido.

No obstante, en API, se exhiben las excepciones siguientes en las DTD puesto que estas restricciones no se pueden representar en una DTD, XSD o ambas puras:
  • Si una XML contiene varios atributos Extn, la DTD generada (no la XSD generada) sólo define un único elemento Extn que aparece como la unión de todos los elementos Extn posibles.
  • Atributos necesarios condicionalmente. Por ejemplo, necesita especificar un grupo de atributos u otro grupo de atributos tales como OrderHeaderKey o EnterpriseCode/OrderNo.
  • La condición obligatoria de un nodo depende de cierto valor de atributo. Por ejemplo, en la API createOrder(), el nodo OrderLine es necesario si DraftOrderFlag="N".
Para definir un tipo de datos personalizado para un atributo en la XSD generada, siga los pasos siguientes:
  1. Asegúrese de que ha ampliado el archivo datatypes.xml y de que el nuevo tipo de datos personalizado está presente en el directorio <runtime_sandbox>/xapidocs/api_javadocs/XSD/datatypes.xsd. Si el nuevo tipo de datos no está presente en datatypes.xsd, ejecute el siguiente mandato para volver a generar el archivo datatypes.xsd basado en las extensiones de datatypes.xml.
    • Para Windows - ejecute deployer.cmd -t xapideployer
    • Para Linux - ejecute ./deployer.sh -t xapideployer
  2. Utilice el tipo de datos personalizado, por ejemplo CustomDataType presente en datatypes.xsd para definir un atributo, por ejemplo, CustomAttribute en el XML de entrada presente en el directorio <runtime_sandbox>/xapidocs/extn/input .

    El ejemplo siguiente corresponde a un archivo XML.

    <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. Ejecute la herramienta xsdGenerator.xml para generar la XSD para el XML de ejemplo. La XSD generada contiene el atributo CustomAttribute personalizado correlacionado con el tipo de datos personalizado CustomDataType.