Formateo del esquema XSD para revisión por pares

Diseñé un modelo de datos que está representado por un esquema XSD. El modelo de datos también proporciona los tipos que se utilizan como parámetros del servicio web en un descriptor WSDL.

Me gustaría enviar el esquema XSD y pedirle a las personas involucradas que revisen por pares el modelo de datos.

¿Qué herramienta o método de presentación sugeriría que se usara como base para las revisiones por pares? El modelo de datos debe ser legible para personas no especializadas, al menos en lo que se refiere a los significados semánticos de los parámetros

Editar:

Para ser más específico: por supuesto, sintácticamente, el esquema valida. En realidad, ya estoy trabajando en un código que se basa en las clases generadas por JAXB. Mi meta es

  1. para congelar el modelo de datos y así los parámetros de entrada
  2. para asegurarse nada se perdió u olvidó de una semántica (en el sentido de punto de vista relevante para el negocio)

Editar 2

He estado pensando en cómo sería mejor difundir un modelo de datos. Estoy pensando en algo así como un JavaDoc para esquemas XSD. ¿Alguien sabe si algo así existe? Básicamente se haría con un conjunto de XSLT, ¿verdad?

10
agregado el autor f3lix, fuente

5 Respuestas

Conozco las siguientes herramientas que generan documentación a partir de archivos de esquema xml (XSD):

  • xs3p
    • XSLT stylesheet that generates single XHTML from XSD
  • xsddoc
  • xnsdoc
    • improved commercial version of xsddoc
    • free for personal/educational use
    • JavaDoc like output
  • XSDdoc 2.0
    • commercial
    • JavaDoc like output

Para un pequeño esquema XML, probablemente sugeriría usar la hoja de estilo XSLT xs3p . Para obtener más información sobre un esquema complejo, sugiero usar xsddoc .

20
agregado

Lo más parecido a Javadoc para un esquema xml que he visto es ejecutar la herramienta Javadoc en la fuente generada desde el esquema. Esto requiere dos cosas: 1) Que su esquema tenga elementos de anotación internos que lo documenten, y que 2) su generador de origen use esas anotaciones como elementos de Javadoc.

0
agregado

Recomiendo usar el XSD para algo. Específicamente, muestre algunas aplicaciones reales, con ejemplos como código real.

Las aplicaciones reales son las que hacen que un esquema sea interesante. Los ejemplos no tienen que ser grandes, sofisticados o completamente realistas. Solo tienen que compilar. Otras personas querrán copiar y pegar los ejemplos del código.

Estos ejemplos son el "mundo de saludo" del esquema. Y actúan como una especie de prueba unitaria para el esquema.

0
agregado

** Disclosure : I work for Innovasys, the producer of the documentation tool mentioned below *

Puede echar un vistazo a Documento de Innovasys. X . Además de generar automáticamente una página estructurada y vinculada para cada elemento, tipo simple, tipo complejo, grupo y grupo de atributos, también generará diagramas XSD vinculados (incluidas secuencias/opciones, etc.) y tablas de estructura que incluyen las anotaciones de sus XSD y da sentido a las relaciones entre los elementos en tus esquemas. El resultado está basado en plantillas para que pueda adaptarlo a su estilo y estructura preferidos. Construirá salida para html listo para web o archivos de ayuda compilados.

Excepcionalmente, también incluye un editor WYSIWYG que le permite crear contenido adicional para complementar lo que se genera automáticamente y las anotaciones de la fuente XSD, para que pueda proporcionar información contextual adicional para su revisión por pares. También hay una función de Extensiones de comunidad que permite a las personas que visualizan el resultado generado grabar comentarios y comentarios, y que se pueden ver y ejecutar directamente desde Document. X.

0
agregado

El muy útil desarrollador de Oxygen xml también admite generar documentación, ver http://www.oxygenxml.com/xml_schema_documentation.html (comercial, pero hay una versión de prueba totalmente funcional de 30 días disponible)

Voy a probarlo ahora, necesito una forma simple de generar un documento con todos los tipos y xsd disponible: descripción de la documentación como una simple descripción de interfaz ...

0
agregado