Feature req: Labels in multiple languages in REST API suggest method(s)

[osma]

We received this feature request for the Finto AI API, which is basically the Annif API:

"Is it possible to have your Finto AI API return all available language equivalents for a given term? Currently, for example, when using YSO EN, it only returns the term in the English language (or the language specified as a parameter), even though there are likely other translations available. The desired functionality would be for the API to return all available equivalents for a term across all supported languages. For example, if we send a project request using yso-en and specify Finnish (fi), Swedish (sv), and English (en) as the desired languages, we would like to receive suggestions for the term in all three of those languages within a single request."

(machine translated from the original Finnish)

One question is how the response data would look like. Currently the suggest response looks like this:

{
  "results": [
    {
      "uri": "http://example.org/subject1",
      "label": "Archaeology",
      "notation": "42.42",
      "score": 0.85
    }
  ]
}

Instead of a single string value for the label field, we could return something like:

      "label": {
          "en": "archaeology",
          "fi": "arkeologia",
          "sv": "arkeologi"
      }

Another option would be to use several language-specific fields like label_en , label_fi, label_sv.

[avalyset]

Looking at this — would a backward-compatible additive approach match the convention already used elsewhere in the NatLibFi ecosystem?

Skosmos REST returns multilingual labels as {"en": "archaeology", "fi": "arkeologia"} (JSON-LD compact form with @container: @language), and that's also what subject.labels already looks like internally in Annif. Keeping the existing label field as-is and adding a new optional labels object would give:

{
  "uri": "http://example.org/subject1",
  "label": "Archaeology",
  "labels": {
    "en": "Archaeology",
    "fi": "arkeologia",
    "sv": "arkeologi"
  },
  "notation": "42.42",
  "score": 0.85
}

Populated only when the client requests it via something like labels=fi,sv,en (comma-separated) or repeated query params. This:

• keeps every existing client working unchanged
• matches Skosmos format exactly (no learning curve for the same audience)
• mirrors the internal subject.labels shape (minimal serialization work)
• avoids the IIIF-style array-per-language overhead that doesn't fit single-label suggestions

Alternative 2 (flat label_en, label_fi) ends up either always present (bloating responses) or dynamically present (harder to type in strongly-typed clients).

Happy to draft a PR if this direction is useful.

[avalyset]

The offer to implement this still stands. #946 exposes project metadata through the REST API using the same shape discussed here — additive optional field, existing response untouched — so there is now a concrete precedent in the codebase to follow if the additive labels object looks right to you.