ecs

Fields supported in schemas/*.yml

YAML with a twist: Flattened field names equivalent to nested. E.g. foo.bar: value and foo:\n bar: value.

Note that we use the wording “schema” and “field set” alternatively to mean the same concept: a group of related fields.

Field set heading

Required field set attributes:

Optional field set attributes:

Field set reuse

Unless otherwise noted via the reusable attribute, a field set is a group of fields that will be defined at the root of the events. As an example, the fields of the event field set are nested like: {"event": {"id": "foo"}}.

Field set reuse lets us define a group of fields that’s expected to be used in multiple places, like for example geo, which can appear under source, destination and other places:

{
  "source": { "ip": "10.10.10.10", "geo": { "country_name": "..." } },
  "destination": { "ip": "10.42.42.42", "geo": { "country_name": "..." } }
}

The reusable attribute is composed of a few sub-attributes:

The “flat” (or dotted) notation to represent where the fields are nested:

  reusable:
    top_level: false
    expected:
      - network
      - network.inner

The above would nest field set vlan at network.vlan.* and network.inner.vlan.*:

{
  "network": {
    "vlan": { },
    "inner": {
      "vlan": {}
    }
  }
}

In some cases we need to nest a field set within itself, as a different name, which can be thought of loosely as a “role”. A good example is nesting process at process.parent, to capture the parent of a process. In these cases, we replace the “flat” key name with a small object with keys at and as:

  reusable:
    top_level: true
    expected:
      - { at: process, as: parent }

The above defines all process fields in both places:

{
  "process": {
    "pid": 4242,
    "parent": {
      "pid": 1
    }
  }
}

The alpha or beta marker can optionally be used along with at and as to include a maturity marker in the field reuses section, marking specific reuse locations as alpha or beta. These notices should not have newlines. A reuse entry cannot have both alpha and beta.

  reusable:
    top_level: true
    expected:
    - at: user
      as: target
      alpha: Reusing these fields in this location is currently considered alpha.
    - at: user
      as: effective
      beta: Reusing these fields in this location is currently considered beta.

The short_override marker can optionally be used along with at and as to set the short description of the nested field, instead of defaulting to the top-level fieldset’s short description. Like short, descriptions must not have newlines.

  reusable:
    top_level: true
    expected:
    - at: user
      as: target
      short_override: My special target short description.

List of fields

Array of YAML objects:

- name: version
  level: core
  type: keyword

Supported keys to describe fields

Guidance on object and flattened field types

An object type field with no defined children creates a namespace where any producer can define arbitrary subfields with any type. This bypasses ECS’s type coordination guarantees — conflicts between producers cannot be detected or prevented by ECS.

A flattened type field indexes all leaf values as keywords regardless of their actual type. This avoids the mapping explosion that object causes when the key names are arbitrary (e.g., HTTP headers), but it sacrifices typed querying and aggregation.

Use of object with no defined children is acceptable only when the field represents opaque, source-specific data with a homogeneous and well-defined shape — for example, string keys with string values only (like labels and container.labels). Use of flattened is acceptable when the key names are arbitrary and unbounded, making object impractical due to mapping explosion (e.g., raw event payloads like entity.raw).

Neither type is appropriate when the subfields carry semantic meaning that consumers would need to query or aggregate on independently. In those cases, the subfields must be defined as explicit leaf fields in the schema with specified types and descriptions. Defining a container and deferring leaf definitions to individual integrations defeats the purpose of a common schema.

Supported keys to describe expected values for a field

  allowed_values:
  - name: authentication
    description: ...
  - name: process
    description: ...
    expected_event_types:
      - start
      - iamgroot

Supported keys when using the alias field type

    - name: a_field
      level: extended
      type: alias
      path: another_field
      description: >
        An alias of another field.

Multi_fields

Minimal example

- name: my_fields
  title: My fields
  description: My awesome fields.
  fields:

    - name: a_field
      level: extended
      type: keyword
      example: 42
      description: >
        A description

        with multiple paragraphs

        requires you to provide a 'short' description as well.
      short: A short version of the description.

    - name: another_field
      level: extended
      type: keyword
      multi_fields:
      - type: text
        name: text
      example: I am Groot
      description: A short description that doesn't require an explicit 'short'.
This site is open source. Improve this page.