Define an Entity Merge algorithm (from OTEP #264)

specification/entities/data-model.md

@@ -18,6 +18,7 @@ weight: 2
 - [Resource and Entities](#resource-and-entities)
   * [Attribute Referencing Model](#attribute-referencing-model)
   * [Placement of Shared Descriptive Attributes](#placement-of-shared-descriptive-attributes)
+- [Merging of Entities](#merging-of-entities)
 - [Examples of Entities](#examples-of-entities)
 
 <!-- tocstop -->
@@ -149,6 +150,42 @@ different values, then **only** the `k8s.node` entity can reference this key
 Other entities (e.g., `k8s.cluster`) can report this attribute in a separate
 telemetry channel (e.g., entity events) where full ownership context is known.
 
+## Merging of Entities
+
+Entities MAY be merged if and only if their types are the same, their
+identity attributes are exactly the same AND their schema_url is the same.
+This means both Entities MUST have the same identity attribute keys and
+for each key, the values of the key MUST be the same.
+
+Here's an example algorithm that will check compatibility:
+
+```
+can_merge(e, e') {
+  e.type == e'.type &&
+  e.schema_url == e'.schema_url &&
+  has_same_attributes(e.identity, e'.identity)
+}
+```
+
+When merging entities, all attributes in description are merged together, with
+one entity acting as "primary" where any conficting attribute values will be
+chosen from the "primary" entity.
+
+Here's an example algorithm that will merge:
+
+```
+merge(e, e') {
+  if can_merge(e, e') {
+    for attribute in e'.description {
+      if !e.description.contains(attribute.key) {
+        e.description.insert(attribute)
+      }
+      // Ignore otehrwise.
+    }
+  }
+}
+```
+
 ## Examples of Entities
 
 _This section is non-normative and is present only for the purposes of

specification/resource/data-model.md

@@ -13,6 +13,8 @@ weight: 2
 <!-- toc -->
 
 - [Identity](#identity)
+- [Merging Resources](#merging-resources)
+  * [Merging Entities into a Resource](#merging-entities-into-a-resource)
 
 <!-- tocstop -->
 
@@ -47,3 +49,35 @@ different if one contains an entity not found in the other.
 Some resources include raw attributes in additon to Entities. Raw attributes are
 considered identifying on a resource. That is, if the key-value pairs of
 raw attributes are different, then you can assume the resource is different.
+
+## Merging Resources
+
+Note: The current SDK specification outlines a [merge algorithm](sdk#merge).
+This specification updates the algorithm to be compliant with entities. This
+section will replace that section upon stabilization of entities. SDKs SHOULD
+NOT update their merge algorithm until full Entity SDK support is provided.
+
+Merging resources is an action of joining together the context of observation.
+That is, we can look at the resource context for a signal and *expand* that
+context to include more details (see 
+[telescoping identity](README.md#telescoping)). As such, a merge SHOULD preserve
+any identity that already existed on a Resource while adding in new identifying
+information or descriptive attributes.
+
+### Merging Entities into a Resource
+
+We define the following algorithm for merging entities into an existing
+resource.
+
+- Construct a set of existing entities on the resource, `E`.
+  - For each entity, `new_entity`, in priority order (highest first),
+    do one of the following:
+    - If an entity `e'` exsits in `E` with the same entity type as `new_entity`:
+       - Perform a [Entity DataModel Merge](../entities/data-model.md#merging-of-entities), if applicable, otherwise ignore `new_entity`.
+    - Otherwise, add the entity `new_entity` to set `E`
+- Update the Resource to use the set of entities `E`.
+  - If all entities within `E` have the same `schema_url`, set the
+    resources `schema_url` to match.
+  - Otherwise set the Resource `schema_url` blank.
+  - Remove any attribute from `Attributes` which exists in either the
+    description or identity of an entity in `E`.