Skip to content

Image Collection Tools Code Review

Jump to bottom
LFDM edited this page Dec 15, 2014 · 44 revisions

Summary and Background

The following is a review of this suite of tools as of December 12, 2014 :

https://github.com/caesarfeta/imgcollect_angular

https://github.com/caesarfeta/JackSON

https://github.com/caesarfeta/JackRDF

https://github.com/PerseusDL/CITE-JSON-LD

https://github.com/perseusdl/imgspect

The original, pretty sparsely defined, requirements which these tools needed to fulfill are defined in https://github.com/PerseusDL/perseids_docs/issues/59. Missing from that issue is the fact that the requirements were meant to be considered in the context of the currently deployed solution for Perseids which uses the the Cite Image Service, Cite Collection Service, Cite Collection Manager and Cite Collection Editor tools from the Homer Multitext project. The implict assumption that the new solution should be a superset of the functionality that the existing implementation provided was not explicitly listed in the issue, but I believe it was conveyed during discussions.

I previously reviewed a earlier prototype of this suite, driven via https://github.com/caesarfeta/imgcollect and provided feedback that included the following:

  1. CITE collections should definitely NOT be fixed. We should be able to add new items to a collection any time. I think probably we do not want to delete items (since they are being used as persistent identifiers) but we may want to enable a status which says an image has been deprecated or superceded. I do think it is certainly reasonable to think about a single image being part of multiple collections, but that does not replace the need for collections to be living things.

  2. To integrate with Perseids we need the ability to directly link from the text of an item being edited (annotated, etc) to the imgcollect/imgspect interface with images which have been associated with that text preselected for use. We can do this easily if we allow a user to create a relationship between a text and an image (i.e. an annotation) within the imgcollect interface when they upload an image and/or add it to a collection. I.e. we should allow browsing images and creating object level annotations between texts (or other things) and the image from either the Perseids SoSOL interface or the Img Collect interface. We should definitely be able to leverage the fact that we know the CTS urn of a text we are editing to automatically identify images for working on with that text in imgspect. This is the aspect of integration that is most important to me. SoSOL already supports the concept of querying for images from user-specified triple stores, the interface just needs to be built out a bit.

  3. I agree that the image ROI selections should be preserved as standoff annotations, but when we do that we should preserve the context of the annotation, whatever that happens to be, and we should be always have the option to serialize (and export) the annotations according to the OA data model, in JSON-LD (with RDF/XML as an option as well). I think it is fine to put the annotation directly into a fuseki triple store as we do it but we should be using a standard ontology when doing so, and capturing all of the necessary information to be able to export it a well-formed OA annotation. OA is a core requirement - it is important for interoperability and I think it is also a really helpful guide when modeling what needs to be preserved.

  4. We do at some point need to put a CITE API unto the image collect service -- this is part of the contract of using CITE URNs and CITE collections. This is maybe not the absolute top priority at the moment, but I do not want to forget about it.

In response to Adam's subsequent pitch to consider a more general role this suite of tools could play in the Perseids architecture, I also identified the following as high-level pre-requisites for the inclusion of these tools in Perseids in this context:

  1. any definition of what makes up a collection of items, and what an expected structure for an item is must be external to the service

  2. any identifiers used for objects must be able to be persistent, stable identifiers not tied to any specific deployment of the service

  3. any ontology used by the service must be externally configurable

  4. where ever standards exist, we should use them

At that time I also provided additional feedback on how they could be used to support a native-JSON implementation of the CITE protocol, this is discussed further below, and also provided background information on the current state of tools supporting CITE collections in Perseus/Perseids in this google document.

Review of the current suite

Overview of Components

To start, here is my understanding of what each of these components currently provides:

imgcollect_angular provides:

  • a UI for creating, editing and updating collections of images and annotations on those images. This UI includes the following features:
    • upload a new image (although as far as I can tell, upload from the UI is not currently working - images can only be added via the fake data seeder)
    • create a CITE collections of images, where those CITE collections are all in the urn:cite:perseus namespace, and prefixed with the http://data.perseus.org/collections urispace
    • add uploaded images to one or more CITE collections of images
    • edit a fixed set of metadata fields on the image collection items
    • view the underlying JSON-LD file
    • integration with imgspect to create ROI annotations on images, where those annotations are added as items identified as belonging to the CITE collection of the image which they annotate. The editable properties of the annotation items are currently fixed. This implementation also breaks the CITE protocol because it creates collections of mixed object types (i.e. images and annotations on images)
    • uniqueness checking on a collection name with a single back-end datastore
    • an id generator for new collection items
    • ability to filter items shown by their association with a single user (but currently the triple that defines the user is hardcoded and does not adhere to any standard provenance ontology)

JackSON provides:

  • lightweight file-system server with a REST API for storing JSON-LD files which also proxies access to a triple store for SPARQL query support for the triples contained in the JSON-LD data objects
  • JSON-LD objects can be retrieved by specifying the URI of the subject of the triples contained within (although it's not clear to me if it works with all URIs or just URNs)
  • Rake tasks for seeding the server with fake data

JackRDF provides:

  • an adapter library to the SPARQL endpoint of a triple store that provides
    • Create/Update/Delete functionality for sets of triples that are:
      • aggregated by the URL subject of the triples
      • sourced from JSON-LD files stored on the local file system
    • special handling to strip a pre-configured (currently hard-coded) urispace from a subject containing a urn before operating on it as a subject
    • conversion between RDF to JSON-LD
    • a rake script for installing and running a fuseki server

CITE-JSON-LD provides

  • erb templates for JSON-LD documents, which can serve as templates for ways to represent CITE collection objects in JSON-LD
  • generators to create sample data adhering to these templates

Changes needed to support only the original image management requirements

These are the minimal changes needed in order to enable use of these tools to fulfill the original requirements (as explicitly stated in the github issue) to provide a means for users of Perseids to manage their own image collections. This feedback accepts the fact that the implicit requirement that existing functionality of the HMT suite of CITE collection tools also be supported may not have been clearly conveyed, and thus does include additional changes that would be required to meet that need. It also accepts for now the hardcoded CITE collection namespace/URIspace references under the assumption that we will externalize this at a later date.

imgcollect_angular

  • uploads of new images needs to be made functional
    • it must support upload from the local filesystem of the user as well as from a remote url
  • editable properties for image collection items must include an optional field for a CTS urn of a text (or passage of text) of which this image is a representation
  • editable properties for image collection items must include all those supported by the current Perseids image collections defined in https://github.com/PerseusDL/cite_collections/blob/master/src/capabilities/capabilities-gf-pub.xml
  • the integration with the Perseids user session that was working in the September prototype but which is not present in the current code must be added
  • filtering by user must then be based upon the current Perseids user and not use a hardcoded user for this filter
  • as there is no versioning support, the interface should restrict edits of existing image collection items to the user who created them, again via use of the Perseids session
  • the ontology used in the image items needs to be reviewed and adjusted as needed to use standard ontologies where ever possible
  • annotation functionality needs to be removed or disabled for now as it breaks the CITE protocol (as described above) and also does not adhere to the OA protocol. We can put this back in only when CITE compliance is in place (more on this below). Prior feedback I provided on this topic may not have been completely clear, and focused more on OA than CITE. It's a nice prototype of value-added functionality and not far from being usable, but it needs to be prioritized now as it is technically out of scope from what is funded. There are also already many other projects working on similar functionality.
  • the URLs at which the uploaded images can be retrieved must not be tied to the URL of the hosting server (see more under JackSON for this as I assume JackSON is responsible for storing image uploads although I can't verify this as the image upload functionality isn't working)

JackSON

  • the source URLs stored in the triple store for the source JSON-LD data and images must not be tied to the URL of the hosting server. At minimum, there must be an externalized (e.g. in the config.yml) setting which allows you to define this at deployment time without requiring a change to any ruby code, only yml config files. JackSON can continue to store these files locally but the public-facing URL for them and at which they can be retrieved must not be assumed to be the physical server address hosting the application. Apache rewrite rules will be used to direct requests to the appropriate JackSON server environment for retrieval. I see that there is already some externalization of these settings in the config.yml already but I'm not sure if it fully meets this requirement. In order to determine that, the deployment instructions need to be clarified to describe how these settings are used in the code and provide guidance on how they should be set to fulfill this requirement.

Changes needed to support CITE Collections more generally in Perseids

The pitch was to consider the role this suite of tools can play more generally in the Perseids and Perseus architecture. I do see a role for them but also alot of work still needed to get them to the point where they could fulfill that role.

The main role would be as a native JSON-LD implementation of the CITE collection protocol. This would be a replacement for the originally scoped plan for Perseids to integrate the Cite Collection Service, Cite Collection Manager and Cite Collection Editor tools from the Homer Multitext project to provide CITE support. Having such an implementation that integrates more seamlessly with Perseids and requires less manual work to maintain would be very helpful, but as they stand today, this suite of tools provides less functionality than the existing implementation and are not compliant with the CITE protocol.

In the earlier review of Imgcollect, I had identified the high-level minimum requirements for this role for the imgcollect and Jack* tools as being:

  1. We need to be able to express the equivalent of a Cite CollectionInventory to define CITE collections managed/understood by the service. This defines the set of collections known to the service and the properties of the objects that make up each collection. This information must be stored external to the service and be updatable without requiring code changes.

  2. The service should have native support for working with CITE urns and all of the other datatypes currently supported by the CITE protocol (which includes CTS urns)

  3. We need to be able to support the equivalent of all the requests in the CITE protocol. I do not particularly care at this point if they are exactly how CITE defines them or RESTful versions ... I think the latter probably makes more sense.

  4. We need the ability to swap in a NoSQL/Document database like MongoDB or Dynamo DB for storing the JSON-LD files.

There are actually more, as relates to user identification/authentication and versioning, but so far none of the above previously identified requirements are in place. There is a start on item 1 with the CITE-JSON-LD repository and JackSON, but it is not functional for this purpose yet. An expansion of the requirements for item #1 is provided below as feedback to the work started in this direction:

  • as a deployer of this suite of tools I must be able provide as a JSON-LD document (and not an erb template) that defines the list of collections my environment supports that contains all of the information currently conveyable by the CiteCollectionInventory schema.

  • This JSON-LD collection inventory document should be able to include other pre-configured named templates that define default collection types. The Arethusa system for configuring treebank tagsets provides a very good example of how this can be done.

  • The templates should clearly define which fields are user-editable and therefore part of the official CITE collection object, and which are internal to the structure of the file (e.g. such as the context, etc.)

  • The image collect and JackSON code must not hardcode any fields to provide a user editing interface but instead draw on information provided in the templates to determine what to display to the end user.

  • The system should support the ability to create new CITE collections whose objects don't adhere to one of the pre-defined templates (as long as they are compliant with the CITE protocol as currently defined in the schemas.

  • User interface support for creating new collections is desirable, but it must not preclude the ability to manage this via the external configuration files, and must read/write from this externalized configuration.

  • The templates must all use standard ontologies whereever possible.

I would really like to be able to take these tools to the point where we can use them in this way because I think generally the approach to a hybrid model for working with CITE collections, where the collection data itself can be versioned and reviewed in a workflow while also immediately published to triple store for querying is going to be essential for our publication workflows. We have already had some discussions about this possiblility, inspired in part by earlier work on this code which this diagram represents. But I think we can't consider their use in this role until the above minimum requirements are met, and we now need to prioritize if/when/how that will take place.

General Reuse/Extensibility notes

We always have to balance the need for meeting minimum requirements for our current use cases with a goal of writing code that can be reused and extended. The latter imposes additional effort, but if it is considered from the start that effort doesn't always have to be prohibitive. The following are some initial notes on the code as it exists today that I see as preventing its reuse and extension. This is not an exhaustive list, just the things that stood out from a quick review of the code.

imgcollect_angular

  • sparql queries are hardcoded
  • fields used in sparql queries are not configurable
  • urispace for identifiers is hardcoded
  • namespace for CITE urns is hardcoded
  • url scope for user identifiers is hardcoded
  • predicate used to associate a user with a collection item is hardcoded and also does not use a standard provenance ontology
  • interface strings are hard-coded and not localizable

JackSON

  • the storage method for JSON-LD files is not abstracted so that it can be switched from the file system to a NoSQL/Document DB
  • there is no support for versioning of the data
  • may be more work needed to abstract deployment location from urls of data stored

JackRDF

  • urispace for urns is hardcoded
  • ontology used for identifying the source location for the JSON-LD file is hardcoded

I have not yet reviewed the code in the IMGSPECT or the CITE-JSON-LD repositories in detail for this, although I believe I had previously provided feedback on IMGSPECT related to a need for Open Annotation support in an earlier review of that code.

Clone this wiki locally