---
last_review: "2025-01-01"
last_reviewer: "-"
documented_code: [ ]
---

```{tags} tutorial, advanced-user, schema, jsonschema
```

# Define a LinkAhead Schema with JSON Schema

:::{note}
This page has been migrated from the old documentation, and has not yet been fully revised.
There might be inconsistencies or errors when using with current LinkAhead versions.
:::
% TODO: Issue: https://gitlab.indiscale.com/caosdb/src/linkahead-docs/-/issues/78
% TODO: Update with info from <https://gitlab.com/caosdb/caosdb-advanced-user-tools/-/issues/42> as
% TODO: soon as it is implemented

## Further information

### Pattern Properties

The JSON-schema parser has rudimentary support for `patternProperties`. Since their names (only the
pattern that their names will suffice) are not known a priori, we create RecordTypes for all pattern
properties. The names of these RecordTypes are created from their parent element's name by appending
the string `"Entry"` and possibly a number if there are more than one pattern properties for one
parent.

All the RecordTypes created for pattern properties have at least an obligatory `__matched_pattern`
property which will -- as the name suggests -- store the matched pattern of an actual data entry.

:::{note}
The `__matched_pattern` property is added automatically to your Schema as soon as there is at
least one pattern property in your JSON schema. So be sure that you don't happen to have an entity
with exactly this name in your database.
:::

E.g., a json schema with

```json
"dataset": {
    "patternProperties": {
        "^[0-9]{4,4}": {
            "type": "boolean"
        },
        "^[0-9]{4,4}-[0-9]{2,2}-[0-9]{2,2}": {
            "type": "object",
            "properties": {
                "date_id": {
                    "$ref": "#/definitions/uuid"
                }
            }
        }
    }
}
```

This would result in a `Dataset` RecordType that has the two properties `DatasetEntry_1` and
`DatasetEntry_2` (as always, name can be overwritten explicitly by specifying the `title` property),
referencing corresponding `DatasetEntry_1` and `DatasetEntry_2` Records.

Apart from the aforementioned `__matched_pattern` property, `DatasetEntry_1` also has the
`DatasetEntry_1_value` property with datatype `BOOLEAN`, that stores the actual value. In turn,
`DatasetEntry_2` is of `type: object` and is treated like any other RecordType. Consequently, it
has, appart from the `__matched_pattern` property, a `date_id` property as specified in its
`properties`.

### Array entries without `items` specification

JSON schema allows for properties of `type: array` without the `items` specification that
consequently can be arrays of any (and of mixed) types. While this is in general problematic when
specifying a {term}`Schema`, sometimes these properties cannot be specified further, e.g., when
you're using an external schema that you cannot change.

These properties can still be added to your Schema by specifying their types explicitly in a
dictionary or, alternatively, they can be ignored. See the `types_for_missing_array_items` and
`ignore_unspecified_array_items` parameters of `models.parser.JsonSchemaParser`, respectively, for
more information.

# JSON schema from LinkAhead Schema

Sometimes you may want to have a [json schema](https://json-schema.org) which describes a LinkAhead
Schema, for example for the automatic generation of user interfaces with third-party tools
like [rjsf](https://rjsf-team.github.io/react-jsonschema-form/docs/).

For this use case, look at the documentation of the `caosadvancedtools.json_schema_exporter` module.