Перевірка схеми JSON перед викликами API

Валідування JSON Схеми перед викликом API

JSON Схема є контрактом, який визначає структуру, типи та обмеження JSON документа. Валідуйте дані до відправлення їх на API, і ви зможете виявити помилки клієнт-серверної сторони замість відлагодження криптичних помилок 400.

Що виглядає JSON Схема

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "format": "email"
    },
    "age": {
      "type": "integer",
      "minimum": 0,
      "maximum": 150
    },
    "role": {
      "type": "string",
      "enum": ["admin", "user", "viewer"]
    }
  },
  "required": ["email", "role"]
}

Ця схема виконує такі умови: email повинен бути валідним рядком електронної пошти, age повинен бути цілим числом від 0 до 150, role повинен бути однією з трьох значень, а обидва email та role повинні бути обов'язковими.

Чому валідувати перед відправкою

Валідування в JavaScript (ajv)

import Ajv from 'ajv';
import addFormats from 'ajv-formats';

const ajv = new Ajv();
addFormats(ajv); // додає "email", "uri", "date-time", тощо.

const schema = {
  type: 'object',
  properties: {
    email: { type: 'string', format: 'email' },
    role:  { type: 'string', enum: ['admin', 'user', 'viewer'] }
  },
  required: ['email', 'role']
};

const validate = ajv.compile(schema);

const payload = { email: 'not-an-email', role: 'superadmin' };
if (!validate(payload)) {
  console.error(validate.errors);
  // [{keyword: 'format', message: 'must match format "email"'}, ...]
}

Валідування в Python (jsonschema)

from jsonschema import validate, ValidationError

schema = {
    "type": "object",
    "properties": {
        "email": {"type": "string", "format": "email"},
        "role":  {"type": "string", "enum": ["admin", "user", "viewer"]}
    },
    "required": ["email", "role"]
}

try:
    validate(instance={"email": "[email protected]"}, schema=schema)
except ValidationError as e:
    print(e.message)  # 'role' is a required property

Рекомендація щодо процесу роботи

Перед перевіркою будь-якого виклику API, скопіюйте свій JSON-пayload у JSON Formatter для перевірки синтаксису та формування візуальної структури. Один додатковий кома або неправильно цитований ключ будуть виконувати мовчазно у багатьох клієнтах HTTP -- виявте його візуально раніше.

Пов'язані статті