JSON validasiyası: JSON Schema, validasiya xətaları

1. JSON validasiyası nə üçün lazımdır

Təsəvvür edək: siz User sinfini yazmısınız və girişə hər zaman belə bir JSON gələcəyini gözləyirsiniz:

{
  "id": 42,
  "name": "Alice",
  "email": "alice@example.com"
}

Amma birdən-birə sizə belə bir şey gəlir:

{
  "id": "qırx iki",
  "name": 123,
  "email": null,
  "admin": true
}

Yaxud ümumiyyətlə belə:

{
  "username": "Alice"
}

Ən yaxşı halda Jackson və ya Gson deserializasiya zamanı istisna atacaq. Ən pis halda — sahələrə susqun şəkildə ilkin dəyərlər təyin olunacaq və biznes-kodunuz düzgün işləməyəcək. Əgər bu, servisiniz üçün konfiqurasiya faylıdırsa — sonra bütün komanda ilə axtaracağınız xoşagəlməz buglara yol aça bilər.

JSON validasiyası — JSON-da strukturun, tiplərin və dəyərlərin müəyyən qaydalara (sxemaya) uyğun olmasını yoxlama prosesidir. Bu, məlumatlar üçün pasport nəzarəti kimidir: keçməyən — borta buraxılmır!

2. JSON Schema: nədir və necə görünür

JSON dünyasında məlumat strukturunu təsvir edən rəsmi standart — JSON Schema var. Bu, proqramınızın tələblərinə JSON-un uyğun gəlib-gəlmədiyini yoxlamaq üçün bir «yoxlama siyahısıdır».

JSON Schema — bu da JSON-dur, sadəcə xüsusi açarlarla: type, properties, required və sair.

Ən sadə sxema nümunəsi

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id":    { "type": "integer" },
    "name":  { "type": "string" },
    "email": { "type": "string", "format": "email" }
  },
  "required": ["id", "name"]
}

Burada nə baş verir:

• Obyekt gözlənilir (type: "object").
• Obyektin "id", "name", "email" sahələri ola bilər (properties-də təsvir olunur).
• "id" — mütləq tam ədəddir (type: "integer").
• "name" — mütləq sətirdir (type: "string").
• "email" — email kimi görünən sətirdir (format açarı "email" dəyəri ilə).
• required vacib sahələrin siyahısını göstərir: "id" və "name".

JSON-da "id" və ya "name" olmasa, yaxud onların tipi uyğun gəlməsə — validasiya keçməyəcək.

JSON Schema imkanları qısa

• Tipin göstərilməsi (type: "string", "integer", "array", "object", "boolean", "null").
• Yerləşmiş obyekt və massivin təsviri (properties, items).
• Vacib və qeyri-vacib sahələr (required).
• Sətir uzunluğunun, ədəd diapazonunun yoxlanması (minLength, maximum və b.).
• Formatın yoxlanması (format: "email", "date", "uri" və b.).
• Enumerasiyalar (enum: icazə verilən dəyərlərin siyahısı).
• Sətirlər üçün müntəzəm ifadələr (pattern).
• Mürəkkəb şərtlər: anyOf, oneOf, allOf (irəliləmiş hallara).

3. Java-da JSON validasiyası: kitabxanalara icmal

Java-nın standart kitabxanasına sxema üzrə JSON validasiyası daxil deyil. Ancaq populyar üçüncü tərəf kitabxanaları var. Ən məşhurları:

• everit-org/json-schema — sadə, pulsuz və populyar.
• networknt/json-schema-validator — sürətlidir, son standartları dəstəkləyir.
• Jackson-module-jsonSchema — Jackson üçün genişlənmədir (amma tamhüquqlu validasiyanı dəstəkləmir).
• Justify, Java JSON Tools — başqaları da var, amma daha az rast gəlinir.

Bu mühazirədə everit-org/json-schema-ya baxacağıq — o, yeni başlayanlar üçün sadədir, yaxşı sənədləşdirilib və əlavə çətinlik tələb etmir.

everit-org/json-schema quraşdırılması

Asılılığı pom.xml-inizə əlavə edin (Maven):

<dependency>
  <groupId>org.everit.json</groupId>
  <artifactId>org.everit.json.schema</artifactId>
  <version>1.14.2</version>
</dependency>

Yaxud Gradle ilə:

implementation 'org.everit.json:org.everit.json.schema:1.14.2'

4. Nümunə: sxema üzrə JSON validasiyası (addım-addım)

Gəlin JSON-u praktikada yoxlayaq. Bunun üçün bizə sxemanın özü, JSON və bir az kod lazımdır.

Sxema nümunəsi (user-schema.json):

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id":    { "type": "integer" },
    "name":  { "type": "string", "minLength": 2, "maxLength": 30 },
    "email": { "type": "string", "format": "email" }
  },
  "required": ["id", "name"]
}

Keçərli JSON nümunəsi (user.json):

{
  "id": 1,
  "name": "Alice",
  "email": "alice@example.com"
}

Keçərsiz JSON nümunəsi:

{
  "id": "bir",
  "name": "",
  "email": "not-an-email"
}

Validasiya üçün kod

import org.everit.json.schema.Schema;
import org.everit.json.schema.loader.SchemaLoader;
import org.json.JSONObject;
import org.json.JSONException;
import org.json.JSONTokener;
import org.everit.json.schema.ValidationException;

import java.nio.file.Files;
import java.nio.file.Paths;

public class JsonValidationExample {
    public static void main(String[] args) throws Exception {
        // Sxemanın fayldan yüklənməsi
        String schemaString = new String(Files.readAllBytes(Paths.get("user-schema.json")));
        JSONObject rawSchema = new JSONObject(new JSONTokener(schemaString));
        Schema schema = SchemaLoader.load(rawSchema);

        // Yoxlama üçün JSON-un yüklənməsi
        String jsonString = new String(Files.readAllBytes(Paths.get("user.json")));
        JSONObject json = new JSONObject(new JSONTokener(jsonString));

        // Validasiya
        try {
            schema.validate(json); // Hər şey qaydasındadırsa — heç nə baş verməyəcək
            System.out.println("JSON keçərlidir!");
        } catch (ValidationException e) {
            System.out.println("JSON keçərli deyil!");
            for (String msg : e.getAllMessages()) {
                System.out.println("Xəta: " + msg);
            }
        }
    }
}

Koda şərhlər:

• Schema sinfi və SchemaLoader.load(...) yükləyicisi istifadə olunur.
• schema.validate(json) metodu sxemaya uyğunluq olmadıqda istisna atır.
• catch blokunda bütün xətaları getAllMessages() vasitəsilə əldə edə bilərsiniz.

Bunu tətbiqə necə inteqrasiya etmək olar?

Adətən sxema resurslarda saxlanılır (məsələn, resources qovluğunda). Siz JSON-u Java obyektinə deserializasiyadan əvvəl yoxlayırsınız. Hər şey qaydasındadırsa — deserializasiya edir və işə davam edirsiniz.

5. Validasiya xətalarının işlənməsi

JSON yoxlamadan keçmədikdə, kitabxana ValidationException istisnasını atır. Mesajda xətaların siyahısı olur: nəyin dəqiq olaraq sxemaya uyğun gəlmədiyi göstərilir.

Xətaların çıxış nümunəsi

Yuxarıdakı keçərsiz JSON üçün çıxış təxminən belə olacaq:

JSON keçərli deyil!
Xəta: #: required key [id] not found
Xəta: #/name: expected minLength: 2, actual: 0
Xəta: #/email: String [not-an-email] is invalid against requested format [email]
Xəta: #/id: expected type: Integer, found: String

Xətaları necə şərh etmək olar:

• required key [id] not found — vacib sahə yoxdur.
• expected minLength: 2, actual: 0 — sətir çox qısadır.
• String [...] is invalid against requested format [email] — email düzgün deyil.
• expected type: Integer, found: String — tip uyğun gəlmir.

Vacibdir! Mesajlar ingiliscə ola bilər, amma kifayət qədər anlaşıqlıdır.

Xətaları istifadəçiyə necə göstərmək olar?

Xətaları siyahı şəklində toplayıb istifadəçiyə ötürə bilərsiniz, məsələn, REST API və ya GUI vasitəsilə. Bu, giriş məlumatlarında nəyin düzgün olmadığını tez anlamağa kömək edəcək.

6. Təcrübə: obyektlər massivinin validasiyası

Tez-tez tək obyekt yox, massiv yoxlamaq lazım olur:

[
  { "id": 1, "name": "Alice", "email": "alice@example.com" },
  { "id": 2, "name": "Bob" },
  { "id": "bu nədir?", "name": 123, "email": "not-an-email" }
]

Sxema:

{
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "id":    { "type": "integer" },
      "name":  { "type": "string", "minLength": 2, "maxLength": 30 },
      "email": { "type": "string", "format": "email" }
    },
    "required": ["id", "name"]
  }
}

Validasiya eyni qaydada işləyir, sadəcə JSON kimi massiv ötürürük. Xətalarda problem olan elementlərin indeksləri göstəriləcək (məsələn, [#/2/id]).

7. JSON validasiyasında tipik xətalar

Xəta №1: Məlumat tiplərinin uyğun gəlməməsi. Çox vaxt ədəd əvəzinə sətir gəlir ("id": "123"), halbuki sxema integer gözləyir. Validasiya keçməyəcək. Məlumat mənbəyinə nəzarət etmirsinizsə — ya sxemanı uyğunlaşdırın, ya da məlumatları öncədən konvertasiya edin.

Xəta №2: Vacib sahələrin olmaması. Əgər sxemada sahə vacib göstərilibsə ("required": ["id","name"]), JSON-da o yoxdursa — xəta alacaqsınız. Bəzən bu gözlənilməz olur: frontend sahəni göndərməyi unudur və ya API dəyişir.

Xəta №3: JSON-da artıq sahələr. Susmaya görə JSON Schema artıq sahələrə icazə verir. Sərt sxema istəyirsinizsə, "additionalProperties": false əlavə etməyi unutmayın. Olmasa, JSON-da istənilən «kənar» sahələr ola bilər.

Xəta №4: Sxemanın səhv versiyası və ya sintaksisi. Sxemanızın versiyasında olmayan açarlardan istifadə etsəniz və ya yazı səhvləri etsəniz, validator sxemanı yükləyə bilməyəcək. Sxemanı https://www.jsonschemavalidator.net/ və ya oxşar servislərdə yoxlayın.

Xəta №5: Xətaların zəif işlənməsi. Təkcə ilk istisnanı tutub istifadəçiyə detalları göstərməsəniz, JSON-da nəyin düzgün olmadığını anlamaq çətin olacaq. Bütün xətaları göstərmək üçün getAllMessages()-dən istifadə edin.

Xəta №6: Həddindən artıq sərt formatlar. "format" yoxlaması: "email" və ya "date" bəzən kifayət qədər «səthi» olur. Sərt validasiya lazımdırsa, kodda əlavə yoxlamalardan istifadə edin.