search

opengeospatial / sensorthings

The official web site of the OGC SensorThings API standard specification.
136 stars 29 forks source link

Inconsistencies on definition of 9.2.7 Usage 7: address to an associationLink #15

Closed ferjm closed 2 years ago

ferjm commented 7 years ago

http://docs.opengeospatial.org/is/15-078r6/15-078r6.html#41 mentions the following:

Response: A JSON object with a value property. The value of the value property is a JSON array containing one element for each associationLink. Each element is a JSON object with a name/value pairs. The name is url and the value is the selfLinks of the related entities.`

Which is not consistent with the example provided in the spec:

 {
  "value": [
      {
        "@iot.selfLinks":
  "http://example.org/v1.0/Observations(1)"
      },
      {
        "@iot.selfLinks":
  "http://example.org/v1.0/Observations(2)"
      }
    ]
  }

First of all, the name of the property in the example is not url as described in the definition but @iot.selfLinks, which also seems incorrect, as it should probably be @iot.selfLink in singular.

Finally, this is also not what the SensorUp reference implementation is returning for these kind of requests. For example, a request to http://scratchpad.sensorup.com/OGCSensorThings/v1.0/Things(29761)/Datastreams/$ref responses with: 

{
  "@iot.count":2,
  "value": [{
    "@iot.selfLink": "http://scratchpad.sensorup.com/OGCSensorThings/v1.0/Datastreams(29768)"
  }, {
    "@iot.selfLink":  "http://scratchpad.sensorup.com/OGCSensorThings/v1.0/Datastreams(29766)"
  }]
}

Which looks more consistent with what a request to an address to a collection of entities responses.

I would propose the specific changes to the spec document myself, but I can't find its source.

hylkevds commented 7 years ago

The description is indeed not very good. I interpreted it as /$ref being a shorthand for ?$select=@iot.selfLink

The only difference between the example and the SensorUp reference implementation is the added @iot.count. Adding that @iot.count does make sense in respect to the rest of the standard, and would match my interpretation as a shorthand for ?$select=@iot.selfLink. On the other hand, the SensorUp implementation deviates from the described standard in multiple ways, so that doesn't mean much ;)

For change proposals I've downloaded the source of the document using wget, and made a GitHub project with that: https://github.com/hylkevds/SensorThingsAPI Feel free to clone that further :)

liangsteve commented 7 years ago

Thanks for finding the mistake. It is a minor mistake in the standard document. "url" was used in a very early version of STA. Then the url notation was updated to selfLink, and then updated to @iot.selfLink. Somehow it wasn't updated in this section. Good eye.

Regarding SensorUp's implementation containing @iot.count, it is compliant to the standard. There is no issue here. :)

selimnairb commented 5 years ago

@taniakhalafbeigi @hylkevds Here is a PR for this issue: https://github.com/opengeospatial/sensorthings/pull/73

hylkevds commented 5 years ago

Thanks for the PR, looks good.

hylkevds commented 2 years ago

Fixed with the publication of Sensing v1.1.