WSDL enumeration restriction with key/value pairs

Question

I'm working on a SOAP webservice which features many inputfields using enumeration restrictions.

These enumerations are much like an HTML select/option setup; I expect a certain value to be returned but the label of that value should be exposed using the WSDL as well.

An example: the client wishes to add an insurance policy regarding his/her house and thus needs to specify the type of building involved.

<xsd:restriction base="xsd:string">
  <xsd:enumeration value="00001" />
  <xsd:enumeration value="00002" />
  <xsd:enumeration value="00003" />
</xsd:restriction>

However, the client does not yet understand what these values 1, 2 and 3 are. So, something like this:

<xsd:restriction base="xsd:string">
  <xsd:enumeration value="00001" label="Brick and mortar" />
  <xsd:enumeration value="00002" label="Straw" />
  <xsd:enumeration value="00003" label="Aircastle" />
</xsd:restriction>

would be great for the client to be used to display these labels to the consumer.

Is there any standard WSDL annotation/syntax for this construction?

Answer 1

Is there any standard WSDL annotation/syntax for this construction?

I'm afraid not. The XML Schema enumeration is used to constrain a value to be within a specified set of possible values. When your client sends you the request, the element with the restriction type will only be allowed to have (in your case) a value of 00001, 00002 or 00003 or it won't be valid.

The restriction only specifies the values, you can't add labels. You could at best add an <annotation> but that would be just documentation. In the client UI, it would be the responsibility of each client to say that 00001 is actually "Brick and mortar" and that 00002 is "Straw" etc.

If you don't want to do that, and instead want to also return labels, then you need a slightly more complex object, maybe something like this:

<option>
  <key>00001</key>
  <label>Brick and mortar</label>
</option>

You provide a label and you restrict the key with a schema like:

<xsd:simpleType name="ValuesType">
  <xsd:restriction base="xsd:string">
    <xsd:enumeration value="00001" />
    <xsd:enumeration value="00002" />
    <xsd:enumeration value="00003" />
  </xsd:restriction>
</xsd:simpleType>

<xsd:complexType name="OptionType">
    <xsd:sequence>
      <xsd:element name="key" type="ValuesType" />
      <xsd:element name="label" type="xsd:string" />
    </xsd:sequence>
</xsd:complexType>

You can return a list of options to the clients and they can present it in the interface with key as value and label as the text of options in <select> inputs, while on the request you will get back the selected value (i.e. the selected key).