คู่มือ JSON Schema: ตรวจสอบโครงสร้างข้อมูลของคุณ

ทุกแอปพลิเคชันที่รับข้อมูลจากแหล่งภายนอกต้องเผชิญกับคำถามพื้นฐานเดียวกัน: ฉันเชื่อถือข้อมูลนี้ได้หรือไม่? ไม่ว่าจะเป็น body คำขอ API ไฟล์กำหนดค่า ข้อความคิว หรือการนำเข้าข้อมูล ข้อมูลที่ไม่น่าเชื่อถือต้องได้รับการตรวจสอบก่อนเข้าสู่ระบบ JSON Schema มอบวิธีที่เป็นมาตรฐานและไม่ขึ้นกับภาษาในการกำหนดว่าข้อมูลที่ถูกต้องควรมีลักษณะอย่างไร และตรวจสอบว่าข้อมูลขาเข้าสอดคล้องกับคำจำกัดความนั้นหรือไม่ คู่มือนี้ครอบคลุมทุกอย่างตั้งแต่การเขียน Schema แรกไปจนถึงรูปแบบขั้นสูงสำหรับการตรวจสอบที่ซับซ้อน พร้อมตัวอย่างที่ใช้งานได้จริงที่คุณสามารถนำไปใช้ได้ทันที

JSON Schema คืออะไร?

JSON Schema คือเอกสาร JSON ที่อธิบายโครงสร้างและข้อจำกัดของเอกสาร JSON อื่นๆ เป็นคำศัพท์ที่ช่วยให้คุณกำหนดคำอธิบายประกอบและตรวจสอบข้อมูล JSON ซึ่งกำหนดมาตรฐานโดย IETF (Internet Engineering Task Force) JSON Schema กำหนดกฎเกี่ยวกับฟิลด์ที่ต้องมี ประเภทที่ต้องเป็น ค่าที่ยอมรับได้ และโครงสร้างของออบเจ็กต์และอาร์เรย์

ลองนึกภาพ JSON Schema เป็นสัญญาข้อมูลของคุณ เช่นเดียวกับ Schema ฐานข้อมูลที่กำหนดคอลัมน์ ประเภท และข้อจำกัดของตาราง JSON Schema กำหนดคุณสมบัติ ประเภท และข้อจำกัดของเอกสาร JSON ข้อมูล JSON ใดๆ ที่ตรงตามข้อจำกัดทั้งหมดใน Schema เรียกว่าอินสแตนซ์ที่ถูกต้อง ในขณะที่ข้อมูลที่ละเมิดข้อจำกัดใดๆ จะไม่ถูกต้อง

สิ่งที่ JSON Schema ไม่ใช่

• ไม่ใช่รูปแบบข้อมูล: JSON Schema ไม่ได้กำหนดวิธีการซีเรียลไลซ์หรือส่งข้อมูล มันอธิบายเฉพาะลักษณะของข้อมูลที่ถูกต้องเท่านั้น
• ไม่ใช่สิ่งทดแทนตรรกะทางธุรกิจ: การตรวจสอบ Schema ตรวจสอบความถูกต้องของโครงสร้าง (ประเภท รูปแบบ ช่วง) กฎทางธุรกิจที่ซับซ้อน (เช่น "ผู้ใช้ไม่สามารถโอนเงินเกินยอดคงเหลือ") เป็นของโค้ดแอปพลิเคชัน
• ไม่ใช่ Schema ฐานข้อมูล: แม้ว่าแนวคิดจะคล้ายกัน แต่ JSON Schema ตรวจสอบเอกสาร JSON ไม่ใช่ตารางฐานข้อมูล อย่างไรก็ตาม คุณสามารถใช้ JSON Schema ร่วมกับข้อจำกัดฐานข้อมูลเพื่อการป้องกันเชิงลึก

เวอร์ชัน JSON Schema

JSON Schema ได้พัฒนาผ่านหลายร่าง แต่ละร่างเพิ่มฟีเจอร์และปรับปรุงคำศัพท์ การเข้าใจเวอร์ชันเหล่านี้ช่วยให้คุณเลือกเวอร์ชันที่เหมาะสมสำหรับโปรเจกต์ของคุณและหลีกเลี่ยงปัญหาความเข้ากันได้

เขียน Schema แรกของคุณ

มาเริ่มด้วยตัวอย่างง่ายๆ: Schema สำหรับออบเจ็กต์ผู้ใช้ที่มีชื่อ อีเมล และอายุ

{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "$id": "https://example.com/schemas/user.json",
    "title": "User",
    "description": "A user account in the system",
    "type": "object",
    "properties": {
        "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100,
            "description": "The user's full name"
        },
        "email": {
            "type": "string",
            "format": "email",
            "description": "The user's email address"
        },
        "age": {
            "type": "integer",
            "minimum": 0,
            "maximum": 150,
            "description": "The user's age in years"
        }
    },
    "required": ["name", "email"],
    "additionalProperties": false
}

Schema นี้ประกาศว่าผู้ใช้ที่ถูกต้องต้องเป็นออบเจ็กต์ โดยที่ name และ email เป็นคุณสมบัติสตริงที่จำเป็น คุณสมบัติ age เป็นทางเลือก แต่ถ้ามีต้องเป็นจำนวนเต็มระหว่าง 0 ถึง 150 ข้อจำกัด additionalProperties: false ป้องกันคุณสมบัติใดๆ ที่ไม่ได้กำหนดใน Schema ซึ่งช่วยจับการสะกดผิดและฟิลด์ที่ไม่คาดคิด

ข้อมูลอ้างอิงคีย์เวิร์ดหลัก

JSON Schema มีคำศัพท์คีย์เวิร์ดที่หลากหลายสำหรับการกำหนดข้อจำกัด นี่คือคีย์เวิร์ดที่สำคัญที่สุด จัดตามหมวดหมู่

คีย์เวิร์ดประเภท

ข้อจำกัดตัวเลข

ข้อจำกัดสตริง

ข้อจำกัดออบเจ็กต์

ข้อจำกัดอาร์เรย์

รูปแบบ Schema ทั่วไป

Schema ในโลกความเป็นจริงมักต้องการรูปแบบที่นอกเหนือจากการตรวจสอบประเภทอย่างง่าย นี่คือรูปแบบที่ใช้บ่อยที่สุด

การตรวจสอบแบบมีเงื่อนไขด้วย if/then/else

ใช้ตรรกะเงื่อนไขเพื่อใช้ข้อจำกัดที่แตกต่างกันตามค่าคุณสมบัติ ตัวอย่างเช่น ออบเจ็กต์การชำระเงินต้องการฟิลด์ที่แตกต่างกันตามวิธีการชำระเงิน

{
    "type": "object",
    "properties": {
        "method": { "enum": ["credit_card", "bank_transfer"] },
        "card_number": { "type": "string" },
        "routing_number": { "type": "string" }
    },
    "required": ["method"],
    "if": {
        "properties": { "method": { "const": "credit_card" } }
    },
    "then": {
        "required": ["card_number"]
    },
    "else": {
        "required": ["routing_number"]
    }
}

การรวมด้วย allOf, anyOf, oneOf

คีย์เวิร์ดการรวมช่วยให้คุณรวม Schema ในรูปแบบที่ทรงพลัง:

• allOf: ข้อมูลต้องตรงตาม Schema ย่อยทั้งหมด ใช้สำหรับรวมข้อจำกัดหลายรายการหรือผสมส่วน Schema ที่นำกลับมาใช้ใหม่ได้
• anyOf: ข้อมูลต้องตรงตาม Schema ย่อยอย่างน้อยหนึ่งรายการ ใช้สำหรับประเภท union ที่ยอมรับได้หลายรูปแบบ
• oneOf: ข้อมูลต้องตรงตาม Schema ย่อยเพียงรายการเดียว ใช้สำหรับตัวเลือกที่ไม่เกิดร่วมกัน

{
    "oneOf": [
        {
            "type": "object",
            "properties": {
                "type": { "const": "email" },
                "address": { "type": "string", "format": "email" }
            },
            "required": ["type", "address"]
        },
        {
            "type": "object",
            "properties": {
                "type": { "const": "phone" },
                "number": { "type": "string", "pattern": "^\\+?[1-9]\\d{1,14}$" }
            },
            "required": ["type", "number"]
        }
    ]
}

การใช้ $ref เพื่อนำ Schema กลับมาใช้ใหม่

คีย์เวิร์ด $ref ช่วยให้คุณอ้างอิงและนำ Schema กลับมาใช้ใหม่ กำจัดการซ้ำซ้อนและรักษาความสามารถในการบำรุงรักษาของ Schema คุณสามารถอ้างอิง Schema ภายในเอกสารเดียวกันหรือในไฟล์ภายนอก

{
    "$id": "https://example.com/schemas/order.json",
    "type": "object",
    "properties": {
        "customer": { "$ref": "#/$defs/address" },
        "shipping": { "$ref": "#/$defs/address" },
        "billing": { "$ref": "#/$defs/address" },
        "items": {
            "type": "array",
            "items": { "$ref": "#/$defs/lineItem" },
            "minItems": 1
        }
    },
    "required": ["customer", "items"],
    "$defs": {
        "address": {
            "type": "object",
            "properties": {
                "street": { "type": "string" },
                "city": { "type": "string" },
                "zip": { "type": "string", "pattern": "^\\d{5}(-\\d{4})?$" },
                "country": { "type": "string", "minLength": 2, "maxLength": 2 }
            },
            "required": ["street", "city", "zip", "country"]
        },
        "lineItem": {
            "type": "object",
            "properties": {
                "product": { "type": "string" },
                "quantity": { "type": "integer", "minimum": 1 },
                "price": { "type": "number", "exclusiveMinimum": 0 }
            },
            "required": ["product", "quantity", "price"]
        }
    }
}

ประเภทที่ nullable

ใน JSON Schema Draft 2020-12 ประเภทที่ nullable แสดงโดยใช้อาร์เรย์ประเภทที่มี "null":

{
    "type": ["string", "null"],
    "description": "An optional display name, or null if not set"
}

ในร่างก่อนหน้านี้ ข้อกำหนด OpenAPI ใช้คีย์เวิร์ด nullable: true สำหรับ JSON Schema มาตรฐาน ให้ใช้วิธีการอาร์เรย์ประเภทเสมอ

การตรวจสอบรูปแบบ

คีย์เวิร์ด format ให้การตรวจสอบความหมายที่นอกเหนือจากการตรวจสอบโครงสร้าง มันระบุว่าสตริงต้องสอดคล้องกับรูปแบบที่รู้จักกันดี รูปแบบที่รองรับทั่วไปรวมถึง:

ตรวจสอบข้อมูล JSON ด้วยโปรแกรม

การตรวจสอบ Schema มีประโยชน์มากที่สุดเมื่อรวมเข้ากับโค้ดแอปพลิเคชัน นี่คือตัวอย่างการใช้ไลบรารียอดนิยมในภาษาต่างๆ

JavaScript ด้วย Ajv

Ajv เป็นตัวตรวจสอบ JSON Schema ที่ใช้กันอย่างแพร่หลายที่สุดใน JavaScript รองรับเวอร์ชันร่างทั้งหมด และให้ประสิทธิภาพที่ยอดเยี่ยมผ่านการคอมไพล์ JIT ของ Schema

import Ajv from 'ajv';
import addFormats from 'ajv-formats';

const ajv = new Ajv();
addFormats(ajv);

const schema = {
    type: 'object',
    properties: {
        name: { type: 'string', minLength: 1 },
        email: { type: 'string', format: 'email' },
        age: { type: 'integer', minimum: 0 }
    },
    required: ['name', 'email'],
    additionalProperties: false
};

const validate = ajv.compile(schema);
const valid = validate({ name: 'Alice', email: 'alice@example.com', age: 30 });

if (!valid) {
    console.log(validate.errors);
    // [{ keyword: 'required', params: { missingProperty: 'email' }, ... }]
}

Python ด้วย jsonschema

from jsonschema import validate, ValidationError

schema = {
    "type": "object",
    "properties": {
        "name": {"type": "string", "minLength": 1},
        "email": {"type": "string", "format": "email"},
        "age": {"type": "integer", "minimum": 0}
    },
    "required": ["name", "email"],
    "additionalProperties": False
}

try:
    validate(instance={"name": "Alice", "email": "alice@example.com"}, schema=schema)
except ValidationError as e:
    print(f"Validation failed: {e.message}")

การตรวจสอบข้อมูล API ด้วย JSON Schema

หนึ่งในแอปพลิเคชันที่มีค่าที่สุดของ JSON Schema คือการตรวจสอบข้อมูลคำขอและการตอบสนอง API สิ่งนี้ทำให้มั่นใจว่า API ของคุณรับอินพุตที่มีรูปแบบดีและส่งคืนข้อมูลในรูปแบบที่คาดหวัง จับข้อผิดพลาดได้ตั้งแต่เนิ่นๆ และให้ข้อความแสดงข้อผิดพลาดที่ชัดเจนแก่ไคลเอ็นต์

มิดเดิลแวร์ Express.js

import Ajv from 'ajv';

const ajv = new Ajv({ allErrors: true });

function validateBody(schema) {
    const validate = ajv.compile(schema);
    return (req, res, next) => {
        if (!validate(req.body)) {
            return res.status(400).json({
                error: 'Validation failed',
                details: validate.errors
            });
        }
        next();
    };
}

app.post('/api/users',
    validateBody({
        type: 'object',
        properties: {
            name: { type: 'string', minLength: 1, maxLength: 100 },
            email: { type: 'string', format: 'email' },
            role: { enum: ['admin', 'editor', 'viewer'] }
        },
        required: ['name', 'email'],
        additionalProperties: false
    }),
    (req, res) => {
        // req.body is guaranteed valid here
        createUser(req.body);
    }
);

OpenAPI กับ JSON Schema

OpenAPI (เดิมชื่อ Swagger) ใช้เซตย่อยของ JSON Schema เพื่อกำหนด Schema คำขอและการตอบสนอง API หากคุณใช้ OpenAPI อยู่แล้ว คุณสามารถแยก Schema จากข้อกำหนด API และใช้สำหรับการตรวจสอบรันไทม์ เครื่องมือเช่น openapi-schema-validator และ express-openapi-validator สามารถทำให้กระบวนการนี้เป็นอัตโนมัติ ทำให้มั่นใจว่าเอกสาร API และตรรกะการตรวจสอบของคุณสอดคล้องกันเสมอ

แนวปฏิบัติที่ดีที่สุด

• ตั้งค่า $schema เสมอ: รวมคีย์เวิร์ด $schema เพื่อประกาศเวอร์ชันร่างที่ Schema ของคุณใช้ ป้องกันความคลุมเครือและทำให้มั่นใจว่าตัวตรวจสอบตีความ Schema ของคุณอย่างถูกต้อง
• ใช้ $id เป็นตัวระบุ Schema: คีย์เวิร์ด $id ให้ตัวระบุที่ไม่ซ้ำกันสำหรับ Schema ของคุณ และทำหน้าที่เป็น URI ฐานสำหรับการแก้ไขการอ้างอิง $ref ตั้งค่าเสมอแม้สำหรับ Schema ภายใน
• ตั้งค่า additionalProperties: false: โดยค่าเริ่มต้น JSON Schema อนุญาตให้มีคุณสมบัติเพิ่มเติมใดๆ ในออบเจ็กต์ การตั้งค่า additionalProperties: false ช่วยจับการสะกดผิดและฟิลด์ที่ไม่คาดคิด ทำให้ Schema ของคุณเข้มงวดขึ้นและ API คาดการณ์ได้มากขึ้น
• ใช้ $defs สำหรับส่วนประกอบที่นำกลับมาใช้ใหม่ได้: กำหนด Schema ทั่วไปใน $defs และอ้างอิงด้วย $ref ลดการซ้ำซ้อนและทำให้ Schema ง่ายต่อการบำรุงรักษา
• เพิ่มคำอธิบาย: ทุกคุณสมบัติและ Schema ควรมีฟิลด์ description ซึ่งทำหน้าที่เป็นเอกสารและช่วยให้นักพัฒนาคนอื่นเข้าใจวัตถุประสงค์และข้อจำกัดของแต่ละฟิลด์
• ตรวจสอบที่ขอบเขตของระบบ: ใช้การตรวจสอบ Schema ที่ขอบของระบบ: API endpoint, consumer ข้อความ, ไปป์ไลน์นำเข้าข้อมูล และตัวโหลดการกำหนดค่า อย่าตรวจสอบข้อมูลที่โค้ดของคุณผลิตขึ้นเองและเชื่อถือแล้ว
• เปิดใช้งานโหมดเข้มงวดในตัวตรวจสอบ: กำหนดค่าตัวตรวจสอบให้ปฏิเสธคีย์เวิร์ดที่ไม่รู้จัก บังคับใช้การตรวจสอบรูปแบบ และรายงานข้อผิดพลาดทั้งหมดแทนที่จะหยุดที่ข้อผิดพลาดแรก ซึ่งช่วยจับปัญหามากขึ้นในการตรวจสอบครั้งเดียว
• กำหนดเวอร์ชันให้ Schema: รวมเวอร์ชัน Schema ใน URI $id (เช่น https://example.com/schemas/user/v2.json) ซึ่งช่วยให้คุณพัฒนา Schema โดยไม่ทำลาย consumer ที่มีอยู่
• ทดสอบ Schema ของคุณ: เขียนการทดสอบหน่วยสำหรับ Schema ของคุณที่มีตัวอย่างที่ถูกต้องและไม่ถูกต้อง ทำให้มั่นใจว่า Schema บังคับใช้ข้อจำกัดตามที่คุณตั้งใจ และจับการถดถอยเมื่อมีการแก้ไข Schema
• ใช้ format สำหรับการตรวจสอบความหมาย: เลือกใช้ format: "email" แทนรูปแบบ regex ที่ซับซ้อน รูปแบบอ่านง่ายกว่า บำรุงรักษาง่ายกว่า และได้รับประโยชน์จากตรรกะการตรวจสอบที่ผ่านการทดสอบอย่างดีในไลบรารีตัวตรวจสอบ