UI schema and element description

Is there a way to set a description on a specific element (control)? I see there is a description field on the properties in the Schema, but that doesn’t seem to work if the property uses a “$ref” for something like a shared list in the definitions. I can put the description on the referenced definition, but if that definition is used by two controls that use a shared list, the control descriptions need to be different.

Please advise if there is another way to control the description that shows under a field element when it has focus, or not focused and using “showUnfocusedDescription”: true.

Hi @dcjarvisvt,

We only consider the description of the JSON Schema, there is no equivalent property in the UI Schema. Also we don’t support overwriting the target properties via a $ref link.

However an easy way of overwriting the description can be implemented using our i18n support, you can find the docs here.

Thanks Stefan. If I understand correctly, properties using a “$ref” shouldn’t overwrite the “description” set in the object defined in properties.

With the below property object, my description isn’t displayed.

    "zlist1": {
      "description": "My List Description",
      "type": "string",
      "$ref": "#/definitions/foobar"
    },

Below is my definition of “foobar”.

"foobar": {
  "type": "string",
  "oneOf": [
    {
      "const": "foo",
      "title": "foo"
    },
    {
      "const": "bar",
      "title": "bar"
    }
  ]
},

If I remove the “$ref” item (which I am using to reference an enum or oneOf for a list), to just display as a normal string, then the description is shown under the control in the UI.

If this a bug, or am I doing something wrong?

Hi @dcjarvisvt,

It’s not really a bug but more of a missing feature.

The reference resolving within JSON Forms is very basic: When we encounter a reference we just follow it without keeping any context. So in your case we follow the references to foobar but lose the context of the alternative description. Therefore we only consider the annotations of the original location. This follows the specification of JSON Schema Draft 7 in which this behavior is a MUST: All other properties in a “$ref” object MUST be ignored.

With JSON Schema Draft 2019-09 and later this was reworked, so following that specification and the example above we should render the description as defined. Note that the specification does not define a behavior for overriding, see here.

We don’t fully implement any of the drafts as they contain many concepts which are hard to map to the forms use case and also contain many seldom used features. Especially in regards to resolving, vocabulary etc. the drafts changed a lot.

So to summarize: The current behavior is the expected one. I would be open for enhancing JSON Forms for the mentioned “annotation collection” behavior, however this will not be an easy task as the current architecture was not designed with this requirement in mind as it did not exist then and was even explicitly excluded in the spec.