Open Manuscript Initiative Ръководство за стил на спецификациите

Метаданни на документа

Поле	Стойност
Тип документ	Политика за управление
Статус	Чернова
Версия	0.1.0
Нормативна терминология	Английски
Приложимо за	Спецификации, профили, регистри, схеми, примери и свързана техническа документация на „OMI“

1. Цел

Настоящото ръководство определя редакционните, структурните, терминологичните и техническите стандарти, използвани от „Open Manuscript Initiative“ (OMI).

Целта му е да гарантира, че документите на OMI са:

• точен;
• вътрешно съгласуван;
• независим от реализацията;
• достъпна за читатели от различни дисциплини;
• подходящ за нормативна техническа употреба;
• стабилен при управление на версиите и превода;
• лесни за преглед, тестване, цитиране и поддръжка.

Авторите и редакторите на техническите документи на OMI ТРЯБВА да спазват настоящото ръководство, освен ако в даден документ изрично не е отбелязано и обосновано изключение.

2. Обхват

Настоящото ръководство се отнася за:

• документи, обозначени като „OMI-SPEC-*“;
• политики за управление;
• профили за внедряване;
• регистри и контролирани речници;
• JSON Схеми и документация за схемите;
• изисквания за съответствие;
• примерни документи и тестови приспособления;
• съответствия за оперативна съвместимост;
• ръководства за миграция;
• официални преводи.

Неофициалните съобщения за проекти, наръчници, публикации в блогове и дискусии в общността ТРЯБВА да спазват правилата за терминология, изложени в това ръководство, но не е задължително да използват шаблона за пълната спецификация.

3. Нормативна терминология

Ключовите думи ТРЯБВА, НЕ ТРЯБВА, ЗАДЪЛЖИТЕЛНО, СЛЕДВА, НЕ СЛЕДВА, ТРЯБВА, НЕ ТРЯБВА, ПРЕПОРЪЧИТЕЛНО, НЕПРЕПОРЪЧИТЕЛНО, МОЖЕ и НЕЗАДЪЛЖИТЕЛНО трябва да се тълкуват като термини за нормативни изисквания, когато и само когато са изписани с главни букви.

OMI документите ТРЯБВА да използват предимно следния поднабор:

• ТРЯБВА и НЕ ТРЯБВА за изискванията за абсолютна оперативна съвместимост или съответствие;
• ТРЯБВА и НЕ ТРЯБВА за категорични препоръки с обосновани изключения;
• MAY за допустимо по избор поведение;
• ПРЕПОРЪЧИТЕЛНО, когато прозата звучи по-естествено от ТРЯБВА;
• ОПЦИОНАЛНО – когато се описва опционален компонент или поле, а не поведение при реализацията.

3.1 Степен на изискването

ЗАДЪЛЖИТЕЛНО изискване:

• е необходимо за съответствие, оперативна съвместимост, цялостност или безопасност;
• може да бъде проверено или обективно преценено;
• не е просто израз на редакционна пристрастност.

Изискване от типа SHOULD:

• определя очакваното поведение;
• допуска изключения само когато последствията са ясни;
• ТРЯБВА да се опишат тези последствия, когато това е целесъобразно.

Изявление за МАЙ:

• дава разрешение;
• не представлява препоръка;
• НЕ ТРЯБВА да се използва за описание на несигурно поведение.

3.2 Избягвайте двусмислени думи в изискванията

В нормативните документи СЛЕДВА да се избягва употребата на следните думи без уточнение:

• обикновено;
• като цяло;
• обикновено;
• подходящ;
• разумно;
• адекватен;
• просто;
• очевидно;
• удобен за ползване;
• ефективен;
• сигурен;
• стандарт.

Когато такива термини са необходими, документът ТРЯБВА да определи измерими критерии или да обясни контекста на вземането на решението.

Лошо:

Реализациите трябва да съхраняват идентификаторите по подходящ начин.

По-добре:

Реализациите ТРЯБВА да запазват стойностите на идентификаторите, без да променят регистъра, пунктуацията или процентното кодиране, освен ако спецификацията на идентификатора изрично не дефинира канонична трансформация.

3.3 По едно изискване на изречение

Нормативните изречения ТРЯБВА да изразяват едно изискване, което може да бъде проверено независимо.

Лошо:

Реализацията ТРЯБВА да проверява валидността на записа, да показва грешките и да запазва неизвестните свойства.

По-добре:

Приложението ТРЯБВА да провери валидността на записа спрямо декларираната схема.

Реализацията ТРЯБВА да докладва за грешки при валидирането.

Приложението ТРЯБВА да запазва свойствата на неизвестните разширения при двупосочен обмен без загуба на данни.

3.4 Идентификатори на изискванията

Техническите спецификации със статус Кандидат за преглед или по-късен статус ТРЯБВА да присвояват стабилни идентификатори на нормативните изисквания.

Препоръчителният формат е:

REQ-<SPEC>-<NNN>

Пример:

REQ-DOC-001
REQ-CIT-014
REQ-VAL-023

Идентификаторите на изискванията ТРЯБВА да остават непроменени в рамките на една основна версия на спецификацията. Ако дадено изискване бъде премахнато, неговият идентификатор НЕ ТРЯБВА да се преотстъпва на друго изискване.

4. Език и глас

4.1 Нормативна терминология

Официалният език на OMI е английски.

В английските спецификации СЛЕДВА да се използва технически стил, разбираем в международен план. Авторите СЛЕДВА да избягват идиоми, хумор, метафори, характерни за определена култура, и ненужни реторични изрази.

4.2 Глас

В спецификациите СЛЕДВА да се използват пряко изразени изречения.

Предпочитано:

Всяко появяване на цитат се отнася до един запис в библиотеката.

Избягвайте:

Трябва да се отбележи, че под „поява на цитат“ обикновено се разбира позоваване на един запис от библиотеката.

Активният залог се предпочита, когато по този начин се изяснява отговорността:

Валидаторът сигнализира за неподдържано свойство.

Пасивният залог МОЖЕ да се използва, когато извършителят няма значение:

Свойството не се включва в каноничния изход.

4.3 Време

Нормативното поведение ТРЯБВА да се изразява в сегашно време.

Предпочитано:

Анализаторът отхвърля невалиден идентификатор.

Избягвайте:

Анализаторът ще отхвърли невалиден идентификатор.

4.4 Лице

В спецификациите СЛЕДВА да се избягва обръщението към читателя с „ти“. Вместо това използвайте съответната роля или компонент:

• автор;
• редактор;
• прилагане;
• процесор;
• валидатор;
• рендериращ модул;
• клиент;
• сървър;
• хранилище.

4.5 Инклузивен и неутрален език

OMI В документите ЗАДЪЛЖИТЕЛНО трябва да се използва уважителен, приобщаващ и основан на ролята език. СЛЕДВА да се избягват местоименията, отнасящи се към пола, когато полът на лицето е без значение.

Примерите и илюстративните идентичности НЕ ТРЯБВА да се основават на стереотипи или да подсказват, че един език, регион, дисциплина, тип институция или модел на публикуване е стандартът за научната дейност.

5. Категории документи

Всеки технически документ на OMI ТРЯБВА да посочва своята категория.

5.1 Спецификация

Спецификацията определя нормативни структури, поведение, ограничения или изисквания за оперативна съвместимост.

Форма на идентификатора:

OMI-SPEC-NNN

5.2 Профил

Профилът избира, ограничава или разширява една или повече спецификации за определена общност, дисциплина, работен процес или контекст на публикация.

Форма на идентификатора:

OMI-PROFILE-NNN

Един профил НЕ ТРЯБВА да противоречи неявно на спецификацията, за която се отнася. Всяка умишлена несъвместимост изисква отделна версия на спецификацията или изрично посочено несъответстващо разширение.

5.3 Регистър

Регистърът дефинира контролирани идентификатори, стойности, типове медии, роли, възможности или точки за разширение.

Форма на идентификатора:

OMI-REG-NNN

Записите в регистъра ТРЯБВА да имат стабилни идентификатори и документирани състояния на жизнения цикъл.

5.4 Схема

Схемата представлява формализация, достъпна за машинно четене, на част от модела на данните на „OMI“.

Форма на идентификатора:

OMI-SCHEMA-NNN

Документът със схемата ТРЯБВА да посочва коя версия на спецификацията за проза реализира.

5.5 Пример

Официален пример илюстрира съдържание, което отговаря на изискванията, или такова, което умишлено не отговаря на тях.

Форма на идентификатора:

OMI-EXAMPLE-NNN

В примерите ЗАДЪЛЖИТЕЛНО трябва да се посочи дали те са:

• нормативен;
• информативен;
• валидно;
• невалидно;
• минимален;
• изчерпателен;
• специфично за профила.

5.6 Документ за управление

Документът за управление определя процеса на проекта, правомощията, жизнения цикъл, версионирането, редакционната практика или правилата за принос.

Документите за управление не получават идентификатори от типа „OMI-SPEC“, освен ако не определят пряко съответствието на изпълнителите.

6. Правила за именоване на файлове и идентификатори

6.1 Имена на файлове

Markdown Имената на файловете ТРЯБВА да са написани с малки букви и символи „кебаб“.

Правилно:

bibliographic-record-model.md
reference-library-architecture.md
specification-lifecycle.md

Неправилно:

BibliographicRecordModel.md
reference_library.md
Reference Library.md

6.2 Постоянни идентификатори

Постоянният идентификатор на документа НЕ ТРЯБВА да се променя, когато:

• заглавието се променя;
• файлът се премества;
• промените в категориите на страничната лента;
• документът е преведен;
• е публикувана нова второстепенна версия или версия с корекции.

6.3 Заглавия и анкери

Текстът на заглавието ТРЯБВА да остане непроменен след публикуването, тъй като генерираните препратки може да се използват от външни източници.

Когато заглавието трябва да се промени, сайтът СЛЕДВА да запази пренасочване или изрична старата връзка, където това се поддържа.

6.4 Имена на обекти

Имената на свойствата, които могат да се четат машинно, ТРЯБВА да се изписват с малки букви и „камел кейс“, освен ако друг стандарт за съпоставяне не изисква различна конвенция.

Примери:

{
  "documentLanguage": "en",
  "bibliographicTargetId": "ref-001",
  "createdAt": "2026-08-06T16:00:00Z"
}

Булевите свойства ТРЯБВА да използват утвърдителни имена, които описват състоянието „true“.

Предпочитано:

isArchived
preserveUnknownProperties
requiresReview

Избягвайте:

notArchived
noPreservation
skipNoReview

6.5 Стойности на изброените елементи

Стойностите в изброяването СЛЕДВА да се изписват с малки букви и „кебаб“ формат:

journal-article
co-author
review-candidate

След като бъдат публикувани в стабилна спецификация, стойностите на изброяването НЕ ТРЯБВА да бъдат преименувани в рамките на една и съща основна версия.

7. Задължителни метаданни за документите

Всяка спецификация ТРЯБВА да започва с метаданни, разбираеми за човека, които съдържат най-малко:

Поле	Изискване
Идентификатор	Постоянен идентификатор на OMI
Заглавие	Официално заглавие
Версия	Версия на документа
Статус	Фаза от жизнения цикъл
Вид документ	Нормативен, информативен или смесен
Редактори	Отговорни редактори или редакционна група
Последно актуализирано	Дата по ISO 8601
Заменя	Предишен документ, ако има такъв
Заменен от	Наследник, ако има такъв
Зависи от	Нормативни зависимости
Използва се от	Известни зависими спецификации
Статус на изпълнението	Обобщение или линк към матрицата за изпълнение

Встъпителната част на файла „Docusaurus“ ТРЯБВА да съдържа само метаданни за публикацията, необходими на сайта, като заглавие, етикет за страничната лента и ред на подреждане. Нормативните метаданни ТРЯБВА да останат видими в тялото на изобразяващия се документ.

8. Структура на стандартните спецификации

Нормативната спецификация „OMI“ ТРЯБВА да използва следната структура. Разделите МОГАТ да бъдат пропуснати само когато не са приложими.

8.1 Резюме

Кратко описание на това, което определя спецификацията, и защо тя съществува.

Резюмето НЕ ТРЯБВА да съдържа нормативни изисквания.

8.2 Статус на настоящия документ

В този раздел се посочва:

• статус на жизнения цикъл;
• очаквания за стабилност;
• дали твърденията за прилагане са уместни;
• дали все още е възможна несъвместима промяна;
• където се обсъждат проблемите и промените.

8.3 Съответствие

В този раздел се дефинират:

• класове на съответстваща реализация;
• задължителни функции;
• допълнителни възможности;
• връзки между профилите;
• как се проверява или декларира съответствието.

8.4 Обхват

В раздела „Обхват“ се определя какво обхваща документът.

Тя ТРЯБВА също така да включва изрична подточка Извън обхвата, когато съществува вероятност от неяснота относно границите.

8.5 Терминология

В документа ЗАДЪЛЖИТЕЛНО трябва да бъдат дефинирани специализираните термини, които все още не са дефинирани в централния терминологичен документ на OMI.

Определенията ТРЯБВА да бъдат кратки и да не съдържат кръгови определения.

8.6 Принципи на проектирането

В този информационен раздел се обясняват архитектурните принципи, които стоят в основата на спецификацията.

Принципите на проектирането НЕ ТРЯБВА да заместват подлежащите на тестване нормативни изисквания.

8.7 Модел на данните или модел на обработката

В основната част на модела се описват обектите, свойствата, връзките, състоянията и поведението при обработката.

Спецификацията в проза остава авторитетна, освен ако в документа изрично не е посочено, че за дадено подмножество авторитетен е артефактът, който може да бъде прочетен от машина.

8.8 Валидиране и обработка на грешки

Документът ТРЯБВА да определи:

• невалиден вход;
• неподдържан вход;
• предупреждения;
• отстраними и неотстраними неизправности;
• изисквания за докладване на грешки;
• поведение при съхранение.

8.9 Разширяемост

Спецификацията ТРЯБВА да посочи точките за разширение и да определи как се обработват неизвестните разширения.

Разширенията НЕ ТРЯБВА да предефинират значението на основните свойства.

8.10 Оперативна съвместимост

В този раздел се описват съответствията с външни стандарти и се разграничават:

• отражения без загуба;
• условно беззагубни съответствия;
• преобразувания със загуба;
• неподдържани конструкции.

8.11 Съображения, свързани със сигурността, поверителността и целостта

Всяка нормативна спецификация ТРЯБВА да отчита дали създава рискове, свързани с:

• активно съдържание;
• извличане на външни ресурси;
• фалшифициране на идентификатори;
• недостоверни метаданни;
• лични данни;
• скрити бележки;
• контрол на достъпа;
• целостта на подписа или на произхода;
• отказ на услуга;
• небезопасно изобразяване.

Твърдението, че не са известни конкретни съображения, е приемливо едва след изричен преглед.

8.12 Съображения, свързани с достъпността

Спецификациите, които засягат представянето или взаимодействието с потребителя, ТРЯБВА да посочват изискванията за достъпност или очакваните съответствия.

8.13 Съображения, свързани с интернационализацията

Спецификациите, засягащи текст, имена, дати, сортиране, идентификатори или визуализация, ТРЯБВА да отчитат:

• Unicode;
• езикови етикети;
• двупосочен текст;
• локализирани имена;
• вариант на скрипта;
• транслитерация;
• стойности на машината, независими от локализацията;
• часови зони и календарно представяне.

8.14 Примери

Примерите ТРЯБВА да се поместват в близост до правилото, което илюстрират. Големите пълни примери ТРЯБВА да се съхраняват като отделни валидирани файлове и да бъдат свързани чрез препратки в спецификацията.

8.15 Източници

Източниците ТРЯБВА да бъдат разделени на:

• Нормативни препратки: необходими за прилагането или тълкуването на спецификацията;
• Информативни източници: обща информация или свързани материали.

8.16 История на промените

Хронологията на версиите ТРЯБВА да обобщава съществените промени. Сама по себе си хронологията в Git не е адекватен заместител на публикуваната хронология на промените.

9. Правила за терминологията

9.1 Основни определения

Термините, чието значение се отнася до различни спецификации, ТРЯБВА да бъдат дефинирани в централния терминологичен документ на OMI.

Една спецификация МОЖЕ да стесни обхвата на даден термин в рамките на собствения си обхват, но НЕ ТРЯБВА да му придава противоречащо значение без да го посочи изрично.

9.2 Предпочитани основни термини

Следващите разграничения ТРЯБВА да бъдат запазени.

Ръкопис

Научен труд, представен като редактируем, структуриран интелектуален обект през целия му жизнен цикъл.

Документ

Конкретно структурирано представяне или пакет от съдържание. Един ръкопис може да има няколко представяния или версии на документа.

Научен обект

Идентифицируема семантична единица, намираща се в даден ръкопис или свързана с него.

Библиографска записка

Структурирано описание на цитиран или подлежащ на цитиране източник, независимо от конкретен случай на цитиране.

Справочна библиотека

Колекция от библиографски записи на ниво ръкопис, подбрани с оглед на възможно или действително цитиране.

Поява на цитати

Препратка от конкретно място в ръкописа към запис в референтната библиотека, която по желание може да включва локатори, префикси, суфикси и цел на цитирането.

Цитиране в окончателен вид

Текст на презентацията, генериран въз основа на цитиране, библиографска записка и профил за визуализация.

Анкера

Стабилна или проследима препратка към място, диапазон, обект или състояние в рамките на научното съдържание.

Анотация

Научен обект, който свързва набор от коментари или структурирана информация с един или повече обекти.

Профил

Деклариран набор от ограничения, стойности по подразбиране или разширения, приложени към една или повече спецификации на „OMI“ с определена цел.

9.3 Изписване с главна буква

Общите понятия се изписват с малки букви:

ръкопис, цитиране, профил

В официалните документи и наименованията на компонентите се използва голяма първа буква:

Модел за цитиране, Open Manuscript Studio, Регистър на спецификациите OMI

Имената на променливите и литералните стойности ТРЯБВА да бъдат форматирани като код:

Свойството „documentLanguage“ съдържа езиков таг по стандарта BCP 47.

9.4 Съкращения

Съкращението ТРЯБВА да бъде изписано изцяло при първото му употребяване в съдържателния текст, освен ако не е всеобщо познато сред целевата техническа аудитория.

Предпочитано:

Език за стилове на цитиране (CSL)

При последващо използване МОЖЕ да се използва CSL.

Акронимите НЕ ТРЯБВА да се поставят в множествено число с апостроф.

Правилно:

DOIs, APIs, URL адреси

10. Представяне на модела на данните

10.1 Описания на обектите

Всяка организация ТРЯБВА да определи:

• цел;
• идентификатор;
• жизнен цикъл;
• задължителни свойства;
• незадължителни свойства;
• взаимоотношения;
• инварианти;
• точки за разширение.

10.2 Таблици със свойства

Таблиците с свойства ТРЯБВА да използват следния ред:

Свойство	Тип	Задължително	Кардиналност	Описание

Допълнителните колони МОГАТ да включват:

• по подразбиране;
• ограничения;
• източник;
• класификация на поверителността;
• въведена версия.

10.3 Кардиналност

Кардиналността ТРЯБВА да се изразява последователно:

• 0..1 — незадължителна единична стойност;
• 1 — точно една стойност;
• 0..* — нула или повече стойности;
• 1..* — една или повече стойности.

10.4 Нулеви, липсващи и празни стойности

В спецификацията ТРЯБВА, когато е уместно, да се прави разграничение между:

• липсващ имот;
• свойство с null;
• празен низ;
• празен масив;
• неизвестна стойност;
• стойност, умишлено неразкрита;
• стойност, която не е приложима.

Тези състояния НЕ ТРЯБВА да се разглеждат като равностойни, освен ако в спецификацията изрично не е посочено друго.

10.5 Дати и часове

Датите и часовете, които могат да се четат машинно, ТРЯБВА да използват формати, съвместими с ISO 8601, както са определени в съответната схема.

Всяка моментална стойност ТРЯБВА да включва отклонение от UTC. Стойностите за UTC ТРЯБВА да използват Z.

Пример:

2026-08-06T16:10:15Z

Дата без час НЕ ТРЯБВА да се тълкува по подразбиране като конкретен момент.

10.6 Езикови етикети

При машинно четимата идентификация на езика ЗАДЪЛЖИТЕЛНО трябва да се използват езиковите маркери по BCP 47, освен ако даден стандарт за съответствие не налага друго представяне.

Примери:

en
hu
de
zh-Hant
sr-Latn

11. Примери и блокове с код

11.1 Валидност

Примерите за код, които претендират за съответствие, ТРЯБВА да са синтаксически валидни и СЛЕДВА да бъдат валидирани автоматично.

Отрезките от примери ТРЯБВА да съдържат видима индикация, като например коментар или многоточие, и НЕ ТРЯБВА да се представят като пълни валидни документи.

11.2 JSON

JSON Примерите ТРЯБВА:

• използвайте двойни кавички;
• използвайте отстъп от две интервали;
• избягвайте коментари в блокове, обозначени с json;
• използвайте стабилни идентификатори на примери;
• избягвайте използването на реални лични данни;
• Използвайте валиден Unicode.

Пример:

{
  "id": "citation-001",
  "targetId": "reference-001",
  "locator": {
    "type": "page",
    "value": "24–31"
  }
}

11.3 XML

XML В примерите ЗАДЪЛЖИТЕЛНО трябва да се декларират пространствата от имена, когато семантиката на пространствата от имена е от значение. Префиксите, използвани в примерите, СЛЕДВА да бъдат последователни в целия набор от спецификации.

11.4 URL адреси и идентификатори

В примерите СЛЕДВА да се използват запазени или явно измислени стойности, когато това е възможно.

Не използвайте идентификатори, които биха могли да бъдат объркани с действителни научни идентификатори, освен ако в примера изрично не се цитира конкретно произведение и цитирането е точно.

11.5 Положителни и отрицателни примери

Техническите характеристики ТРЯБВА да включват:

• поне един минимален валиден пример;
• поне един представителен валиден пример;
• невалидни примери за важни правила за валидиране;
• Примери за миграция при промяна на съществуващо поведение.

При невалидните примери ЗАДЪЛЖИТЕЛНО трябва да се посочи защо са невалидни.

11.6 Примери за етикети

Примерите ТРЯБВА да бъдат обозначени и цитирани последователно:

Example 1 — Minimal citation occurrence
Example 2 — Citation with a page locator
Example 3 — Invalid unresolved target

12. Фигури и диаграми

12.1 Цел

Диаграмата ТРЯБВА да изяснява взаимоотношенията, преходите между състоянията, архитектурата или процесите, които биха били трудни за разбиране само въз основа на текста.

Диаграмата НЕ ТРЯБВА да бъде единственото нормативно представяне на дадено изискване.

12.2 Достъпност

Всяка значима цифра ТРЯБВА да има:

• алтернативен текст;
• подпис;
• съответстващо обяснение в проза.

Информацията НЕ ТРЯБВА да зависи единствено от цвета.

12.3 Източник на диаграмата

Редактируемият изходен код за важни диаграми ТРЯБВА да се съхранява в хранилището заедно с експортираните ресурси.

12.4 Означения

Спецификацията ТРЯБВА да обяснява неочевидната нотация. Диаграмите от типа на UML НЕ ТРЯБВА да предполагат формална UML семантика, освен ако документът изрично не я възприеме.

13. Таблици и списъци

Таблиците ТРЯБВА да се използват за структурирано сравнение, а не като заместител на дълги прозаични откъси.

Таблицата ТРЯБВА да има ясни заглавия на колоните. Клетките СЛЕДВА да съдържат кратки стойности.

Списъците с булети са подходящи за неподредени набори. Номерираните списъци ТРЯБВА да се използват само когато редът или последователността на стъпките има значение.

Вложените списъци ТРЯБВА да бъдат ограничени, за да се запази четливостта и качеството на превода.

14. Препратки

14.1 Вътрешни препратки

При нормативни позовавания на друг документ от серията „OMI“ ТРЯБВА да се използва неговият постоянен идентификатор и СЛЕДВА да се включи заглавието му.

Предпочитано:

Вижте OMI-SPEC-006, Модел на библиографския запис.

В източника може да има относителна връзка Markdown, която да съпътства идентификатора.

14.2 Позовавания на раздели

В позоваванията СЛЕДВА да се посочва наименованието на раздела, а не само номера му, тъй като номерата могат да се променят по време на изготвянето на документа.

Предпочитано:

Вижте раздела „Нормализация на идентификаторите“ в документа OMI-SPEC-006.

14.3 Външни източници

Външните нормативни препратки ТРЯБВА да сочат към стабилни и авторитетни източници. Спецификацията ТРЯБВА да посочва версията или изданието, към което се прави препратка, когато тълкуването може да се промени между отделните версии.

14.4 Трайност на връзките

В документите СЛЕДВА да се дава предимство на постоянните идентификатори и каноничните URL адреси на документацията пред временните проектни страници.

15. Съвпадение между схемата и прозата

15.1 Правомощия

Всяка спецификация, базирана на схема, ТРЯБВА да посочва връзката на авторитет между текста и схемата.

Препоръчително правило:

• прозата определя семантиката и поведението при обработката;
• схемата определя структурни ограничения, които могат да бъдат проверени от компютър;
• конфликтът е дефект в спецификацията, който ТРЯБВА да бъде отстранен;
• Приложенията НЕ ТРЯБВА да измислят семантика единствено въз основа на механизмите на схемата.

15.2 Описания на схеми

Описанията на свойствата в схемата ТРЯБВА да използват същата терминология като текстовата спецификация и ТРЯБВА да съдържат препратки към съответното изискване или раздел, когато инструментите позволяват това.

15.3 Неизпълнение на задълженията

Схемата по подразбиране НЕ ТРЯБВА да се разглежда като инструкция за въвеждане на стойност, освен ако в текстовата спецификация изрично не е определено такова поведение при обработката.

15.4 Допълнителни свойства

В спецификациите ТРЯБВА изрично да се определи дали неизвестните свойства са:

• отхвърлено;
• пренебрегнато;
• запазени;
• подлежащи на разширения;
• допуска се само в декларирани пространства от имена.

16. Изготвяне на документи за съответствие

16.1 Класове на съответствие

Спецификацията ТРЯБВА да дефинира именовани класове на съответствие, когато не всяка реализация изпълнява една и съща роля.

Примери:

• производител, отговарящ на изискванията;
• съобразен потребител;
• валидатор за съответствие;
• съвместим рендерер;
• съвместим редактор;
• процесор за съхранение, отговарящ на изискванията.

16.2 Наблюдаемо поведение

Изискванията за съответствие ТРЯБВА да се основават на наблюдаеми входни данни, изходни данни, състояние или документирани възможности.

Избягвайте да поставяте изисквания относно вътрешната архитектура, освен ако тази архитектура не е необходима за оперативната съвместимост или сигурността.

Лошо:

Реализациите ТРЯБВА да използват релационна база данни.

По-добре:

Реализациите ТРЯБВА да запазват стабилни идентификатори на обектите при операциите по запазване и презареждане.

16.3 Допълнителни функции

Една опционална функция МОЖЕ да бъде пропусната. Ако е реализирана, тя ТРЯБВА да отговаря на всички изисквания, определени за тази функция.

16.4 Декларации за съответствие

Декларацията за съответствие ТРЯБВА да включва:

• име и версия на реализацията;
• идентификатор на спецификацията и точната версия;
• поддържан клас на съответствие;
• поддържани профили;
• известни ограничения;
• версия на набора от тестове, ако има такава.

17. Терминология, свързана с грешките и предупрежденията

OMI В документите ТЕЗИ термини ТРЯБВА да се използват последователно.

Грешка

Състояние, което нарушава нормативна изискване или пречи на правилното изпълнение на исканата операция.

Предупреждение

Състояние, което е допустимо или може да бъде отстранено, но може да доведе до загуба на информация, намалена оперативна съвместимост или неочаквани резултати.

Неподдържана функция

Функция, която е общопризната, но не се предлага в дадената реализация.

Неизвестна функция

Функция или разширение, което реализацията не разпознава.

Невалидна стойност

Стойност, която нарушава ограниченията по отношение на синтаксиса, типа, диапазона, кардиналността или семантиката.

Нерешена препратка

Препратка, чиято цел не може да бъде идентифицирана или достъпна в текущия контекст на обработка.

В спецификациите СЛЕДВА да се посочи дали всяко състояние изисква отхвърляне, възстановяване, запазване или уведомяване на потребителя.

18. Съответствия за оперативна съвместимост

Документът за картиране ТРЯБВА да прави разграничение между:

• изходен модел;
• целеви модел;
• посока на картографиране;
• определяне на предварителните условия;
• съхранена информация;
• преобразувана информация;
• пропусната информация;
• генерирана информация;
• двусмислие;
• обратимост.

Таблиците за съпоставяне ТРЯБВА да използват изрично посочени резултати, като например:

lossless
conditionally lossless
lossy
unsupported
implementation-defined

Думата „съвместим“ НЕ ТРЯБВА да се използва, без да се посочи размерът на съвместимостта.

19. Формулировки за преустановяване и замяна

Функцията, която вече не се използва, остава дефинирана, но вече не се препоръчва за ново съдържание или реализации.

Уведомленията за преустановяване на използването ТРЯБВА да съдържат следното:

• отпадналата функция;
• версията, в която е била обявена за остаряла;
• причината;
• заместителят, когато е наличен;
• насоки за миграцията;
• най-ранната версия, в която може да се извърши премахването.

Замененият документ ТРЯБВА да остане достъпен и ТРЯБВА да посочва документа, който го замества.

Нормативният текст НЕ ТРЯБВА да бъде премахван без предупреждение от публикуваните стабилни версии.

20. Класификация на редакционните промени

Всяко искане за събиране, засягащо дадена спецификация, ТРЯБВА да класифицира промените като една или повече от следните:

• редакционно пояснение;
• нормативно разяснение;
• съвместимо нормативно допълнение;
• несъвместима нормативна промяна;
• пример за поправка;
• коригиране на схемата;
• коригиране на сигурността;
• актуализация на превода;
• отпадане;
• заместване.

Класификацията ТРЯБВА да съответства на Политиката за версии на OMI.

21. Насоки за превод

21.1 Нормативен източник

Освен ако изрично не е посочено друго, спецификацията на английски език има нормативен характер, а преводите са с информативен характер.

21.2 Свързване на изходния код с версията

Всеки официален превод ТРЯБВА да съдържа:

• идентификатор на изходния документ;
• точната версия на изходния код;
• версия на превода;
• статус на превода;
• дата на последната синхронизация.

21.3 Непреводими символи

Следното ТРЯБВА да остане непроменено, освен ако в дадена спецификация не е определен локализиран етикет за показване:

• имена на свойства;
• стойности на изброяването;
• идентификатори на изисквания;
• идентификатори на схеми;
• типове медии;
• URI-адреси на пространствата от имена;
• код;
• буквални протоколни маркери.

21.4 Съгласуваност на терминологията

Официалните преводи ТРЯБВА да използват одобрен списък с терминология, специфична за съответния език. Преводачите СЛЕДВА да запазват концептуалните разграничения, дори когато в ежедневния език те често се смесват.

21.5 Нормативни ключови думи

Ключовите думи, изписани с главни букви, СЛЕДВА да останат на английски език в официалните преводи, придружени от преведено обяснение, когато това е целесъобразно. По този начин се избягва двусмислието при правната или техническата интерпретация.

22. Редактиране с помощта на изкуствен интелект

Инструментите, подпомагани от изкуствен интелект, МОГАТ да се използват за подпомагане на изготвянето, редактирането, превода, прегледа на терминологията, създаването на примери или проверката на последователността.

22.1 Отговорността на човека

Всеки публикуван документ от типа „OMI“ ТРЯБВА да има редактор или редакционна група, отговорни за:

• фактическа точност;
• нормативна коректност;
• съответствие със съществуващите спецификации;
• спазване на правата върху интелектуалната собственост;
• преглед на сигурността и поверителността;
• окончателно одобрение.

Резултатите от изкуствения интелект НЕ ТРЯБВА да се приемат за достоверни само защото са изложени гладко или в технически стил.

22.2 Проверка

Съдържанието, създадено с помощта на изкуствен интелект, ТРЯБВА да бъде проверено по отношение на:

• наборът от спецификации на източника;
• авторитетни външни стандарти;
• схеми и примери;
• поведение при изпълнение, където е уместно;
• терминология на проекта.

Генерираните цитати, идентификатори, цитати и външни препратки ТРЯБВА да бъдат независимо проверени преди публикуването.

22.3 Промени в нормативната уредба

Всяко предложение, изготвено с помощта на изкуствен интелект, което променя нормативното поведение, ТРЯБВА да отговаря на същите изисквания относно жизнения цикъл, прегледа, тестването и версионирането, както всяко предложение, изготвено от човек.

Никое нормативно правило НЕ МОЖЕ да бъде прието единствено въз основа на препоръка на изкуствен интелект.

22.4 Чувствителна информация

Редакторите НЕ ТРЯБВА да предоставят на услуга, базирана на изкуствен интелект, поверителни ръкописи, лични данни, рецензионни материали, подлежащи на ембарго, удостоверения, частни ключове или непублична информация, свързана със сигурността, освен ако услугата и контекстът на обработката не са изрично одобрени за тази информация.

22.5 Произход

Проектът МОЖЕ да отразява значителна помощ от изкуствен интелект в бележките към приносите, описанията на заявките за събиране на промени или редакционните метаданни. Такова разкриване ТРЯБВА да описва ролята на инструмента, вместо да му приписва авторство или отговорност.

Пример:

Преглед на езика и последователността с помощта на изкуствен интелект; цялото нормативни съдържание е проверено и одобрено от посочения редактор.

Незначителната помощ при правописа, граматиката, търсенето или форматирането не изисква оповестяване на ниво документ, освен ако това не се изисква от политиката на проекта или приложимите правила.

22.6 Превод

Преводите, изготвени от машинен преводач, ТРЯБВА да се разглеждат като чернови, докато не бъдат проверени от компетентен преводач или експерт по съответната тематика.

Машинният превод НЕ ТРЯБВА да бъде обозначен като официален превод на OMI без човешка проверка и потвърждаване на верността спрямо изходния текст.

23. Практики, свързани с репозиториите и pull-request-овете

23.1 Една обща загриженост

Заявката за промяна на спецификацията ТРЯБВА да се отнася до един цялостен архитектурен или редакционен въпрос. Несвързаното преструктуриране ТРЯБВА да се отделя, когато това е възможно.

23.2 Описание на заявката за събиране

В заявката за съгласуване ТРЯБВА да се посочи:

• какво се промени;
• защо се е променило;
• дали дадено поведение е нормативно;
• въздействие върху съвместимостта;
• засегнатите спецификации и схеми;
• извършена проверка;
• нерешени въпроси.

23.3 Разлики, подлежащи на преглед

Мащабното механично преформатиране ТРЯБВА да бъде отделено от съществените нормативни промени, за да могат рецензентите да установят разликите в поведението.

23.4 Създадени файлове

Генерираните артефакти ТРЯБВА да посочват източника си и командата за генериране. Генерираните файлове НЕ ТРЯБВА да се редактират ръчно, освен ако работният процес изрично не го позволява.

23.5 Валидиране

Преди сливането съответните проверки ТРЯБВА да включват:

• Markdown създаване;
• проверка на вътрешните връзки;
• JSON и проверка на синтаксиса на XML;
• валидиране на схемата;
• примерни тестове;
• проверка на терминологията;
• проверки за дублиране на идентификатори;
• проверки на ключа за превод.

24. Достъпност и четимост

OMI спецификациите ТРЯБВА да могат да се използват от читатели с различни устройства и различни нужди по отношение на достъпа.

Авторите ЗАДЪЛЖИТЕЛНО ТРЯБВА:

• използвайте логична йерархия на заглавията;
• посочете описателен текст за линка;
• да се предостави алтернативен текст за изображения с конкретно значение;
• избягвайте да предавате смисъл само чрез цвета;
• да се определя езикът на текстовете, които не са на английски, когато инструментът поддържа тази функция;
• избягвайте излишно широките таблици;
• да обясни символите и съкращенията;
• пазете абзаците да са по темата.

Техническата точност има предимство пред произволните оценки за разбираемост, но излишно сложните изречения ТРЯБВА да бъдат пренаписани.

25. Контролен списък за качество

Преди даден документ да премине в статус Кандидат за преглед, редакторите ТРЯБВА да потвърдят всички приложими точки по-долу.

25.1 Определение и обхват

• Документът има постоянен идентификатор.
• Декларирани са версията и състоянието на жизнения цикъл.
• Границите на обхвата и извън обхвата са ясно определени.
• Изброени са зависимостите и свързаните с тях спецификации.

25.2 Терминология

• Термините съответстват на терминологията на „OMI“.
• Определени са нови термини.
• Подобните понятия се разграничават последователно.
• Имената на свойствата и литералните стойности се форматират съгласно правилата за кодиране.

25.3 Нормативно качество

• Нормативните ключови думи са използвани умишлено.
• Изискванията могат да бъдат тествани независимо едно от друго.
• Идентификаторите на изискванията се присвояват, когато е необходимо.
• Поведението при липса на указания е изрично определено.
• Определена е обработката на грешки.
• Класовете за съответствие се дефинират при необходимост.

25.4 Модели и примери

• Единиците, връзките и кардиналностите са изрично посочени.
• Разграничават се липсващи, нулеви, празни и неизвестни състояния.
• Примерите са синтаксически правилни.
• Показани са важни случаи на невалидност.
• Примерите не разкриват лични или поверителни данни.

25.5 Оперативна съвместимост

• Външните съответствия определят посоката и загубата на информация.
• Определена е обработката на неизвестни разширения.
• Документирани са ефектите от версията и миграцията.
• Схемата и прозата са съгласувани.

25.6 Преглед на рисковете

• Съображенията, свързани със сигурността, бяха преразгледани.
• Разгледани са въпросите, свързани с поверителността и произхода.
• Взети са предвид съображенията за достъпност.
• Разгледани са въпросите, свързани с интернационализацията.

25.7 Публикуване

• Вътрешните връзки се отварят.
• Нормативните и информативните препратки са разделени.
• Историята на промените е актуализирана.
• Сайтът се създава успешно.
• Официалните преводи посочват точната версия на изходния текст.

26. Изключения

Една спецификация МОЖЕ да се отклони от настоящото ръководство, когато предметът изисква различно представяне или нотация.

Изключението ТРЯБВА:

• бъдете конкретни;
• да има ограничен обхват;
• посочете причината;
• да се запази оперативната съвместимост и възможността за преразглеждане;
• да бъде одобрено чрез обичайната процедура за разглеждане.

Само удобството или запазването на стария формат не са достатъчно основание за постоянна изключение.

27. Поддържане на настоящото ръководство

Настоящото ръководство се регулира от Политиката за жизнения цикъл и версиите на спецификациите на „OMI“.

Редакционните корекции МОГАТ да бъдат публикувани като версии на кръпки. Съвместимите допълнения МОГАТ да бъдат публикувани като второстепенни версии. Промените, които нарушават установената структура на документа, идентификаторите или тълкуването, изискват основна версия.

Промените в настоящото ръководство ТРЯБВА да бъдат оценени с оглед на тяхното въздействие върху:

• съществуващите спецификации;
• официални преводи;
• автоматизирани инструменти;
• документация за схемата;
• външни източници;
• работен процес на авторите.

28. Обобщение

OMI Спецификациите трябва да представляват нещо повече от просто обяснителен текст. Те са дългосрочни технически споразумения между автори, редактори, издатели, хранилища, разработчици на софтуер, системи за съхранение и бъдещи изпълнители.

Следователно последователната структура, точната терминология, изискванията, които могат да бъдат тествани, трайните идентификатори, проверените примери и отчетната редакционна проверка са съществени части от самия стандарт.