OMI Интеграция с „API“ версия 1

Статус: Чернова
Идентификатор на протокола: omi-integration/1

1. Цел

Интеграцията „OMI“ (API) дефинира независим от платформата договор между реализация на „Open Manuscript Initiative“, като например Open Manuscript Studio, и външна научна система.

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

API“ не превръща Studio в собственик на външен редакционен работен процес. Той осигурява контролирана граница, през която могат да се обменят преносими научни обекти и контекст на работния процес.

2. Език за съответствие

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

Една реализация, която претендира за съответствие с „omi-integration/1“, ТРЯБВА да реализира откриването на възможности и ТРЯБВА да идентифицира всяка поддържана опционална възможност.

3. Роли в архитектурата

Протоколът разграничава четири логически роли.

3.1 Услугата „OMI“

Услугата „OMI“ хоства или обработва преносими научни обекти. Open Manuscript Studio е една от възможните услуги от типа „OMI“.

3.2 Външна платформа

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

3.3 Съединител

Коннекторът съпоставя родовите данни, разрешенията и жизнения цикъл на външната платформа с интеграцията „OMI“ API. Коннекторът МОЖЕ да бъде реализиран като плъгин, модул, услуга или шлюз.

3.4 Потребителски агент

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

4. Обща лексика, свързана с ресурсите

В „API“ се използват умишлено общи имена на ресурсите.

4.1 Инсталиране

Един идентификатор на „installation“ съответства на едно внедряване на външна платформа.

Примери:

една инсталация на „OJS“;
една инсталация на „OMP“;
един институционален архив;
един наемател на услугата за хостинг на публикации.

4.2 Контекст

„context“ е организационната или издателската сфера в рамките на дадена инсталация.

Примери:

списание на „OJS“;
преса от типа „OMP“;
колекция от хранилища;
конференция;
институционална единица.

Коннекторите НЕ ТРЯБВА да приемат, че context означава journal.

4.3 Подаване

„submission“ е научен обект или обект от работния процес, управляван външно, свързан с ръкопис в OMI.

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

4.4 Компонент

„component“ е част от подаденото или публикуваното съдържание, която е ограничена в обхвата си.

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

Компонентите МОГАТ да бъдат вложени, когато външната платформа поддържа йерархия.

4.5 Съавтор

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

4.6 Файл

Един „file“ представлява защитен или публичен двоичен ресурс, управляван от една от свързаните системи.

4.7 Задание за преглед

Идентификаторът „reviewAssignment“ представлява официалното външно възлагане на работа по рецензиране на даден рецензент или на неговата идентичност.

4.8 Кръг за преглед

Идентификаторът „reviewRound“ обозначава отделен цикъл на преглед за дадено подаване или компонент.

4.9 Ревизия

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

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

„publication“ представлява състоянието на публикацията или метаданните, управлявани от външната платформа за публикуване.

5. Идентификатори на ресурси

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

Приложението „OMI“ СЛЕДВА да съхранява туплата:

installationId + resourceType + externalId

като каноничен външен източник.

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

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

Пример:

{
  "installationId": "pkp-example",
  "resourceType": "submission",
  "externalId": "1542",
  "uri": "urn:example:ojs:submission:1542"
}

6. Базов път към API

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

/api/integrations/v1/

При внедряването е ВЪЗМОЖНО сайтът „API“ да бъде монтиран под пътя на друго приложение, но семантиката на ресурсите ТРЯБВА да остане непроменена.

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

7. Определяне на възможностите

7.1 Крайна точка

GET /api/integrations/v1/capabilities

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

Пример за отговор:

{
  "protocol": "omi-integration/1",
  "implementation": {
    "name": "Open Manuscript Studio",
    "version": "0.1.0"
  },
  "capabilities": [
    "launch",
    "metadata.read",
    "files.read",
    "manuscript.read",
    "manuscript.write",
    "review.read",
    "review.write",
    "revision.write",
    "publication.export"
  ]
}

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

8. Регистър на първоначалните възможности

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

Възможност	Значение
`launch`	Влизане на потребител с удостоверение в работна среда на OMI
`metadata.read`	Прочети метаданни за външно подаване
`metadata.write`	Записване на разрешените метаданни във външната система
`contributors.read`	Прочетете за сътрудниците и ролите с ограничен обхват
`contributors.write`	Разрешено е въвеждането на промени от сътрудниците
`files.read`	Изброяване и извличане на оторизирани файлове
`files.write`	Качване на файлове във външния работен поток
`manuscript.read`	Извличане на представяне на ръкопис от „OMI“
`manuscript.write`	Изпратете представяне на ръкопис за списанието „OMI“
`review.read`	Извличане на контекста на оторизирания преглед
`review.write`	Връщане на структурирани резултати от прегледа
`revision.read`	Извличане на историята на версиите или метаданните за версиите
`revision.write`	Създаване на нова външна ревизия
`publication.read`	Прочитане на метаданни/състояние, свързани с публикацията
`publication.export`	Експортиране на производни на публикации

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

9. Подписано представяне

Операцията по стартиране позволява на оторизиран потребител във външна платформа да влезе в съответното работно пространство на OMI, без да се разкрива базата данни или частната сесия на външната платформа.

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

{
  "protocol": "omi-integration/1",
  "installationId": "pkp-example",
  "context": {
    "externalId": "1",
    "type": "journal"
  },
  "submission": {
    "externalId": "1542"
  },
  "actor": {
    "externalId": "27"
  },
  "scope": ["manuscript.read", "manuscript.write"],
  "issuedAt": "2026-08-07T18:00:00Z",
  "expiresAt": "2026-08-07T18:05:00Z",
  "nonce": "b4b65f2b-0c63-4c21-8b82-876728f0bd31"
}

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

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

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

Пример за контекст от списание:

{
  "externalId": "1",
  "type": "journal",
  "name": {"en": "Example Journal"},
  "url": "https://journal.example.org/"
}

Пример за контекст в пресата:

{
  "externalId": "3",
  "type": "press",
  "name": {"en": "Example University Press"},
  "url": "https://press.example.org/"
}

Полето „type“ е описателно и разширяемо. Клиентите НЕ ТРЯБВА да отхвърлят иначе валиден контекст единствено поради това, че неговият тип е неизвестен.

11. Метаданни за подаването

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

{
  "externalId": "1542",
  "type": "article",
  "status": "review",
  "title": {
    "en": "Example manuscript",
    "hu": "Példa kézirat"
  },
  "abstract": {
    "en": "Example abstract"
  },
  "keywords": {
    "en": ["history", "publishing"]
  },
  "primaryLocale": "en",
  "identifiers": [],
  "updatedAt": "2026-08-07T17:30:00Z"
}

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

12. Съавтори

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

{
  "externalId": "author-12",
  "name": {
    "given": "Ada",
    "family": "Example"
  },
  "roles": ["author"],
  "scope": {
    "type": "submission",
    "externalId": "1542"
  },
  "identifiers": [
    {"scheme": "orcid", "value": "0000-0000-0000-0000"}
  ]
}

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

13. Компоненти

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

{
  "externalId": "chapter-7",
  "type": "chapter",
  "parentExternalId": null,
  "title": {"en": "Chapter Seven"},
  "sequence": 7
}

Коннекторът на статия от типа „OJS“ МОЖЕ да не показва никакви компоненти. Коннекторът на публикация от типа „OMP“ МОЖЕ да показва глави, предни и задни части, приложения или други компоненти на публикацията.

14. Обмен на файлове

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

{
  "externalId": "file-889",
  "name": "manuscript.docx",
  "mediaType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
  "size": 482931,
  "stage": "submission",
  "checksum": {
    "algorithm": "sha256",
    "value": "..."
  }
}

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

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

15. Обмен на ръкописи

Когато се поддържат manuscript.read или manuscript.write, предпочитаният каноничен обект за обмен е пакет от типа „OMI“, който отговаря на приложимите спецификации за формат на файловете и архитектурата на контейнерите на OMI.

Коннекторите МОГАТ допълнително да поддържат производни формати като JATS, HTML или DOCX.

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

16. Модел за преразглеждане

При операциите по редактиране ПРОИЗХОДЪТ ТРЯБВА да се запази.

Протоколът за преразглеждане ТРЯБВА да съдържа:

{
  "externalId": "revision-4",
  "sequence": 4,
  "createdAt": "2026-08-07T18:20:00Z",
  "createdBy": {"externalId": "27"},
  "source": "omi",
  "parentExternalId": "revision-3"
}

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

17. Рецензиране от колеги

17.1 Правомощия

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

17.2 Проверка на представянето на заданията

{
  "externalId": "review-991",
  "roundExternalId": "round-2",
  "target": {
    "type": "submission",
    "externalId": "1542"
  },
  "reviewMode": "double-anonymous",
  "dueAt": "2026-09-01T23:59:59Z",
  "permissions": ["manuscript.read", "review.write"]
}

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

17.3 Анонимност

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

17.4 Резултат от структурирания преглед

{
  "assignmentExternalId": "review-991",
  "recommendation": "revisions-required",
  "summary": "The argument is promising but requires clarification.",
  "annotations": [
    {
      "anchor": "omi:anchor:01J...",
      "visibility": "author-and-editor",
      "body": "Please provide a source for this statement.",
      "status": "open"
    }
  ]
}

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

18. Обмен на публикации

Ресурсите за публикации МОГАТ да предоставят метаданни, свързани с публикациите, както и изисквания за производни материали. Профилите от типа „OJS“ могат да свързват статуса на публикацията със статии и броеве; профилите от типа „OMP“ могат да го свързват с монографии, поредици, глави, формати на публикации и каталожни записи.

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

19. Картографиране на профили в „OJS“

Един конектор от типа „OJS“ ТРЯБВА да съответства на:

ресурс „OMI“	концепция „OJS“
инсталация	инсталация на „OJS“
контекст	списание
подаване	обект от работния поток „подаване/статия“
компонент	опционален компонент на статията
сътрудник	автор/сътрудник
файл	файл за подаване
преглед на задачата	преглед на задачата
кръг на преглед	кръг на преглед
ревизия	проследимо състояние на подаване/ревизия
публикация	OJS публикация/статия статус на публикацията

Коннекторът „OJS“ ТРЯБВА да използва поддържаните услуги на приложението „OJS“, хранилища и хукове, а не директен достъп до различни бази данни от Studio.

20. Картографиране на профили в „OMP“

Един конектор от типа „OMP“ ТРЯБВА да съответства на:

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

Конъкторът „OMP“ ТРЯБВА да запазва обхвата на съавторите, когато това е възможно, и НЕ ТРЯБВА да обединява авторството на ниво глава в авторство на цялата книга.

21. Обхват на разрешенията

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

metadata.read
metadata.write
contributors.read
contributors.write
files.read
files.write
manuscript.read
manuscript.write
review.read
review.write
revision.read
revision.write
publication.read
publication.export

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

22. Семантика на HTTP

JSON Крайните точки ТРЯБВА да използват UTF-8 JSON и СЛЕДВА да използват следния тип медия:

application/json

Бъдещите типове медии, специфични за „OMI“, МОГАТ да бъдат регистрирани за канонични пакети или структурирани ресурси.

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

200 успешно четене или актуализиране;
201 създаден е нов ресурс;
204 успешна операция без отговор от тялото;
400 неправилно оформено заявка;
401 липсваща или невалидна автентификация;
403 автентифициран, но без разрешение;
404 ресурсът не е намерен или е умишлено скрит;
409 конфликт при синхронизиране или ревизия;
410 външният ресурс е умишлено премахнат;
422 семантично невалиден полезен товар;
429 Превишена е квотата.

23. Представяне на грешки

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

{
  "error": {
    "code": "revision_conflict",
    "message": "The external manuscript has changed since the requested base revision.",
    "details": {
      "expectedRevision": "revision-3",
      "currentRevision": "revision-4"
    }
  }
}

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

24. Паралелизъм и синхронизация

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

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

25. Идемпотентност

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

26. Изисквания за сигурност

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

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

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

27. Защита на личните данни и поверителност на прегледа

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

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

28. Произход

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

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

29. Елегантно прекъсване на връзката

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

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

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

30. Възможност за разширение

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

Пример:

{
  "extensions": {
    "org.pkp.ojs": {
      "stageId": 3
    }
  }
}

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

31. Договаряне на версията

Идентификаторът на протокола за тази спецификация е:

omi-integration/1

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

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

32. Профили за съответствие

Един бъдещ регистър от типа „OMI“ МОЖЕ да публикува профили с имена, като например:

omi-integration/1/core
omi-integration/1/ojs
omi-integration/1/omp
omi-integration/1/repository
omi-integration/1/review

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

33. Непроменлива характеристика на проекта

Интеграционният API ТРЯБВА да запази архитектурното разделение между научния обект и платформата за работни потоци.

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

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

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

1. Цел​

2. Език за съответствие​

3. Роли в архитектурата​

3.1 Услугата „OMI“​

3.2 Външна платформа​

3.3 Съединител​

3.4 Потребителски агент​

4. Обща лексика, свързана с ресурсите​

4.1 Инсталиране​

4.2 Контекст​

4.3 Подаване​

4.4 Компонент​

4.5 Съавтор​

4.6 Файл​

4.7 Задание за преглед​

4.8 Кръг за преглед​

4.9 Ревизия​

4.10 Публикуване​

5. Идентификатори на ресурси​

6. Базов път към API​

7. Определяне на възможностите​

7.1 Крайна точка​

8. Регистър на първоначалните възможности​

9. Подписано представяне​

10. Представяне на контекста​

11. Метаданни за подаването​

12. Съавтори​

13. Компоненти​

14. Обмен на файлове​

15. Обмен на ръкописи​

16. Модел за преразглеждане​

17. Рецензиране от колеги​

17.1 Правомощия​

17.2 Проверка на представянето на заданията​

17.3 Анонимност​

17.4 Резултат от структурирания преглед​

18. Обмен на публикации​

19. Картографиране на профили в „OJS“​

20. Картографиране на профили в „OMP“​

21. Обхват на разрешенията​

22. Семантика на HTTP​

23. Представяне на грешки​

24. Паралелизъм и синхронизация​

25. Идемпотентност​

26. Изисквания за сигурност​

27. Защита на личните данни и поверителност на прегледа​

28. Произход​

29. Елегантно прекъсване на връзката​

30. Възможност за разширение​

31. Договаряне на версията​

32. Профили за съответствие​

33. Непроменлива характеристика на проекта​