package-spec

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

package-spec

Skill authority

技能权威性

The rules and patterns defined in this skill and its reference files are the authoritative source of truth. When examining existing integrations in the

elastic/integrations

repository for reference, you may encounter patterns that conflict with what is specified here -- many integrations contain legacy patterns that predate current standards. Always follow this skill over patterns observed in other integrations. If a reference integration uses a deprecated or prohibited pattern, do not copy it.

本技能及其参考文件中定义的规则和模式是权威的事实来源。在

elastic/integrations

仓库中查看现有集成作为参考时，你可能会遇到与本规范冲突的模式——许多集成包含的旧模式早于当前标准。请始终遵循本技能的要求，而非其他集成中观察到的模式。如果某个参考集成使用了已弃用或被禁止的模式，请勿复制。

When to use

使用场景

Use this skill when tasks include:

building or reviewing
```
manifest.yml
```
at root or data stream level
adding or validating
```
changelog.yml
```
entries
selecting the correct change type and semantic version bump
configuring policy templates, inputs, and variable declarations
debugging
```
elastic-package lint
```
or
```
elastic-package check
```
errors on manifests or changelogs
reviewing variable scoping across package, policy template, input, and data stream levels
validating Handlebars template variables against manifest declarations
configuring routing rules and their required manifest flags
determining which
```
format_version
```
is needed for a package's features

当你需要完成以下任务时，使用本技能：

构建或审核根目录或数据流级别的
```
manifest.yml
```
添加或验证
```
changelog.yml
```
条目
选择正确的变更类型和语义化版本升级规则
配置策略模板、输入和变量声明
调试
```
elastic-package lint
```
或
```
elastic-package check
```
在清单或变更日志上的错误
审核包、策略模板、输入和数据流级别的变量作用域
验证Handlebars模板变量与清单声明的一致性
配置路由规则及其所需的清单标志
确定包的功能需要哪个
```
format_version
```

When NOT to use

不适用场景

Package scaffolding and directory layout (
```
create-integration
```
)
Ingest pipeline design (
```
ingest-pipelines
```
)
Field mapping and ECS compliance (
```
ecs-field-mappings
```
)
CEL programs (
```
cel-programs
```
)

Transform configuration (see

review-integration

skill's

references/transform-guide.md

)

包脚手架和目录布局（参考
```
create-integration
```
技能）
摄入管道设计（参考
```
ingest-pipelines
```
技能）
字段映射与ECS合规性（参考
```
ecs-field-mappings
```
技能）
CEL程序（参考
```
cel-programs
```
技能）

转换配置（参考

review-integration

技能的

references/transform-guide.md

）

Handoff

交接指引

For package directory layout and required files, see

create-integration

references/package-layout.md

. For

elastic-package

CLI commands and troubleshooting, see

elastic-package-cli

关于包目录布局和所需文件，请查看

create-integration

references/package-layout.md

。关于

elastic-package

CLI命令和故障排除，请查看

elastic-package-cli

技能。

format_version

The

format_version

field in

manifest.yml

declares which elastic/package-spec version the package conforms to. The current standard for new packages is

"3.4.2"

Use the minimum version that supports the features the package actually uses, not the latest available spec version. Bumping without needing new features:

forces users to run a newer Kibana than necessary
breaks backward compatibility for no reason
makes it harder to determine which features the package depends on

Only bump when the package uses a feature introduced in a newer spec version:

Feature	Minimum format_version
Basic package structure	1.0.0
Input-level variables	2.0.0
`elasticsearch.privileges`	2.3.0
`routing_rules.yml` support	2.9.0
`lifecycle` field	3.0.0
Secret variables ( `secret: true` )	3.0.0
`elasticsearch.source_mode`	3.0.3

See

references/format-version-features.md

for the full feature-to-version table including recent spec additions (3.6.0+), and

references/manifest-rules.md

for the review procedure.

manifest.yml

中的

format_version

字段声明了包遵循的elastic/package-spec版本。新包的当前标准版本为

"3.4.2"

。

请使用支持包实际使用功能的最低版本，而非最新可用的规范版本。无需求升级版本会：

强制用户运行比实际需要更新的Kibana
无故破坏向后兼容性
难以确定包依赖的功能

只有当包使用了新版本规范中引入的功能时，才升级版本：

功能	最低format_version
基础包结构	1.0.0
输入级变量	2.0.0
`elasticsearch.privileges`	2.3.0
`routing_rules.yml` 支持	2.9.0
`lifecycle` 字段	3.0.0
机密变量（ `secret: true` ）	3.0.0
`elasticsearch.source_mode`	3.0.3

完整的功能对应版本表（包括3.6.0+的最新规范新增内容）请查看

references/format-version-features.md

，审核流程请查看

references/manifest-rules.md

。

conditions.kibana.version

The current standard constraint is

"^8.19.0 || ^9.1.0"

. This is set in the root

manifest.yml

only -- data stream manifests must NOT set their own

conditions

When an integration uses features that require a newer agent (e.g., CEL functions introduced in v9.3.0), the constraint must be adjusted accordingly. For systematic version verification of CEL features, see the

review-integration

skill's version check references.

当前的标准约束为

"^8.19.0 || ^9.1.0"

。此约束仅在根目录的

manifest.yml

中设置——数据流清单不得设置自己的

conditions

。

当集成使用需要更新Agent的功能时（例如，v9.3.0中引入的CEL函数），必须相应调整约束。关于CEL功能的系统版本验证，请查看

review-integration

技能的版本检查参考文档。

Variable scoping

变量作用域

Fleet variables exist at four levels:

Package level --
```
manifest.yml
```
top-level
```
vars:
```
Policy template level --
```
manifest.yml
```
under
```
policy_templates[].vars:
```

Input level --

manifest.yml

under

policy_templates[].inputs[].vars:

Data stream level --

data_stream/*/manifest.yml

under

streams[].vars:

A variable declared in an inner scope must not reuse the name of a variable in an outer scope. This is variable shadowing and is rejected by

elastic-package

validation.

See

references/manifest-rules.md

-> Variable shadowing for full rules, examples, and common patterns.

Fleet变量存在四个级别：

包级别——
```
manifest.yml
```
顶层的
```
vars:
```
策略模板级别——
```
manifest.yml
```
中
```
policy_templates[].vars:
```
下的变量

输入级别——

manifest.yml

中

policy_templates[].inputs[].vars:

下的变量

数据流级别——

data_stream/*/manifest.yml

中

streams[].vars:

下的变量

内部作用域中声明的变量不得重用外部作用域中的变量名称。这种变量遮蔽行为会被

elastic-package

验证拒绝。

完整规则、示例和常见模式请查看

references/manifest-rules.md

-> 变量遮蔽部分。

Manifest rules (brief)

清单规则（简要）

Every Handlebars
{{var}}
must be declared in a manifest -- undeclared variables silently resolve to empty strings. Handlebars helpers (
```
{{#if}}
```
,
```
{{#each}}
```
,
```
{{#unless}}
```
,
```
{{#contains}}
```
) and built-in variables (
```
{{data_stream.type}}
```
,
```
{{data_stream.dataset}}
```
,
```
{{data_stream.namespace}}
```
,
```
{{output}}
```
) are exempt.
Routing rules require dynamic flags -- when a data stream uses
```
routing_rules.yml
```
, the data stream manifest must declare
```
elasticsearch.dynamic_dataset: true
```
and
```
elasticsearch.dynamic_namespace: true
```
.
Use proper YAML nesting, not dotted keys --
```
elasticsearch.dynamic_dataset
```
as a literal key name creates a single flat key, not a nested object. Use nested
```
elasticsearch:
```
->
```
dynamic_dataset:
```
structure.

See

references/manifest-rules.md

for complete rules, correct/incorrect examples, and the review checklist.

每个Handlebars
{{var}}
必须在清单中声明——未声明的变量会静默解析为空字符串。Handlebars辅助函数（
```
{{#if}}
```
、
```
{{#each}}
```
、
```
{{#unless}}
```
、
```
{{#contains}}
```
）和内置变量（
```
{{data_stream.type}}
```
、
```
{{data_stream.dataset}}
```
、
```
{{data_stream.namespace}}
```
、
```
{{output}}
```
）除外。
路由规则需要动态标志——当数据流使用
```
routing_rules.yml
```
时，数据流清单必须声明
```
elasticsearch.dynamic_dataset: true
```
和
```
elasticsearch.dynamic_namespace: true
```
。
使用正确的YAML嵌套，而非点式键——将
```
elasticsearch.dynamic_dataset
```
作为字面键名会创建一个扁平键，而非嵌套对象。请使用嵌套的
```
elasticsearch:
```
->
```
dynamic_dataset:
```
结构。

完整规则、正确/错误示例和审核清单请查看

references/manifest-rules.md

。

Changelog schema

变更日志Schema

changelog.yml

is a version-grouped array; newer versions go on top:

yaml

- version: "1.2.0"
  changes:
    - description: Added example parsing for edge-case payloads.
      type: enhancement
      link: https://github.com/elastic/integrations/pull/12345

Each entry requires

description

type

, and

link

. Valid types:

enhancement

bugfix

breaking-change

changelog.yml

是按版本分组的数组；新版本条目放在顶部：

yaml

- version: "1.2.0"
  changes:
    - description: Added example parsing for edge-case payloads.
      type: enhancement
      link: https://github.com/elastic/integrations/pull/12345

每个条目需要

description

、

type

和

link

。有效的类型包括：

enhancement

、

bugfix

、

breaking-change

。

Version bump rules

版本升级规则

patch (
```
x.y.Z
```
): bug fixes and low-risk fixes
minor (
```
x.Y.z
```
): new content -- new data streams, new fields, new features
major (
```
X.y.z
```
): breaking changes -- field type changes or removals on existing integrations, ECS mapping conflicts, required config/auth changes that break existing policies, data stream restructuring, default behavior changes that alter collected or normalized data

补丁版本（
```
x.y.Z
```
）：bug修复和低风险修复
次版本（
```
x.Y.z
```
）：新增内容——新数据流、新字段、新功能
主版本（
```
X.y.z
```
）：破坏性变更——现有集成的字段类型变更或移除、ECS映射冲突、破坏现有策略的必需配置/认证变更、数据流重构、改变采集或标准化数据的默认行为变更

Adding changelog entries

添加变更日志条目

Edit

changelog.yml

directly, or use

elastic-package changelog add

(see

elastic-package-cli

skill for command flags and

--next patch|minor|major

usage).

直接编辑

changelog.yml

，或使用

elastic-package changelog add

（命令标志和

--next patch|minor|major

用法请查看

elastic-package-cli

技能）。

Common changelog pitfalls

常见变更日志陷阱

Adding the entry under the wrong version or not at the top
Missing
```
link
```
field --
```
elastic-package lint
```
validates that the PR/issue number is a positive integer and rejects
```
pull/0
```
; use a real PR number or
```
pull/99999
```
as a development placeholder and replace before merge
Bumping manifest/package version inconsistently with changelog intent

See

references/changelog-patterns.md

for detailed patterns, breaking-change checklist, and CI examples.

将条目添加到错误版本下或未放在顶部
缺少
```
link
```
字段——
```
elastic-package lint
```
会验证PR/issue编号是否为正整数，并且拒绝
```
pull/0
```
；使用真实的PR编号或
```
pull/99999
```
作为开发占位符，并在合并前替换
清单/包版本升级与变更日志意图不一致

详细模式、破坏性变更清单和CI示例请查看

references/changelog-patterns.md

。

Upstream: elastic/package-spec

上游参考：elastic/package-spec

The elastic/package-spec repository is the upstream authority for package structure, manifest schema, and validation rules. The

spec/changelog.yml

in that repo documents which features were added in each spec version.

Key points from the package-spec versioning model:

Packages must specify
```
format_version
```
in root
```
manifest.yml
```
A package at
```
format_version: x.y.z
```
must be valid against specs in the range
```
[x.y.z, X.0.0)
```
where
```
X = x + 1
```
Patch versions may add stricter validations (e.g., 3.6.0 added pipeline tag and on_failure validation)
Minor versions add new feature support
Major versions are reserved for significant format changes

See

references/format-version-features.md

for the curated feature-to-version table.

elastic/package-spec仓库是包结构、清单Schema和验证规则的上游权威。该仓库中的

spec/changelog.yml

记录了每个规范版本中新增的功能。

包规范版本模型的关键点：

包必须在根目录
```
manifest.yml
```
中指定
```
format_version
```
```
format_version: x.y.z
```
的包必须在
```
[x.y.z, X.0.0)
```
范围内的规范下有效，其中
```
X = x + 1
```
补丁版本可能添加更严格的验证（例如，3.6.0新增了管道标签和on_failure验证）
次版本添加新功能支持
主版本保留用于重大格式变更

整理后的功能对应版本表请查看

references/format-version-features.md

。

Reference files

参考文件

File	Contains
`references/manifest-rules.md`	Full rules for format_version selection, variable shadowing, Handlebars variable declarations, routing rules, YAML structure, and severity-tagged review checklist
`references/changelog-patterns.md`	Changelog entry patterns, semver rules, breaking-change checklist, CI examples
`references/format-version-features.md`	Feature-to-version table sourced from elastic/package-spec, including recent spec additions

文件	内容
`references/manifest-rules.md`	format_version选择、变量遮蔽、Handlebars变量声明、路由规则、YAML结构的完整规则，以及带严重程度标记的审核清单
`references/changelog-patterns.md`	变更日志条目模式、语义化版本规则、破坏性变更清单、CI示例
`references/format-version-features.md`	源自elastic/package-spec的功能对应版本表，包括最新规范新增内容