Walidator JSON Schema

Czym jest walidator JSON Schema?

// A 5-line schema that catches three real bugs
const schema = {
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id":    { "type": "integer", "minimum": 1 },
    "email": { "type": "string", "format": "email" },
    "age":   { "type": "integer", "minimum": 0, "maximum": 150 }
  },
  "required": ["id", "email"],
  "additionalProperties": false
};

// Three bugs the schema catches:
const bad = { "id": "42", "age": 200 };
//   /id   → type: expected integer, got string
//   /email → required: missing
//   /age   → maximum: 200 > 150

// In Node:        new Ajv().compile(schema)(bad)  // false; ajv.errors has the paths
// In Python:      jsonschema.validate(bad, schema)
// In the browser: this tool — same errors, same paths, no install

Główne funkcje

Przykłady

{
  "id": 42,
  "email": "alice@example.com",
  "age": 30
}

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": { "type": "integer", "minimum": 1 },
    "email": { "type": "string", "format": "email" },
    "age": { "type": "integer", "minimum": 0, "maximum": 150 }
  },
  "required": ["id", "email"],
  "additionalProperties": false
}

{
  "id": "42",
  "age": 200
}

{
  "type": "object",
  "properties": {
    "id": { "type": "integer" },
    "email": { "type": "string", "format": "email" },
    "age": { "type": "integer", "maximum": 150 }
  },
  "required": ["id", "email"]
}

{
  "type": "order.created",
  "data": { "orderId": "ORD-001234", "totalUsd": 49.99 }
}

{
  "oneOf": [
    {
      "properties": {
        "type": { "const": "order.created" },
        "data": {
          "type": "object",
          "properties": {
            "orderId": { "type": "string", "pattern": "^ORD-[0-9]{6}$" },
            "totalUsd": { "type": "number", "minimum": 0 }
          },
          "required": ["orderId", "totalUsd"]
        }
      },
      "required": ["type", "data"]
    },
    {
      "properties": {
        "type": { "const": "order.refunded" },
        "data": { "type": "object", "required": ["refundId"] }
      },
      "required": ["type", "data"]
    }
  ]
}

[
  { "sku": "A1", "qty": 3 },
  { "sku": "B2", "qty": 5 },
  { "sku": "A1", "qty": 3 }
]

{
  "type": "array",
  "minItems": 1,
  "uniqueItems": true,
  "items": {
    "type": "object",
    "properties": {
      "sku": { "type": "string", "pattern": "^[A-Z][0-9]+$" },
      "qty": { "type": "integer", "minimum": 1 }
    },
    "required": ["sku", "qty"]
  }
}

Jak używać

1. 1

   Wklej swój JSON Schema

   Wrzuć schemat do prawego pola. Walidator automatycznie wykrywa wersję z URI $schema, jeśli jest obecny; w przeciwnym razie wybierz Draft 2020-12, 2019-09 lub Draft-07 z paska narzędzi.

2. 2

   Wklej swoje dane JSON

   Wrzuć dokument JSON, który chcesz sprawdzić, do lewego pola. Walidacja działa podczas pisania; duże wejścia (>200 KB) przełączają się na ręczny przycisk Waliduj, aby pisanie pozostało płynne.

3. 3

   Czytaj listę błędów

   Każdy błąd ma ścieżkę JSON Pointer, keyword i jednolinijkowy komunikat. Kliknij błąd, aby przeskoczyć do miejsca w danych, popraw go i obserwuj, jak licznik spada w czasie rzeczywistym.

Typowe pułapki JSON Schema

{ "qty": 1.0 }   schema: { "type": "integer" }   → error: not an integer

{ "qty": 1 }     schema: { "type": "integer" }   → valid

{ "properties": { "name": { "type": "string", "required": true } } }

{ "properties": { "name": { "type": "string" } }, "required": ["name"] }

{ "properties": { "id": { "type": "integer" } } }   accepts: { "id": 1, "foo": "bar", "x": null }

{ "properties": { "id": { "type": "integer" } }, "additionalProperties": false }

{ "type": "string", "nullable": true }   in 2020-12: nullable is just an unknown keyword

{ "type": ["string", "null"] }   in 2020-12: explicitly allows null

pattern: "[A-Z]+"   accepts: "helloX"   (because X matches)

pattern: "^[A-Z]+$"   accepts only: "HELLO"

oneOf: [ { type: "string" }, { type: "string", maxLength: 10 } ]   on: "hi"   → error: matches both

anyOf: [ { type: "string" }, { type: "string", maxLength: 10 } ]   on: "hi"   → valid

Typowe przypadki użycia

Walidacja żądań API

Wklej ciało żądania i schemat endpointa przed wdrożeniem. Wychwyć odpowiedzi 400, których nie pokryły testy — brakujące pola required, błędne typy, liczby poza zakresem.

Weryfikacja ładunków webhooków

Dostawca przysłał ładunek, który Twój handler odrzuca? Zwaliduj rzeczywisty ładunek względem swojego schematu, potem względem opublikowanego schematu dostawcy. Diff między nimi to Twój błąd.

Linting plików konfiguracyjnych

package.json, tsconfig.json, helm values.yaml — każdy plik konfiguracyjny ma publiczny schemat. Wklej schemat, wklej konfigurację, znajdź literówkę. Pomiń metodę prób i błędów.

Testowanie komponentów OpenAPI

Wyciągnij komponent schematu z dokumentu OpenAPI 3.1, wklej tutaj, zwaliduj przykładowe ładunki. Szybciej niż uruchamianie mock servera, deterministycznie, bez SDK.

Pre-flight wysyłki formularza

Wklej przykładowy ładunek formularza zanim podepniesz walidację frontendową. Potwierdź, że schemat odrzuca to, co powinien, akceptuje to, co powinien, a potem wyślij ten sam schemat na klienta i serwer.

Kontrola kontraktu w pipelinie danych

Wynik ETL się rozjechał? Wklej przykładowy wiersz i schemat docelowy. Wskaż, który producent się zmienił i które klucze pękły, zanim pipeline ponowi 10 000 rekordów.

Szczegóły techniczne

Zgodność z Draft 2020-12

Implementuje opublikowaną specyfikację Draft 2020-12 — keyword'y, system typów, słownictwo format. Skontrolowane krzyżowo z wynikami Ajv 8.x i ajv-formats.

Ścieżki błędów w JSON Pointer

Błędy używają JSON Pointer wg RFC 6901 (/user/email/0). Każde naruszenie keyword wskazuje pojedynczą lokalizację w danych — bez niejednoznaczności, bez wyszukiwania po stringu.

Rozwiązywanie wewnętrznych $ref

Rozwiązuje wskaźniki $ref w obrębie jednego dokumentu (#/$defs/foo, #/properties/bar). Cykle wykrywane i raportowane. Zewnętrzne $ref przez HTTP wyłączone dla prywatności.

Najlepsze praktyki

Zawsze ustawiaj additionalProperties: false

Na kontraktach wejściowych (ciała żądań, pliki konfiguracyjne, wiadomości w kolejce) nieznane klucze to zwykle błędy — literówki, przypadkowe pola lub sondowanie napastnika. Odrzucaj je domyślnie.

Używaj $defs do reużywalnych podschematów

Wklej ten sam kształt dwa razy, a się rozjadą. Przenieś wspólne definicje do $defs i odwołuj się przez $ref — jedno źródło prawdy, każda zmiana propaguje się wszędzie.

Waliduj przed logiką biznesową

Uruchamiaj walidację schematu zaraz po JSON.parse, zanim dotkniesz sparsowanej struktury. Zawężanie typów, ustawianie wartości domyślnych i zapis zakładają, że kontrakt się trzyma — upewnij się, że tak jest.

Często zadawane pytania