XML Implementation Guide

With EDI it is common to give a trading partner an Implementation Guide that helps direct the trading partner in developing the mapping for a specific EDI transaction. The implementation guide helps describe general and specific requirements for that specific transaction set. The Implementation Guide was often created using a word processor but there were tools available to help make the process simpler.

In terms of XML, has anyone had experience in creating an Implementation Guide describing the requirements of the transaction set? Since XML is less formalized than EDI is, it’s more important that we communicate clearly the expectations of the partner and what each particullar tag is used for. How we name specific tags in an XML can play a big role in how clear the requirements are. And giving a partner just the Schema isn’t always enough.

Has anyone used any tool like XMLSPY or others to help create an Implementation Guide from an XML Schema. Any thoughts on this would be welcome.

Thanks in advance…

Some XML standards implemented this type like OAGIS,Rosettanet,CIDX,PIDX,ebXML etc…which have pre-defined specifications that are normally ready to use ofcourse this is based on the industry.
But i believe using XMLSPY or other tools most organizations taking with the help of BusinessAnalysts or Functional teams will prepare the proprietary XML specifications.

just my thoughts,


As RMG suggests, various industry standards have emerged that provide effective substitutes for given EDI transaction sets. These standards should generally provide adequate documentation regarding their usage. If however, you need to develop/use a custom XML representation of your transactions you certainly might want to have an implementation guide as you’ve described.

A tool such as XMLSpy can help in documenting a schema, but you’ll find that the automatically generated documentation can (naturally) only describe the structures and relationships defined in the schema. It can’t give you any information about the semantics (intended meaning/usage/transformation requirements) of the data. Someone who understands those semantics will inevitably have to author the verbiage necessary to describe them.

Now I’d suggest that one way of combining the authoring of semantic descriptions with auto-generation of the documentation would be to make liberal use of annotations in your schema definition. Essentially, place an annotation on every element you need to describe and include all the text you want to provide the information that would appear in the implementation guide. When you generate the documentation from something like XMLSpy all the annotated text will appear with it in-line.

This certainly won’t be as “clean” as a dedicated implementation guide, but you could always create a stylesheet or other filtering app of some sort to pull just the annotations from the schema document and format them more appropriately. HTH.

Thanks for your replies RMG and Michael. We do not have an industry standard to utilize so more often than not we utilize a custom XML specification. I spent many years in the MFG industry doing EDI integrations. I’m now in a financial industry using XML integrations. We do have some business ‘mapping’ guides but they are more for internal use and not specifically for the partner.

Thanks again for your replies.


Financial industry have also some standards like SWIFT,fpML (XML)etc…visit fpML.com