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 second option, which allows reusing the same structure in other structures or operations, but has an overhead of defining it separately and giving it a unique name.
- Add a structs element to your module element if needed.
Inside of that element add a struct element and give it a unique name by setting the name attribute.
- If the structure is largely based on the fields of an existing object then set the object attribute to be the fully qualified name of that object.
- 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 object specified by the object attribute on the current 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 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.
- Follow the steps of another tutorial if you want to define the nested structure inline.
- 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.
- This step above also applies to referencing the current standalone structure in the definition of other structures.
Here's an example of a standalone structure named
location struct and an operation that uses it as part of the input structure.
Code:
<structs>
<struct name="location struct" object="state province">
<param name="city name" type="city name"/>
<param name="state province code"/>
</struct>
</structs>
...
<operation name="search flights">
<input>
<param name="airlines" type="" list="true"/>
<struct name="origin" ref="location struct"/>
<struct name="destination" ref="location struct"/>
</input>
<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>