[DocumentationRequest] Machine Readable Version of Standard using OData CSDL Schema

[riedel]

Many tools /particularly all the Microsoft .NET LINQ Support) won't work on SensorThings Services without the related CSDL Schema available on $metadata.

As this is a static file and SensorThings is OData compliant it should be possible to provide it as an annex to the standard.

[riedel]

As a side note: from this one could probably also generate an OpenAPI interface using this official stylesheet: https://tools.oasis-open.org/version-control/browse/wsvn/odata/trunk/spec/examples/V4-CSDL-to-OpenAPI.xsl which would accelerate adoption

[KathiSchleidt]

Hi Till,
as bridging the gap between the OData based STA and the soon to be OpenAPI based WFS3 is one of the currently burning issues, utilizing CSDL sounds especially interesting (what with "free OpenAPI conversion"!). You state that the CSDL (sorry, not familiar with this, too many different technologies buzzing around!) just requires a simple static file - as you seem to be familiar with CSDL, could you provide support in the creation of this file?

[riedel]

It seems there was an actual effort on this reading the standard:

"Things API does not follow the OData Common Schema Definition Language and as a result does not follow its metadata service entity model. Thus, SensorThings API should not be seen as an OData compliant API. SensorThings API’s future work will explore possible harmonization between SensorThings API and OData."

I am not familiar enough to understand what are the current show stoppers of making SensorThings OData compliant.

Maybe someone of the editors could comment on this and the possible needed changes in the standard.

[liangsteve]

The reason was at the time STA about to be published, CSDL was introduced in a later version of OData. As a result it wasn't included in STA and listed as a future work.

[hylkevds]

I just had a quick look through the CSDL Schema definition, looking for those points that might cause issues.

• Arbitrary property objects are possible
• Observation/result of type ANY is possible ("type":["number","string","array","object","boolean","null"])
• Geo types seem to be covered (docs.oasis-open.org/odata/odata-json-csdl/v4.0/csd01/schema/edm.json#/definitions/Edm.Geography)

The only possible problem that I see is:

• no time interval, but that could be solved by specifying a String with a validation regular expression

[volcan01010]

I'd like to add a +1 for this.

We have sensor data served via FROST API. I tried to use the python-odata library to query it, but was unable to instantiate a Client class because it relies on the OData metadata file:

>>> client = pyodata.Client(SERVICE_URL, requests.Session())
HttpError: Metadata request failed, status code: 404, body:
b'{"code":404,"type":"error","message":"Not a valid id: Path is not valid."}'

It was looking for the metadata file at: FROST-Server/v1.1/$metadata

[hylkevds]

If you have experience with OData, could you create a $metadata document for the SensorThings API?
It should be a (mostly) static document, shouldn't it?

[volcan01010]

Unfortunately, I don't have experience with OData aside from hand-written FROST Server requests. Today was my first attempt at connecting via a dedicated library.

[hylkevds]

As an experiment I've implemented OData 4.0 and 4.01 for a STA endpoint. Due to differences in the encoding, I've given these versions different URLs, to make it clear what is being used:

https://ogc-demo.k8s.ilt-dmz.iosb.fraunhofer.de/ODATA_4.0/
https://ogc-demo.k8s.ilt-dmz.iosb.fraunhofer.de/ODATA_4.01/

In theory, one could use the same URL for STA and different OData versions, since OData defines a header for clients to request a maximum OData version, but for these experiments I prefer making things explicit.

If you're still interested, can you try out these endpoints?
The 4.0 version seems to work fine in Excel 2019+ (For windows, Mac version have no OData support)

[riedel]

Did you have to modify the actual API or is this just implementing the "/$metadata" URL?

[hylkevds]

It does modify the API slightly, since there are small differences in the JSON keys for generated properties, as documented in #136.

[volcan01010]

Thanks for doing this, I am interested to try it. I had a quick attempt to connect, but it turns out that the "Enterprise-ready Python OData client" created by SAP only supports OData V2 and didn't like the JSON output.

I hadn't spotted that this library was so out-of-date before. It seems to be the most established Python OData framework on GitHub, too. I'll have a look at other clients later.

[riedel]

Yes, @hylkevds, first of all many thx!! @volcan01010 : have you tried this PR SAP/python-pyodata#77 ?

[riedel]

Actually I tried using both excel 2016 and linqpad 6/7 and I strangely get SSL validation errors on both. However, this error seems not uncommon: meancrazy/LINQPadOData4#26. If I accept an invalid certificate, I get Data at root level is invalid. Line 1, position 1 in Linqpad. I think it expected XML rather than the returned json. If I modify the request header for $metadata to application/xml I get the error "Error: Object reference not set to an instance of an object"

[hylkevds]

I'm pretty sure Excel 2016 only supports OData 3.0, not 4.0. OData 3.0 only has XML.
Certificate exceptions are always tricky without specific error, could be many things.

[riedel]

The error, however, is from meancrazy/LINQPadOData4 which uses Microsoft's OData v4 Client Code Generator.

[hylkevds]

What headers does it send in its request to the landing page?
And did you point it at the 4.0 or the 4.01 endpoint?

[riedel]

I used 4.0. It pretty much sends no headers at all (except for the path). So I used mitm proxy to ask for XML, which seems to be the expected default also for the 4.0 client. There seems to be an easy way to validate metadata in .net btw (haven't tried): https://github.com/cmshawns/ODataValidator/blob/master/ODataValidator/ODataValidator.cs