YAADMINTwo schemas, different purposes#
The external/community package schema is not the builtin YAADMIN schema. Do not copy builtin yaadmin licensing/publisher fields into a community manifest and assume they are accepted.
External manifest fields#
Required top-level fields are schema_version, id, name, version, description, controlhub and entrypoints. Optional fields are enabled_by_default, publisher, permissions, configuration and python_dependencies.
| Field | Published contract |
|---|---|
schema_version | Constant 1 |
id | Pattern ^[a-z][a-z0-9_]*$ |
name, version, description | Nonempty strings; module version is not enforced SemVer here |
controlhub.sdk_major | Constant 1 |
controlhub.min_version | Optional nonempty string |
entrypoints.modules, entrypoints.integrations, entrypoints.backends | ID-to-dotted-import-path maps |
publisher.name, publisher.url | Optional nonempty strings |
enabled_by_default | Boolean, external default false |
python_dependencies | Unique nonempty dependency strings |
The manifest ID must appear in at least one entrypoint map. Reserved yaadmin_/controlhub_ identities and first-party publisher impersonation are rejected for community packages.
Tool contract#
RegisteredTool requires name, module, description, risk and fn. Optional fields are approval, timeout_seconds, tags, enabled, target_required, supports_dry_run, idempotent, input_schema and output_schema.
Defaults include approval=POLICY, timeout_seconds=120, enabled=true and false for target_required/supports_dry_run/idempotent. Input/output schemas are optional. Runtime validates names, enum values, handler callability, timeout and flags.
Permission contract#
Permission declarations require module_id, code and title. Optional fields are description, category, tool_names and resolver_kinds. Codes use the module namespace and pattern ^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$. Duplicate codes are rejected.
Settings contract#
Configuration entries require env_name and title. Optional fields are kind, description, required, restart_required and placeholder. Kinds are text, bool, number and secret; env names start with CONTROLHUB_. Runtime setting defaults include restart_required=true.
Package and validation#
module.json
python/
your_package/
module.pyValidation imports Python. Module entries require METADATA.name matching the entry ID, a callable register and matching primary version/permission-code sets. Integration entries require NAME and callable load_config; backend entries require callable register.
Localization and tests#
UA/RU/EN localization is SDK guidance, with actual en/ru/uk dictionaries in Codex. Mandatory localization validation is not universal. Test source covers manifest/loader/contract expectations; reading tests is not evidence that they passed in a deployment.
Lifecycle and updates#
Install/uninstall changes need restart; already discovered modules support enable/disable. Generic administration provides settings/health/detail. No automatic dependency installer or universal update callback is proven. .yaupdate validation belongs to Update Manager, not ordinary module upload.