= Elastic Common Schema (ECS) Reference
:doctype: book
:ecs: ECS

include::{asciidoc-dir}/../../shared/versions/stack/current.asciidoc[]
include::{asciidoc-dir}/../../shared/attributes.asciidoc[]

:ecs_repo: https://github.com/elastic/ecs/
:ecs_github_repo_link: {ecs_repo}blob/{source_branch}
:ecs_issue: {ecs_repo}issues/
:ecs_pull: {ecs_repo}pull/

[[ecs-reference]]
== Overview

This is the documentation of ECS version {{ ecs_generated_version }}.

[float]
=== What is ECS?

The Elastic Common Schema (ECS) is an open source specification,
developed with support from the Elastic user community.
ECS defines a common set of fields to be used when storing event data in Elasticsearch,
such as logs and metrics.

ECS specifies field names and Elasticsearch datatypes for each field,
and provides descriptions and example usage.
ECS also groups fields into ECS levels, which are used to signal how much a field
is expected to be present. You can learn more about ECS levels in <<ecs-guidelines>>.
Finally, ECS also provides a set of naming guidelines for adding custom fields.

The goal of ECS is to enable and encourage users of Elasticsearch to normalize their event data,
so that they can better analyze, visualize, and correlate the data represented in their events.
ECS has been scoped to accommodate a wide variety of events, spanning:

- *Event sources*: whether the source of your event is an Elastic product,
  a third- party product, or a custom application built by your organization.
- *Ingestion architectures*: whether the ingestion path for your events includes Beats processors,
  Logstash, Elasticsearch ingest node, all of the above, or none of the above.
- *Consumers*: whether consumed by API, Kibana queries, dashboards, apps, or other means.

[float]
=== New to ECS?

If you're new to ECS and looking for an introduction to its benefits and examples of the
core concepts, <<ecs-getting-started>> is a great place to start.

[float]
=== My events don't map with ECS

ECS is a permissive schema. If your events have additional data that cannot be
mapped to ECS, you can simply add them to your events, using custom field names.


[float]
=== Maturity

ECS improvements are released following https://semver.org/[Semantic Versioning].
Major ECS releases are planned to be aligned with major Elastic Stack releases.

Any feedback on the general structure, missing fields, or existing fields is appreciated.
For contributions please read the
https://github.com/elastic/ecs/blob/master/CONTRIBUTING.md[Contribution
Guidelines].



include::using-ecs/index.asciidoc[]
include::fields/fields.asciidoc[]
include::fields/field-values.asciidoc[]
include::migrating/index.asciidoc[]
include::additional-info/index.asciidoc[]
include::release-notes/index.asciidoc[]