Walidator JSON Schema

Czym jest walidacja JSON Schema?

Walidacja JSON Schema to proces sprawdzania, czy dokument JSON spełnia zestaw strukturalnych i wartościowych ograniczeń zdefiniowanych w JSON Schema. Sam schemat jest dokumentem JSON opisującym oczekiwaną strukturę danych: które właściwości są wymagane, jakie typy muszą mieć, dozwolone zakresy dla liczb, wzorce łańcuchów, długości tablic i wiele więcej. Specyfikacja JSON Schema jest utrzymywana na json-schema.org i publikowana jako seria projektów IETF — Draft 7 i Draft 2020-12 są najszerzej stosowane.

Zwykła walidacja JSON sprawdza jedynie składnię (czy nawiasy są prawidłowo zagnieżdżone? czy łańcuchy są ujęte w cudzysłów?). Walidacja schematu idzie dalej. Odpowiada na pytania: czy odpowiedź z tego API zawiera pole "id", które zawsze jest liczbą całkowitą? Czy pole "status" przyjmuje jedną z trzech dozwolonych wartości? Czy obiekty zagnieżdżone mają właściwą strukturę? Tego rodzaju weryfikacja strukturalna wychwytuje błędy, które całkowicie umykają sprawdzaniu składni — poprawny składniowo JSON może być semantycznie błędny dla Twojej aplikacji.

JSON Schema jest stosowany w definicjach OpenAPI/Swagger, walidacji plików konfiguracyjnych, walidacji formularzy, ograniczeniach dokumentów bazodanowych i testach automatycznych. Narzędzia takie jak Ajv (JavaScript), jsonschema (Python) i check-jsonschema (CLI) implementują specyfikację, umożliwiając programową walidację danych. Ten walidator online pozwala wkleić zarówno schemat, jak i dokument danych, aby natychmiast sprawdzić zgodność — bez instalowania żadnej biblioteki.

Dlaczego używać walidatora JSON Schema online?

Ręczne pisanie schematów i debugowanie błędów walidacji jest powolne. Walidator JSON Schema online daje natychmiastową informację zwrotną — czy dane pasują do schematu — z czytelnymi komunikatami błędów wskazującymi dokładnie, która właściwość nie spełnia wymagań.

Przypadki użycia walidacji JSON Schema

Słownik słów kluczowych JSON Schema

JSON Schema jest budowany ze słów kluczowych, z których każde nakłada ograniczenie na walidowane dane. Poniższa tabela zawiera najczęściej używane słowa kluczowe w Draft 7 i późniejszych wersjach. Każde słowo kluczowe można łączyć z innymi w tym samym obiekcie schematu.

Porównanie wersji JSON Schema: Draft 7 vs 2019-09 vs 2020-12

JSON Schema przeszło przez kilka wersji roboczych. Draft 7 (opublikowany w 2018 r.) jest najszerzej obsługiwany przez narzędzia. Draft 2019-09 wprowadził $defs (zastępując definitions), unevaluatedProperties i $recursiveRef. Draft 2020-12 (najnowsze stabilne wydanie) zastąpił $recursiveRef przez $dynamicRef i wprowadził prefixItems do walidacji krotek. Wybierając wersję, sprawdź, czy Twoja biblioteka walidacyjna ją obsługuje. Ajv obsługuje wszystkie trzy wersje. Biblioteka jsonschema dla Pythona obsługuje do 2020-12 od wersji 4.0.

Przykłady kodu

Poniższe przykłady pokazują, jak programowo walidować JSON względem schematu. Każdy używa dobrze utrzymywanej biblioteki dla danego ekosystemu języka.

import Ajv from 'ajv';

const ajv = new Ajv();

const schema = {
  type: 'object',
  properties: {
    name: { type: 'string', minLength: 1 },
    age: { type: 'integer', minimum: 0 },
    email: { type: 'string', format: 'email' }
  },
  required: ['name', 'email'],
  additionalProperties: false
};

const data = { name: 'Alice', age: 30, email: 'alice@example.com' };

const validate = ajv.compile(schema);
const valid = validate(data);
console.log(valid);          // → true
console.log(validate.errors); // → null

// Invalid data — missing required "email"
validate({ name: 'Bob', age: 25 });
console.log(validate.errors);
// → [{ instancePath: '', keyword: 'required', params: { missingProperty: 'email' } }]

from jsonschema import validate, ValidationError

schema = {
    "type": "object",
    "properties": {
        "name": {"type": "string", "minLength": 1},
        "age": {"type": "integer", "minimum": 0},
        "tags": {
            "type": "array",
            "items": {"type": "string"},
            "uniqueItems": True
        }
    },
    "required": ["name"]
}

# Valid data
validate(instance={"name": "Alice", "age": 30, "tags": ["admin"]}, schema=schema)
# → No exception raised

# Invalid data — wrong type for "age"
try:
    validate(instance={"name": "Alice", "age": "thirty"}, schema=schema)
except ValidationError as e:
    print(e.message)
    # → 'thirty' is not of type 'integer'
    print(e.json_path)
    # → $.age

package main

import (
    "fmt"
    "strings"
    "github.com/santhosh-tekuri/jsonschema/v5"
)

func main() {
    schemaJSON := `{
        "type": "object",
        "properties": {
            "id": { "type": "integer" },
            "status": { "enum": ["active", "inactive"] }
        },
        "required": ["id", "status"]
    }`

    compiler := jsonschema.NewCompiler()
    compiler.AddResource("schema.json", strings.NewReader(schemaJSON))
    schema, _ := compiler.Compile("schema.json")

    // Valid data
    data := map[string]interface{}{"id": 1, "status": "active"}
    err := schema.Validate(data)
    fmt.Println(err) // → <nil>

    // Invalid — missing "status"
    bad := map[string]interface{}{"id": 2}
    err = schema.Validate(bad)
    fmt.Println(err) // → validation failed: missing properties: 'status'
}

# Install via pip
pip install check-jsonschema

# Validate a file against a schema
check-jsonschema --schemafile schema.json data.json
# → ok -- validation done

# Validate against a remote schema (e.g., GitHub Actions workflow)
check-jsonschema --builtin-schema vendor.github-workflows my-workflow.yml

# Validate multiple files at once
check-jsonschema --schemafile schema.json file1.json file2.json file3.json

Często zadawane pytania