Concurrent d'XML Schema (W3C 2001), RelaxNG (OASIS - ISO 2003) permet de formaliser des langages XML.

Lors de la mise en place d'un Web Service, la validation auprès du schéma ne suffit pas, on doit aussi effectuer les tests des messages et leur documentation. Ces deux tâches déplaisent aux développeurs et la documentation, moins critique, est souvent négligée.

Relax NG peut nous aider à automatiser tout ça en minimisant nos efforts. Nous allons voir pourquoi, en prenant comme exemple une requête vers un service fictif permettant d'obtenir des propositions de cocktails à partir de recettes incomplètes :

VodkaCointreau1.5

En réponse à cette requête, le service peut nous proposer le cosmopolitan, par exemple.

Créer le schéma de validation du message

Le Web Service est prêt, le point d'accès est ouvert, on fait donc les tests. Tous les tests ne faisant pas appel à une trop grande intelligence métier peuvent être automatisés en écrivant un schéma. Voici celui de nos requêtes, en utilisant la syntaxe compacte de Relax NG :

start = element cocktail {
	element dose {
		element ingredient { text }?,
		element quantity { 
			attribute unit { "cl" | "gill" },
			xsd:decimal
			}?
		}+
	}

Ajouter des règles métiers

Schematron permet d'ajouter de l'intelligence à notre schéma en insérant des règles ne traitant pas de la syntaxe, mais de la logique du métier. Dans notre exemple, nous pouvons préciser que deux doses avec le même ingrédient sont équivalentes à une dose unique cumulée, ou que la somme des doses ne peut pas dépasser la taille du verre, ou émettre un avertissement si plus de 5 ingrédients sont listés.

Ajouter les annotations

Grâce au schéma, nous avons déjà les éléments les plus importants (structure, cardinalité, types, règles...) mais ça ne suffit pas. Il faut la documentation textuelle à proprement parler. Relax NG nous laisse choisir le vocabulaire d'annotation et nous allons choisir le célèbre Dublin Core :

namespace dc = "http://purl.org/dc/elements/1.1/"
dc:title [ "Requête du service de proposition de cocktail" ]
dc:author [ "Pierre D" ]
start = element cocktail {
	element dose {
		[ dc:description [ "Un ingrédient est un liquide. Uilisez son nom anglais." ] ]
		element ingredient { text }?,
		element quantity { 
			attribute unit { "cl" | "gill" },
			xsd:decimal
			}?
		}+
	}

Génération des rendus

Nous avons réuni toute l'information nécessaire à une documentation complète, mais elle est exprimée d'une façon que seuls les profils les plus techniques peuvent lire. Comme Relax NG a une syntaxe XML et qu'on peut passer de l'une à l'autre automatiquement et sans pertes (avec trang, par exemple), il est possible d'appliquer à notre schéma enrichi des transformations XSL, afin d'obtenir des textes structurés en HTML ou Docbook ou des diagrammes UML en SVG. De nombreux fichiers XSL sont déjà disponibles sur le Web et il est facile de les adapter.

Génération des exemples

A des fins de documentation, mais aussi de tests, il peut être utile de générer automatiquement des exemples de messages. C'est possible grâce aux instances generators, comme ceux fournis par Sun ou par Oxygen XML Editor.

Conclusion

Il existe une syntaxe simple, standard et dotée d'un écosystème d'outils riches permettant de générer, avec un minimum d'efforts, une documentation complète avec structure, cardinalités, types, règles, annotations et exemples : Relax NG Compact.

Utilisez-la.