Question

I have to write documentation for an existing WSDL file and would prefer to do so inside the document. The problem is, that I cannot find anything about whether wsdl:documentation allows the usage of xml:lang as an attribute or if any documentation generator would use it.

So far I have not found anything on the web and I simply cannot believe that I’m the only one who would like to do a dual language documentation. Any hints?

Answer 1

From the WSDL 1.1 specification:

WSDL uses the optional wsdl:document element as a container for human readable documentation. The content of the element is arbitrary text and elements (“mixed” in XSD). The documentation element is allowed inside any WSDL language element.

From the WSDL 2.0 specification (emphasis mine):

WSDL 2.0 uses the optional documentation element information item as a container for human readable or machine processable documentation. The content of the element information item is arbitrary character information items and element information items (“mixed” content in XML Schema [XML Schema: Structures]). The documentation element information item is allowed inside any WSDL 2.0 element information item.

Like other element information items in the “http://www.w3.org/ns/wsdl” namespace, the documentation element information item allows qualified attribute information items whose [namespace name] is not “http://www.w3.org/ns/wsdl“. The xml:lang attribute (see [XML 1.0]) MAY be used to indicate the language used in the contents of the documentation element information item.

It seems that this was somehow forgotten in V1 and fixed in V2. Basically, you are on your own.

But even if the specification would mandate the use of xml:lang for documentation, you can never know what your clients will use to process the WSDL you provide them and never know if they can properly extract the documentation out of it.

I hope you don’t mind me saying this, but I think you are approaching this the wrong way. Documentation for a web service doesn’t resume itself to the WSDL. Yes, providing a WSDL is mandatory for your clients to be able to easily generate the plumbing code needed to call you web service, but it only details the technicalities of the calls. It says nothing about how your web service should be used.

YMMV but beyond the WSDL you might want to:

• start with an overview of what your web service does;
• what each of its operations is used for and when;
• what’s the meaning of the parameters, what constraints are there for each (e.g. some business constraint that can’t be reinforced with XSD restrictions);
• some SOAP message samples containing typical data needed/returned by the web service;
• describe what errors to expect, what codes/description will they have and how to troubleshoot them;
• emphasize business constraints (I’m thinking red bold text?!);
• what if you want to insert a picture to describe the overall architecture?
• etc etc

Adding all those details in the WSDL would be restrictive. So how about making your documentation composed of the WSDL and a nicely formatted (language specific) PDF file with details like the ones I mentioned above?