| name | ecs-rfc-guide |
| description | Guides contributors through the Elastic Common Schema (ECS) RFC (Proposal) process: template sections, target maturity (alpha/beta), rfcs/text artifacts, and optional OTel mapping. Use when a change needs an RFC, when drafting or reviewing RFC PRs, or when the user asks how to propose new ECS field sets or substantial schema changes. |
ECS RFC (Proposal) guide
When this applies
Use after ecs-pr-triage (or equivalent judgment) says Needs RFC, or when the user is starting a new field set, breaking change, novel use case, or ECS-wide design.
Authoritative process: rfcs/PROCESS.md. Template: rfcs/0000-rfc-template.md. High-level triggers: rfcs/README.md.
Current process (short)
- Single Proposal stage — template must keep
Stage: **Proposal**.
- Contributor opens a PR that adds the RFC markdown under
rfcs/ (name like 0000-<dash-separated-name>.md until numbered).
- Specify Target maturity:
alpha, beta, or mixture (see Field stability).
- The PR author assigns the next available RFC number (scan
rfcs/text/ for the highest existing number). ECS team reviews holistically and merges on approval.
- If applicable, the RFC PR should include the schema changes (
schemas/*.yml, generated artifacts, docs) at the agreed maturity level — proposal and implementation land together in a single PR.
Template walkthrough
Copy rfcs/0000-rfc-template.md. Remove HTML comments as sections are filled.
| Section | What “good” looks like |
|---|
| Summary | 2–5 sentences: what, why, impact. |
| Usage | End-to-end: producer → storage → queries/dashboards/detections. |
| Fields | Every proposed field: name, type, description, level/maturity, example. Prefer YAML blocks. If object/flattened without children, justify shape and conflict avoidance (see schemas/README.md). |
| Source data | ≥2 real examples (JSON/logs); link or place large payloads under rfcs/text/<n>/. |
| Scope of impact | Ingestion (Beats/Agents), Kibana/apps, ECS repo (docs/tooling). |
| Concerns | Risks + resolved mitigations; OTel overlap; naming; adoption. |
| People | Author, SMEs, reviewers. |
| References | Prior art, semconv links, related issues/PRs. |
rfcs/text/<number>/ folder
When the RFC adds or changes fields:
- Create
rfcs/text/<number>/ with standalone YAML snippets, large JSON examples, or mappings — especially when the markdown would be huge.
- Use the next free folder number (scan
rfcs/text/; duplicates get fixed at merge per template notes).
- Align filenames with affected field sets (e.g.
faas.yml, gen_ai.yaml) for reviewer navigation.
OTel alignment (optional)
ECS tracks relationships between its fields and OTel semconv via otel: metadata tags in schemas/*.yml.
- When a new or changed field has a clear OTel semconv counterpart, adding an
otel: block (with relation: match | equivalent | related | conflict | na) is encouraged but not required.
- The
otel: metadata is used to generate alignment documentation — it is not a gate for merging.
- If unsure whether an OTel mapping applies, omit it; it can be added later.
Maturity choice (alpha vs beta)
- Alpha — earlier, may change more; good for exploratory or fast-moving domains.
- Beta — clearer adoption path; still subject to change before GA.
- Mixture — some fields alpha, some beta; explain per field or group.
Promotion after merge is out of band from the RFC (team process per PROCESS.md).
PR hygiene
- Link the Proposal PR at the bottom of the RFC (
### RFC Pull Requests).
- Do not replace process with old multi-stage labels found in historical RFCs under
rfcs/text/*.md; those are legacy examples only.
Example RFCs (depth reference)
Implementation in the RFC PR
The RFC PR itself should include the schema implementation: schemas/*.yml changes, make-generated artifacts, and a CHANGELOG.next.md entry. There is no separate "handoff" — proposal and schema land together.
Related
