Справочник
Манифест состава
Формат 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устроен так же — строка с JSONholkas-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:
- Записать
name, затем перевод строки LF. - Для каждой строки
items, в её исходном порядке, записатьtype, TAB,name, TAB,origin, TAB,source. Отсутствующий илиnull-источник записывается пустым текстом. - Если
parameterнеnullи не пустая строка, дописать TAB и исходный текст параметра. Если параметра нет — не дописывать даже TAB. Завершить строку LF. - Закодировать полученный текст как 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, а не путь к локальному файлу.