The mechanism for working with property values in WSRP is ambiguously defined in the WSRP 2.0 specification and needs clarification.
Relevant statements from the specification
Section 4.1.12 of the specification contains the following descriptions:
name: Name of the property being described. If this property's value is not carried within the stringValue alternative of the Property structure, this name also becomes the name of the XML element carrying the property's value with the type field defining the type of this element.
type: Type of the property, using a namespace qualified name. We would encourage these to either be from the set of schema-defined types or be explicitly typed in the schema element of an enclosing ModelDescription. This allows the Consumers to prepare the appropriate serializer/deserializer. The namespace for the schema-defined types used by this specification is http://www.w3c.org/2001/XMLSchema. Producers can assume that all Consumers support the basic types defined by http://www.w3c.org/TR/xmlschema-2/.
schemaLocation: This optional field carries a URI which resolves into a schema containing the type for the described Property. If a URI can not be provided for resolving the type definition, the field of type ModelTypes in the enclosing structure will need to contain the definition for the type.
Section 4.1.17 of the specification contains the following descriptions:
name: Name of the property.
type: A reference to a schema-defined type for the property's payload. If a PropertyDescription was supplied with a matching name, it is an error for this type to not match the type supplied in that PropertyDescription.
value: The property's value. The type information needed to properly serialize/deserialize this value is carried in the relevant PropertyDescription. Note that the WSDL from [Section 14] defines two means by which this field may be sent, either as a generic array of elements or as a single element with a type of string. This second choice was added as many properties are likely to be of this type and it allows the web stack to automatically do the (de)serializing to the wire format.
From the wsrp-2.0-types.xsd schema
<complexType name="PropertyDescription"> <sequence> <element name="description" type="types:LocalizedString" minOccurs="0"/> <element name="label" type="types:LocalizedString" minOccurs="0"/> <element name="hint" type="types:LocalizedString" minOccurs="0"/> <element name="usage" type="xsd:string" minOccurs="0" maxOccurs="unbounded"/> <element name="aliases" type="xsd:QName" minOccurs="0" maxOccurs="unbounded"/> <element name="extensions" type="types:Extension" minOccurs="0" maxOccurs="unbounded"/> </sequence> <attribute name="name" type="xsd:QName" use="required"/> <attribute name="type" type="xsd:QName" use="required"/> <attribute name="schemaLocation" type="xsd:anyURI" use="optional"/> </complexType> <element name="PropertyDescription" type="types:PropertyDescription"/> <complexType name="ModelTypes"> <sequence> <any namespace="##other" processContents="lax"/> </sequence> </complexType> <complexType name="ModelDescription"> <sequence> <element name="propertyDescriptions" type="types:PropertyDescription" minOccurs="0" maxOccurs="unbounded"/> <element name="modelTypes" type="types:ModelTypes" minOccurs="0"/> <element name="extensions" type="types:Extension" minOccurs="0" maxOccurs="unbounded"/> </sequence> </complexType> <element name="ModelDescription" type="types:ModelDescription"/> <complexType name="Property"> <sequence> <element name="stringValue" type="xsd:string" minOccurs="0"/> <any namespace="##other" minOccurs="0" maxOccurs="unbounded" processContents="lax"/> </sequence> <attribute name="name" type="xsd:QName" use="required"/> <attribute name="type" type="xsd:QName" use="optional"/> <!--<attribute ref="xsi:type" use="optional"/>--> <attribute ref="xml:lang" use="optional"/> </complexType>
Properties are defined by the producer and used by the consumer. Registration properties are set by the consumer during the registration process. Examples of registration properties include billing code, license keys, password or any other data required by the producer for the consumer to establish a relationship with the producer. Portlet properties are used as a data interface for use by the consumer to modify a portlet's persistent state/configuration. Examples include font size, number of rows to display in a list, sort order or any other data that can be used to configure or personalize the portlet.
The meta data describing properties should be sufficient to allow the consumer to at least pass the correct data format expected by the producer for setting these properties. Some consumers may render a user interface that allows the end user to enter property values while others may simply rely on the direct use of XML for setting the property values; still other may rely on a combination of both types of interfaces for setting property values. Regardless of which method is used, there should be sufficient information describing the property such the correct XML can be passed to the producer for setting property values. It would be expected that the producer would validate the XML property values according to format and application logic but it would not make much sense for the consumer to continually attempt to set property values that are not remotely close to the expected format. One would not expect the consumer to pass an array where only a single value is expected or vise versa nor pass an arbitrary string where a date format is expected and finally pass an XML element name that is not expected just to have the producer throw an exception.
There are two use cases with respect to the issues discussed in this document:
- Setting a string property value
- A property with a type of xsd:string is defined
- Setting array versus a single value property values
- A property requires either an array of values or a single value
- The first issue has to do with passing string property values. The WSRP specification specifies a known element - stringValue of type xsd:string - that is part of the Property type for passing a string. It's a convenience mechanisms for automatically serializing this value without having to create custom serialization code. The Property type also permits the passing of any other arbitrary XML value/payload. What if a producer wanted to specify a custom XML element of type xsd:string? For example:
How can the consumer determine from the property description that this is the intended XML format for setting this property value? It is not clear how to determine from the property description whether the string value should come through "stringValue" or the arbitrary XML value when the type is xsd:string.
The second issue has to do with the "<Any>" XML payload being an array and not a single element. For events, the arbitrary "<Any>" element at most occur once and if the desire is to specify an array, then a custom XSD array type would be used to specify the event type. How does the producer specify that a property value should only occur once or more than once when the WSRP XSD already indicates that the "<Any>" element can occur more than once?
- Keep the existing specification wording with further clarifications
- To solve issue 1, require clarification that if no schema is specified in the property description (no schema or location specified) when the property type is xsd:string, then the value will be in "stringValue", otherwise the XML root element will have the same name and namespace as the property name.
- To solve issue 2, the resolution to issue #1 applies and if any other type, a schema must be found that contains an element definition with the same name as the property (and also same type) that specifies whether it occurs more than once.