From f008fdfe784516ec35ba23494243fbbf4ef145a8 Mon Sep 17 00:00:00 2001
From: Andrew Kroh <andrew.kroh@elastic.co>
Date: Fri, 27 Mar 2026 11:06:11 -0400
Subject: [PATCH] docs: add guidance on object and flattened field types

Add documentation to schemas/README.md explaining when object and
flattened field types are acceptable in ECS schema definitions,
and when explicit leaf fields must be used instead.

Add a review checkpoint to the RFC template requiring
contributors to justify any use of object or flattened types
without defined children.
---
 rfcs/0000-rfc-template.md |  9 +++++++++
 schemas/README.md         | 25 +++++++++++++++++++++++++
 2 files changed, 34 insertions(+)

diff --git a/rfcs/0000-rfc-template.md b/rfcs/0000-rfc-template.md
index 1ac7c95052..843963a12f 100644
--- a/rfcs/0000-rfc-template.md
+++ b/rfcs/0000-rfc-template.md
@@ -25,6 +25,15 @@ Stage X: Provide a brief explanation of why the proposal is being marked as aban
 
 <!--
 Stage 1: Describe at a high level how this change affects fields. Include new or updated yml field definitions for all of the essential fields in this draft. While not exhaustive, the fields documented here should be comprehensive enough to deeply evaluate the technical considerations of this change. The goal here is to validate the technical details for all essential fields and to provide a basis for adding experimental field definitions to the schema. Use GitHub code blocks with yml syntax formatting, and add them to the corresponding RFC folder.
+
+If any proposed field uses `type: object` or `type: flattened` without defining
+child fields, explain:
+- Why explicit leaf field definitions are not appropriate
+- The expected shape and value types of data that will appear under this field
+- How cross-integration type conflicts will be prevented
+
+See the "Guidance on `object` and `flattened` field types" section in
+schemas/README.md for details on when these types are acceptable.
 -->
 
 <!--
diff --git a/schemas/README.md b/schemas/README.md
index bb9e9fce3e..de7f6521f3 100644
--- a/schemas/README.md
+++ b/schemas/README.md
@@ -171,6 +171,31 @@ Supported keys to describe fields
   - array: the content of the field should be an array (even when there's only one value).
 - beta (optional): Adds a beta marker for the field to the description. The text provided in this attribute is used as content of the beta marker in the documentation. Note that when a whole field set is marked as beta, it is not necessary nor recommended to mark all fields in the field set as beta. Beta notices should not have newlines.
 
+#### 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.
+
+Neither type is appropriate when the subfields carry semantic meaning (e.g.,
+`mfa_enabled`, `managed`, `granted_permissions`). 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
 
 ```YAML