Преминете към основното съдържание

OMI-SPEC-330 — Контейнерна архитектура

Статус​

Чернова

Версия: 0.1.0

Старият идентификатор: OMI-SPEC-012

Зависи от: OMI-SPEC-320 (формат на файла)

Цел​

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

Контейнерът допълва спецификацията „File Format“: OMI-SPEC-320 определя логическото представяне на ръкописа, докато настоящата спецификация определя как свързаните файлове се обединяват в един пакет.

Препоръчително разположение на контейнерите​

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

paper.omi
├── META-INF/
│   ├── manifest.json
│   ├── mimetype
│   ├── checksums.json
│   └── signatures.json
├── manuscript/
│   ├── document.json
│   ├── metadata.json
│   ├── history.json
│   └── review.json
├── annotations.json
├── citations.json
├── anchors.json
├── provenance.json
├── media/
│   ├── images/
│   ├── figures/
│   ├── assets/
│   └── datasets/
├── profiles/
└── plugins/

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

Контейнерът на „OMI“ трябва да бъде:

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

META-INF​

Директорията „META-INF“ съдържа информация за управление на ниво пакети.

manifest.json​

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

mimetype​

Файлът „mimetype“ определя типа на носителя на пакета. Точната му стойност и изискванията за разположението му ще бъдат определени преди достигането на статуса „Кандидат за преглед“.

checksums.json​

Контролните суми позволяват на системите да откриват случайно променяне или повреждане на данните.

signatures.json​

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

Елементи на ръкописа​

Директорията „manuscript“ съдържа основните структурирани представяния:

  • document.json — структура и съдържание на ръкописа;
  • metadata.json — описателни, административни и консервационни метаданни;
  • history.json — версия и история на промените;
  • review.json — прегледайте обектите, включени в пакета.

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

Файлове за взаимоотношенията​

Пакетът може да съхранява колекциите от връзки поотделно:

  • annotations.json;
  • citations.json;
  • anchors.json;
  • provenance.json.

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

Медии и ресурси​

Двоичните файлове и ресурсите, създадени от външни автори, трябва да се поместват в media.

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

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

Профили и плъгини​

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

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

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

Компресиране и сериализация​

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

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

Валидиране​

Проверката на контейнерите трябва да включва:

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

Съображения, свързани със сигурността​

Реализациите трябва да третират контейнерите като недостоверни входни данни.

Процесорите трябва да се защитават срещу:

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

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

Хронология на промените​

  • 0.1.0 — Прехвърлено от временния адрес OMI-SPEC-012 към основния адрес OMI-SPEC-330; поправена е неправилната структура на Markdown и са разширени първоначалните изисквания към пакетите.

Обобщение​

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

Той определя структурата и целостта на ниво пакет, като оставя семантиката на ръкописа на формат на файловете „OMI“ и свързаните с него спецификации на модела.