From 9fc6984ff15fa42a4e4e36bb0ef3d1b933702cd5 Mon Sep 17 00:00:00 2001
From: jack-berg <34418638+jack-berg@users.noreply.github.com>
Date: Wed, 12 Apr 2023 17:31:28 -0500
Subject: [PATCH] Lay initial groundwork for file configuration (#3360)

Initial followup to [OTEP
#225](https://github.com/open-telemetry/oteps/pull/225).

This lays the initial groundwork for file configuration in the
specification. There are placeholders TODOs for many various followup
tasks. Additional work is also needed to figure out how to merge [SDK
Configuration](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/sdk-configuration.md),
[SDK Environment
Variables](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/sdk-environment-variables.md)
and file configuration into a cohesive story.

This PR proposes the configuration schema live in
`opentelemetry-specification/specification/configuration/schema/`, which
implies that at some point additional build steps will be needed to
confirm changes to the schema are valid and allowed.

cc @MrAlias, @codeboten
---
 CHANGELOG.md                                  |  3 +
 .../configuration/file-configuration.md       | 73 +++++++++++++++++++
 .../schema/opentelemetry_configuration.json   | 15 ++++
 3 files changed, 91 insertions(+)
 create mode 100644 specification/configuration/file-configuration.md
 create mode 100644 specification/configuration/schema/opentelemetry_configuration.json

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4921c3137ad..336669d767e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -31,6 +31,9 @@ release.
 
 ### SDK Configuration
 
+- Lay initial groundwork for file configuration
+  ([#3360](https://github.com/open-telemetry/opentelemetry-specification/pull/3360))
+
 ### Telemetry Schemas
 
 ### Common
diff --git a/specification/configuration/file-configuration.md b/specification/configuration/file-configuration.md
new file mode 100644
index 00000000000..dbe949b2c7b
--- /dev/null
+++ b/specification/configuration/file-configuration.md
@@ -0,0 +1,73 @@
+# File Configuration
+
+**Status**: [Experimental](../document-status.md)
+
+<!-- toc -->
+
+- [Overview](#overview)
+- [Configuration Model](#configuration-model)
+  * [Stability Definition](#stability-definition)
+- [Configuration file](#configuration-file)
+- [SDK Configuration](#sdk-configuration)
+  * [In-Memory Configuration Model](#in-memory-configuration-model)
+  * [Operations](#operations)
+- [References](#references)
+
+<!-- tocstop -->
+
+## Overview
+
+File configuration provides a mechanism for configuring OpenTelemetry which is
+more expressive and full-featured than
+the [environment variable](../sdk-environment-variables.md) based scheme, and
+language agnostic in a way not possible
+with [programmatic configuration](../sdk-configuration.md#programmatic).
+
+File configuration defines a [Configuration Model](#configuration-model),
+which can be expressed in a [configuration file](#configuration-file).
+Configuration files can be validated against the Configuration Schema, and
+interpreted to produce configured OpenTelemetry components.
+
+## Configuration Model
+
+The configuration model is defined
+in [./schema/](./schema/opentelemetry_configuration.json) using
+the [JSON Schema](https://json-schema.org/).
+
+### Stability Definition
+
+TODO: define stability guarantees and backwards compatibility
+
+## Configuration file
+
+A configuration file is a file representation of
+the [Configuration Model](#configuration-model).
+
+TODO: define acceptable file formats
+
+TODO: define environment variable substitution
+
+## SDK Configuration
+
+SDK configuration defines the interfaces and operations that SDKs are expected
+to expose to enable file based configuration.
+
+### In-Memory Configuration Model
+
+SDKs SHOULD provide an in-memory representation of
+the [Configuration Model](#configuration-model). In general, SDKs are encouraged
+to provide this in-memory representation in a manner that is idiomatic for their
+language. If an SDK needs to expose a class or interface, the
+name `Configuration` is RECOMMENDED.
+
+### Operations
+
+TODO: define how to parse configuration file to configuration model
+
+TODO: define how to apply configuration model to produce configured sdk
+components
+
+## References
+
+* Configuration
+  proposal ([OTEP #225](https://github.com/open-telemetry/oteps/pull/225))
diff --git a/specification/configuration/schema/opentelemetry_configuration.json b/specification/configuration/schema/opentelemetry_configuration.json
new file mode 100644
index 00000000000..2dc9cb04f8a
--- /dev/null
+++ b/specification/configuration/schema/opentelemetry_configuration.json
@@ -0,0 +1,15 @@
+{
+    "$id": "https://opentelemetry.io/otelconfig/OpenTelemetryConfiguration",
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "title": "OpenTelemetryConfiguration",
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+        "file_format": {
+            "type": "number"
+        }
+    },
+    "required": [
+        "file_format"
+    ]
+}