Holkas
Написать в поддержку Поддержка

Справочник

Манифест состава

Формат holkas-manifest/2 — список объектов для повторного переноса. Поля файла, описание DAT и SCR в parameter, контрольная сумма и причины отказа при импорте.

На этой странице

Что сохраняет манифест

Манифест задаёт какие объекты выбрать из источника: тип, имя и описание отбора строк у набора данных. Скрипт автора хранит в описании и сам SQL, и правила его запуска. Определения классов, тела функций и строки справочников в нём не хранятся. Их Holkas прочитает из источника при построении нового плана; скрипт автора возьмёт из самого состава.

Имя — ключ манифеста: двух манифестов с одним именем не бывает. Отдельной версии нет; номер релиза пишут в имени, например «Зарплата 8.5.6.1». Имя не фиксирует состояние базы или коммит Git. Если нужна передача конкретного снимка, используйте ZIP-пакет либо нужную версию Git. Работа с манифестом в интерфейсе — Сохранить состав доработки.

Поля файла

Файл — JSON в UTF-8. Имена полей пишутся в camelCase, как в таблицах ниже; строки и регистр значений важны. Экспорт Holkas опускает поля со значением null.

ПолеТипНазначение
formatСтрокаholkas-manifest/2. Прежний holkas-manifest/1 тоже принимается (см. ниже). Другая метка отклоняется.
nameНепустая строкаИмя сохранённого состава; по нему определяется, есть ли уже такой манифест.
descriptionСтрока, необязательнаяПояснение к составу.
exportedAtСтрока даты и времениМомент экспорта. Штатный экспорт записывает UTC в ISO 8601.
exportedByСтрока, необязательнаяКто выгрузил файл. Не выдаёт права на источник или приёмник.
itemsМассивСтроки состава. Пустой список допустим, но объектов для переноса в нём нет.
hashСтрокаsha256: и 64 шестнадцатеричных символа в нижнем регистре. При чтении сравнивается с вычисленной суммой.

Список верхних полей описывает штатный экспорт. Проверка структуры файла, контрольной суммы и проверка существования объектов в источнике — разные этапы.

Строка items

ПолеТипНазначение
typeНепустая строкаКод типа Holkas, например CLS, JFP, DAT. Для новых файлов используйте коды из справочника объектов.
nameНепустая строкаИмя объекта в источнике.
originСтрокаОдно из трёх значений: manual, catalog, describer. Другие значения отклоняются.
sourceСтрока, необязательнаяСохранённая информация об источнике добавления строки. Это происхождение записи, а не команда подключиться по указанному адресу.
parameterСтрока, необязательнаяJSON-текст описания: holkas-dataset/1 для DAT, holkas-script/1 для SCR (скрипт автора). Непустой параметр у другого типа отклоняется.

origin показывает, откуда строка попала в состав: вручную, из каталога подключения или через описатель. При импорте и повторном раскрытии он не запускает описатель заново и не меняет выбранный источник переноса.

Дубли при импорте не становятся двумя независимыми позициями. Для сопоставления Holkas приводит тип к коду, имя сравнивает без учёта регистра и сохраняет первую строку, включая её происхождение и параметр. При этом контрольная сумма проверяется до удаления дублей, по всем строкам исходного файла.

Описание DAT внутри parameter

У скрипта автора (SCR) parameter устроен так же — строка с JSON holkas-script/1, — а его поля описаны на странице Скрипт автора. Всё сказанное ниже о строке и контрольной сумме относится и к нему.

У обычного объекта достаточно типа и имени. Для чтения набора данных из базы нужно ещё описание: какую таблицу, границу, части и ссылки использовать.

parameter — строка с JSON, а не вложенный JSON-объект. Поэтому в полном манифесте видны \" и, если внутри текста были переносы, \n. После разбора внешнего JSON это обычный текст описания. Читаемый отдельный файл того же учебного набора есть на странице Описание набора данных.

Условная строка состава с минимальным описанием (это фрагмент, не полный файл с контрольной суммой):

{
  "type": "DAT",
  "name": "Статусы согласования",
  "origin": "manual",
  "parameter": "{\"format\":\"holkas-dataset/1\",\"name\":\"Статусы согласования\",\"root\":{\"table\":\"EXTRA_DICTS\",\"key\":[\"CODE\"],\"where\":{\"keys\":[[\"HKSITE_STATUS\"]]}},\"prune\":false}"
}

В полном учебном файле описана также часть EXTRA_DICTS_VALUES. Не заменяйте его параметр сокращённым фрагментом: это изменит состав переносимых строк и контрольную сумму файла.

Имя внутри описания должно в точности совпадать с items[].name. Сам импорт манифеста ещё не проверяет пригодность описания DAT по базе. При раскрытии состава неверное или отсутствующее описание даст пометку no_definition с пояснением; строку нужно исправить перед планом.

Как вычисляется hash

Что именно защищает контрольная сумма

Входит в hash

name
Имя манифеста — оно же ключ. В прежнем формате /1 сюда входила и version.
items · в порядке списка
Для каждой строки: type, name, origin, source и непустой parameter.
parameter · буквальный текст
Даже перенос строки внутри описания DAT изменит вычисленную сумму.

Не входит в hash

description
Пояснение к составу.
exportedAt + exportedBy
Время экспорта и имя экспортировавшего пользователя.
Отступы внешнего JSON
Сумма вычисляется по разобранным значениям полей.
Проверка целостности выбранных полей
name + LF + строки → UTF-8 → SHA-256

Это не электронная подпись. Тот, кто изменил состав и пересчитал hash, может получить другой корректный файл.

Правила holkas-manifest/2. Они относятся к отдельному манифесту состава; у manifest.json внутри ZIP-пакета другая структура и нет такого поля hash.

Алгоритм фиксирован для holkas-manifest/2:

  1. Записать name, затем перевод строки LF.
  2. Для каждой строки items, в её исходном порядке, записать type, TAB, name, TAB, origin, TAB, source. Отсутствующий или null-источник записывается пустым текстом.
  3. Если parameter не null и не пустая строка, дописать TAB и исходный текст параметра. Если параметра нет — не дописывать даже TAB. Завершить строку LF.
  4. Закодировать полученный текст как UTF-8 без BOM, вычислить SHA-256 и записать его в нижнем шестнадцатеричном регистре с префиксом sha256:.

Для файла прежнего формата holkas-manifest/1 после name и LF идут ещё version и LF — остальное так же. Скрипт ниже проверяет оба формата.

Здесь TAB — символ \t, LF — \n; это не два печатных символа обратной косой черты и буквы. В конце последней строки тоже есть LF. Значения не обрезаются и не сортируются. Пробельная строка parameter считается непустой для расчёта суммы, хотя не является пригодным описанием набора.

Внешний JSON можно переформатировать, если разобранные значения сохранятся. Но переформатирование JSON внутри строки parameter меняет её текст и требует другой суммы. Перестановка items тоже меняет сумму. format не входит в сумму, но проверяется отдельно на точное значение.

Проверить файл без Holkas

Следующий скрипт Python 3 вычисляет сумму по указанному правилу и сравнивает с hash. Он читает файл и ничего не меняет. Это проверка суммы, а не полная проверка схемы или доступности объектов.

import hashlib
import json
import sys

with open(sys.argv[1], encoding="utf-8") as file:
    manifest = json.load(file)

lines = [manifest["name"]]
if manifest["format"] == "holkas-manifest/1":
    lines.append(manifest["version"])
for item in manifest.get("items") or []:
    fields = [item["type"], item["name"], item["origin"], item.get("source") or ""]
    if item.get("parameter"):
        fields.append(item["parameter"])
    lines.append("\t".join(fields))

payload = ("\n".join(lines) + "\n").encode("utf-8")
actual = "sha256:" + hashlib.sha256(payload).hexdigest()
print(actual)
sys.exit(0 if actual == manifest["hash"] else 1)

Сохраните как check_manifest.py и запустите:

python3 check_manifest.py contracts-manifest.json

Код завершения 0 означает совпадение суммы. Само совпадение не подтверждает автора файла: в формате нет электронной подписи. Для обычного изменения состава проще отредактировать манифест в Holkas и выгрузить заново.

Что проверяется при импорте

Сначала Holkas разбирает JSON, проверяет метку формата и имя, затем сумму и строки состава. У файла holkas-manifest/1 после проверки суммы версия переходит в имя: «1» отбрасывается, другая версия дописывается через пробел («Зарплата» + 8.5.6.1 → «Зарплата 8.5.6.1»). После этого Holkas проверяет, нет ли уже манифеста с таким именем. Существующий состав не перезаписывается молча.

Видимость в файл не попадает: загруженный манифест виден только тому, кто его загрузил, и администратору, пока автор не сделает его общим.

Успешный импорт означает, что список принят. Он не подтверждает наличие объектов в выбранной базе. Для этого раскройте манифест против источника: получите ok, unsupported_type, not_in_source, unchecked или no_definition. Отдельно проверяются описание DAT по базе и фактическая граница строк.

КодПричинаСледующее действие
manifest_unreadableНеразбираемый JSON, пустой файл, нет имени (у /1 — имени или версии) или строка без типа/имени.Сверить полный файл и его поля; повторно скачать экспорт.
manifest_formatДругая метка формата, неизвестный origin или параметр у типа, которому он не положен.Сверить формат и версию Holkas. Не заменять метку без преобразования содержимого.
manifest_hashВычисленная сумма не совпадает с hash.Проверить передачу и ручные изменения; получить согласованный файл заново.
duplicate_nameМанифест с таким именем уже существует.Сверить имеющийся состав; чтобы загрузить файл рядом, переименуйте существующий манифест в Holkas.

Импорт и экспорт доступны в интерфейсе, CLI, REST и MCP. В MCP аргумент file — содержимое JSON, а не путь к локальному файлу.