First cut at Entity API + SDK specification.

specification/entities/README.md

@@ -26,3 +26,5 @@ traces, metrics, logs, profiles etc.
 ## Specifications
 
 - [Data Model](./data-model.md)
+- [API](./api.md)
+- [SDK](./sdk.md)

specification/entities/api.md

@@ -0,0 +1,80 @@
+<!--- Hugo front matter used to generate the website version of this page:
+linkTitle: API
+--->
+
+# Entities API
+
+**Status**: [Development](../document-status.md)
+
+<!-- toc -->
+
+- [Overview](#overview)
+- [ResourceProvider](#resourceprovider)
+  * [ResourceProvider operations](#resourceprovider-operations)
+    + [Get the active Resource](#get-the-active-resource)
+  * [Resource](#resource)
+  * [Attach an Entity](#attach-an-entity)
+
+<!-- tocstop -->
+
+## Overview
+
+The Entities API is provided for instrumentation authors to build
+[Entities](./data-model.md#entity-data-model) and report them
+against the OpenTelemetry [Resource](../resource/README.md) for all signals.
+
+This detection of the environment and its entities is expected
+to happen early / immediately in the lifespan of a system being
+observed, however, the Entities are allowed to change over the
+lifespan of the Resource.
+
+The Entities API consists of these main components:
+
+- [ResourceProvider](#resourceprovider)
+- [Resource](#resource)
+
+## ResourceProvider
+
+`Resource`s can be accessed with a `ResourceProvider`.
+
+Normally, the `ResourceProvider` is expected to be accessed from a central place.
+Thus, the API SHOULD provide a way to set/register and access a global default
+`ResourceProvider`.
+
+### ResourceProvider operations
+
+The `ResourceProvider` MUST provide the following functions:
+
+* Get the active `Resource`
+
+#### Get the active Resource
+
+This API MUST return the current `Resource` for which Telemetry
+is being reported.
+
+### Resource
+
+The `Resource` is responsible for emitting `Entity`s and tracking
+the current set of entities attached to the `Resource`.
+
+The `Resource` MUST provide a function to:
+
+- [Attach an Entity](#attach-an-entity)
+
+### Attach an Entity
+
+The effect of calling this API is to attach (or update) an Entity
+to the current `Resource`.
+
+The API MUST accept the following parameters:
+
+- `entity_type`: A string that uniquely identifies the type of Entity.
+  See [entity data model](./data-model.md#entity-data-model) for details.
+- `identity`: Specifies the attributes which identify the entity.
+  This API MUST be structured to accept a variable number of
+  attributes, but must see at least one attribute.
+- `description` (optional): Specifies the attributes which describe the
+  entity. This API MUST be structured to accept a variable number
+  of attributes, including none.
+- `schema_url` (optional): Specifies the Schema URL that should be recorded in
+  the emitted telemetry.

specification/entities/sdk.md

@@ -0,0 +1,123 @@
+<!--- Hugo front matter used to generate the website version of this page:
+linkTitle: SDK
+--->
+
+# Entities SDK
+
+**Status**: [Development](../document-status.md)
+
+<!-- toc -->
+
+- [Overview](#overview)
+- [ResourceProvider](#resourceprovider)
+  * [ResourceProvider Creation](#resourceprovider-creation)
+  * [Active Resource](#active-resource)
+  * [Configuration](#configuration)
+  * [Shutdown](#shutdown)
+  * [ForceFlush](#forceflush)
+- [Resource](#resource)
+  * [Attach an Entity](#attach-an-entity)
+  * [Flattened Resource](#flattened-resource)
+  * [Resolve conflicts in Schema URL](#resolve-conflicts-in-schema-url)
+
+<!-- tocstop -->
+
+## Overview
+
+Users of OpenTelemetry need a way for instrumentation interactions with the
+OpenTelemetry API to actually produce telemetry. The OpenTelemetry Entities SDK
+(henceforth referred to as the SDK) is an implementation of the OpenTelemetry
+API that provides users with this functionally.
+
+All language implementations of OpenTelemetry MUST provide an SDK.
+
+The Entities SDK consists of these main components:
+
+- [ResourceProvider](#resourceprovider)
+- [Resource](#resource)
+
+## ResourceProvider
+
+The ResourceProvider MUST provide a way to retrieve the current
+[Resource](../resource/sdk.md) for use in there parts of the OpenTelemetry SDK.
+This `Resource` MUST include all registered `Entity`s.
+
+### ResourceProvider Creation
+
+The SDK SHOULD allow the creation of multiple independent `ResourceProvider`s.
+
+### Active Resource
+
+This SDK MUST implement the
+[Get the active Resource API](api.md#get-the-active-resource).
+
+The SDK MUST provide exactly one `Resource` per `ResourceProvider` via this API.
+
+### Configuration
+
+TBD
+
+### Shutdown
+
+TBD
+
+### ForceFlush
+
+TBD
+
+## Resource
+
+The SDK `Resource` is responsible for managing the current set of associated
+`Entity`s on the `Resource.
+
+The SDK MUST track associated `Entity`s on this `Resource`.
+
+### Attach an Entity
+
+The `Resource` MUST implement the [Attach an Entity](api.md#attach-an-entity)
+operation.  This operation will try to associate a new `Entity` on the
+`Resource`.
+
+If the incoming `Entity`'s `entity_type` property is not found in the current
+set of `Entity`s on `Resource`, then the new `Entity` is added to the set.
+
+If the incoming `Entity`'s `entity_type` property matches an existing `Entity`
+in the current set AND the `identity` attributes for these `Entity`s are
+different, then the SDK MUST ignore the new entity.
+
+If the incoming `Entity`'s `entity_type` property matches an existing `Entity`
+in the current set AND the `identity` attributes for these `Entity`s are
+the same but the `schema_url` is different, then the SDK MUST ignore the new
+entity.
+
+If the incoming `Entity`'s `entity_type` property matches an existing `Entity`
+in the current set AND the `identity` attributes for these `Entity`s are
+the same AND the `schema_url` is the same, then the SDK MUST add any new
+attributes found in the `description` to the existing entity. Any new
+ `description` attributes with the same keys as existing `description`
+ attributes SHOULD replace previous values.
+
+### Flattened Resource
+
+The SDK MUST return a flattened `Resource` for usage in exporters. This
+flattened resource MUST provide the fields expected in the `Resource`
+data model:
+
+- `attributes`: The complete set of all attributes
+- `schema_url`: The Schema URL that should be recorded for this resource.
+  See [resolve conflicts in schema url](#resolve-conflicts-in-schema-url).
+- `entity_refs`: References to the `Entity` data model in `Resource`.
+  These each include:
+  - `type`: The type of the entity.
+  - `schema_url`: The Scheam URL that was recorded for this Entity.
+  - `id_keys`: The attribute keys for the Entity identity. Values are found
+    in the `Resource.attributes` property.
+  - `description_keys`: The attribute keys for the Entity description. Values
+    are found in the `Resource.attributes` property.
+
+### Resolve conflicts in Schema URL
+
+If all detected entities and initial `Resource` have the same URL, then
+this is chosen for the resulting `Resource`.
+
+Otherwise, the Schema URL of the resulting `Resource` SHOULD be empty.