Cập Nhật JSON Schema: Người Bạn Mới Của Dữ Liệu 🛡️

Giới thiệu

Bạn đã bao giờ gặp phải tình huống mà API của bạn trả về { age: "twenty-five" } thay vì { age: 25 } và toàn bộ ứng dụng của bạn bị sập? Đúng vậy, ai cũng đã trải qua điều đó. Hãy cùng nói về JSON Schema – người bạn mới của bạn trong cuộc chiến chống lại dữ liệu không ổn định.

JSON Schema là gì? Đó là một hợp đồng cho dữ liệu JSON của bạn, giống như định nghĩa kiểu của TypeScript nhưng dành cho việc xác thực tại thời gian chạy. Nó nói với dữ liệu của bạn: "Này, bạn phải trông giống như thế này, nếu không, chúng ta sẽ gặp rắc rối."

JSON Schema Là Gì?

Khái niệm này xuất hiện vào khoảng năm 2009-2010 khi các nhà phát triển cảm thấy mệt mỏi vì phải viết logic xác thực tùy chỉnh cho từng endpoint API. Một người thông minh đã nói: "Sao chúng ta không mô tả cấu trúc dữ liệu của mình bằng... nhiều JSON hơn?" Và thế là JSON Schema đã ra đời.

Cấu Trúc Cơ Bản Của JSON Schema

Hãy cùng phân tích những gì tạo nên một schema:

const userSchema = {
  type: "object",
  properties: {
    name: { type: "string", minLength: 1, maxLength: 100 },
    age: { type: "number", minimum: 0, maximum: 150 },
    email: { type: "string", format: "email" },
    hobbies: {
      type: "array",
      items: { type: "string" },
      maxItems: 10,
      uniqueItems: true
    },
    isActive: { type: "boolean" }
  },
  required: ["name", "age"],
  additionalProperties: false
};

Các Mô Hình Schema Thông Dụng

1. Enums (Giới Hạn Tùy Chọn)

const statusSchema = {
  type: "object",
  properties: {
    status: { enum: ["active", "inactive", "pending", "banned"] },
    priority: { type: "string", enum: ["low", "medium", "high", "urgent"] }
  }
};

2. Đối Tượng Lồng Nhau

const addressSchema = {
  type: "object",
  properties: {
    street: { type: "string" },
    city: { type: "string" },
    country: { type: "string" },
    zipCode: { type: "string", pattern: "^[1-9][0-9]{5}$" }
  },
  required: ["street", "city", "country"]
};

const personSchema = {
  type: "object",
  properties: {
    name: { type: "string" },
    homeAddress: addressSchema,
    workAddress: addressSchema
  }
};

3. Mảng Với Loại Mục Cụ Thể

const orderSchema = {
  type: "object",
  properties: {
    orderId: { type: "string" },
    items: {
      type: "array",
      minItems: 1,
      items: {
        type: "object",
        properties: {
          productId: { type: "string" },
          quantity: { type: "number", minimum: 1 },
          price: { type: "number", minimum: 0 }
        },
        required: ["productId", "quantity", "price"]
      }
    }
  }
};

JSON Schema và YAML

Một bí mật thú vị là JSON Schema hoàn toàn tương thích với YAML! Vì YAML thực sự là phiên bản dễ đọc hơn của JSON, bạn có thể sử dụng cùng một định nghĩa schema.

name: "Alice"
age: 30
email: "alice@example.com"
hobbies:
  - "coding"
  - "coffee"
  - "cats"

Logic xác thực không quan tâm dữ liệu của bạn bắt đầu từ JSON hay YAML – nó trở thành cùng một cấu trúc đối tượng trong bộ nhớ. Điều này có nghĩa là:

• Sử dụng JSON Schema để xác thực các tệp cấu hình YAML
• Chấp nhận cả JSON và YAML trong các API của bạn
• Giữ một định nghĩa schema cho nhiều định dạng dữ liệu

Tại Sao Bạn Nên Quan Tâm?

1. Phát Hiện Lỗi Sớm

const user = { name: "Bob", age: "thirty-five" };
calculateInsurance(user.age * 1.2); // NaN lại xuất hiện!

2. API Tự Động Tài Liệu

Schema của bạn chính là tài liệu. Không còn tài liệu API lỗi thời nữa.

3. Thỏa Thuận Giữa Frontend và Backend

Khi cả hai bên xác thực theo cùng một schema, sự hiểu lầm trở nên không thể xảy ra.

4. Thông Điệp Lỗi Tốt Hơn

Thay vì "Có gì đó sai sai," bạn sẽ nhận được "Thuộc tính 'email' phải phù hợp với định dạng 'email'."

Kết Luận

Trong Phần 2, chúng ta sẽ đi sâu vào việc triển khai xác thực JSON Schema với AJV, bao gồm:

• Cài đặt AJV trong dự án của bạn
• Các tính năng xác thực nâng cao
• Từ khóa tùy chỉnh và thông điệp lỗi
• Mẹo tối ưu hóa hiệu suất

Bạn đã sẵn sàng để không còn phải gỡ lỗi những vấn đề dữ liệu bí ẩn vào lúc 2 giờ sáng nữa chưa? Hãy thực hiện điều đó! 🚀

Chuyển Hướng Chuỗi:

• Phần 1: Hiểu Biết Cơ Bản ← Bạn đang ở đây
• Phần 2: Triển Khai Với AJV (Sắp tới)
• Phần 3: Ứng Dụng Thực Tế & HAL (Sắp đến)