Usage Guide

Schemas check JSON-like objects for conformance, e.g. nested dictionaries containing primitives and lists. They especially have a JSON schema representation - though ska_schemas.validate() will generally implement more thorough checks.

All schemas are identified by a URI of the form:

https://schema.skao.int/ska-[subsystem]-[interface]/[major].[minor]

The entire URI should be lower-case alphanumerical. The [subsystem] identifies the leading party for maintaining the schema, and [interface] the concrete interface implemented. Depending on context, this might either be data produced or consumed by the sub-system in question.

Versioning should follow semantic versions: Changes in minor version indicate backwards-compatible changes such as adding new fields or otherwise introducing additional accepted schemas. Changes that break backwards compatibility should change the major version.

You can use the URIs with ska_schemas.validate() to validate data:

from ska_telmodel_client import TMData
from ska_schemas import validate

uri = "https://schema.skao.int/ska-telmodel-layout-location/0.0"
layout_dict = TMData()['instrument/ska1_low/layout/low-layout.json'].get_dict()
validate(uri, layout_dict)

Furthermore you can use ska_schemas.example_by_uri() to retrieve examples of certain schemas (which are replicated in the schema section of this documentation).

Schema validation using JSON schemas

The schema validation documented above works only for schemas (and schema versions) that are supported by the used version of the schemas library. However, these schemas are also make public on the Internet, and therefore can can be retrieved as JSON schemas.

This allows “dynamically” checking against newer schemas, which is useful as a fallback. To use this, set jsonschema_fallback=True parameter for the ska_schemas.validate() function:

from ska_telmodel_client import TMData
from ska_schemas import validate

uri = "https://schema.skao.int/ska-telmodel-layout-location/0.0"
layout_dict = TMData()['instrument/ska1_low/layout/low-layout.json'].get_dict()
validate(uri, layout_dict, jsonschema_fallback=True)

Keep in mind that:

JSON validation is not quite the same as the default validation method performed by the schemas library (it is generally more permissive)
The HTTP request can fail, so this method is less reliable overall.
However, this function will cache schemas, so repeated calls are faster and safe (see ska_schemas.schema._validate_schema_using_document_url())