.. _Usage Guide:

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
:py:meth:`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 :py:meth:`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 :py:meth:`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
:py:meth:`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
  :py:meth:`ska_schemas.schema._validate_schema_using_document_url`)