Формат переноса библиотеки#

Baseline#

• Экспорт/импорт библиотеки ДОЛЖЕН использовать расширение *.rkl.
• Контейнер *.rkl ДОЛЖЕН использовать tar.zst.
• Текстовые датасеты внутри *.rkl ДОЛЖНЫ использовать кодировку UTF-8.
• Базовый scope экспорта библиотеки включает только данные уровня библиотеки.
• Данные Raw исключаются из baseline scope экспорта/импорта библиотеки.
• Пакет переноса ДОЛЖЕН включать manifest-метаданные, версию формата и данные целостности.

Baseline структуры пакета#

• manifest.json (required)
• library.json (required)
• taxonomy.json (required)
• content.ndjson (required)
• tags.json (required)
• tag_links.ndjson (required)
• attachments.ndjson (required)
• progress.ndjson (optional)
• notes.ndjson (optional)

Baseline manifest#

• manifest.json ДОЛЖЕН включать: format, version, encoding, container, exported_at, library, datasets, integrity.
• format ДОЛЖЕН быть rkl.
• encoding ДОЛЖЕН быть utf-8.
• container ДОЛЖЕН быть tar.zst.
• library ДОЛЖЕН включать id и name.
• datasets ДОЛЖЕН включать путь и checksum для каждого включенного датасета.
• integrity ДОЛЖЕН включать алгоритм checksum и checksum manifest.

Baseline датасетов#

• library.json ДОЛЖЕН включать id, name, icon.
• taxonomy.json ДОЛЖЕН включать таксономию типов/подтипов и определения схем полей.
• Строки content.ndjson ДОЛЖНЫ включать id, type, status, created_at, updated_at, status_changed_at.
• tags.json ДОЛЖЕН включать метаданные тегов.
• Строки tag_links.ndjson ДОЛЖНЫ включать content_id, tag_id.

Правило переноса таксономии#

• Таксономия ДОЛЖНА переноситься вместе с библиотекой при export/import.
• В scope таксономии входят: типы контента, подтипы контента, схемы полей, теги и связи тег-контент.
• Импорт ДОЛЖЕН восстанавливать таксономию до или одновременно с контентными датасетами, чтобы ссылки контента оставались валидными.

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

• Формат переноса библиотеки ДОЛЖЕН поддерживать датасеты вложений (метаданные вложений и связи с контентом).

Baseline датасета вложений#

• Имя файла датасета метаданных вложений: attachments.ndjson.
• Каждая строка вложения ДОЛЖНА включать: id, content_id, uri.
• Опциональные поля строки вложения: name, mime, size, created_at.
• content_id в attachments.ndjson ДОЛЖЕН ссылаться на существующую запись контента.

Правила валидации и безопасности#

• Импорт ДОЛЖЕН отклонять пакет при отсутствии любого required датасета.
• Импорт ДОЛЖЕН отклонять пакет при ошибке checksum любого датасета.
• Импорт ДОЛЖЕН отклонять небезопасные пути в архиве (../, абсолютные пути и эквиваленты path traversal).
• Импорт ДОЛЖЕН валидировать схему и ссылки до финального commit.
• Импорт ДОЛЖЕН быть атомарным: при критической ошибке валидации частичное финальное состояние не фиксируется.

Baseline порядка импорта#

• Сначала выполняется проверка контейнера пакета и целостности manifest.
• Затем восстанавливаются метаданные библиотеки (library.json).
• Таксономия восстанавливается до контентных датасетов.
• Затем восстанавливаются контентные датасеты.
• Затем восстанавливаются теги и связи тег-контент.
• attachments.ndjson восстанавливается после контентных датасетов.
• После этого выполняется финальная проверка ссылочной целостности и атомарный commit импорта.