New JSON-LD context-based version

[joshmoore]

This is an attempt to update the omero-marshal JSON output to replace all uses of TBD. This is done by introducing a top-level context of:

{'@context': {'@base': 'http://www.openmicroscopy.org/Schemas/OME/2016-06#',
              'omero': 'http://www.openmicroscopy.org/Schemas/OMERO/2016-06#'},

Decisions made that may need reviewing:

• Adds an argument to encode() "include_context"
  • Sets include_context true for the top-level but internal calls revert to False
  • Sets include_context to False for tiny elements like permissions, details, and externalInfo
• Essentially ignores the 2015 split schema URLs since they seem to be untested (remove?)
• Moves all enums into the default (@base) OME schema namespace
• Renames PixelsType to the @base PixelType
• Renames Illumination to the @base IlluminationType
• Moves all other TBD classes into the as-yet nonextant omero: namespace https://www.openmicroscopy.org/Schemas/OMERO/2016-06/
  • decided again shortening the omero: prefix to save characters (e.g. ro:)

[sbesson]

With a bit of delay, some feedback & a few initial questions ahead of the upcoming discussions around the extension of the OMERO JSON API:

• overall, very supportive of any proposal allowing to fix these TBD namespaces. In the absence of a published schema, http://www.openmicroscopy.org/Schemas/OMERO/2016-06 is probably as good as a starting point as any
• on the include_context keyword, is there a situation where one would not want to include the context in the marshalled representation of an object?
• as the @type of most objects is getting updated, I assume the decision to use @vocab is primarily for consistency instead of e.g. defining another ome prefix and having ome:Image?

Given the modifications to the format, one of the consideration is the impact of this proposal on the OMERO JSON API. At minimum, I suspect this will bring us to increasing the API_VERSION to the next number communicating backwards incompatible changes. Two immediate questions:

• my general feeling would be to start building a roadmap towards version 1.0 of the OMERO JSON API i.e. api/v1/ endpoints
• is there some mechanism allowing omero-marshal to selectively return the current format? Understanding this is additional infrastructure and legacy code that needs to be maintained, from an end-user perspective, being able to maintain api/v0 at least for a while means we could start rolling out these changes as backwards-compatible API additions rather than considering all the implications of backwards-incompatible API changes

/cc @kkoz @will-moore @jburel

[joshmoore]

• on the include_context keyword, is there a situation where one would not want to include the context in the marshalled representation of an object?

Yes, recursively. The first invocation sets it to True and then all subsequent to False to avoid massive repetitions.

• -as the @type of most objects is getting updated, I assume the decision to use @vocab is primarily for consistency instead of e.g. defining another ome prefix and having ome:Image?

Exactly. Open for discussion though.

• my general feeling would be to start building a roadmap towards version 1.0 of the OMERO JSON API i.e. api/v1/ endpoints

👍

• is there some mechanism allowing omero-marshal to selectively return the current format?

I don't think it would be too difficult, just wasn't even a consideration during the hackathon.