Validasiya JSON və JSON Schema

1. Giriş

Beləliklə, siz artıq obyektləri JSON-a (və əksinə) çevirməyi bilirsiniz. Amma proqramınıza qəribə nəsə düşsə nə etmək lazımdır? Məsələn, belə bir JSON gözləyirdiniz:

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

Amma gəldi:

{
  "name": 42,
  "id": "not a number"
}

Bəli, C# serializatorları bu xaosu deserializasiya etməyə çalışacaq, amma tez-tez bu runtime xətalara, məlumat itkisinə və ya hətta işin darmadağın olmasına gətirib çıxarır. Məlumatları irəli göndərmədən, bazaya saxlamadan və ya şəbəkə ilə ötürmədən əvvəl məlumatların düzgün olduğunu yoxlayın — yoxsa kodunuz sanki təhlükəsizliyi olmayan akrobat kimidir.

Buna görə validasiya lazımdır: bu avtomatlaşdırılmış yoxlamadır ki, JSON qaydalara uyğun gəlir — dəyərlərin tipləri, sahələrin məcburluğu, diapazonlar, struktur və s.

2. JSON-u validasiya etməyin yolları hansılardır?

C# və .NET-də üç əsas yanaşma var:

• Xüsusi kodla validasiya: obyektləri əl ilə parse edirsiniz, yoxlamalar yazırsınız və səhvlərdə exception atırsınız.
• Modeldə validation atributları: məsələn, [Required], [Range], [EmailAddress] kimi atributlar System.ComponentModel.DataAnnotations ad sahəsindən.
• JSON Schema vasitəsilə validasiya — bu günümüzün qəhrəmanıdır!

JSON Schema — bu, sənədin necə olmalı olduğunu formal şəkildə təsvir etməyə imkan verən standartdır. Sxema özü də JSON-dır. Siz hansı sahələrin lazım olduğunu, hansı tiplərin gözlənildiyini, hansı dəyərlərin qəbul ediləcəyini və s. təyin edirsiniz.

Sxemalarla siz aşağıdakılar təsvir edə bilərsiniz:

• Hansı sahələrin mövcud olmalı olduğunu.
• Hansı tiplərin gözləndiyini (string, array, number, object ...).
• Hansı sahələrin məcburi, hansıların könüllü olduğunu.
• Dəyərlərin diapazonları (məsələn, yaş 0-dan 150-ə qədər).
• Maskalar, ölçülər, dəyər siyahıları və s.

Ən sadə sxema nümunəsi

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

3. JSON Schema-nın əsas elementləri

Gəlin nümunələrlə əsas açarların nə demək olduğunu anlayaq.

$schema

"https://json-schema.org/draft/2020-12/schema"

type

"type": "object"

properties

"properties": { ... }

required

"required": ["id"]

items

"items": { ... }

enum

"enum": ["A", "B"]

minimum

maximum

"minimum": 0

minLength

maxLength

"minLength": 3

pattern

"pattern": "^[a-zA-Z]+$"

Vizual: insanların array-ı üçün sxema nümunəsi

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

4. C#-də JSON-u sxemaya qarşı necə yoxlamaq olar

.NET-də JSON Schema-nın standart dəstəyi yoxdur (hazırki vəziyyətə görə .NET 9). Praktikada xarici kitabxanalardan istifadə olunur: NJsonSchema və Newtonsoft.Json.Schema (Json.NET Schema).

Newtonsoft.Json.Schema paketinin quraşdırılması

Layihə qovluğunda terminalda icra edin:

dotnet add package Newtonsoft.Json.Schema

Vacib: Newtonsoft.Json.Schema — kommersiya kitabxanasıdır (nokommersiya məqsədlər üçün pulsuzdur). Pet-proyektlər üçün ideal uyğun gəlir.

Sxemaya uyğunluğun yoxlanılması nümunəsi

using Newtonsoft.Json.Linq;
using Newtonsoft.Json.Schema;

string schemaJson = @"{
  'type': 'object',
  'properties': {
    'id':    { 'type': 'integer' },
    'name':  { 'type': 'string' },
    'email': { 'type': 'string', 'format': 'email' }
  },
  'required': ['id', 'name']
}";

// Tutaq ki, belə bir JSON var
string json = @"{
  'id': 123,
  'name': 'Alice',
  'email': 'alice@example.com'
}";

// Əvvəlcə sxemani parse edirik
JSchema schema = JSchema.Parse(schemaJson);

// JSON-u JToken-ə parse edirik
JToken jsonObj = JToken.Parse(json);

// JSON-un sxemaya uyğun olub-olmadığını yoxlayırıq
bool valid = jsonObj.IsValid(schema, out IList<string> errors);

if (valid)
{
    Console.WriteLine("JSON etibarlıdır!");
}
else
{
    Console.WriteLine("JSON ETİBARLİ DEYİL!");
    foreach (var error in errors)
        Console.WriteLine(error);
}

JSON yoxlamasını tətbiqdə necə istifadə etmək olar?

Adətən: əvvəlcə validasiya (IsValid), sonra deserializasiya (JsonConvert.DeserializeObject<T>) və yalnız bundan sonra — biznes-logic. Bu zibil məlumatlarını erkən mərhələdə kəsir.

if (jsonObj.IsValid(schema))
{
    // Hər şey qaydasındadır, deserializasiya etmək olar
    var person = JsonConvert.DeserializeObject<Person>(json);
}
else
{
    // Emalı dayandır! Məlumatlar düzgün deyil.
}

5. JSON Schema-nı real həyatda tətbiqi

Validasiya nə vaxt lazım olur?

• API vasitəsilə məlumat alınanda (xüsusən xarici sistemlərdən və müxtəlif klientlərdən).
• Microservice-lər və bazalar arasında məlumat miqrasiyasında.
• UI-formların generasiyasında və avtomatik doldurmada, əgər forma sxemaya əsasən qurulursa.
• Müsahibələrdə: "əgər səhv JSON gəlsə?" sualı tez-tez verilir.

Maraqlı məqam meraklılar üçün

• Format yoxlamaları: "format": "email", "date-time".
• Birgə qaydalar: anyOf, oneOf, allOf.
• Daxili obyektlər və array-lərin validasiyası.
• Sxemaların öz ehtiyaclarına uyğun genişləndirilməsi.

6. Böyük praktik nümunə

Giriş məlumatları (istifadəçilər siyahısı):

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

Sxema:

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

.NET-də yoxlama:

string jsonArray = @"[ ... ]"; // yuxarıya bax
string schemaJson = @"{ ... }"; // yuxarıya bax

JSchema schema = JSchema.Parse(schemaJson);
JToken arrayToken = JToken.Parse(jsonArray);

bool isValid = arrayToken.IsValid(schema, out IList<string> errs);
if (!isValid)
{
    foreach (var error in errs)
        Console.WriteLine(error);
    // Mesaj nümunələri:
    // "String 'chto eto?' is not a valid integer."
    // "Integer 123 is not a valid string."
    // "String 'not-an-email' is not a valid email address."
}

7. JSON sxemaları ilə işləyərkən tipik səhvlər

Səhv №1: sxema ilə aktual məlumatların uyğunsuzluğu. Model dəyişəndən sonra sxemanı yeniləməyi unudurlar. Validasiya ya səhvləri buraxır, ya da düzgün məlumatları bloklayır.

Səhv №2: sxemadakı və modeldəki tiplərin fərqi. Modeldə sahənin tipi dəyişib (məsələn, id string oldu), amma sxemada hələ də integer qalıb — validator şikayət etməyə başlayacaq.

Səhv №3: biznes üçün vacib sahələrin olmaması. Sahə məcburi kimi işarələnməsə belə, biznes-logic ona güvənə bilər — olmaması uğursuzluğa gətirər.

Səhv №4: məlumat formatının düzgün olmaması. string tipli email və ya tarix sahəsi "sətir" kimi görünə bilər, amma valid deyil. format və/və ya əlavə yoxlamalardan istifadə edin.

Səhv №5: kitabxananın standartdan geri qalması. Standart inkişaf edir, amma kitabxanalar həmişə ona uyğunlaşmır. Bəzi yoxlamalar olmaya və ya fərqli işləyə bilər.

2

Tapşırıq

C# SELF, səviyyə, dərs

Bağlanıb

JSON Schema ilə obyektlər massivi

JSON Schema ilə obyektlər massivi

Açıq

1

Sorğu/viktorina

, səviyyə, dərs

Əlçatan deyil

JSON-məlumatlarla işləmək

JSON-un sintaksisi və strukturu üzrə əsaslar

Açıq