`annotation.value` vs. `annotation.text`

[hoehrmann]

There is insufficient guidance in https://github.com/sdmx-twg/sdmx-json/blob/71fe5eaa9fcd29e3c15f2f0216a19b9b650b1dbd/data-message/docs/1-sdmx-json-field-guide.md regarding these properties:

• value - String optional. A non-localised value text of the annotation.
• text - String optional. A human-readable (best-language-match) text of the annotation.
• texts - Object optional. A list of human-readable localised texts (see names) of the annotation.

The SDMX 3.0 Information Model specification also does not shine light on why this has value and text. Consider the case of only a single language in the system. Would the same text be in all three properties? Should reading applications treat them with any kind of preference if multiple values are available? Should generating applications simply ignore the value property? Or does value serve some other purpose, like, value could be for machine-readable code, while text is for humans.

(In doubt, please handle this as a public review comment on SDMX 3.1 once the comment period begins.)

[dosse]

Thanks for this feedback.

Currently, in the SDMX Information Model, the value property is non-localised, while the text property is (always) localised. Indeed, if the language is not specified then English resp. und is assumed.

Therefore, if a localised content is needed then in SDMX-JSON text (and texts) is to be used, while when non-localised content is needed then value is to be used.