jsonschema.md

Модуль jsonschema

Схема - некая структура вложенности объектов, параметров, данных переменных, к примеру схемой можно назвать POST запрос фронта на точку API сервера, в виде JSON тела со следующей структурой.

Вся эта структура с ее вложенностью и есть то что можно назвать схемой

{
    "count": 100,
    "params": {
        "number": { 
            "min": 1,
            "max": 100
        },
        "type": 55
    }
}

---

Другой пример, представим себе что мы используем GeoPandas для сохранения .shp файла с геометрией и атрибутами полей.

# схема по сохранения полей в выходной файл 
SCHEMA = {
    "geometry": "Unknown",
    'properties': {
        'uuid': 'int',
        'attr1': 'str',
        'attr2': 'date',
        'attr3': 'str',
        'attr4': 'float'
    }
}

# сохраняем GeoDataFrame в выходной файл
geo_df.to_file(
               path_to_save.as_posix(), # путь к сохраняемому файлу
               mode='w',                # модификатор доступа  
               encoding='UTF-8',        # кодировка
               schema=SCHEMA            # указывем схему сохранения
           )

---

Другой пример, это обычные объекты с вложенными объектами

class A:
    name = 'name'
    number = 55 
    list = [1, 2, 3, 4, 5]

    def __init__(self, obj):
        self.inner_obj = obj
    
class B:
    name = 'name2'
    number = 100

a = A(obj=B())

# Структуру объекта A можно представить:
struct = {
    "name": "name",
    "number": 55,
    "list": [1, 2, 3, 4, 5],
    "inner_obj": {
        "name": "name2",
        "number": 100
    }
}

---

jsonschema - модуль для проверки соответствия (объекта, словаря, json ...) заданной схему с указанием типов данных, это полезно использовать при валидации запросов/ответов от API и содержимого json файлов, то есть мы можем описать схему данных, и проверять соответствие объекта этой самой схеме, что сразу и является его валидацией, то есть пройдя проверку, мы можем быть уверены, что объект соответствует указанным нами требованиям, и что объект пригоден к последующей обработке.

Установка

pip install jsonschema

Общая суть модуля проста, мы описываем правила валидации, нахождения определенных атрибутов с указанием какие из атрибутов являются обязательными, и описываем типы данных.

Вот пример того как можно удобно валидировать структуру данных на соответствие схеме:

import jsonschema
def validate_structure_by_schema(input_data, schema):
    """
    Проверяет структуру на соответствие установленной схеме данных
    """
    try:
        jsonschema.validate(instance=input_data, schema=schema)
    except jsonschema.exceptions.ValidationError as e:
        return False
    return True

Наша структура

{
    "count": 100,
    "params": {
        "number": { 
            "min": 1,
            "max": 100
        },
        "type": 55
    }
}

Опишем правила валидации для этой структуры:

SCHEMA_FOR_VALIDATION = {
        "type": "object", # указываем тип объекта
        "properties": {   # свойства которые должны быть у этого объекта
            "count": {    # название поля которое должно быть и вложенная структура
                "type": "integer", # тип данных число
                "minimum": 1,      # минимальное значение
                "maximum": 100     # максимальное значение
                },
            "params": {
                "type": "object",
                "properties": {
                    "number": {
                        "type": "object",
                        "properties": {
                            "min": {"type": "integer", "minimum": 1},
                            "max": {"type": "integer", "maximum": 1000},
                        },
                        "required": ['min', 'max']
                    },
                    "type": {"type": "integer", "minimum": 1},
                },
                "required": ['number']
            }
        },
        "required": [ # указываем какие атрибуты должны быть обязательными на этом уровне
            'count', 
            'params'
        ] 
    }