Walidator JSON

Co to jest walidacja JSON?

JSON (JavaScript Object Notation) to powszechnie stosowany, lekki format wymiany danych, zaprojektowany tak, aby był czytelny dla ludzi i łatwy do przetwarzania przez maszyny. Jego głównym celem jest przedstawianie danych strukturalnych — obiektów, tablic, łańcuchów znaków, liczb, wartości logicznych i null — w sposób niezależny od języka programowania.

Walidacja JSON to proces programowego weryfikowania, czy dokument JSON jest zarówno poprawny składniowo, jak i strukturalnie. Obejmuje to sprawdzenie dwóch głównych aspektów:

• Walidacja składniowa: Zapewnienie, że surowy tekst spełnia formalną gramatykę określoną przez specyfikację JSON ECMA-404. Parsery w większości nowoczesnych języków programowania (np. JSON.parse() w JavaScript, json.loads() w Pythonie, JSONDecoder w Javie) oczekują prawidłowej składni i zgłoszą błędy, jeśli dane wejściowe są niepoprawne.
• Walidacja strukturalna (schematyczna): Poza składnią, walidacja schematu sprawdza, czy dane JSON odpowiadają oczekiwanej strukturze, w tym typom danych, wymaganym właściwościom, ograniczeniom wartości oraz zagnieżdżonym obiektom/tablicom. Walidacja schematu jest zazwyczaj przeprowadzana za pomocą JSON Schema, które definiuje zasady określające, jakie dane są uznawane za poprawne.

Dlaczego warto walidować JSON?

Walidacja JSON jest kluczowa wszędzie tam, gdzie dane są serializowane do przesyłania, przechowywania lub komunikacji między usługami. Główne powody to:

• Zapobieganie błędom: Wykrywaj i zgłaszaj błędy składniowe (np. brakujące przecinki, niezamknięte nawiasy, niedozwolone znaki) na wczesnym etapie — zanim rozpoczniesz przetwarzanie danych.
• Integralność i bezpieczeństwo danych: Odrzucaj błędne lub złośliwe ładunki JSON, co pomaga zapobiegać awariom backendu, atakom typu injection oraz uszkodzeniom danych.
• Bezpieczeństwo typów: Wymuszaj ścisłe typowanie — na przykład zapewniając, że pole oczekiwane jako wartość logiczna nie jest przesyłane jako ciąg znaków, a identyfikatory UUID, adresy e-mail i numery mają odpowiedni format.
• Kompatybilność międzyjęzykowa: Gwarantuj, że JSON wygenerowany w jednym środowisku (np. Node.js) będzie bezpiecznie przetwarzany w innym (np. Python, Go, Java), eliminując błędy związane z serializacją/deserializacją.
• Utrzymywalność i odporność: Zweryfikowane struktury danych poprawiają możliwość śledzenia oraz zmniejszają ryzyko trudnych do zlokalizowania błędów w plikach konfiguracyjnych, logach i zapytaniach/odpowiedziach API.
• Prywatność i bezpieczeństwo: Walidacja może być przeprowadzana całkowicie po stronie klienta (w przeglądarce), co zapobiega przesyłaniu surowych lub wrażliwych danych z urządzenia użytkownika na potrzeby walidacji.

Typowe błędy walidacji JSON (z szczegółowymi przykładami)

Klucze bez cudzysłowów

Wszystkie klucze w obiektach JSON muszą być napisane jako łańcuchy znaków ujęte w podwójne cudzysłowy.

{ name: "Alice" }

{ "name": "Alice" }

Wiele formatów podobnych do JSON (np. literały obiektów w JavaScript) umożliwia używanie kluczy bez cudzysłowów, ale standardowy JSON tego nie pozwala.

Cudzysłowy pojedyncze

Łańcuchy JSON muszą używać wyłącznie podwójnych cudzysłowów; pojedyncze cudzysłowy są niedozwolone.

{ 'name': 'Bob' }

{ "name": "Bob" }

Używanie pojedynczych cudzysłowów spowoduje błędy analizatora we wszystkich zgodnych bibliotekach JSON.

Przecinki na końcu

Brak przecinka na końcu ostatniego elementu w obiekcie lub tablicy.

{
  "a": 1,
  "b": 2,
}

{
  "a": 1,
  "b": 2
}

Przecinki na końcu mogą działać w JavaScript, ale nie w ścisłych parserach JSON.

Nieprawidłowe ucieczkowanie znaków

Cudzysłowy i znaki specjalne w ciągach znaków muszą być poprzedzone znakiem odwrotnego ukośnika (backslash).

{ "quote": "Tom powiedział \"cześć\"" }

{ "quote": "Tom powiedział \"cześć\"" }

Inne sekwencje ucieczki to \\ dla ukośnika wstecznego, \n dla nowych linii oraz \t dla tabulatorów.

Nieprawidłowe typy danych

Ciągi znaków nie powinny być używane do reprezentowania liczb, wartości logicznych ani wartości null.

{ "enabled": "prawda", "count": "10" }

{ "enabled": true, "count": 10 }

JSON rozróżnia wartości logiczne, liczby i ciągi znaków — upewnij się, że używasz właściwego typu.

Klucze nieprymitywne

Klucze obiektu JSON muszą zawsze być ciągami znaków; nie można używać liczb, wartości logicznych ani innych typów jako kluczy.

{ 123: "abc" }

{ "123": "abc" }

Zduplikowane klucze

Chociaż zgodne ze specyfikacją JSON, powtarzające się klucze są częstym źródłem błędów.

{ "name": "Alice", "name": "Bob" }

Większość parserów zachowa tylko ostatnią wartość ("Bob"), cicho pomijając wcześniejsze.

Użycie komentarzy

Standardowy JSON nie pozwala na komentarze, mimo że niektóre edytory je obsługują.

{
  // Informacje o użytkowniku
  "name": "Alice"
}

{
  "name": "Alice"
}

Walidacja schematu: Wymuszanie struktury i typów danych

JSON Schema to potężny standard do definiowania i weryfikacji oczekiwanej struktury dokumentów JSON. Pozwala na określenie:

• Pola obowiązkowe (`required`)
• Typy danych (`type`: string, number, boolean, object, array, null)
• Formaty łańcuchów znaków (`format`: e-mail, uuid, data-czas, itp.)
• Dopasowywanie wzorców dla łańcuchów znaków (`pattern`)
• Zakresy liczb (`minimum`, `maksimum`)
• Walidacja długości tablicy i elementów (`minItems`, `maxItems`, `items`)
• Zagnieżdżona walidacja dla obiektów i tablic
• Ograniczenia wyliczeniowe (`enum`)

Przykład: Schemat użytkownika (Draft-07)

{
  "type": "obiekt",
  "properties": {
    "id":    { "type": "łańcuch", "format": "uuid" },
    "name":  { "type": "łańcuch", "minLength": 1 },
    "email": { "type": "łańcuch", "format": "email" },
    "is_active": { "type": "logiczna" }
  },
  "required": ["id", "name", "email"],
  "additionalProperties": false
}

Co to wymusza:

• id musi być poprawnym ciągiem znaków UUID.
• nazwa musi być niepustym tekstem.
• adres e-mail musi odpowiadać standardowemu formatowi adresu e-mail.
• is_active (opcjonalne) musi być wartością logiczną (boolean).
• Dozwolone są tylko właściwości zdefiniowane powyżej.

Przykład z życia: Walidacja odpowiedzi API Stripe

Załóżmy, że otrzymujesz odpowiedzi JSON z API Stripe (np. PaymentIntent). Walidacja schematu zapewnia, że nigdy nie przetworzysz danych niepełnych lub o niepoprawnym typie.

{
  "type": "object",
  "properties": {
    "id":      { "type": "string", "pattern": "^pi_" },
    "object":  { "type": "string", "const": "payment_intent" },
    "amount":  { "type": "integer", "minimum": 1 },
    "currency":{ "type": "string", "minLength": 3, "maxLength": 3 },
    "status":  { "type": "string", "enum": [
      "wymaga_metody_płatności",
      "wymaga_potwierdzenia",
      "w_toku",
      "zakończono_pomyślnie",
      "anulowano"
    ]}
  },
  "required": ["id", "object", "amount", "currency", "status"],
  "additionalProperties": false
}

• id musi zaczynać się od "pi_"
• obiekt musi zawsze być "payment_intent"
• ilość musi być liczbą całkowitą większą lub równą 1
• waluta musi być ciągiem trzech liter (np. "usd", "eur")
• status musi być jedną z określonych wartości

Korzyści

• Wczesne wykrywanie błędów: Zidentyfikuj krytyczne zmiany w API lub niekompletne dane zanim trafią do Twojej logiki biznesowej.
• Testowanie automatyczne: Wykorzystuj schematy w pipeline'ach CI/CD do walidacji rzeczywistych i symulowanych odpowiedzi.
• Spójność międzyzespołowa: Standaryzacja kontraktów danych pomiędzy frontendem, backendem i zewnętrznymi API.

Poprawna walidacja JSON — obejmująca zarówno składnię, jak i schemat — zapobiega trudnym do wykrycia błędom, wymusza najlepsze praktyki i zabezpiecza Twoje aplikacje przed błędnymi lub złośliwymi danymi wejściowymi. Niezależnie od tego, czy jest używana w plikach konfiguracyjnych, przesyłanych danych API czy komunikacji między usługami, solidna walidacja stanowi podstawę nowoczesnych systemów programistycznych.

Prywatność i Bezpieczeństwo

Wszystkie walidacje i sprawdzenia schematów są wykonywane lokalnie w Twojej przeglądarce. Żadne dane nie są przesyłane ani rejestrowane. Twój JSON pozostaje całkowicie prywatny.

Przykłady kodu do walidacji JSON

Dowiedz się, jak walidować JSON w różnych językach programowania, korzystając z wbudowanych bibliotek lub popularnych frameworków. Te przykłady pokazują zarówno walidację składni, jak i walidację schematu.

const jsonString = '{"name":"Alice","age":30}';
try {
  const obj = JSON.parse(jsonString);
  console.log("Valid JSON:", obj);
} catch (e) {
  console.error("Invalid JSON!", e.message);
}

const Ajv = require("ajv");
const ajv = new Ajv();
const schema = { type: "object", properties: { age: { type: "integer" } }, required: ["age"] };
const data = { age: 30 };
const validate = ajv.compile(schema);
console.log(validate(data) ? "Valid!" : ajv.errorsText(validate.errors));

import json
try:
    obj = json.loads('{"name":"Alice","age":30}')
    print("Valid JSON:", obj)
except json.JSONDecodeError as e:
    print("Invalid JSON:", e)

import json, jsonschema
schema = {
    "type": "object",
    "properties": { "age": { "type": "integer" } },
    "required": ["age"]
}
data = {"age": 30}
try:
    jsonschema.validate(data, schema)
    print("Valid!")
except jsonschema.ValidationError as e:
    print("Schema validation error:", e)

package main
import (
  "encoding/json"
  "fmt"
)
func main() {
  data := []byte(`{"name":"Alice","age":30}`)
  var obj map[string]interface{}
  if err := json.Unmarshal(data, &obj); err != nil {
    fmt.Println("Invalid JSON:", err)
  } else {
    fmt.Println("Valid JSON:", obj)
  }
}

import com.fasterxml.jackson.databind.ObjectMapper;
public class Main {
  public static void main(String[] args) {
    String json = "{"name":"Alice","age":30}";
    try {
      Object obj = new ObjectMapper().readTree(json);
      System.out.println("Valid JSON: " + obj);
    } catch (Exception e) {
      System.out.println("Invalid JSON: " + e.getMessage());
    }
  }
}

using System;
using System.Text.Json;
class Program {
  static void Main() {
    string json = "{"name":"Alice","age":30}";
    try {
      var doc = JsonDocument.Parse(json);
      Console.WriteLine("Valid JSON!");
    } catch (JsonException e) {
      Console.WriteLine("Invalid JSON: " + e.Message);
    }
  }
}

<?php
$json = '{"name":"Alice","age":30}';
$obj = json_decode($json);
if (json_last_error() === JSON_ERROR_NONE) {
  echo "Valid JSON";
} else {
  echo "Invalid JSON: " . json_last_error_msg();
}

require 'json'
begin
  obj = JSON.parse('{"name":"Alice","age":30}')
  puts "Valid JSON!"
rescue JSON::ParserError => e
  puts "Invalid JSON: #{e.message}"
end

echo '{"name":"Alice","age":30}' | jq empty && echo "Valid" || echo "Invalid"

fn main() {
  let data = r#"{"name":"Alice","age":30}"#;
  match serde_json::from_str::<serde_json::Value>(data) {
    Ok(_) => println!("Valid JSON!"),
    Err(e) => println!("Invalid JSON: {}", e),
  }
}

import org.json.JSONObject
fun main() {
  try {
    val obj = JSONObject("{\"name\":\"Alice\",\"age\":30}")
    println("Valid JSON: $obj")
  } catch (e: Exception) {
    println("Invalid JSON: ${e.message}")
  }
}

import Foundation
let json = "{\"name\":\"Alice\",\"age\":30}"
if let data = json.data(using: .utf8) {
  do {
    let _ = try JSONSerialization.jsonObject(with: data)
    print("Valid JSON!")
  } catch {
    print("Invalid JSON: \(error)")
  }
}

const jsonString = '{"name":"Alice","age":30}';
try {
  const obj = JSON.parse(jsonString);
  console.log("Valid JSON:", obj);
} catch (e) {
  console.error("Invalid JSON!", e.message);
}

SELECT '{"name":"Alice","age":30}'::jsonb; -- Will error if not valid JSON

SELECT JSON_VALID('{"name":"Alice","age":30}');

$json = '{"name":"Alice","age":30}'
try {
  $obj = $json | ConvertFrom-Json
  Write-Output "Valid JSON!"
} catch {
  Write-Output "Invalid JSON: $($_.Exception.Message)"
}

use JSON;
my $str = '{"name":"Alice","age":30}';
eval { decode_json($str) };
print $@ ? "Invalid JSON: $@" : "Valid JSON!";

import 'dart:convert';
void main() {
  const jsonString = '{"name":"Alice","age":30}';
  try {
    final obj = jsonDecode(jsonString);
    print('Valid JSON: $obj');
  } catch (e) {
    print('Invalid JSON: $e');
  }
}

json = ~s({"name":"Alice","age":30})
case Jason.decode(json) do
  {:ok, _} -> IO.puts("Valid JSON!")
  {:error, err} -> IO.puts("Invalid JSON: #{err}")
end

import play.api.libs.json._
object Main extends App {
  val str = """{"name":"Alice","age":30}"""
  try {
    val json = Json.parse(str)
    println("Valid JSON!")
  } catch {
    case e: Exception => println("Invalid JSON: " + e.getMessage)
  }
}

O tym narzędziu