Le cinque ragioni principali per documentare i propri schemi

Lo sviluppo di schemi è spesso un processo iterativo, e gli sviluppatori di solito non partono da zero: gli schemi XML, e sempre più spesso gli schemi JSON, vengono creati assemblando elementi da documenti esistenti o ereditandoli da altri team. La capacità di comprendere come i componenti di uno schema si relazionano tra loro e di analizzare le note sulle scelte di sviluppo è estremamente utile, ma spesso impossibile a causa della mancanza di una documentazione efficace.

Esaminiamo alcune delle ragioni per cui la documentazione dovrebbe essere una parte integrante dello sviluppo dei vostri schemi XSD, JSON o di altri formati.

Vantaggi della documentazione dello schema XSD

Ecco le principali ragioni per cui non dovreste trascurare la fase di documentazione per il vostro prossimo schema.

1. Permette una comunicazione semplice e diretta tra i membri del team di sviluppo.

Lo sviluppo di uno schema è spesso un processo collaborativo, e una documentazione chiara e concisa aiuta a evitare confusione e ad aumentare la produttività, poiché diversi sviluppatori lavorano su aspetti diversi di uno schema o di una collezione di schemi. La revisione tra pari è un altro processo facilitato da una documentazione chiara, che consente a diversi esperti di valutare il modello di dati.

2. Permette una rapida integrazione di progetti preesistenti.

Questo concetto è strettamente legato al precedente. Il codice proveniente da un'azienda acquisita o da un reparto trasferito trae sempre vantaggio dalla documentazione. Anche se il progetto è nato all'interno della vostra organizzazione, lo sviluppatore originale potrebbe non essere più disponibile, oppure lo sviluppo potrebbe essere stato suddiviso in diverse fasi, e quindi nessuna singola persona conosce l'intero progetto.

Naturalmente, pochi progetti sono costituiti esclusivamente da schemi. Per un'analisi completa del codice esistente, è utile generare diagrammi UML per documentare e visualizzare facilmente il progetto.

3. Centralizza le informazioni relative agli schemi importati o inclusi.

Invece di dover esaminare numerosi documenti per stabilire le relazioni tra di essi, la documentazione dello schema può includere informazioni su tutti i documenti correlati in un'unica posizione centralizzata.

4. Permette a soggetti non tecnici di comprendere e analizzare le definizioni degli schemi

Poiché la documentazione dello schema è comprensibile agli esseri umani, essa apre la strada alla collaborazione con un'ampia gamma di esperti in diversi settori, che possono comprendere e fornire contributi durante lo sviluppo e l'evoluzione dello schema.

5. Gli strumenti automatizzati semplificano il processo.

In realtà, non c'è alcuna scusa per non documentare i propri schemi, soprattutto quando i software rendono il processo semplice. Vediamo come è possibile farlo utilizzando uno di questi strumenti: XMLSpy.

XMLSpy offre una documentazione degli schemi completamente personalizzabile, ma al tempo stesso completa, per gli schemi XSD, gli schemi JSON e le tassonomie XBRL. Vediamo come funziona.

Genera la documentazione dello schema XML

L'editor XML XMLSpy offre la generazione automatica di documentazione per gli schemi XML, gli schemi JSON, le tassonomie XBRL e persino le definizioni WSDL, e il processo è simile per ciascuno di essi. Con il documento dello schema aperto, selezionare "Genera documentazione" dal menu "Progettazione schema".

È possibile utilizzare il modello di documentazione integrato, oppure, se è installato Altova StyleVision, è possibile creare un proprio modello, personalizzandolo in base alle proprie esigenze. Successivamente, è possibile scegliere se generare la documentazione in formato HTML, Word, RTF o PDF. (Nota: la generazione di documenti in formato PDF richiede che StyleVision sia installato sullo stesso computer.)

Altre opzioni consentono di definire come vengono gestite le immagini, e infine, quali componenti e dettagli specifici vengono documentati. Esaminiamo la documentazione generata per un file XSD, e poi vi mostrerò le varie opzioni per documentare gli schemi JSON e XBRL.

Ecco un estratto della documentazione HTML relativa allo schema XSD per i rapporti di spesa, incluso nel progetto di esempi di XMLSpy.

I componenti dello schema vengono visualizzati graficamente, insieme al codice sorgente corrispondente, e i collegamenti ipertestuali consentono di accedere facilmente a dettagli relativi a elementi, attributi e tipi correlati.

Le proprietà e le caratteristiche sono presentate in modo chiaro, per consentire un'analisi immediata.

Quando componenti provenienti da altri schemi sono stati inclusi, anche tali schemi vengono documentati.

Genera la documentazione dello schema JSON

L'adozione sempre più diffusa di JSON Schema per applicare la validazione dei dati ai flussi JSON sottolinea, inoltre, l'importanza della documentazione per questo tipo di schema.

Le opzioni per la generazione della documentazione per JSON Schema sono simili a quelle per XSD, ma, ovviamente, specifiche per JSON, e includono opzioni per fornire dettagli sulle proprietà, sugli array, sui modelli e così via.

Documentazione della tassonomia XBRL

Ora passiamo alle tassonomie XBRL, che sono tra gli schemi più complessi disponibili. La documentazione in questo caso è utile non solo per gli sviluppatori delle tassonomie, ma anche per gli stakeholder XBRL che non sono esperti tecnici, come i commercialisti e altri professionisti che operano nel settore finanziario.

Disponibile nel menu XBRL di Editor della tassonomia XBRL, Il comando "Genera documentazione" offre le opzioni consuete, ma in questo caso specifiche per i componenti XBRL, come le etichette e le basi di collegamento.

Che siate impegnati con schemi XSD, JSON o XBRL, i vantaggi della generazione di documentazione per visualizzare, comprendere e comunicare la struttura e le relazioni degli schemi sono numerosi, e il fatto che possiate generare automaticamente la documentazione in XMLSpy in pochi secondi elimina qualsiasi ostacolo al completamento del lavoro.

Se non siete ancora clienti, potete provare XMLSpy gratuitamente per 30 giorni.