JSON Schema
Example Output
Overview
JSON Schema is a schema language for JSON documents.
JSON-Schema can be generated from a LinkML schema and used to validate JSON documents using standard JSON-Schema validators.
To run:
gen-json-schema personinfo.yaml > personinfo.schema.json
To use this in combination with the standard python jsonschema validator (bundled with linkml):
jsonschema -i data/example_personinfo_data.yaml personinfo.schema.json
See also
Data Validation for other validation strategies
Note
Note that any JSON that conforms to the derived JSON Schema can be converted to RDF using the derived JSON-LD context.
Inheritance
Because JSON-Schema does not support inheritance hierarchy, slots are “rolled down” from parent.
For example, in the personinfo schema, slots such as id and name are inherited from NamedThing, and aliases are inherited from a mixin:
NamedThing:
slots:
- id
- name
HasAliases:
mixin: true
attributes:
aliases:
multivalued: true
Person:
is_a: NamedThing
mixins:
- HasAliases
slots:
- birth_date
- age_in_years
- gender
(some parts truncated for brevity)
This would generate the following JSON-Schema:
"Person": {
"additionalProperties": false,
"description": "A person (alive, dead, undead, or fictional).",
"properties": {
"age_in_years": {
"type": "integer"
},
"aliases": {
"items": {
"type": "string"
},
"type": "array"
},
"birth_date": {
"type": "string"
},
"gender": {
"$ref": "#/definitions/GenderType"
},
"id": {
"type": "string"
},
"name": {
"type": "string"
},
},
"required": [
"id"
],
"title": "Person",
"type": "object"
},
Composition
JSON-Schema support schema composition through:
allOf
anyOf
oneOf
not
Currently there are no directly equivalent constructs in LinkML, although future versions of LinkML will support an expressive constraint mechanism.
Note that many uses of the above constructs may be better handled by using inheritance (see below) in LinkML. Future versions of LinkML may support translation of certain object oriented patterns to JSON-Schema compositions, for example:
The union_of slot could be used to generate oneOf
Inlining
LinkML separates the underlying logical model from choices of how references are inlined in JSON.
If an inlined directive is added to a slot definition as follows:
has_employment_history:
range: EmploymentEvent
multivalued: true
inlined: true
inlined_as_list: true
then the JSON-Schema will use a $ref
:
"has_employment_history": {
"items": {
"$ref": "#/definitions/EmploymentEvent"
},
"type": "array"
},
However, if a slot is not inlined and the range is a class with an identifier, then the reference is by key.
For example, given:
FamilialRelationship:
is_a: Relationship
slot_usage:
related to:
range: Person
required: true
Here the value of related_to
is expected to be a string must be an
identifier for a Person
object:
the range is treated as a simple string in the JSON-Schema
"FamilialRelationship": {
"additionalProperties": false,
"description": "",
"properties": {
"ended_at_time": {
"format": "date",
"type": "string"
},
"related_to": {
"type": "string"
},
"started_at_time": {
"format": "date",
"type": "string"
}
},
"required": [
"type",
"related_to"
],
"title": "FamilialRelationship",
"type": "object"
},
Thus the JSON-Schema loses some information that is useful for validation, and for understanding of the schema.
Patterns
Both LinkML and JSON-Schema support the same subset of ECMA-262 regular expressions.
See Regular Expressions.
For example, the following schema fragment
classes:
# ...
Person:
# ...
slot_usage:
primary_email:
will generate:
"primary_email": {
"pattern": "^\\S+@[\\S+\\.]+\\S+",
"type": "string"
}
Enums
Enumerations are treated as simple strings. If the LinkML schema has additional metadata about the enumeration values, this is lost in translations.
Example:
classes:
# ...
FamilialRelationship:
is_a: Relationship
slot_usage:
type:
range: FamilialRelationshipType
required: true
related to:
range: Person
required: true
#...
enums:
FamilialRelationshipType:
permissible_values:
SIBLING_OF:
description: a relationship between two individuals who share a parent
PARENT_OF:
description: a relationship between a parent (biological or non-biological) and their child
CHILD_OF:
description: inverse of the PARENT_OF type
Generates
"FamilialRelationship": {
"additionalProperties": false,
"description": "",
"properties": {
"ended_at_time": {
"format": "date",
"type": "string"
},
"related_to": {
"type": "string"
},
"started_at_time": {
"format": "date",
"type": "string"
},
"type": {
"$ref": "#/definitions/FamilialRelationshipType"
}
},
"required": [
"type",
"related_to"
],
"title": "FamilialRelationship",
"type": "object"
},
"FamilialRelationshipType": {
"description": "",
"enum": [
"SIBLING_OF",
"PARENT_OF",
"CHILD_OF"
],
"title": "FamilialRelationshipType",
"type": "string"
},
Docs
Command Line
gen-json-schema
Generate JSON Schema representation of a LinkML model
gen-json-schema [OPTIONS] YAMLFILE
Options
- -i, --inline
Generate references to types rather than inlining them. Note that declaring a slot as inlined: true will always inline the class
- -t, --top-class <top_class>
Top level class; slots of this class will become top level properties in the json-schema
- --not-closed, --closed
Set additionalProperties=False if closed otherwise true if not closed at the global level
- -f, --format <format>
Output format (default=json)
- Options
json
- --metadata, --no-metadata
Include metadata in output (default=–metadata)
- --useuris, --metauris
Include metadata in output (default=–useuris)
- -im, --importmap <importmap>
Import mapping file
- --log_level <log_level>
Logging level (default=WARNING)
- Options
CRITICAL | ERROR | WARNING | INFO | DEBUG
- --mergeimports, --no-mergeimports
Merge imports into source file (default=mergeimports)
Arguments
- YAMLFILE
Required argument
Code
- class linkml.generators.jsonschemagen.JsonSchemaGenerator(schema: Union[str, TextIO, linkml_runtime.linkml_model.meta.SchemaDefinition], top_class: Optional[str] = None, **kwargs)[source]
Generates JSONSchema documents from a LinkML SchemaDefinition
- serialize(**kwargs) str
Generate output in the required format
- Parameters
kwargs – Generater specific parameters
- Returns
Generated output