Optional Properties

[hylkevds]

Problem description

There seem to be different opinions on the meaning of "Zero-to-one" or "Zero-to-many" as applied to Entity properties. Properties affected by this:

• Thing.properties
• Observation.resultQuality
• Observation.validTime
• Observation.parameters

The two interpretations are:

1. The client does not have to include it, but a server must accept it: An Observation is valid if it does not have a validTime, but the server must accept an Observation sent by a client that does have a validTime.
2. A server may reject an Observation that has a validTime.

The way I interpret the current version of the Spec is option 1, for the simple reason that the spec does not specify how a server that does not implement validTime is supposed to respond to an Observation with a validTime. A second reason is that there are three properties that are explicitly listed as OPTIONAL, namely:

• Datastream.observedArea
• Datastream.phenomenonTime
• Datastream.resultTime

And thus all other properties are not optional. Note that these three properties are server-generated, so there is no ambiguity regarding these three for a client posting a Datastream.

Advantages / Disadvantages

Advantages of making more properties optional: Easier to implement a Server (but not by much).

Disadvantages of making more properties optional: Harder to implement a client, since a client doesn't know what it can and can not send to the server.

Changes to the spec

If we choose not to make these properties optional I don't think there is a need to change the standard, though it would probably be good to add tests to the conformance suit to test if the server properly supports the properties. As far as I know all current server implementations implement these properties.

To make these four properties truly optional we would need to make some changes:

• Explain the meaning of "optional"
• Add "Optional" to these properties
• Exaclty specify how a server that does not support these properties must respond when a client sends a POST, PUT or PATCH request with one of these properties. This includes:
  • HTTP error code: 501 Not Implemented ?
  • The error message: Must be machine readable so a client can figure out what exact field is not implemented.
• Add tests to the conformance suit that tests if the server gives the correct error (or implements the optional properties)

Note that implementations not implementing Thing.proprties currently fail the conformance tests.

What are the general opinions?

[bertt]

Our interpretation is also number 1: server must support 'optional' properties, client has freedom to omit them in the request. So the testsuite should also check on those properties. It would be nice if the spec also describes what should be in the response in case of null values (return null or omit null values).

[hylkevds]

In a recent discussion on the tc-discuss list, someone pointed at 08-131r3: The Specification Model, Standard for Modular specifications:

Req 26 The only optional requirements acceptable in a specification conformant to this standard shall be expressible as a list of conformance classes to be passed. NOTE Standards and implementations are restricted by this, but not instances of schemas. For example, a XML schema standard can specify an optional element, which data instances may use or not., However schemaaware processors claiming conformance to the standard should be able to handle all elements defined in the schema, whether they are required by the schema or not.

In this case, I would say we are describing a schema, and the server is a "schemaaware processor", and thus "should be able to handle all elements defined in the schema".