docs: add guidance on object and flattened field types

rfcs/0000-rfc-template.md

@@ -27,6 +27,13 @@ Describe at a high-level how these field changes will be used in practice. Real
 If the changes include field additions or modifications, please create a folder under rfcs/text/ named with the next available RFC number (check existing folders to find it; any duplicates will be corrected at merge). This is where proposed schema changes as standalone YAML files or extended example mappings and larger source documents should go.
 
 Describe how this change affects fields. Include new or updated yml field definitions for all fields in this proposal. For each proposed field, include at minimum: name, type, description, maturity level and example value(s). The list should be exhaustive and comprehensive enough to deeply evaluate the technical considerations of this change. The goal here is to validate the technical details for all fields and to provide a basis for adding the field definitions to the schema at the target maturity level. 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.
 -->
 
 ## Source data

schemas/README.md

@@ -195,6 +195,16 @@ Supported keys to describe fields
       attribute: exception.message
   ```
 
+#### 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
 
 ```YAML