wiki:NDG3/Vocab/HighLevelSpec

Simple High Level Specification for the Vocab Server Governance

Reason: to allow folk not at the BODC to control lists. Status: Version 0.3. In discussion.

Note that we expect a staged development, not all stages of which might occur in NDG3.

Key architectural assumption:

The vocab server will be deployed with a RESTful interface (and maybe others as well, but for NDG purposes we only care about the REST interface). Browser clients will also be developed for navigating and populating lists.

The restul API we anticipate is recorded here.

This document discusses only the issues associated with populating the lists, and has been informed by a previous version of this document and extensive  discussion. It is not yet complete.

Currently out of scope: How to deal with mappings between items internal to lists and between lists.

Outputs

  1. Service to allow list item additions, item modifications and item deprecations.
    • Given we anticipate a  RESTful interface, we might a priori assume that this is accomplished via
      • POST on a list/item to create an item in a list
      • PUT on a list/item to update an item in a list
      • GET on a list/item to return an xml document description of that item.
      • DELETE on a list/item to deprecate it.
    • We would expect this to be synchronous.
  2. A web client that allows one to interact with a list and make modifications to items via the service interface (thus providing a complete test case for the service interface as well as a functional tool for list modification).
    • Initially expect this to use local http authentication, and move to NDG security in a subsequent release (beyond NDG3).
      • Note that the creation of user accounts should be out of band.
    • After login expect to offer a user a selection of lists for which they have permission to modify.
  3. Service to allow list modifications. In practice we expect this to consist of a set of item modifications, which would be carried out as above.
    • Initially provide a synchronous response but consider that for post NDG3 we might allow asynchronous responses for large sets.
    • We would expect the RESTful interface to look something like:
      • POST would return an error (list creation should be out of band, ie via negotiation with the content provider - BODC).
      • PUT would update the list
      • GET would download a copy
      • DELETE would return an error (lists cannot be deleted).
  4. The backend service would be expected to carry out certain automatic quality control activities.
    • Clearly in the case of item modifications one can only check the internal validity of the item
    • For set modifications there might be consistency checks between set members
    • (and obviously double check the permissions)
  5. The backend service would operate by collecting up modifications to a list during the day into a "working copy of the list" (which we need to be able to separately address), and then update the official version of the list at a specific time (and increment the list version).
    • It should be possible for a list governor to contact BODC out of band to get the working copy manually propagated to the official version in extremis.

(Note that all methods should return appropriate http access codes)

Use Cases

  • CF maintainer. Complete collection of list changes. (Currently provided as one xml document?, so how would that work).
  • Metafor designer:
    • needs to be able to get controlled vocab lists created by negotiation with BODC
    • needs to be able to add items to controlled vocab lists as they arise.
  • NERC DDC staff member
    • as for Metafor designer

NDG3: Capability, Discovery, Vocab, Software, MOLES, Security, Community, Roadmap. See also:  CSML.