Formattazione dello schema XSD per la revisione tra pari

Question

Ho progettato un modello di dati che è rappresentato da uno schema XSD. Il modello di dati fornisce anche i tipi utilizzati come parametri del servizio Web in un descrittore WSDL.

Vorrei inviare lo schema XSD in giro e chiedere alle persone coinvolte di rivedere il modello di dati tra pari.

Quale strumento o metodo di presentazione suggeriresti di utilizzare come base per le revisioni tra pari? Il modello di dati dovrebbe essere leggibile per le persone non qualificate, almeno per quanto riguarda i significati semantici dei parametri

Modifica

Per essere più specifici: ovviamente, sintatticamente, lo schema convalida. In realtà sto già lavorando su un codice basato sulle classi generate da JAXB. Il mio obiettivo è

1. per bloccare il modello di dati e quindi i parametri di input
2. per essere sicuro nulla è stato perso o dimenticato da a semantico (nel senso di rilevante dal punto di vista commerciale).

Modifica 2

Ho pensato a come sarebbe probabilmente meglio diffondere un modello di dati. Sto pensando a qualcosa come un JavaDoc per gli schemi XSD. Qualcuno sa se esiste qualcosa del genere? Fondamentalmente sarebbe fatto con una serie di XSLT, giusto?

Answer 1

Conosco i seguenti strumenti che generano documentazione dai file XML Schema (XSD):

• xs3p
  • Foglio di stile XSLT che genera XHTML singolo da XSD
• xsddoc
  • gratuito / LGPL
  • principalmente basato su XSLT
  • output come JavaDoc
  • vedi esempi xsddoc
• xnsdoc
  • versione commerciale migliorata di xsddoc
  • gratuito per uso personale / educativo
  • output come JavaDoc
• XSDdoc 2.0
  • commerciale
  • output come JavaDoc

Per un piccolo schema XML, suggerirei probabilmente di usare il foglio di stile XSLT xs3p . Per uno schema più complesso, suggerisco di utilizzare xsddoc .

Answer 2

Raccomando usando l'XSD per qualcosa. In particolare, mostra alcune applicazioni reali, con esempi come codice reale.

Le applicazioni reali sono ciò che rende interessante uno schema. Gli esempi non devono essere grandi, sofisticati o completamente realistici. Devono solo compilare. Altre persone vorranno copiare e incollare gli esempi di codice.

Questi esempi sono il "ciao mondo" dello schema. E fungono da una specie di unit test per lo schema.

Answer 3

La cosa più vicina a Javadoc per uno schema XML che ho visto è l'esecuzione dello strumento Javadoc sul sorgente generato dallo schema. Ciò richiede due cose: 1) Che il tuo schema abbia degli elementi di annotazione interni che lo documentano e che 2) il tuo generatore di sorgenti usa quelle annotazioni come elementi Javadoc.

Answer 4

L'utilissimo sviluppatore Oxygen XML supporta anche la generazione di documentazione, vedi http://www.oxygenxml.com/xml_schema_documentation.html (commerciale, ma è disponibile una versione di prova di 30 giorni completamente funzionale)

Lo proverò ora, ho bisogno di un modo semplice per generare un documento con tutti i tipi e disponibile xsd: descrizione della documentazione come semplice descrizione dell'interfaccia ...

Answer 5

** Divulgazione: lavoro per Innovasys, il produttore dello strumento di documentazione di seguito *

Puoi dare un'occhiata a Documento Innovasys! X . Oltre a generare automaticamente una pagina strutturata e collegata per ogni elemento, tipo semplice, tipo complesso, gruppo e gruppo di attributi, genererà anche diagrammi XSD collegati (comprese sequenze / scelte ecc.) E tabelle di strutture che includono le annotazioni dei tuoi XSD e dare un senso alle relazioni tra gli elementi nei tuoi schemi. L'output è basato su template in modo da poterlo adattare al tuo stile e struttura preferiti. Costruirà l'output in html pronto per il web o in file di aiuto compilati.

In modo univoco include anche un editor WYSIWYG che ti consente di creare contenuti aggiuntivi per integrare le cose generate automaticamente e le annotazioni dalla fonte XSD, in modo da poter fornire ulteriori informazioni contestuali per la tua peer review. C'è anche una funzione di estensione della comunità che consente alle persone che visualizzano l'output generato di registrare commenti e feedback e che possono essere visualizzati e attivati ??direttamente dall'interno di Document! X.