Any time that you need to define a structure either for the input/output of your service operation or as part of another structure, you have one of the two options: define the structure inline as an integral part of the same input, output or standalone structure; or define the structure as a standalone reusable named structure outside the context of the current structure and then just reference it by name in the current structure.
The following tutorial shows you the steps for the first option, which provides the simplicity of defining the whole structure in-place, but has a limitation of not being able to reuse the same structure in other structures or operations.
- Add nested elements inside the output, input or struct element that defines your current structure as follows.
- To describe a single parameter add a param element. Give it a unique name within the structure by setting the name attribute.
- To specify the parameter type set the type attribute to the name of a logical type defined in the model. Note, that if the parameter name matches a field name in the current object (or in the object specified by the object attribute on the standalone structure), then you don't have to specify the parameter type. In this case the type of that field will be used, which reduces the maintenance in case if you need to change the field type.
- To specify whether or not the parameter is required set the required attribute to true or false accordingly. If not set explicitly, the required attribute will be inherited from the field with the matching name in the current object or the object specified by the object attribute for a standalone structure.
- To specify that the parameter is a collection of values rather than a single value, set the list attribute to true.
- In order to add a nested structure as opposed to a single parameter, add a struct element inside the element for your current structure. Give it a unique name within the structure by setting the name attribute.
- To specify a collection of structures rather than a single nested structure, set the list attribute to true.
- If you want to define the nested structure inline, then repeat these steps for that structure.
- You can also define the nested structure separately in the model and/or reference an existing standalone structure by setting the ref attribute to the name of that structure.
Here's an example of an operation output structure defined inline.
Code:
<operation name="search flights">
<output list="true">
<param name="flight" type="flight number" required="true"/>
<param name="origin" type="airport code"/>
<param name="destination" type="airport code"/>
<param name="departure" type="time"/>
<param name="schedule" type="day of week" list="true"/>
</output>
</operation>