Compatibility between OData and STA

[hylkevds]

At the last TC meeting I gave a little demo of using STA/OData in Excel.

Here are the differences I found so far:

	STA	OData 4.0	OData 4.01
Self Links	@iot.selfLink	@odata.id	@id
NavLinks	@iot.navigationLink	@odata.navigationLink	@navigationLink
ID property	@iot.id	id (@ and . confuse clients)	id (@ and . confuse clients)
Context		@odata.context	@context
Flexible Properties	property type ANY	not supported, cast to Edm.String	Edm.Untyped
Time Interval/Value	phenomenonTime, validTime	not supported, use phenomenonTime.start and phenomenonTime.end	not supported, use phenomenonTime.start and phenomenonTime.end
Non existing entities	404 Not Found	204 No Content	204 No Content

Things that STA has that can not easily be mapped to OData:

• Type ANY doesn't exist in OData 4.0. Version 4.01 has Edm.Untyped.
• No TimeInterval or TimeValue, only Edm.DateTimeOffset. This is an issue for Observation/phenomenonTime, Observation/validTime, Datastream/phenomenonTime and Datastream/resultTime.
  One solution would be to just use Edm.String, but this doesn't help clients. A better solution is to split the interval into intervalProperty.start and intervalProperty.end in the OData interface.

Our test endpoint, for people that would like to try it out:

• STA: https://ogc-demo.k8s.ilt-dmz.iosb.fraunhofer.de/v1.1/
• OData 4.0: https://ogc-demo.k8s.ilt-dmz.iosb.fraunhofer.de/ODATA_4.0/
• OData 4.01: https://ogc-demo.k8s.ilt-dmz.iosb.fraunhofer.de/ODATA_4.01/

It's the same server instance, so the database in these three endpoints is the same.

Related to #72
Also in the FROST wiki.

[hylkevds]

Some more progress:

• The ANY result type can be forced to Edm.String, since everything can be displayed as a String. This makes Excel content.
• Times that are a TimeInterval can be mapped to a custom type with start and end (both mandatory):

  "TimeInterval": {
      "$Kind": "ComplexType",
      "@Core.Description": "An ISO time interval.",
      "start": {
          "$Type": "Edm.DateTimeOffset"
      },
      "end": {
          "$Type": "Edm.DateTimeOffset"
      }
  }
  

• Times that are a TimeObject (Interval or Instant) can be mapped to a custom type with start and optional end:

  "TimeValue": {
      "$Kind": "ComplexType",
      "@Core.Description": "An ISO time instant or time interval.",
      "start": {
          "$Type": "Edm.DateTimeOffset"
      },
      "end": {
          "$Type": "Edm.DateTimeOffset",
          "$Nullable": true
      }
  },
  

[charlycou]

@hylkevds, some other differences that I have noticed:

• Self links: equivalent to read URLs, @readLink. @id is not necessarily an URL.
• $select query param: STA spec should mention the possibility to use wildcard character '*'. From OData spec

The value of the $select query option is a comma-separated list of properties, qualified action names, ..., the star operator (*),...

• Addressing references : http://example.org/v1.1/Datastreams(1)/Observations/$ref
  STA response:

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

OData response:

{
  "@context": "http://host/service/$metadata#Collection($ref)",
  "value": [
    { "@id": "Observations(1)" },
    { "@id": "Observations(2)" }
  ]
}

• $expand navigation path: STA $expand query option example 2 is not compatible with OData.

http://example.org/v1.1/Things?$expand=Datastreams/ObservedProperty

I don't find the OData spec very clear on expand path. But from ABNF expand path should contain only one navigation property that should be the last segment of the path. All segments before the navigation property segment must be type cast segments or complex type property segments in Odata.
Hence, given the STA model that does not contain navigation property inside complex type, $expand query using expand path should not be possible in STA. Instead, STA $expand query option example 2 could be replaced by http://example.org/v1.1/Things?$expand=Datastreams($select=ObservedProperty)

• Built-in Filter Operations substringof: seems to be removed in OData 4.01. Replaced by contains.