שלחתי מספיק ממשקי API כדי לדעת את הרגע המדויק שבו פרויקט צריך סכימת JSON. זה אף פעם לא בהתחלה. חלפו שלושה שבועות, כאשר צוות שני מתחיל לצרוך את נקודת הקצה שלך, מישהו שולח גוף בקשה פגום, ו-a null מחליק לתוך שדה שכולם הניחו שהוא תמיד מחרוזת פתאום אתה צריך חוזה - מסמך שאומר, בצורה שמכונה יכולה לאכוף, " כך נראה מטען תקף." המסמך הזה הוא סכימת JSON, וכתיבה אחת ביד מנקודת קצה שכבר מחזירה נתונים אמיתיים היא אחת העבודות היותר מייגעות בעבודה האחורית.
TL;DR: הדבק דגימת JSON לתוך מחולל סכמת JSON, בחר Draft-07 או 2020-12, והוא מסיק סכימה - סוגים,
requiredשדות, פריטי מערך ממוזגים ופורמטים של מחרוזת כמוdate-timeוuuid. הוא פועל כולו בדפדפן שלך, כך שמטענים הנושאים אסימונים ונתונים אישיים לעולם אינם עוזבים את הדף. התייחס לפלט כאל טיוטה ראשונה חזקה, ולאחר מכן הדק אותו עם האילוצים שרק אתה מכיר.
בניתי את הכלי הזה עבור Toolz.dev כי המשכתי לעשות את אותו הדבר ביד: לפתוח גוף תגובה, לפזול אליו ולתמלל את צורתו לסעיף סכימה אחר סעיף. זה חוזר על עצמו, ותעתוק חוזר הוא המקום שבו מסתתרות טעויות. מדריך זה מסביר מה המחולל עושה, היכן הסקת מסקנות אמינה, היכן היא זקוקה לשיפוט שלך, וכיצד סכימה שנוצרה משתלבת בזרימת עבודה אמיתית של אימות.
מהי סכימת JSON, ומדוע ליצור אחת מנתונים?
JSON Schema הוא אוצר מילים לתיאור המבנה של JSON, המתוחזק כ מפרט בפני עצמו ולא כמוסכמה סכימה היא בעצמה מסמך JSON שמצהיר על הסוג הצפוי של כל שדה, אילו שדות נדרשים, איזו צורה מקבלים אובייקטים ומערכים מקוננים, ו - עם מילות מפתח כמו pattern, enum, minimum, ו format - אילו ערכים מותרים בפועל. מאמתים כמעט בכל שפה קוראים סכימה ואומרים לך אם מסמך נתון תואם. זה הדבר הכי קרוב שיש לעולם JSON למערכת טיפוס שעוברת על פני גבולות שירות.
הסיבה ליצור סכימה ממדגם, במקום לכתוב אותה מאפס, היא שרוב הסכימה היא מכנית. הליכה על מטען והקלטה " זוהי מחרוזת, זהו מספר שלם, לאובייקט זה יש את המפתחות הללו" הוא בדיוק סוג העבודה שמכונה צריכה לעשות. מה כן לא מכני הוא הרובד הסמנטי: לדעת את זה status יכול להיות רק אחד מארבעה מיתרים, זה age לא יכול להיות שלילי, זה email חייב להתאים דפוס כתובת אמיתית דור מטפל הפיגומים מכני כך שאתה יכול לבזבז את תשומת הלב שלך על האילוצים החשובים אתה מתחיל ממסמך שכבר תואם את המציאות ולהוסיף כללים, במקום להתחיל מקובץ ריק ומקווה שזכרת כל שדה.
יש גם ממד אמון. כשאתה מקליד סכימה ביד, אתה מקודד את מה שאתה להאמין נקודת הקצה חוזרת אמונות נסחפות מהמציאות - שדה מתווסף, מספר שלם הופך לריק, נקודת קצה שהחזירה אובייקט בודד מתחילה להחזיר מערך סכימה שנוצרת מתגובה ממשית מעוגנת למה שהשירות שלח באמת ביום שבו לכדת אותו העוגן הזה שווה הרבה מאוד כשאתה מאתר באגים מדוע אימות עובר בבימוי ונכשל בייצור.
כיצד המחולל מסיק סכימה
המנוע מנתח את ה-JSON שלך והולך על הערך באופן רקורסיבי, פולט צומת סכימה עבור כל חלק במבנה הכללים שמרניים בכוונה, מכיוון שסכימה רופפת מדי היא חסרת תועלת וסכימה קפדנית מדי דוחה נתונים תקפים.
עבור סקלרים, זה מבחין integer מ number - - 42 הופך integer, 4.2 הופך number - כי ההבחנה הזו משמעותית למאמתים ולכל מי שקורא את הסכימה. בוליאנים ו null מפה לסוגים שלהם מיתרים הופכים type: string, ואם זיהוי הפורמט פועל, המנוע בודק את הערך מול קבוצה של דפוסים ידועים ומתייג אותו: date-time, date, time, email, uri, uuid, ו ipv4.
עבור אובייקטים, הוא מקליט כל מפתח, מסיק סכימה עבור כל ערך, ו - אם required הסקת מסקנות מופעלת - מסמן מפתח הנדרש כאשר הוא קיים בכל אובייקט במיקום זה. עבור אובייקט בודד שפירושו כל המפתחות; המקרה המעניין הוא מערכים.
עבור מערכים של אובייקטים, המחולל עושה משהו שימושי יותר מהליכה נאיבית. במקום לפלוט סכימה נפרדת לכל אלמנט או סכימה רחבה anyOf של צורות כמעט זהות, הוא ממזג את כל האובייקטים במערך לאחד items סכימה המתארת אלמנט בודד נדרש מפתח הקיים בכל אלמנט; מפתח הקיים רק בחלק מהאלמנטים נותר אופציונלי. זה משקף את האופן שבו אוספי API אמיתיים מתנהגים: רשימה מעוטרת שבה רוב הרשומות נושאות avatarUrl אבל כמה לא. הסכימה הממוזגת לוכדת את " שדות אלה תמיד מופיעים, אלה לפעמים מופיעים" בהגדרה אחת הניתנת לקריאה. אתה יכול לראות זאת במדגם המובנה, שבו members למערך יש שני אובייקטים - אחד עם an active שדה ואחד ללא - וסימני סכימת הפריט שנוצרו id ו role נדרש אבל עוזב active אופציונלי.
עבור מערכים של סקלרים מעורבים, המנוע ממוטט את סוגי האלמנטים ליחיד type מערך - ["integer", "string", "boolean"] - במקום איחוד מילולי. כאשר צורות אובייקט ולא אובייקט מתערבבות באמת במערך אחד, זה נופל בחזרה anyOf, שהוא המבנה הנכון של סכימת JSON עבור " אחת מהחלופות הללו."
כיצד להשתמש במחולל סכימת JSON
שלב 1: הדבק דוגמה מייצגת
זרוק תגובת API, מתקן, קובץ תצורה או גוף webhook. הדבר החשוב ביותר שאתה יכול לעשות למען הדיוק הוא להדביק א נציג סמפליי אם יש לך מספר רשומות מתגובה אמיתית, כלול את כולן בתוך מערך - הגנרטור ימזג אותן ויסיק אופציונליות בצורה נכונה דגימה של רשומה אחת אומרת למנוע שכל שדה שהוא רואה קיים תמיד, וזה לרוב שגוי טען תחילה את הדגימה המובנית כדי לראות כיצד מטפלים באובייקטים מקוננים, מערכי אובייקטים ומחרוזות מעוצבות לפני שאתה מדביק את שלך.
שלב 2: בחר את הניב
בחר Draft-07 עבור התאימות הרחבה ביותר בין ספריות אימות, או 2020-12 עבור המפרט הנוכחי. הכלי כותב את הנכון $schema מזהה על השורש כך שהמאמת שלך מיישם את הכללים הנכונים. עבור צורות האובייקט והמערך שהמחולל הזה מייצר, הפלט המבני זהה בשני הדיאלקטים; ההבדל הנראה לעין הוא המזהה. אם אינך בטוח באיזה כלי העבודה שלך תומך, Draft-07 הוא ברירת המחדל הבטוחה - יש לו את התמיכה הרחבה ביותר בספרייה מכל גרסה.
שלב 3: הגדר את האפשרויות שלך
הוסף א title אם אתה רוצה את הסכימה תיעוד עצמי. להחליט אם לפלוט required - רוב הזמן אתה רוצה את זה, אבל במהלך חקירה מוקדמת אתה עשוי להעדיף סכימה רופפת יותר. שמור על זיהוי פורמט פועל אלא אם כן אתה רואה תוצאות חיוביות שגויות. והפעל מצב קפדני (additionalProperties: false) כאשר הסכימה שומרת על משהו שאתה שולט בו במלואו, כמו קובץ תצורה או גוף בקשה, ואתה רוצה שמפתחות בלתי צפויים יידחו במקום להתעלם מהם.
שלב 4: יצירה, סקירה וייצוא
הקש Generate, ולאחר מכן קרא את הפלט באופן ביקורתי. בדוק את זה required תואם את הכוונה שלך, המספר השלם מול המספר הזה יצא נכון, ושכל הפורמטים שזוהו נכונים ולא מקריים. כאשר זה נראה נכון, העתק את הסכימה או הורד אותה בתור א .json הקובץ מוכן לרדת למאמת או למאגר שלך.
דוגמה מעובדת
שקול את התגובה הזו מהיפותטית /projects נקודת קצה:
{
"id": "5b2a1f6e-8c3d-4a1b-9f7e-2c1d3e4f5a6b",
"name": "Toolz",
"createdAt": "2026-01-14T09:30:00Z",
"score": 4.8,
"members": [
{ "id": 1, "role": "owner", "active": true },
{ "id": 2, "role": "editor" }
]
}
המחולל מייצר סכימה שבה id הוא מחרוזת עם format: "uuid", createdAt הוא מחרוזת עם format: "date-time", score הוא א number (לא מספר שלם, בגלל העשרוני), ו members הוא מערך אשר items סכימה דורשת id ו role אבל לא active. הפרט האחרון הוא התמורה: משני חברים לדוגמה הסיק זאת נכון active הוא אופציונלי. לעשות את ההיגיון הזה ביד על פני מטען גדול זה בדיוק סוג של עבודה זהירה ומשעממת שגנרטור מסיר.
היכן שההסקה מסתיימת והשיפוט שלך מתחיל
אני רוצה להיות ישיר לגבי הגבולות, כי סכימה שנוצרה המועברת ישר לייצור היא טעות. מסקנות רואה סוגים ומבנה; זה לא יכול לראות כוונה.
זה לא יכול לדעת את זה role הוא enum של owner, editor, ו viewer - מהמדגם זה רק יודע role הוא מחרוזת. זה לא יכול לדעת את זה score נע בין 0 ל-5, זה name יש אורך מקסימלי, או שקוד שבמקרה נראה כמו UUID הוא למעשה מזהה אטום שאמור להישאר מחרוזת רגילה. זה מסיק required מנוכחות, אז שדה אופציונלי שבמקרה מופיע במדגם שלך יסומן נדרש עד שתתקן אותו. וזה עובד מהנתונים שאתה נותן לו: אם המדגם שלך לעולם לא כולל א null עבור שדה שניתן לבטל, הסכימה לא תדע ששדה יכול להיות ריק.
המודל המנטלי הנכון הוא פיגומים המחולל בונה את המסגרת במדויק - כל שדה, הסוג שלו, הקינון, צורות המערך, רשימת הדרישות מבוססת הנוכחות אתה מוסיף אז את האילוצים הסמנטיים: enums, תבניות, גבולות מספריים, וכל הפורמטים שהמנוע לא יכול היה לראות מערך אחד זה מהיר יותר ופחות נוטה לשגיאות מאשר להתחיל מכלום, כי התעתיק המבני המייגע כבר נעשה ונכון.
דראפט-07 לעומת 2020-12: במה כדאי לבחור?
| התחשבות | טיוטה-07 | 2020-12 |
|---|---|---|
| תמיכה בספרייה | הרחב ביותר; נתמך כמעט בכל מקום | צומח; בדוק את המאמת שלך |
| סטטוס | פרוס רחב, יציב | מפרט נוכחי |
$schema ערך |
http://json-schema.org/draft-07/schema# |
https://json-schema.org/draft/2020-12/schema |
| מילות מפתח של פריט מערך | items עבור סכמות של פריט בודד |
items / prefixItems פיצול עבור tuples |
| הכי טוב כאשר | תאימות מקסימלית חשובה | אתה רוצה את התכונות החדשות ביותר מפרט |
עבור הסכמות שהכלי הזה מייצר - אובייקטים, רשימות נדרשות, מערכים של צורת פריט בודדת - שני הדיאלקטים מבטאים את אותו מבנה ההחלטה המעשית מסתכמת במה שספריית האימות שלך תומכת. אם אתה מחווט את הסכימה לערימה מבוססת, התאם את הגרסה של מסמכי האימות שלך. אם אתה מתחיל מחדש ואין לך אילוץ, Draft-07 נשאר הבחירה הפרגמטית לתמיכה במערכת האקולוגית שאין שני לה.
מקרי שימוש נפוצים
תיעוד API קיים. כאשר אתה יורש נקודת קצה ללא סכימה, יצירת אחת מתגובה אמיתית נותנת לך מסמך התחלה מדויק תוך שניות. לאחר מכן אתה משכלל אותו לחוזה שפורסם. זה משתלב באופן טבעי עם יצירת סוגים עבור קוד הלקוח שלך - אותה דוגמה יכולה להזין את json ל-Typescript כלי כך שחוזה השרת וסוגי הלקוחות שלך מגיעים מאותו מקור אמת.
אימות גופי בקשה. עבור גוף בקשה שאתה שולט בו, צור סכימה מדוגמה חוקית, הפעל מצב קפדני כדי לדחות מפתחות בלתי צפויים, והוסף את ה-enums והגבולות שנקודת הקצה שלך אוכפת. כעת בקשות שגויות נכשלות בקצה עם שגיאת אימות ברורה במקום לגרום לכשלים מבלבלים עמוק במטפל שלך.
אימות קובץ תצורה. יישומים שקוראים את תצורת JSON נהנים מאוד מסכימה. צור אחד מתצורה ידועה-טובה, הדק אותו ואמת בעת האתחול כך ששגיאת הקלדה במקש תצורה נכשלת בקול רם במקום להשבית תכונה בשקט.
בדיקות ומתקנים. סכימה משמשת כנכס בדיקה. אמת את המשחקים שלך נגדו ב-CI כך שמתקן שנסחף מהצורה ייתפס לפני שהוא מייצר מבחן ירוק מטעה.
בדיקת חוזים בין שירותים. כאשר שני שירותים מסכימים על מטען, סכימה משותפת היא החוזה. הפקתו מהודעה אמיתית וחידוד זה נותן לשני הצוותים מסמך שהם יכולים לאמת נגדו באופן עצמאי.
פרטיות: מדוע זה פועל בדפדפן שלך
דוגמאות API הן חלק מהטקסט הרגיש ביותר שמפתח מטפל בהם הם מכילים באופן שגרתי אסימוני גישה, מזהי הפעלה, כתובות דואל, מזהי רשומות פנימיים, ומדי פעם נתונים אישיים שאסור להדביק אותם לעולם בטופס אינטרנט אקראי בדיוק בגלל זה מחולל סכימת JSON עושה את כל העבודה שלו בצד הלקוח הניתוח, ההסקה וההסדרה מתרחשים ב-JavaScript בדפדפן שלך שום דבר לא מועלה, נרשם או מאוחסן בשרת אתה יכול לאמת זאת על ידי פתיחת לשונית הרשת שלך בזמן שאתה יוצר, או על ידי ניתוק מהאינטרנט - הכלי עדיין עובד אכפת לי מזה כי לא הייתי משתמש בכלי ששלח את המטענים שלי למישהו אחר's שרת, ולא הייתי מבקש ממך גם את אותו עיקרון עובר בכל Toolz.dev, שהוא הטיעון שאני מעלה בהרחבה ב פרטיות נתונים בכלים מקוונים לכתוב.
איך זה מתאים לערכת הכלים הרחבה יותר של JSON
סכימה היא חפץ אחד בזרימת עבודה גדולה יותר של JSON. לפני שאתה יוצר סכימה, זה עוזר לקבל קלט נקי ותקין - ה פורמט JSON יעצב ויאמת מטען כך שלא תזין טקסט פגום לתוך המחולל. לאחר שיש לך סכימה, לעתים קרובות אתה רוצה סוגים עבור קוד היישום שלך, וזה המקום שבו json ל-Typescript מגיע פנימה ואם הצינור שלך נע בין פורמטים, ה JSON ל-YAML ממיר מטפל בהמרה הרבה מערכות config ו-CI מצפות. כתבתי על איך החלקים האלה מתחברים ב מדריך אולטימטיבי לכלי JSON, ועל הרכבת ערכה רחבה יותר ב- ערכת כלים למפתחי אינטרנט סקירה כללית הנקודה של ערכת כלים מחוברת היא שדגימה בודדת יכולה לזרום דרך מספר כלים - סכימה, סוגים, המרת פורמטים - מבלי לעזוב את הדפדפן שלך.
שָׁוא
כיצד אוכל ליצור סכימת JSON מ-JSON?
הדבק את ה-JSON שלך בעורך, בחר Draft-07 או 2020-12, ולחץ על Generate. הכלי מסיק את סוג כל שדה, מחלץ את המקשים הנדרשים ומוציא סכימה שתוכל להעתיק ישירות למאמת. שום דבר לא מועלה - ההסקה פועלת כולה בדפדפן שלך.
מה ההבדל בין טיוטה-07 ל-2020-12?
הן שתי גרסאות של מפרט JSON Schema.לטיוטה-07 יש את התמיכה הרחבה ביותר בספריות והיא ברירת מחדל בטוחה. 2020-12 היא המהדורה הנוכחית ומשנה את אופן ביטוי המערכים ותתי הסכמות, בין היתר. עבור צורות האובייקט והמערך הכלי הזה מייצר המבנה זהה; ההבדל העיקרי הנראה לעין הוא $schema מזהה.
כיצד הכלי מחליט אילו שדות נדרשים?
מפתח מסומן כנדרש כאשר הוא מופיע בכל אובייקט שהמחולל רואה. עבור אובייקט בודד שפירושו כל מפתח; עבור מערך של אובייקטים זה אומר מפתחות הקיימים בכל האלמנטים. מפתחות המופיעים רק בחלק מהרשומות נותרו מחוץ לדרוש, מה שמשקף כיצד ממשקי API משמיטים שדות אופציונליים. אתה יכול לכבות לחלוטין את זיהוי השדה הנדרש.
מה קורה עם מערך של אובייקטים?
האובייקטים מתמזגים לאחד items סכימה המתארת אלמנט בודד, והמאפיין מוקלד כמערך שלו. מפתחות הקיימים בכל אלמנט הופכים נדרשים; מפתחות הקיימים רק בחלק מהשהייה אופציונליים. זה שומר על הסכימה קריא במקום לייצר גדול anyOf של צורות כמעט זהות.
אילו פורמטים של מחרוזת הוא מזהה?
זה מזהה date-time, date, time, email, uri, uuid, ו ipv4 מחרוזות ומוסיף את ההתאמה format מילת מפתח זיהוי הוא המאמץ הטוב ביותר מדגם יחיד, אז לסקור את התוצאות - קוד שבמקרה נראה כמו UUID יהיה מתויג כאחד אתה יכול להשבית את זיהוי פורמט אם אתה מעדיף סוגי מחרוזת רגילה.
האם אני יכול ליצור סכימה ממדגם בודד?
כן, אבל מדגם אחד מציג רק צורה אפשרית אחת שדה שהוא מספר במדגם שלך עשוי להיות null או מחרוזת במקום אחר, ושדה אופציונלי שבמקרה קיים יסומן נדרש ככל שהמדגם מייצג יותר - באופן אידיאלי מספר רשומות אמיתיות - כך הסוגים המשוערים והרשימה הנדרשת מדויקים יותר.
האם סכימה שנוצרה מוכנה לאימות ייצור?
התייחסו אליו כאל נקודת התחלה חזקה ולא כאל מסמך מוגמר.Inference לוכדת סוגים, מבנה ושדות נדרשים במדויק, אך עדיין יש להוסיף ביד אילוצים סמנטיים - enums, דפוסי מחרוזת, מינימום מספרי ומקסימום, פורמטים שהוא לא יכול לראות מערך אחד. Generating מסיר את הפיגומים המייגעים כדי שתוכלו להתמקד בכללים הללו.
האם ה-JSON שלי מועלה לשרת?
מס 'כל מנוע ההסקה פועל כמו JavaScript בדפדפן שלך שום דבר לא מועבר, נרשם, או מאוחסן אתה יכול לאשר זאת על ידי צפייה בכרטיסיית הרשת שלך בזמן שאתה יוצר, או על ידי ניתוק מהאינטרנט - הכלי עדיין עובד.
