search

INSIDE-information-systems / OAPIF

OGC API - Features (ex: WFS3) deployment on French Groundwater Information Network features
3 stars 4 forks source link

Provide a document summarizing the patterns applied from GML -> GeoJSON/JSON-LD #6

Open sgrellet opened 5 years ago

KathiSchleidt commented 5 years ago

Sylvain's MindMap Notes:

- simplify the polka steps one level

- Ignore simple types

- every time max Cardinality is > 1

KathiSchleidt commented 5 years ago

GeoJSON Feature Base: gml:identifier -> json id (but including path): BSS000AAAA -> https://data.geoscience.fr/id/well/BSS000AAAA JSON "type": "Feature" JSON "geometry": Geometry nested in Feature, in this case eposb:bholeHeadworks//gwml-wellconstruction:collarLocation

KathiSchleidt commented 5 years ago

XLink Handling: The 2 XML attributes are transformed to a JSON Object as follows

-> "sampledFeature": { "@href": "https://sweet.jpl.nasa.gov/2.3/realmEarthReference.owl#EarthLithosphere", "@title": "Lithosphere" }

KathiSchleidt commented 5 years ago

dataType and featureType What worries me a bit here is the loss of the namespace. While this will usually be harmless, it can also lead to serious confusion in cases where a type of the same name is available from different namespaces (as unfortunately often the case within the entirety of OGC Data Models!) I'm wondering if we shouldn't do an approach similar to the xlink handling above, instead of just providing the type as a string, providing an object with the type (still string) together with a namespace

KathiSchleidt commented 5 years ago

XML Attributes vs. Elements Element names are directly adopted, attribute names are utilized together with an @ prefix as done in XPath I'm a bit worried here as to possible overlaps with other meanings of the @ prefix in JSON/IoT. While I believe we're on the safe side, this is something to keep an eye on

sgrellet commented 5 years ago

"value": when a XML tag also has attributes example :

<eposb:length uom="http://qudt.org/vocab/unit/M">82.0</eposb:length>

becomes

        "length": {
          "value": 82,
          "@uom": "http://qudt.org/vocab/unit/M"
        },

but when no attributes -> direct JSON property

<gml:timePosition>2007-05-20T22:00:00Z</gml:timePosition>

becomes

"timePosition": "2007-05-20T22:00:00Z"
KathiSchleidt commented 5 years ago

time is a simple type, makes sense however, the moment we have multiple values within one type, it becomes a datatype, and to my view should be typed you've started to make exceptions for the common stuff like xlinks and measures, but then we should also leave it out in other places! please look at custodian, tell me at what degree of nesting we should have stopped there, then maybe I can see the difference!

aaime commented 5 years ago

The current translation rules in the code are simple and stay away from any knowledge of specific GML datatypes, they just use a few general patterns based on the information available at the encoding level (which is some typing info, but not the full breath of info available in the schema):

  1. If attributes are found, encoded them as part of the properties prefixing them with "@"
  2. If the complex type being encoded is a "complex type with simple content", then encode it as a straight value, unless it has attributes, in which case encode it as an object with attributes and the value in a property called value
  3. If the type of the attribute being encoded ends with <X>PropertyType or <X>_PropertyType, contains a single element whose type is X, then skip the "polka steps" and encode directly the content
  4. If the type is a complex, encode its XML type (as @typeName or @dataType), removing the "Type" suffix at the end (unless it's a complex type with simple content, rule 2)
  5. If the attribute is a instance of Feature (which app-schema should produce when the underlying data type extends GML AbstractFeature) then encode it as a fully blown GeoJSON feature, including its identifier, otherwise use a plain JSON object
aaime commented 5 years ago

For reference, here is the current output (should be the final version, there are no more changes planned in our activities): https://gist.githubusercontent.com/aaime/d2c1cf46895aad2706ea871bbfa1c96f/raw/238dd828066cf9022493b3e4ca52a9f8a57b5c4d/borehole2.json

sgrellet commented 5 years ago

add recent adjutement regarding @datatype see https://github.com/INSIDE-information-systems/WFS3/issues/15#issuecomment-490028212

KathiSchleidt commented 5 years ago

To my understanding, the adjustment mentioned in #15 means that the description above is now correct

KathiSchleidt commented 5 years ago

@aaime : is the following correct:

  1. When a feature type is chained from the main feature, these will be provided in an array containing individual feature objects, regardless of the number of instances being provided.
aaime commented 5 years ago

@KathiSchleidt about "6" yes that's correct. Eventually we could encode them as a straight object in case the XML schema states the chained feature cannot appear more than once in the output (max multiplicity = 1) and throw an exception if the actual result is more than one (I guess it could be happening depending on what the database query return)

sgrellet commented 5 years ago

Link to work done under INSPIRE : https://github.com/INSPIRE-MIF/2017.2/blob/master/GeoJSON/geojson-encoding-rule.md. We should compare with their rules

KathiSchleidt commented 5 years ago

Note: the example GeoJSON provided is not up to date, not aligned with final report (missing @ before dataType and featureType) - should be updated

nmco commented 5 years ago

For reference: OGC Testbed-14 Next Generation APIs: Complex Feature Handling Engineering Report https://docs.opengeospatial.org/per/18-021.html