Known limitations of LinkML for `json-schema` generation

[jsheunis]

We are using (or proposing to use) LinkML for several purposes, including the generation of json-schema documents from YAML schemas, which can then in turn be used for automatic online form generation to submit (ideally validated) data. As such, the ideal YAML-schema -> LinkML -> json-schema process would allow:

• the specification of all structure and constraints required in the eventual data
• the correct propagation of said structure and constraints from LinkML to json-schema

Currently, this is not the case and there are known limitations in LinkML that necessitate workarounds:

1. Inability to specify minItems for an array in LinkML

ValueError:  Unknown argument: minItems = 1

2. Cannot specify format of a json-schema property in YAML

ValueError:  Unknown argument: format = 'textarea'

3. title property of a slot does not propagate to json-schema

No error when running gen-json-schema, but the title property is just not in the resulting document for the related slot.

4. The json-schema document's title comes from LinkML schema's name in metadata

...even though there is a title property in the LinkML schema's metadata as well.

5. The need for the inlined directive

For LinkML class attributes with a range that is another class, the fully resolved class and its properties will not propagate to the json-schema document unless the inlined directive is used, see: https://linkml.io/linkml/generators/json-schema.html#inlining. This implies we should inlining wherever appropriate if the goal is to not lose schema information (which is very useful for validation) when propagating to json-schema

6. Unpopulated (dynamic) enums

Any reference in a LinkML schema to an ontology lookup, for example for populating dynamic enums (https://linkml.io/linkml/faq/modeling.html#how-do-i-constrain-the-value-of-a-slot-using-an-ontology-or-vocabulary) isn't propagated to the jsonschema document. The resulting enum just mentions a string as input type and provides no options.

---

I would be glad to learn if some of these limitations actually have LinkML-based solutions.

[jsheunis]

Many (all) of these limitations also exist for SHACL generation. Also, the annotation fields detailed here https://linkml.io/linkml/schemas/annotations.html#annotations do not propagate to the exported format, specifically SHACL-related examples given here: https://linkml.io/linkml/developers/tool-developer-guide.html#customizing-and-application-hints.