مدقق JSON

ما هو التحقق من صحة JSON؟

JSON (ترميز كائنات جافا سكريبت) هو تنسيق تبادل بيانات خفيف الوزن وشائع الاستخدام، تم تصميمه ليكون قابلًا للقراءة البشرية وسهل التحليل والتوليد بواسطة الآلات. الغرض الأساسي منه هو تمثيل البيانات المهيكلة—مثل الكائنات، والمصفوفات، والسلاسل النصية، والأرقام، والقيم المنطقية، والقيم الفارغة—بطريقة غير مرتبطة بلغة برمجة معينة.

التحقق من صحة JSON هو عملية التحقق البرمجي من أن وثيقة JSON صحيحة من الناحيتين التركيبية والهيكلية. يشمل ذلك فحص جانبين رئيسيين:

• التحقق النحوي: ضمان أن النص الخام يتبع القواعد النحوية الرسمية كما هو محدد في مواصفة ECMA-404 لـ JSON. تتوقع أدوات التحليل في معظم لغات البرمجة الحديثة (مثل JSON.parse() في جافا سكريبت، json.loads() في بايثون، و JSONDecoder في جافا) وجود صيغة صحيحة، وستقوم بإظهار أخطاء إذا كان الإدخال غير صحيح التنسيق.
• التحقق الهيكلي (السكريما): تتجاوز عملية التحقق من البنية الصياغية (Syntax) فحص تطابق بيانات JSON مع الهيكل المتوقع، بما في ذلك أنواع البيانات والخصائص المطلوبة وقيود القيم والكائنات/المصفوفات المتداخلة. يتم عادةً إجراء التحقق من المخطط (Schema Validation) باستخدام JSON Schema، الذي يحدد قواعد البيانات الصحيحة والمعتمدة.

لماذا التحقق من صحة JSON؟

التحقق من صحة JSON أمر بالغ الأهمية في كل مكان يتم فيه تسلسل البيانات للإرسال، أو التخزين، أو التواصل بين الخدمات. الأسباب الرئيسية تشمل:

• منع الأخطاء: اكتشف وأفِد عن أخطاء النظام اللغوي (مثل الفواصل المفقودة، الأقواس غير المتطابقة، الأحرف غير القانونية) مبكرًا — قبل محاولة معالجة البيانات.
• سلامة البيانات والأمان: رفض حمولات JSON غير الصحيحة أو الخبيثة، مما يساعد في منع تعطل الخادم الخلفي، وهجمات الحقن، أو تلف البيانات.
• سلامة الأنواع: فرض نوعية صارمة—ضمان، على سبيل المثال، أن الحقل المتوقع أن يكون منطقيًا (boolean) لا يُرسل كسلسلة نصية، أو أن معرّفات UUID، والبريد الإلكتروني، والأرقام تتبع الصيغة الصحيحة.
• التوافق عبر اللغات البرمجية: ضمان أن يكون ملف JSON المُنتَج في بيئة واحدة (مثل Node.js) قابلًا للاستخدام بأمان في بيئة أخرى (مثل Python أو Go أو Java)، مع تجنب أخطاء التسلسل وفك التسلسل.
• الصيانة والصلابة: تحسين هياكل البيانات المُحقّقة يُعزّز إمكانية التتبع ويقلل من خطر الأخطاء الصعبة في ملفات التكوين، والسجلات، أو طلبات/استجابات واجهة برمجة التطبيقات.
• الخصوصية والأمان: يمكن إجراء التحقق بالكامل على جهاز العميل (داخل المتصفح)، مما يمنع خروج البيانات الخام أو الحساسة من جهاز المستخدم أثناء عملية التحقق.

أخطاء شائعة في التحقق من صحة JSON (مع أمثلة مفصلة)

مفاتيح غير محاطة بعلامات اقتباس

يجب أن تكون جميع المفاتيح في كائنات JSON عبارة عن سلاسل نصية محاطة بعلامتي اقتباس مزدوجتين.

{ name: "أليس" }

{ "name": "أليس" }

تسمح العديد من التنسيقات المشابهة لـ JSON (مثل كائنات جافا سكريبت) باستخدام المفاتيح بدون علامات اقتباس، ولكن JSON القياسي لا يدعم ذلك.

علامات الاقتباس المفردة

يجب استخدام علامات الاقتباس المزدوجة فقط في سلاسل JSON؛ علامات الاقتباس المفردة غير مسموح بها.

{ 'name': 'بوب' }

{ "name": "بوب" }

استخدام علامات الاقتباس الفردية سيؤدي إلى أخطاء في محلل النحو في جميع مكتبات JSON المتوافقة.

الفواصل الأخيرة

عدم وجود فاصلة منقوطة زائدة بعد العنصر الأخير في الكائن أو المصفوفة.

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

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

قد تعمل الفواصل الزائدة في جافا سكريبت، لكنها لا تُقبل في محللات JSON الصارمة.

الهروب غير الصحيح للأحرف

يجب أن تُهرب علامات الاقتباس والحروف الخاصة داخل السلاسل النصية باستخدام الشرطة المائلة العكسية (Backslash).

{ "quote": "قال توم \"مرحباً\"" }

{ "quote": "قال توم \"مرحباً\"" }

تتضمن سلاسل الهروب الأخرى \\ للفاصل العكسي، \n للأسطر الجديدة، و\t للجداول.

أنواع بيانات غير صحيحة

يجب عدم استخدام السلاسل النصية للأرقام أو القيم المنطقية (صح/خطأ) أو القيم الفارغة (null).

{ "enabled": "صحيح", "count": "10" }

{ "مفعل": true, "عدد": 10 }

يتميّز JSON بالتمييز بين القيم المنطقية (booleans) والأعداد والنصوص — تأكد من استخدام النوع الصحيح.

مفاتيح غير أولية

يجب أن تكون مفاتيح كائن JSON دائمًا من نوع النصوص؛ لا يمكنك استخدام الأرقام أو القيم المنطقية أو أنواع أخرى كمفاتيح.

{ 123: "ابج" }

{ "123": "أبجد" }

مفاتيح مكررة

على الرغم من سماح مواصفة JSON بذلك، إلا أن المفاتيح المكررة تُعد من المصادر الشائعة للأخطاء البرمجية.

{ "name": "أليس", "name": "بوب" }

معظم المحللات ستحتفظ فقط بالقيمة الأخيرة ("بوب")، متجاهلةً القيم السابقة بدون إظهار أي تحذير.

استخدام التعليقات

الـ JSON القياسي لا يسمح بالتعليقات، رغم أن بعض المحررين يدعمونها.

{
  // معلومات المستخدم
  "name": "أليس"
}

{
  "name": "أليس"
}

التحقق من الصحة باستخدام المخطط: تطبيق الهيكل وأنواع البيانات

يُعد JSON Schema معيارًا قويًا لتعريف والتحقق من هيكل مستندات JSON المتوقعة. يتيح لك تحديد:

• الحقول المطلوبة (`required`)
• أنواع البيانات (`type`: نص، رقم، منطقية، كائن، مصفوفة، فارغ)
• صياغات السلاسل النصية (`format`: البريد الإلكتروني، معرّف UUID، التاريخ والوقت، إلخ.)
• مطابقة الأنماط للنصوص (`pattern`)
• نطاقات الأرقام (`الحد الأدنى`, `الحد الأقصى`)
• التحقق من طول المصفوفة والعناصر (`minItems`، `maxItems`، `items`)
• التحقق المتداخل للأشياء والمصفوفات
• قيود التعداد (`enum`)

مثال: مخطط المستخدم (مسودة-07)

{
  "type": "كائن",
  "properties": {
    "id":    { "type": "سلسلة نصية", "format": "uuid" },
    "name":  { "type": "سلسلة نصية", "minLength": 1 },
    "email": { "type": "سلسلة نصية", "format": "البريد الإلكتروني" },
    "is_active": { "type": "منطقي" }
  },
  "required": ["id", "name", "email"],
  "additionalProperties": false
}

ما يفرضه هذا:

• يجب أن يكون المعرف سلسلة UUID صحيحة.
• يجب أن يكون الاسم نصًا غير فارغ.
• يجب أن يكون البريد الإلكتروني مطابقًا للتنسيق القياسي للبريد الإلكتروني.
• is_active (اختياري) يجب أن يكون قيمة منطقية (صح أو خطأ).
• لا يُسمح بأي خصائص غير تلك المعرفة أعلاه.

مثال عملي: التحقق من صحة استجابات واجهة برمجة تطبيقات Stripe

افترض أنك تتلقى استجابات JSON من واجهة برمجة تطبيقات Stripe (مثل PaymentIntent). يمكن للتحقق من صحة المخطط ضمان عدم معالجة بيانات غير مكتملة أو ذات نوع خاطئ أبدًا.

{
  "type": "كائن",
  "properties": {
    "id":      { "type": "نص", "pattern": "^pi_" },
    "object":  { "type": "نص", "const": "نية_الدفع" },
    "amount":  { "type": "عدد صحيح", "minimum": 1 },
    "currency":{ "type": "نص", "minLength": 3, "maxLength": 3 },
    "status":  { "type": "نص", "enum": [
      "يتطلب_طريقة_الدفع",
      "يتطلب_تأكيد",
      "قيد_المعالجة",
      "ناجح",
      "ملغي"
    ]}
  },
  "required": ["id", "object", "amount", "currency", "status"],
  "additionalProperties": false
}

• يجب أن يبدأ المُعرف بـ "pi_"
• يجب أن يكون الكائن دائمًا "payment_intent"
• يجب أن يكون المبلغ عددًا صحيحًا أكبر من أو يساوي 1
• يجب أن تكون العملة سلسلة مكونة من ثلاثة أحرف (مثل، "usd"، "eur")
• يجب أن تكون الحالة من القيم المحددة

الفوائد

• اكتشاف الأخطاء المبكر: كشف تغييرات API الهامة أو البيانات الناقصة قبل وصولها إلى منطق عملك.
• الاختبار الآلي: استخدم المخططات في خطوط تكامل ونشر مستمرة (CI/CD) للتحقق من صحة الاستجابات الحقيقية والمزيفة.
• التناسق بين الفرق: توحيد عقود البيانات بين الواجهة الأمامية، الواجهة الخلفية، وواجهات برمجة التطبيقات الخارجية.

التحقق الصحيح من صحة JSON — بما يشمل كل من الصياغة والمخطط — يمنع الأخطاء الخفية، ويعزز أفضل الممارسات، ويحمي تطبيقاتك من المدخلات المغلوطة أو الضارة. سواء أُستخدم في ملفات التهيئة، أو حمولة واجهات البرمجة (API)، أو رسائل بين الخدمات، فإن التحقق القوي هو أساس أنظمة البرمجيات الحديثة.

الخصوصية والأمان

تتم جميع عمليات التحقق من الصحة وصلاحية المخطط محليًا في متصفحك. لا يتم رفع أو تسجيل أي بيانات. تبقى بيانات JSON الخاصة بك خاصة تمامًا.

أمثلة تعليمية للتحقق من صحة JSON

اكتشف كيفية التحقق من صحة JSON في لغات البرمجة المختلفة باستخدام المكتبات المدمجة أو الأُطُر الشهيرة. توضح هذه الأمثلة التحقق من صحة البنية النحوية وكذلك التحقق من صحة المخطط، مما يضمن دقة وسلامة بيانات JSON.

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)
  }
}

حول هذه الأداة