ecs-field-mappings

ecs-field-mappings

When to use

Use this skill when tasks include:

• adding or modifying files under data_stream/<stream>/fields/
• populating ecs.yml with ECS field references
• selecting event.kind, event.category, event.type, and event.outcome values
• choosing field type and mapping properties (metric_type, dimension, multi_fields, and related options)
• checking whether a field already exists in ECS before adding custom fields
• troubleshooting mapping validation/build failures from elastic-package check, elastic-package lint, or pipeline test schema checks

ECS dependency configuration

Every package needs _dev/build/build.yml at the package root. This file pins the ECS schema version used for field resolution.

dependencies:
  ecs:
    reference: "[email protected]"

This file is required whenever the package has any field file. The scaffold does not generate it — create it manually. If it is missing or uses an outdated version, tests report ECS fields as undefined (e.g., field "destination.ip" is undefined).

Field files and roles

A data stream's fields/ directory contains a small set of YAML files with distinct responsibilities:

base-fields.yml

Fixed routing constants and @timestamp. All six fields are ECS fields, so each entry uses external: ecs. Override type and value where the data stream needs a constant_keyword with a fixed value — the description is inherited from ECS automatically.

- name: data_stream.type
  external: ecs
- name: data_stream.dataset
  external: ecs
- name: data_stream.namespace
  external: ecs
- name: event.module
  external: ecs
  type: constant_keyword
  value: <package_name>
- name: event.dataset
  external: ecs
  type: constant_keyword
  value: <package_name>.<stream_name>
- name: '@timestamp'
  external: ecs

Do not add other fields here. Only these routing constants and @timestamp belong in base-fields.yml.

constant_keyword candidates