What is the Elastic Common Schema (ECS)?
ECS is an open specification of common field names and types for logs and security events, now converging with OpenTelemetry semantic conventions.
Definition
Elastic Common Schema
Also called ECS
The Elastic Common Schema (ECS) is an open-source specification that defines common field names, data types, and descriptions for storing logs, metrics, and security events, so data from different sources can be analyzed and correlated together.
How it works
Elastic's reference describes ECS as an open-source specification, developed with support from the Elastic user community, that defines a common set of fields for storing event data such as logs and metrics in Elasticsearch. For each field it specifies the name, the Elasticsearch data type, a description, and example usage. It groups fields into levels that signal how often a field is expected to be present, and provides naming guidelines for custom fields. The stated goal is to let users normalize their event data so they can better analyze, visualize, and correlate it.
Fields are grouped into field sets: source.ip, destination.port, user.name, host.hostname, process.command_line, event.category, event.outcome, and so on. ECS is permissive, so events can carry extra fields beyond the schema.
A few guidelines from Elastic matter most when mapping a new source:
- Every document must have
@timestamp, andecs.versionrecords which ECS version the mapping follows. - Populate core fields first. ECS marks each field as core (common across use cases and relied on by searches, dashboards, and alerts) or extended (narrower use cases, more likely to change).
- Field names are lowercase, use underscores to join words, and nest with dots.
- For custom fields, Elastic suggests capitalized names, since ECS never uses capitals and so won't collide with them in a future version.
In 2023, Elastic and OpenTelemetry announced they would converge ECS and OpenTelemetry Semantic Conventions into a single open schema maintained by OpenTelemetry, with OpenTelemetry's conventions becoming the successor to ECS. The announcement noted that ECS brings schema coverage for security-domain fields.
Example
A Windows process event, a Linux audit event, and an EDR event all describe a process starting, each with different native field names. Mapped to ECS, all three carry event.category: process, process.name, process.command_line, and user.name. A detection for a suspicious command line is then written once against process.command_line and covers every source.
Why it matters for a SOC
Schema choice decides how much work every detection and query takes. Elastic's public detection-rules repository ships ECS schemas alongside its rules, and content written for ECS-shaped data carries over to any tool that stores data in the same shape. Teams choosing a schema today usually weigh ECS and its OpenTelemetry successor against OCSF, and in every case the real cost is maintaining the normalization mappings for each source.
Related terms
- Log normalizationLog normalization is the process of converting each field in log data from many different sources into a consistent name, format, and data type, so events can be searched, correlated, and analyzed together.
- SIEMA SIEM (security information and event management) system collects security logs from across an organization, stores them in one searchable place, and runs detection rules over them so a security team can find, investigate, and respond to threats.
- Detection engineeringDetection engineering is the practice of designing, building, testing, deploying, and maintaining the rules and analytics that turn security telemetry into alerts, treated with the rigor of software engineering.
Go deeper
FAQ
- What is the difference between ECS and OCSF?
- Both are open schemas for normalizing security data. ECS grew out of the Elastic Stack and is converging with OpenTelemetry semantic conventions. OCSF is a vendor-neutral security event schema whose categories organize event classes, each aligned with a specific domain.
Sources
- Elastic Common Schema (ECS) reference · accessed November 16, 2026
- GitHub - elastic/ecs · accessed November 16, 2026
- Open Cybersecurity Schema Framework · accessed November 16, 2026
- GitHub - elastic/detection-rules · accessed November 16, 2026
- Announcing the Elastic Common Schema (ECS) and OpenTelemetry Semantic Convention Convergence · accessed November 16, 2026
- ECS guidelines and best practices | Elastic Docs · accessed November 16, 2026
- Custom fields in ECS | Elastic Docs · accessed November 16, 2026
