🤸‍♀️ "Бесполезные" слова JSON Schema

Сегодня хочу рассказать о нескольких ключевых словах JSON Schema, польза которых может быть на первый взгляд сомнительной. На конкретных примерах, хоть и выдуманных🙄, убедимся, что в жизни эти ключевые слова вполне могут пригодиться.


✅ multipleOf
Позволяет ограничивать кратность числовых значений заданному числу. Если по-простому: проверяемое значение должно без остатка делиться указанное вами. Примеры:

🔘Бронирование переговорных комнат доступно на любую продолжительность в минутах с шагом в 15 минут (15 мин, 30 мин и т.д.).

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "minutes" : {
      "type": "integer",
       "multipleOf": 15
    }    
  }
}

😀Общая площадь квартиры должна иметь точность до 1 знака после запятой.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "area" : {
      "type": "number",
      "multipleOf": 0.1
    }    
  }
}

🔘Цена должна иметь точность до 2 знаков после запятой. Дополнительно явно учтём, что величина должна быть строго положительной.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "price" : {
      "type": "number",
      "multipleOf": 0.01,
      "minimum": 0,
      "exclusiveMinimum": true
    }   
  }
}

🔘Заказ на производство ПЭТ-бутылок ограничен ассортиментом тары с ёмкостью в 0.5л, 1.0л, 1.5л, и 2.л. Значит значение должно делиться на 0.5 с дополнительными ограничениями на диапазон.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "capacity" : {
      "type": "number",
      "minimum": 0,
      "exclusiveMinimum": true,
      "maximum": 2.5,
      "exclusiveMaximum": true,
      "multipleOf": 0.5
    }
  }
}

😫 const
Ограничивает значение поля единственным значением. Формально использование const эквивалентно использованию enum с одним единственным значением, но const позволяет выстраивать более гибкие условия. Пример:

🔘Роль пользователя должна строго соответствовать значению "seller" либо "cashier", хотя ролевая модель может предусматривать больше доступных вариантов.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "role" : {
      "type": "string",
      "oneOf": [
        {"const": "seller"},
        {"const": "cashier"}
      ]
    }
  }
}

✅ if-then-else
Позволяет задать условия проверки полей. Например, мы можем проверить значение и в зависимости от результата проверки потребовать выполнение других условий. Пример:

🔘Для любого оплаченного заказа обязательно должны присутствовать реквизиты оплаты в составе номера счёта и суммы платежа.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    
    "order_status": { "enum": ["pending", "processing", "paid"] },
    "payment_details": {
      "type": "object",
      "properties": {
        "account_number": { "type": "string" },
        "amount_paid": { "type": "number" }
      },
      "required": ["account_number", "amount_paid"]
    }
  },
  "if": {
    "properties": { "order_status": { "const": "paid" } }
  },
  "then": {
    "required": ["payment_details"]
  },
  "else": {}
}

✅ not
Позволяет запретить использование конкретных значений или целых групп значений. Использование not полезно, когда проще описать исключение, чем правило. Примеры:

🔘При регистрации пользователей необходимо удостовериться, что их имена не входят в перечень зарезервированных слов.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "name" : {
      "type": "string",
      "not": { "enum": ["admin", "root", "guest"] }
    }
  }
}

😀Название книги не должно быть пустым и не должно состоять только из пробелов.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "minLength": 1,
      "not": { "pattern": "^\\s*$" }
    }
  }
}

#проектирование #интеграции #сервисы #форматы