Update API Annex doc references to GeoJSON inclusion, given IIIF NavPlace Extension?

[hadro]

With the potential approval of the NavPlace extension, does the section in the Annex doc on Linking to External Services with a section talking about geojson-ld need to be revised or updated?

[azaroth42]

Yes :+1: I would say deleted, and replaced with a reference to the navPlace extension, when it is published.

[kirschbombe]

Now that navPlace is published, the Annex doc should be updated. Should this go to @thehabes or @mikeapp? I can also take a stab at it.

[thehabes]

I don't mind doing it! I will look at it tomorrow or the 13th. I can't make the call this Friday 1/14, I will be out 1/14-1/18 but I can have something together for you to look at.

Just to confirm, I am 99% sure we are talking about main/source/annex/services/index.md, Section 3 (Services) and more specifically Section 3.2 (GeoJSON).

I have a IIIF/API repo fork, I will put a PR together. I'll post back here when it's up and I will let @kirschbombe and the Cookbook know.

I agree with @azaroth42. Do we change the icon to ![not allowed] under presentation API, and just have section 3.2 link out to navPlace as the solution for using GeoJSON? Or are we thinking about a complete removal and actually deleting it from the Section 3 table and deleting 3.2, expecting that people will be routed to navPlace when searching for "GeoJSON with IIIF".

[kirschbombe]

All good questions @thehabes! Is GeoJSON still the service? It's just used in the API via navPlace? If that's the case, I wonder if we should keep "GeoJSON" in the table and replace 3.2 description with info about using navPlace to use the GeoJSON service.

[thehabes]

In Presentation API 3, there is context collision around the type property (when embedding the GeoJSON content in the service), where the service object type would have to be an array to support GeoJSON API (object must have type "Feature" or "FeatureCollection") rules and IIIF Presentation API 3 rules (object must have a type property with a value describing what kind of service it is like "GeoService1"), but the type property is not necessarily expected to be an array of strings by either GeoJSON or IIIF. Therefore, it cannot be used as a service natively. One would have to provide extra context to make sure it all fits together. This issue does not exist in IIIF Presentation API 2 because service objects are not required to contain a type property. That's probably enough to say "GeoJSON is not supported as a service under Presentation API 3" or at least "Ill Advised".

Example of Collision

{
   "id": "http://my.geo.service/GeoJSON/point/12,12/",
   "type": ["Feature", "GeoJSONService"],
   "properties":{},
   "geometry":{
      "type":"Point",
      "coordinates":[12,12]
   }
}

In the playground when using the IIIF Presentation 3 context to process this, the type is seen as

"type": [
      "https://json-ld.org/playground/Feature",
      "https://json-ld.org/playground/GeoJSONService"
    ]

because Presi 3 doesn't process a type that is an array of strings.

To make this work, one would have to define "GeoJSONService" in a context file and make sure it scopes in the GeoJSON-LD context, and also make sure that for type the GeoJSON-LD context takes priority over the IIIF Presentation 3 context.

If you do that properly, then type is seen as

"type": [
      "https://purl.org/geojson/vocab#Feature"
      "https://my.vocab.com/GeoJSONService"
    ]

Of course, one can avoid all of this by using a referenced object in the service property, but they still need to define "GeoJSONService" in a @context somewhere, like so

{
   "@context":[
      {
         "GeoJSONService":{
            "@type":"@id",
            "@id":"http://my.geo.service/GeoJSON#GeoJSONService"
         }
      }
   ],
   "id":"http://my.geo.service/GeoJSON/point/12,12/",
   "type":"GeoJSONService"
}

With navPlace, since it its own property and not a service object and scopes in the GeoJSON-LD context to the property itself, there are no context collisions (unless you cause ones in the properties property). So navPlace is the IIIF-safe way for using GeoJSON in Presentation API 3. It can be used with any IIIF resource type, eliminating any need for a GeoJSON service object.

[thehabes]

Since the value for navPlace can be embedded, you can still provide your service that way like

{
   "navPlace":{
      "id": "http://my.geo.service/GeoJSON/point/12,12/",
      "type":"Feature"
   }
}

[thehabes]

The draft PR is available at https://github.com/IIIF/api/pull/2089

[kirschbombe]

Update: will migrate GeoJson service info to Services page and update the text to say only use with v2, for v3 use navPlace and link to extension

[kirschbombe]

First pass in draft PR https://github.com/IIIF/api/pull/2092