search

opengeospatial / sensorthings

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

Extension: Arbitrary Entity Linking #97

Closed hylkevds closed 5 months ago

hylkevds commented 4 years ago

I made a write up for an arbitrary entity linking extension at: https://github.com/INSIDE-information-systems/SensorThingsAPI/blob/master/EntityLinking/Linking.md

I think this may be a solution for most cases that need additional links between entities, like #45 and #65

Comments are welcome, it's not implemented yet.

mjacoby commented 4 years ago

I really appreciate that this topic is being addressed as I think that it an important feature when it comes to using STA in real-world scenarios! Your proposal seems consistent and well-designed. However, I would like to bring up one question for discussion: Does it make sense to put this into the properties property or should be consider putting it in the JSON describing the entity itself?

From the begining of STA I always wondered why adding custom properties to the JSON description of an entity is not allowed as it would provide lots of freedom and make the properties property obsolete. From client-side I do not see any problem with that because clients can simply ignore unkown properties on deserialization (which is a functionality available in almost every JSON library). The rest would stay as you described, i.e. the should be a possibility to formally describe the extended data model. This way we would also be closer to OData again.

From my perspective, there are two main arguments for using this approach over putting that information into the properties property.

  1. Readability - The JSON is easier to read because it is less nested
  2. Performance/Implementation - having such a huge "unstructured" JSON property in many objects will probably affect performance or at least make implementation harder. I'm not 100% sure on this but this is what my gut instinct tells me.

I would love to here some comments on this from the community, especially from users and server developers.

hylkevds commented 4 years ago

The main reason for putting those links in the properties is backwards compatibility.

  1. You can use this link model even on servers that don't have specific support for it. The data will be there, you just don't get generated navigation links or expand support.
  2. Ease of implementation on the server side. On the server side there is no strict need for additional tables or columns, since the properties are already there.
  3. Also on the client side there is less hassle. For instance, adding arbitrary fields to a Java class is not possible, so to somehow add generic support for these additional links outside of the properties field would be tricky. Or you would need to generate the client classes for each use-case.

Performance should not be a big issue. These links are not "huge" in any way, and for filtering it's possible to add indices on JSON properties optimised for each use-case.

In the future (v2.0 or so) it may be good to investigate if it's better to put these links in a special "references" field though.

hylkevds commented 4 years ago

I've made a prototype implementation, thanks to BRGM, so everyone can give it a try. Implemented are:

https://lubw-frost.docker01.ilt-dmz.iosb.fraunhofer.de/v1.1 This service has stations and rivers.

Some examples:

The extension is also active on the "free for all" instance https://ogctest.docker01.ilt-dmz.iosb.fraunhofer.de/v1.1/ if anyone wants to try it with their own data model.

liangsteve commented 4 years ago

The group will explore the possibility to make this an official OGC STA extension.

rob-metalinkage commented 4 years ago

This is akin to the "graph shapes" view of the world.

One possible way to think of this is to have predefined names for collections of properties - there is a W3C standard for asking for a data profile by name

https://www.w3.org/TR/dx-prof-conneg/

where X is a token understood by the server or a URI

The W3C spec also provides for a mechanism to list available profiles: simply "_profile=alt"

This is quite a powerful mechanism for linking all the different technical resources for a specification by having these available - check out work in progress here:

https://defs-dev.opengis.net/def/schema/hy_features/hyf?_profile=alt

this is how we can attach JSON-context etc to conformance classes

?_profile=jsoncontext
hylkevds commented 4 years ago

@rob-metalinkage, collections of properties is not what this extension is about, that would be the domain of the $select query parameter. This is about adding relations between entities beyond the relations that the data model already defines, and supporting those relations by generating navigation links like those that exist for the official relations, and by allowing them in the existing query parameters $expand and $filter.

hylkevds commented 5 months ago

Since data model extensions are much better supported in v1.1 and ever more so in v2.0, adding relations between Entities is much better done using a proper data model extension. Closing this.