Англійська для написання схеми JSON з чіткими описами полів

Схема JSON корисна лише наскільки корисні її описи. Схема сама по собі забезпечує структуру, але англійська всередині "description" поля є тим, що насправді говорить іншому розробнику — або API-споживачу, який читає сформовані документи — що поля означають, коли їх використовувати, і що відбувається, якщо вони неправильно. У цьому підручнику розглянуто правила написання описів схем, які можна дотримуватися.

Ключовий словник

** Опис поля ** — пояснення, яке можна прочитати, і яке прив’ язано до властивості схеми, зазвичай, викладено безпосередньо у створеній документації API. “Опис не є просто «ІД користувача» — він вказує «внутрішній UUID, який було присвоєно при створенні облікового запису, відрізняється від публічного імені користувача». ”

** Обмеження ** — правило, яке обмежує коректні значення для поля, наприклад, мінімум, максимум, шаблон або енум, яке слід пояснити англійською мовою, а не залишити неявним у самій схемі. “В описі чітко вказано обмеження: « Має бути між 1 і 100 включно; значення за межами цього діапазону повертають помилку 400 », а не залишати читачеві вивести це з ключових слів minimum / maximum окремо.”

** Типове значення ** — значення, яке буде використано, якщо поле буде пропущено, значення якого слід завжди вказувати явно, а не вважати очевидним.

• “Опис: « Кількість результатів на сторінку. Типове значення 20, якщо не вказано. Максимально допустима кількість — 100.’”*

** Nullable проти optional ** — відмінність між полем, яке може бути повністю відсутнім (необов’ язковим), і полем, яке має бути присутнім, але може містити нульове значення (nullable); об’ єднання цих двох значень у описі може призвести до виникнення помилок. “Це поле є нульовим, необов’ язковим — воно завжди має бути присутнім у відповіді, але його значення буде null доки користувач не завершить впровадження.”

** Прикладне значення ** — конкретне прикладне значення, включене до схеми, використовується для вилучення неоднозначності, яку проза сама по собі часто не може повністю розв’ язати.

• “Замість того, щоб просто описати формат дати словами, ми включили приклад: \"2026-07-02T14:30:00Z\", який негайно вирішує будь- які неоднозначності щодо обробки часових поясів.” *

Звичайні фрази

• «Це поле представляє [що це означає], а не [поширене нерозуміння]»
• «Типове значення [значення], якщо пропущено.»
• « Має бути [обмеження]; значення поза цим діапазоном повертають [спеціальна помилка]. »
• “Це поле є нульовим — завжди присутнє, але може бути нульовим до [умова].”
• «Див. приклад значення для очікуваного формату.»

Приклади висловлювань

Написання опису, який вилучає можливу неоднозначність:

• "" description”:\ “Загальна вартість у найменшій грошовій одиниці (наприклад, у центах за USD), а не у десятковій системі числення. Наприклад, $12.50 позначається як 1250.""*

Документування обмеження з його наслідками, а не лише з його правилом:

• "" description”: \ “Розмір сторінки для результатів зі сторінками. Має бути між 1 і 100. Запити з розміром сторінки більше 100 не відкидаються — їх розмір обмежується до 100, отже, перевірте поле « pageSize » у відповіді, щоб переконатися, що сторінка була використана.""*

Явно відрізняти нульовий від необмежений, оскільки сам по собі синтаксис схеми не дає змоги зробити це:

• "" description”: \ “Перевірена адреса електронної пошти користувача. Це поле завжди присутнє в об’ єкті відповіді, але буде нульовим доти, доки користувач не завершить перевірку електронної пошти — не вважайте відсутній ключ еквівалентом порожнього.\ ""*

Запис опису для поля, назва якого є неоднозначною:

• ""description”: ”« стан » посилається на поточний стан пересилання (наприклад, « у_ пересиланні », « доставлено »), а не на стан HTTP запиту API. Див. «ShipmentStatus» enum для повного списку коректних значень.""*

Професійні поради

• Написайте описи, які розв’язують найбільш ймовірне нерозуміння, а не просто повторюйте назву поля — «загальна ціна в центах, а не доларах» набагато корисніше, ніж «ціна»
• Завжди вказуйте типове значення явно в описі, навіть якщо воно також закодовано в ключовому слові "default" — не кожен споживач схеми або інструмент чітко використовує це ключове слово.
• Явно відрізняти nullable від optional, коли поле може бути заплутаним для будь-якого з них — це відмінність викликає реальні помилки виробництва, коли споживачі приймають неправильний.
• Спаруйте обмеження з їх наслідком, а не тільки правилом — “capped at 100” говорить розробнику, що насправді відбувається, в той час як “must be ≤ 100” само по собі не говорить, що станеться, якщо вони надіслали 150.
• Включити ** конкретний приклад значення ** для будь- якого поля, формат якого неоднозначний (дати, валюта, кодовані ідентифікатори) — описи формату у прозі часто неправильно розбираються, але приклади рідко.

Практичні вправи

1. Написати опис поля для гіпотетичного поля « сума », який пояснює його одиницю вимірювання і формат.
2. Напишіть опис, який відрізняє поле з нульовою значенням від необов’ язкового поля.
3. Напишіть опис для поля з обмеженнями, у якому буде вказано правила і те, що трапиться, якщо їх буде порушено.

Наприклад, мова опису мовлення: мова опису мовлення для немовляти

Написання ефективної документації JSON Schema є ключовим для того, щоб ваш API або файл налаштувань був легко зрозумілим для всіх - особливо при роботі з командою, яка включає розробників, чия перша мова не є англійською. Це не просто переклад слів; це про передачу значення точно і уникнення потенційної плутанини, що виникає з тонких відмінностей у тому, як концепції виражаються в різних мовах. Давайте розглянемо деякі загальні проблеми і стратегії для чіткого спілкування, зосередившись на конкретних потребах тих, хто розвиває свій професійний словник англійської мови.

Одна з найчастіших проблем виникає при описі обмежень. Простий переклад може бути «має бути числом», але в цьому відсутній необхідний нюанс. Замість цього, розгляньте формулювання на зразок: “Це поле вимагає ціле значення, що представляє кількість. Від’ ємні значення не допускаються, оскільки вони не відповідають нашій бізнес- логіці.» Або, якщо ви документуєте обмеження максимальної довжини: « Поле message має містити текст довжиною не більше 255 символів. Це обмеження забезпечує ефективне зберігання і запобігає несподіваним помилкам під час обробки. » Ключовим у цьому випадку є чітке вказати * чому * існує обмеження — зв’ язок з практичною причиною допомагає зрозуміти його. Аналогічно, при вказанні типів даних, не вказуйте просто « рядок ». Замість цього, вкажіть, який тип рядка очікується: « Поле name має бути рядком, що містить лише буквенно- цифрові символи і пробіли; це забезпечить послідовне форматування для ідентифікації користувача. »

Іншою областю, де часто трапляються непорозуміння, є надання прикладів. Просто перерахувати приклад недостатньо. Ты должен объяснить, что за этим стоит. Уявіть, що ви отримали коментар перегляду коду, наприклад: « Поле « стан » слід задокументувати прикладом, який чітко показує дозволені значення ». Хороша відповідь не повинна бути просто {"status": "active"}. Замість цього, програма буде писати щось на зразок: « Я оновив документацію, щоб додати приклад, що демонструє чинні параметри стану для цього поля. Зокрема, {"status": "active"} представляє обліковий запис користувача, який в даний час ввімкнений і може виконувати всі дії. Ця інформація допоможе вам забезпечити правильну заповненість даними під час ініціалізації нових користувачів. » Поясніть * наслідки * прикладу — що це означає у контексті вашої програми?

Нарешті, пам’ятайте про важливість активного голосу і уникати надмірно формальної або складної мови. Хоча технічна точність є найважливішою, прагнення до ясності і прямоти значно поліпшить розуміння. Фрази на кшталт « Його слід перевірити на …» часто можна замінити на « Це поле має …», що призводить до більш доступного і легко перетравлюваного пояснення. Розгляньте, як ви поясните ту ж саму концепцію колегі, який не має глибокого розуміння схеми JSON — цей рівень ясності є тим, чого має досягти ваша документація.