Документація

Вступ

API лише читає. Записи редагують через адмінку, див. нижче. Відповіді містять тільки опубліковане: виведених з ужитку записів і нотаток редакторів там немає. Id вмілостей, проб, точок проби й відзначень не змінюються, тож за ними можна зберігати, хто що здобув.

Як додати свої вмілості

Зміни вносять в адмінці. Вхід за кодом, який приходить на пошту. Права видає власник каталогу.

• Редактор краю змінює записи свого краю, додає спеціалізації й погоджує подання від свого краю.
• Дописувач лише надсилає подання. Опублікує його редактор краю.

Одну вмілість простіше додати формою в адмінці. Якщо їх багато або в них є зображення, підготуйте zip. Надсилати весь каталог не потрібно, лише те, що край додає або змінює.

prague.zip
├── catalog.json
└── images/
    ├── cz-istoriia-ukraintsiv-u-chekhii-i.svg
    └── …

В адмінці натисніть «Завантажити zip». Спершу ви побачите звіт: що буде додано чи змінено, які є помилки і яких зображень бракує. Нічого не змінюється, поки ви не підтвердите.

Зображення

• .svg, .png, .webp або .jpg, до 2 МБ, назва латиницею без пробілів.
• SVG без скриптів і посилань на зовнішні файли. Експорт з Illustrator варто пропустити через SVGOMG, це ще й зменшить файл у рази.

Перевірка без надсилання

Той самий звіт можна отримати локально з репозиторію:

dotnet run --project tools/ProjectK.Catalog.Cli -- validate prague.zip --against catalog

Формат catalog.json

{
  "schemaVersion": 2,
  "source": { "krai": "cz", "name": "Пласт у Чехії, станиця Прага", "contact": "…" },
  "badges": [
    {
      "id": "cz-istoriia-ukraintsiv-u-chekhii-i",
      "family": "cz-istoriia-ukraintsiv-u-chekhii",
      "level": 1,
      "title": "Історія українців у Чехії I",
      "categories": ["zahalni-vmilosti"],
      "ulady": ["upyu"],
      "status": "trial",
      "images": { "color": "cz-istoriia-ukraintsiv-u-chekhii-i.svg" },
      "requirements": [
        { "id": "1", "text": "Розповість про українську еміграцію до Праги в 1920-х роках." }
      ],
      "author": "ст.пл. Ім'я Прізвище",
      "updatedOn": "2026-10-13"
    }
  ]
}

source.krai — код краю, 2–3 латинські літери: ua, pl, cz, de, us, ca. Поле з помилкою в назві, наприклад requirments, не пропускається мовчки, а дає помилку перевірки.

Поля вмілості

• idобов’язкове
  string

  Латиницею, малими літерами, через дефіс. Новим записам край дає префікс свого коду: cz-. Після публікації не змінюється.

• titleобов’язкове
  string

  Назва з рівнем: «Історія українців у Чехії I».

• requirementsобов’язкове
  Requirement[]

  Пункти вимог: { "id": "1", "text": "…" }. Текст у markdown: **жирний**, *курсив*, підпункти рядками з - .

• categoriesнеобов’язкове
  string[]

  Id спеціалізацій з /v1/categories.

• uladyнеобов’язкове
  string[]

  Для яких уладів.

  Значення: upp upn upyu usp ups
• familyнеобов’язкове
  string

  Спільний id для рівнів I, II, III однієї вмілості.

• levelнеобов’язкове
  integer

  Номер рівня, 1–5.

• imagesнеобов’язкове
  object

  color і bw: назви файлів з теки images/.

• prerequisitesнеобов’язкове
  string[]

  Id вмілостей, які треба мати спершу.

• instructorRequirementsнеобов’язкове
  string

  Вимоги до інструктора.

• authorнеобов’язкове
  string

  Хто розробив.

• updatedOnнеобов’язкове
  date

  Коли востаннє змінювався текст, рррр-мм-дд.

• statusнеобов’язкове
  string

  Без статусу запис вважається затвердженим. Нові вмілості краю зазвичай починають з trial.

  Значення: approved trial retired
• kraiнеобов’язкове
  string

  Якщо не вказано, береться з source.krai.

• notesнеобов’язкове
  string[]

  Нотатки для редакторів. У публічному API їх немає.

Проби (probes) і відзначення (awards) мають ті самі поля, що й у схемах Probe та Award, тільки зображення вказуються назвами файлів, а не адресами. Id точки проби має бути унікальним серед усіх проб.

Доповнення краю

Коли край хоче додати вимогу до чужої вмілості чи ще одну точку до проби, запис не копіюють, а надсилають доповнення в overrides. Доповнення вже приймаються й перевіряються, але API їх поки не показує.

"overrides": [
  {
    "krai": "cz",
    "target": "badge:aktorstvo-i",
    "addRequirements": [{ "id": "cz-1", "text": "Візьме участь у виставі українського театру в Празі." }]
  }
]

Поля доповнення

• kraiобов’язкове
  string

  Свій код краю.

• targetобов’язкове
  string

  Що доповнюємо: badge:<id>, probe:<id> або award:<id>.

• addRequirementsнеобов’язкове
  Requirement[]

  Нові пункти вимог. Id з префіксом краю: cz-1.

• removeRequirementsнеобов’язкове
  string[]

  Id пунктів, які для краю не діють.

• addPointsнеобов’язкове
  object[]

  Нові точки проби: { "section": "А", "id": "cz-probe-1-a-1", "text": "…" }.

• removePointsнеобов’язкове
  string[]

  Id точок проби, які для краю не діють.

• titleнеобов’язкове
  string

  Інша назва для краю.

• hiddenнеобов’язкове
  boolean

  true ховає запис для краю.

• noteнеобов’язкове
  string

  Пояснення для редакторів.