Comments on: 10 practical recommendations for designing and building highly reusable XML Schemas http://www.summa-tech.com/blog/2009/11/07/ten-practical-recommendations-for-designing-and-building-highly-reusable-xml-schemas/ Summa Blog Wed, 08 Feb 2012 05:43:31 +0000 http://wordpress.org/?v=2.7 hourly 1 By: Jorge Balderas http://www.summa-tech.com/blog/2009/11/07/ten-practical-recommendations-for-designing-and-building-highly-reusable-xml-schemas/comment-page-1/#comment-1956 Jorge Balderas Thu, 03 Dec 2009 21:30:24 +0000 http://www.summa-tech.com/blog/?p=1405#comment-1956 That's a good one I missed Dave. The annotation/documentation element is particularly helpful for schema documenting. Several tools extract comments from this element and allow you to generate javaoc-like documentation... That’s a good one I missed Dave. The annotation/documentation element is particularly helpful for schema documenting. Several tools extract comments from this element and allow you to generate javaoc-like documentation…

]]> By: daveg http://www.summa-tech.com/blog/2009/11/07/ten-practical-recommendations-for-designing-and-building-highly-reusable-xml-schemas/comment-page-1/#comment-1921 daveg Tue, 01 Dec 2009 15:59:10 +0000 http://www.summa-tech.com/blog/?p=1405#comment-1921 Thanks, this is a good concise overview of points that I had previously considered "common sense" but never really spelled out for myself or others. I would suggest one more essential: documentation! Using blocks to describe the meaning of elements is very helpful and very important. For example, declaring an element named "weight" that contains an integer is insufficient in a schema, especially those that will be shared across business or business units. Much more helpful is to document "the total shipping weight of the package, in pounds". What are the important elements to capture in schema documentation? * Units of measure * When the element is relevant or not relevant * The semantic meaning of this element relative to others (e.g. "this date should always be prior to the transaction date") * How the information is to be interpreted * Expected state transitions This is another reason why enumerated types are so helpful, because you can document not only the possible values, but the precise meaning of those values and the expected transitions between them. Thanks, this is a good concise overview of points that I had previously considered “common sense” but never really spelled out for myself or others.

I would suggest one more essential: documentation!

Using blocks to describe the meaning of elements is very helpful and very important.

For example, declaring an element named “weight” that contains an integer is insufficient in a schema, especially those that will be shared across business or business units.

Much more helpful is to document “the total shipping weight of the package, in pounds”.

What are the important elements to capture in schema documentation?
* Units of measure
* When the element is relevant or not relevant
* The semantic meaning of this element relative to others (e.g. “this date should always be prior to the transaction date”)
* How the information is to be interpreted
* Expected state transitions

This is another reason why enumerated types are so helpful, because you can document not only the possible values, but the precise meaning of those values and the expected transitions between them.

]]>