Extend negative assessing annotations with predefined comments

[nichtich]

Negative assessing annotation (motivation=assessing and bodyValue=-1) should be allowed to optionally include a comment from a list of predefined comments to clarify the reason for negative annotation. Following Web Annotation Data Model this can be modeled like this (annotation records reduced to fields relevant to this issue):

{
  "motivation": "assessing",
  "body": [
    {
      "type": "TextualBody",
      "value": "-1"
    },
    {
      "type": "SpecificResource",
      "value": "URI-OF-PREDEFINED-COMMENT",
      "purpose": "tagging"
    }
  ]
}

There is another method to use plain text comments (pro: can directly be displayer, con: no identifier)

   {
      "type": "TextualBody",
      "value": "PREDEFINED-COMMENT",
      "purpose": "tagging"
    }

In both cases clients need a list of predefined comments, so I prefer the first variant with SpecificResource.

Open question is whether to deprecate bodyValue (a shortcut for TextualBody object) and also use this more verbose form for simple annotations, e.g.

{
  "motivation": "assessing",
  "body": {
    "type": "TextualBody",
    "value": "-1"
  }
}

But we still need to support both single-value body and array body, so I thing its easier to have

• annotations with plain bodyValue
• annotations with body, being an array of two elements, the first TextualBody with value=-1 and the second SpecificResource with purpose=tagging.

[stefandesu]

Some questions:

• It's probably not allowed to use both bodyValue and body, right? Creating the sum of assessment annotations is easier if bodyValue is always present (which is currently assumed).
• Where do the clients get the list of predefined comments? Will there be a new API endpoint or should they be hardcoded and we assume clients that implement this (let's be honest, this probably means only Cocoda) just copy this list (from the documentation)?
• Should the SpecificResource/tagging body be restricted to negative assessments? What if the assessment is patched from negative to positive?

[nichtich]

It's probably not allowed to use both bodyValue and body, right?

I think it's allowed, so we could use this form:

{
  "motivation": "assessing",
  "bodyValue": "-1",
  "body": {
    "type": "TextualBody",
    "value": "PREDEFINED-COMMENT",
    "purpose": "tagging"
  }
}

Should the SpecificResource/tagging body be restricted to negative assessments? What if the assessment is patched from negative to positive?

Our use case only covers negative assessments so body would only be allowed when there is bodyValue with -1 and changing the assessment would disallow a comment.

Where do the clients get the list of predefined comments?

We could put it into /status endpoint in annotations.tagMismatch (list of URIs).

[stefandesu]

I assume it would be enough to add a check whether the specified comment URI belongs to the mismatch vocabulary, i.e. is in the https://uri.gbv.de/terminology/mismatch/ namespace as defined in https://github.com/gbv/jskos-server/issues/198#issuecomment-1508225692?

Now that we're using a vocabulary, how will API consumers access that vocabulary? Should the whole vocabulary, including labels, be given in /status?

I will likely implement this on Wednesday.

[stefandesu]

We decided to do like this:

• The mismatch vocabulary needs to be imported in the same jskos-server instance that is managing the annotations.
• The vocabulary URI is given in the configuration (and therefore can be found at the /status endpoint).
• Clients implicitly know that concepts for that mismatch vocabulary can be loaded from the same API.
• The documentation will simply recommend a vocabulary to be used for negative assessment tagging and include instructions on how to import and configure it, but the data itself will not be included in the repository. We will likely add the data to https://github.com/gbv/jskos-data instead. If no vocabulary is configured, negative assessments cannot be tagged.

[stefandesu]

First implementation of this feature is now in Dev. It should work as expected, but there are still some open issues:

• [x] The mismatch vocabulary is not yet officially defined. See #198.
• [x] No documentation (requires definition of mismatch vocabulary and adding it to jskos-data).
• [ ] It currently needs a workaround for jskos-validate. See https://github.com/gbv/jskos-validate/issues/17. (If this made it into release, I don't think it would be a big issue though.)

[stefandesu]

I've added detailed documentation about this feature: https://github.com/gbv/jskos-server/tree/dev#mapping-mismatch-tagging-for-negative-assessment-annotations

I'm not 100% sure whether that's the best spot for it. What do you think, @nichtich?

I also don't think we should delay this too much for that fix in jskos-validate. The current workaround is totally fine in my opinion.