3.10 Documentation of WSDL description

For transmitting important information in the context of X-Road, specific documentation elements can be added to WSDL description, which enable annotating dataservices (WSDL operations) with the version of dataservice, title, and notes intended for the user and developer.

If documentation elements are used correctly in WSDL description, it is possible to create a user interface of the MISP2 portal based on WSDL description (https://github.com/jointxroad/components/blob/master/component_descriptions.md#x-road-portal-misp2), which is convenient to use for testing the dataservice, and also for creating cheap web interface for end user, if necessary.

Documentation elements are described in the following Table 3.

Table 3 X-Road documentation elements

Documentation element

Description

/definitions/binding/operation/@name

Code of dataservice

/definitions/binding/operation/xrd:version

Version of dataservice

/definitions/portType/operation/documentation/xrd:title

Title of dataservice (for a user)

/definitions/portType/operation/documentation/xrd:notes

Note of dataservice (for a user)

/definitions/portType/operation/documentation/xrd:techNotes

Note of dataservice (for a developer)

 

Specific documentation elements of X-Road are intended mainly for the end user. They must enable automatic generation of web interfaces for dataservices. Documentation elements are highly necessary also for developers who interface information systems and also for business people reading the descriptions in RIHA.

Annotation of dataservices can take place on the following levels:

  • Level 0: WSDL does not include any tag intended for a human user and is intended only for systematic use;
  • Level 1: WSDL is annotated and dataservice supports some use e.g. via MISP2 portal;
  • Level 2: Separate XForms description is created to enable convenient use of dataservice (or dataservices) in an instance supporting XForms technology, referred in documentation of dataservice (or dataservices).

XForms standard is further discussed in module 7 (c 7.2).

 

Notes intended for a developer can be included in an XML note. Thus, inside a WSDL document, it is possible to provide an overview of the operation of dataservice or to explain better the structure of dataservice.

Names of elements must be simple and comprehensible, and the names of elements and dataservices must provide good overview of their meaning.

Last modified: Wednesday, 3 May 2017, 4:15 PM