Add ability to parse Schema files according to OTEP 0152 (#2267)

* Add ability to parse Schema files according to OTEP 0152

The parser and parsed representation (AST) are placed in a separate
Go module so that they are can be consumed independently without
the need to bring the rest of the SDK.

Ability to use the parsed representation for schema conversions
can be added later.

* Fixes based on PR comments

* Rename "label" to "attributes"

See https://github.com/open-telemetry/oteps/pull/181

* Fixes based on PR comments

* Add README.md

* Wrap the error in Parse()

* Add docs for exporter types

* Use yaml.NewDecoder

* Verify parsed content in the test

* Fix indentation in README example

* Fix README spaces vs tabs

* Correctly space imports

* Add heading to README

Co-authored-by: Tyler Yahn <MrAlias@users.noreply.github.com>

.github/dependabot.yml

@@ -336,3 +336,14 @@ updates:
     schedule:
       day: sunday
       interval: weekly
+
+  -
+    package-ecosystem: gomod
+    directory: /schema
+    labels:
+      - dependencies
+      - go
+      - "Skip Changelog"
+    schedule:
+      day: sunday
+      interval: weekly

CHANGELOG.md

@@ -19,6 +19,7 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 ### Added
 
 - Adds `otlptracegrpc.WithGRPCConn` and `otlpmetricgrpc.WithGRPCConn` for reusing existing gRPC connection. (#2002)
+- Added a new `schema` module to help parse Schema Files in OTEP 0152 format. (#2267)
 
 ## [1.0.1] - 2021-10-01
 

bridge/opencensus/go.mod

@@ -73,3 +73,5 @@ replace go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp => ../
 replace go.opentelemetry.io/otel/bridge/opencensus/test => ./test
 
 replace go.opentelemetry.io/otel/example/fib => ../../example/fib
+
+replace go.opentelemetry.io/otel/schema => ../../schema

bridge/opencensus/test/go.mod

@@ -69,3 +69,5 @@ replace go.opentelemetry.io/otel/sdk/metric => ../../../sdk/metric
 replace go.opentelemetry.io/otel/trace => ../../../trace
 
 replace go.opentelemetry.io/otel/example/fib => ../../../example/fib
+
+replace go.opentelemetry.io/otel/schema => ../../../schema

bridge/opentracing/go.mod

@@ -69,3 +69,5 @@ replace go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp => ../
 replace go.opentelemetry.io/otel/bridge/opencensus/test => ../opencensus/test
 
 replace go.opentelemetry.io/otel/example/fib => ../../example/fib
+
+replace go.opentelemetry.io/otel/schema => ../../schema

example/fib/go.mod

@@ -68,3 +68,5 @@ replace go.opentelemetry.io/otel/sdk/metric => ../../sdk/metric
 replace go.opentelemetry.io/otel/trace => ../../trace
 
 replace go.opentelemetry.io/otel/example/fib => ./
+
+replace go.opentelemetry.io/otel/schema => ../../schema

example/jaeger/go.mod

@@ -69,3 +69,5 @@ replace go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp => ../
 replace go.opentelemetry.io/otel/bridge/opencensus/test => ../../bridge/opencensus/test
 
 replace go.opentelemetry.io/otel/example/fib => ../fib
+
+replace go.opentelemetry.io/otel/schema => ../../schema

example/namedtracer/go.mod

@@ -71,3 +71,5 @@ replace go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp => ../
 replace go.opentelemetry.io/otel/bridge/opencensus/test => ../../bridge/opencensus/test
 
 replace go.opentelemetry.io/otel/example/fib => ../fib
+
+replace go.opentelemetry.io/otel/schema => ../../schema

example/opencensus/go.mod

@@ -73,3 +73,5 @@ replace go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp => ../
 replace go.opentelemetry.io/otel/bridge/opencensus/test => ../../bridge/opencensus/test
 
 replace go.opentelemetry.io/otel/example/fib => ../fib
+
+replace go.opentelemetry.io/otel/schema => ../../schema

example/otel-collector/go.mod

@@ -72,3 +72,5 @@ replace go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp => ../
 replace go.opentelemetry.io/otel/bridge/opencensus/test => ../../bridge/opencensus/test
 
 replace go.opentelemetry.io/otel/example/fib => ../fib
+
+replace go.opentelemetry.io/otel/schema => ../../schema

example/passthrough/go.mod

@@ -72,3 +72,5 @@ replace go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp => ../
 replace go.opentelemetry.io/otel/bridge/opencensus/test => ../../bridge/opencensus/test
 
 replace go.opentelemetry.io/otel/example/fib => ../fib
+
+replace go.opentelemetry.io/otel/schema => ../../schema

example/prometheus/go.mod

@@ -71,3 +71,5 @@ replace go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp => ../
 replace go.opentelemetry.io/otel/bridge/opencensus/test => ../../bridge/opencensus/test
 
 replace go.opentelemetry.io/otel/example/fib => ../fib
+
+replace go.opentelemetry.io/otel/schema => ../../schema

example/zipkin/go.mod

@@ -70,3 +70,5 @@ replace go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp => ../
 replace go.opentelemetry.io/otel/bridge/opencensus/test => ../../bridge/opencensus/test
 
 replace go.opentelemetry.io/otel/example/fib => ../fib
+
+replace go.opentelemetry.io/otel/schema => ../../schema

exporters/jaeger/go.mod

@@ -73,3 +73,5 @@ replace go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp => ../
 replace go.opentelemetry.io/otel/bridge/opencensus/test => ../../bridge/opencensus/test
 
 replace go.opentelemetry.io/otel/example/fib => ../../example/fib
+
+replace go.opentelemetry.io/otel/schema => ../../schema

exporters/otlp/otlpmetric/go.mod

@@ -80,3 +80,5 @@ replace go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp => ./o
 replace go.opentelemetry.io/otel/bridge/opencensus/test => ../../../bridge/opencensus/test
 
 replace go.opentelemetry.io/otel/example/fib => ../../../example/fib
+
+replace go.opentelemetry.io/otel/schema => ../../../schema

exporters/otlp/otlpmetric/otlpmetricgrpc/go.mod

@@ -78,3 +78,5 @@ replace go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp => ../
 replace go.opentelemetry.io/otel/bridge/opencensus/test => ../../../../bridge/opencensus/test
 
 replace go.opentelemetry.io/otel/example/fib => ../../../../example/fib
+
+replace go.opentelemetry.io/otel/schema => ../../../../schema

exporters/otlp/otlpmetric/otlpmetrichttp/go.mod

@@ -80,3 +80,5 @@ replace go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetricgrpc => ../
 replace go.opentelemetry.io/otel/bridge/opencensus/test => ../../../../bridge/opencensus/test
 
 replace go.opentelemetry.io/otel/example/fib => ../../../../example/fib
+
+replace go.opentelemetry.io/otel/schema => ../../../../schema

exporters/otlp/otlptrace/go.mod

@@ -76,3 +76,5 @@ replace go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp => ../
 replace go.opentelemetry.io/otel/bridge/opencensus/test => ../../../bridge/opencensus/test
 
 replace go.opentelemetry.io/otel/example/fib => ../../../example/fib
+
+replace go.opentelemetry.io/otel/schema => ../../../schema

exporters/otlp/otlptrace/otlptracegrpc/go.mod

@@ -72,3 +72,5 @@ replace go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp => ../
 replace go.opentelemetry.io/otel/bridge/opencensus/test => ../../../../bridge/opencensus/test
 
 replace go.opentelemetry.io/otel/example/fib => ../../../../example/fib
+
+replace go.opentelemetry.io/otel/schema => ../../../../schema

exporters/otlp/otlptrace/otlptracehttp/go.mod

@@ -73,3 +73,5 @@ replace go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp => ../
 replace go.opentelemetry.io/otel/bridge/opencensus/test => ../../../../bridge/opencensus/test
 
 replace go.opentelemetry.io/otel/example/fib => ../../../../example/fib
+
+replace go.opentelemetry.io/otel/schema => ../../../../schema

exporters/prometheus/go.mod

@@ -75,3 +75,5 @@ replace go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp => ../
 replace go.opentelemetry.io/otel/bridge/opencensus/test => ../../bridge/opencensus/test
 
 replace go.opentelemetry.io/otel/example/fib => ../../example/fib
+
+replace go.opentelemetry.io/otel/schema => ../../schema

exporters/stdout/stdoutmetric/go.mod

@@ -73,3 +73,5 @@ replace go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp => ../
 replace go.opentelemetry.io/otel/bridge/opencensus/test => ../../../bridge/opencensus/test
 
 replace go.opentelemetry.io/otel/example/fib => ../../../example/fib
+
+replace go.opentelemetry.io/otel/schema => ../../../schema

exporters/stdout/stdouttrace/go.mod

@@ -71,3 +71,5 @@ replace go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp => ../
 replace go.opentelemetry.io/otel/bridge/opencensus/test => ../../../bridge/opencensus/test
 
 replace go.opentelemetry.io/otel/example/fib => ../../../example/fib
+
+replace go.opentelemetry.io/otel/schema => ../../../schema

exporters/zipkin/go.mod

@@ -74,3 +74,5 @@ replace go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp => ../
 replace go.opentelemetry.io/otel/bridge/opencensus/test => ../../bridge/opencensus/test
 
 replace go.opentelemetry.io/otel/example/fib => ../../example/fib
+
+replace go.opentelemetry.io/otel/schema => ../../schema

go.mod

@@ -69,3 +69,5 @@ replace go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp => ./e
 replace go.opentelemetry.io/otel/bridge/opencensus/test => ./bridge/opencensus/test
 
 replace go.opentelemetry.io/otel/example/fib => ./example/fib
+
+replace go.opentelemetry.io/otel/schema => ./schema

internal/metric/go.mod

@@ -69,3 +69,5 @@ replace go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp => ../
 replace go.opentelemetry.io/otel/bridge/opencensus/test => ../../bridge/opencensus/test
 
 replace go.opentelemetry.io/otel/example/fib => ../../example/fib
+
+replace go.opentelemetry.io/otel/schema => ../../schema

internal/tools/go.mod

@@ -76,3 +76,5 @@ replace go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp => ../
 replace go.opentelemetry.io/otel/bridge/opencensus/test => ../../bridge/opencensus/test
 
 replace go.opentelemetry.io/otel/example/fib => ../../example/fib
+
+replace go.opentelemetry.io/otel/schema => ../../schema

metric/go.mod

@@ -70,3 +70,5 @@ replace go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp => ../
 replace go.opentelemetry.io/otel/bridge/opencensus/test => ../bridge/opencensus/test
 
 replace go.opentelemetry.io/otel/example/fib => ../example/fib
+
+replace go.opentelemetry.io/otel/schema => ../schema

schema/README.md

@@ -0,0 +1,33 @@
+# Telemetry Schema Files
+
+The `schema` module contains packages that help to parse and validate
+[schema files](https://github.com/open-telemetry/oteps/blob/main/text/0152-telemetry-schemas.md).
+
+Each `major.minor` schema file format version is implemented as a separate package, with
+the name of the package in the `vmajor.minor` form.
+
+To parse a schema file, first decide what file format version you want to parse,
+then import the corresponding package and use the `Parse` or `ParseFile` functions
+like this:
+
+```go
+import schema "go.opentelemetry.io/otel/schema/v1.0"
+
+// Load the schema from a file in v1.0.x file format.
+func loadSchemaFromFile() error {
+	telSchema, err := schema.ParseFile("schema-file.yaml")
+	if err != nil {
+		return err
+	}
+	// Use telSchema struct here.
+}
+
+// Alternatively use schema.Parse to read the schema file from io.Reader.
+func loadSchemaFromReader(r io.Reader) error {
+	telSchema, err := schema.Parse(r)
+	if err != nil {
+		return err
+	}
+	// Use telSchema struct here.
+}
+```

schema/go.mod

@@ -0,0 +1,71 @@
+module go.opentelemetry.io/otel/schema
+
+go 1.15
+
+require (
+	github.com/Masterminds/semver/v3 v3.1.1
+	github.com/stretchr/testify v1.7.0
+	gopkg.in/yaml.v2 v2.4.0
+)
+
+replace go.opentelemetry.io/otel => ../
+
+replace go.opentelemetry.io/otel/bridge/opencensus => ../bridge/opencensus
+
+replace go.opentelemetry.io/otel/bridge/opencensus/test => ../bridge/opencensus/test
+
+replace go.opentelemetry.io/otel/bridge/opentracing => ../bridge/opentracing
+
+replace go.opentelemetry.io/otel/example/fib => ../example/fib
+
+replace go.opentelemetry.io/otel/example/jaeger => ../example/jaeger
+
+replace go.opentelemetry.io/otel/example/namedtracer => ../example/namedtracer
+
+replace go.opentelemetry.io/otel/example/opencensus => ../example/opencensus
+
+replace go.opentelemetry.io/otel/example/otel-collector => ../example/otel-collector
+
+replace go.opentelemetry.io/otel/example/passthrough => ../example/passthrough
+
+replace go.opentelemetry.io/otel/example/prometheus => ../example/prometheus
+
+replace go.opentelemetry.io/otel/example/zipkin => ../example/zipkin
+
+replace go.opentelemetry.io/otel/exporters/jaeger => ../exporters/jaeger
+
+replace go.opentelemetry.io/otel/exporters/otlp/otlpmetric => ../exporters/otlp/otlpmetric
+
+replace go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetricgrpc => ../exporters/otlp/otlpmetric/otlpmetricgrpc
+
+replace go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp => ../exporters/otlp/otlpmetric/otlpmetrichttp
+
+replace go.opentelemetry.io/otel/exporters/otlp/otlptrace => ../exporters/otlp/otlptrace
+
+replace go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc => ../exporters/otlp/otlptrace/otlptracegrpc
+
+replace go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp => ../exporters/otlp/otlptrace/otlptracehttp
+
+replace go.opentelemetry.io/otel/exporters/prometheus => ../exporters/prometheus
+
+replace go.opentelemetry.io/otel/exporters/stdout/stdoutmetric => ../exporters/stdout/stdoutmetric
+
+replace go.opentelemetry.io/otel/exporters/stdout/stdouttrace => ../exporters/stdout/stdouttrace
+
+replace go.opentelemetry.io/otel/exporters/zipkin => ../exporters/zipkin
+
+replace go.opentelemetry.io/otel/internal/metric => ../internal/metric
+
+replace go.opentelemetry.io/otel/internal/tools => ../internal/tools
+
+replace go.opentelemetry.io/otel/metric => ../metric
+
+replace go.opentelemetry.io/otel/schema => ./
+
+replace go.opentelemetry.io/otel/sdk => ../sdk
+
+replace go.opentelemetry.io/otel/sdk/export/metric => ../sdk/export/metric
+
+replace go.opentelemetry.io/otel/sdk/metric => ../sdk/metric
+
+replace go.opentelemetry.io/otel/trace => ../trace

schema/go.sum

@@ -0,0 +1,15 @@
+github.com/Masterminds/semver/v3 v3.1.1 h1:hLg3sBzpNErnxhQtUy/mmLR2I9foDujNK030IGemrRc=
+github.com/Masterminds/semver/v3 v3.1.1/go.mod h1:VPu/7SZ7ePZ3QOrcuXROw5FAcLl4a0cBrbBpGY/8hQs=
+github.com/davecgh/go-spew v1.1.0 h1:ZDRjVQ15GmhC3fiQ8ni8+OwkZQO4DARzQgrnXU1Liz8=
+github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
+github.com/stretchr/testify v1.7.0 h1:nwc3DEeHmmLAfoZucVR881uASk0Mfjw8xYJ99tb5CcY=
+github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v2 v2.4.0 h1:D8xgwECY7CYvx+Y2n4sBz93Jn9JRvxdiyyo8CTfuKaY=
+gopkg.in/yaml.v2 v2.4.0/go.mod h1:RDklbk79AGWmwhnvt/jBztapEOGDOx6ZbXqjP6csGnQ=
+gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c h1:dUUwHk2QECo/6vqA44rthZ8ie2QXMNeKRTHCNY2nXvo=
+gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

schema/v1.0/ast/ast_schema.go

@@ -0,0 +1,56 @@
+// Copyright The OpenTelemetry Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package ast // import "go.opentelemetry.io/otel/schema/v1.0/ast"
+
+import "go.opentelemetry.io/otel/schema/v1.0/types"
+
+// Schema represents a Schema file in FileFormat 1.0.0 as defined in
+// https://github.com/open-telemetry/oteps/blob/main/text/0152-telemetry-schemas.md
+type Schema struct {
+	// Schema file format. SHOULD be 1.0.0 for the current specification version.
+	// See https://github.com/open-telemetry/oteps/blob/main/text/0152-telemetry-schemas.md#schema-file-format-number
+	FileFormat string `yaml:"file_format"`
+
+	// Schema URL is an identifier of a Schema. The URL specifies a location of this
+	// Schema File that can be retrieved (so it is a URL and not just a URI) using HTTP
+	// or HTTPS protocol.
+	// See https://github.com/open-telemetry/oteps/blob/main/text/0152-telemetry-schemas.md#schema-url
+	SchemaURL string `yaml:"schema_url"`
+
+	// Versions section that lists changes that happened in each particular version.
+	Versions map[types.TelemetryVersion]VersionDef
+}
+
+// VersionDef corresponds to a section representing one version under the "versions"
+// top-level key.
+type VersionDef struct {
+	All        Attributes
+	Resources  Attributes
+	Spans      Spans
+	SpanEvents SpanEvents `yaml:"span_events"`
+	Logs       Logs
+	Metrics    Metrics
+}
+
+// Attributes corresponds to a section representing a list of changes that
+// happened in a particular version.
+type Attributes struct {
+	Changes []AttributeChange
+}
+
+// AttributeChange corresponds to a section representing attribute changes.
+type AttributeChange struct {
+	RenameAttributes *AttributeMap `yaml:"rename_attributes"`
+}

schema/v1.0/ast/common.go

@@ -0,0 +1,25 @@
+// Copyright The OpenTelemetry Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package ast // import "go.opentelemetry.io/otel/schema/v1.0/ast"
+
+// RenameAttributes corresponds to a section that describes attribute renaming.
+type RenameAttributes struct {
+	AttributeMap AttributeMap `yaml:"attribute_map"`
+}
+
+// AttributeMap corresponds to a section representing a mapping of attribute names.
+// The keys are the old attribute name used in the previous version, the values are the
+// new attribute name starting from this version.
+type AttributeMap map[string]string

schema/v1.0/ast/logs.go

@@ -0,0 +1,26 @@
+// Copyright The OpenTelemetry Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package ast // import "go.opentelemetry.io/otel/schema/v1.0/ast"
+
+// Logs corresponds to a section representing a list of changes that happened
+// to logs schema in a particular version.
+type Logs struct {
+	Changes []LogsChange
+}
+
+// LogsChange corresponds to a section representing logs change.
+type LogsChange struct {
+	RenameAttributes *RenameAttributes `yaml:"rename_attributes"`
+}

schema/v1.0/ast/metrics.go

@@ -0,0 +1,36 @@
+// Copyright The OpenTelemetry Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package ast // import "go.opentelemetry.io/otel/schema/v1.0/ast"
+
+import "go.opentelemetry.io/otel/schema/v1.0/types"
+
+// Metrics corresponds to a section representing a list of changes that happened
+// to metrics schema in a particular version.
+type Metrics struct {
+	Changes []MetricsChange
+}
+
+// MetricsChange corresponds to a section representing metrics change.
+type MetricsChange struct {
+	RenameMetrics    map[types.MetricName]types.MetricName `yaml:"rename_metrics"`
+	RenameAttributes *AttributeMapForMetrics               `yaml:"rename_attributes"`
+}
+
+// AttributeMapForMetrics corresponds to a section representing a translation of
+// attributes for specific metrics.
+type AttributeMapForMetrics struct {
+	ApplyToMetrics []types.MetricName `yaml:"apply_to_metrics"`
+	AttributeMap   AttributeMap       `yaml:"attribute_map"`
+}

schema/v1.0/ast/spans.go

@@ -0,0 +1,53 @@
+// Copyright The OpenTelemetry Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package ast // import "go.opentelemetry.io/otel/schema/v1.0/ast"
+
+import "go.opentelemetry.io/otel/schema/v1.0/types"
+
+// Spans corresponds to a section representing a list of changes that happened
+// to spans schema in a particular version.
+type Spans struct {
+	Changes []SpansChange
+}
+
+// SpanEvents corresponds to a section representing a list of changes that happened
+// to span events schema in a particular version.
+type SpanEvents struct {
+	Changes []SpanEventsChange
+}
+
+// SpansChange corresponds to a section representing spans change.
+type SpansChange struct {
+	RenameAttributes *RenameAttributes `yaml:"rename_attributes"`
+}
+
+// SpanEventsChange corresponds to a section representing span events change.
+type SpanEventsChange struct {
+	RenameEvents     *RenameSpanEvents          `yaml:"rename_events"`
+	RenameAttributes *RenameSpanEventAttributes `yaml:"rename_attributes"`
+}
+
+// RenameSpanEvents corresponds to section representing a renaming of span events.
+type RenameSpanEvents struct {
+	EventNameMap map[string]string `yaml:"name_map"`
+}
+
+// RenameSpanEventAttributes corresponds to section representing a renaming of
+// attributes of span events.
+type RenameSpanEventAttributes struct {
+	ApplyToSpans  []types.SpanName  `yaml:"apply_to_spans"`
+	ApplyToEvents []types.EventName `yaml:"apply_to_events"`
+	AttributeMap  AttributeMap      `yaml:"attribute_map"`
+}

schema/v1.0/parser.go

@@ -0,0 +1,106 @@
+// Copyright The OpenTelemetry Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package schema // import "go.opentelemetry.io/otel/schema/v1.0"
+
+import (
+	"fmt"
+	"io"
+	"net/url"
+	"os"
+	"strconv"
+	"strings"
+
+	"github.com/Masterminds/semver/v3"
+	"gopkg.in/yaml.v2"
+
+	"go.opentelemetry.io/otel/schema/v1.0/ast"
+)
+
+// Major file version number that this library supports.
+const supportedFormatMajor = 1
+
+// Maximum minor version number that this library supports.
+const supportedFormatMinor = 0
+
+// Maximum major+minor version number that this library supports, as a string.
+var supportedFormatMajorMinor = strconv.Itoa(supportedFormatMajor) + "." +
+	strconv.Itoa(supportedFormatMinor) // 1.0
+
+// ParseFile a schema file. schemaFilePath is the file path.
+func ParseFile(schemaFilePath string) (*ast.Schema, error) {
+	file, err := os.Open(schemaFilePath)
+	if err != nil {
+		return nil, err
+	}
+	return Parse(file)
+}
+
+// Parse a schema file. schemaFileContent is the readable content of the schema file.
+func Parse(schemaFileContent io.Reader) (*ast.Schema, error) {
+	var ts ast.Schema
+	d := yaml.NewDecoder(schemaFileContent)
+	err := d.Decode(&ts)
+	if err != nil {
+		return nil, err
+	}
+
+	if err := checkFileFormatField(ts.FileFormat); err != nil {
+		return nil, err
+	}
+
+	if strings.TrimSpace(ts.SchemaURL) == "" {
+		return nil, fmt.Errorf("schema_url field is missing")
+	}
+
+	if _, err := url.Parse(ts.SchemaURL); err != nil {
+		return nil, fmt.Errorf("invalid URL specified in schema_url field: %w", err)
+	}
+
+	return &ts, nil
+}
+
+// checkFileFormatField validates the file format field according to the rules here:
+// https://github.com/open-telemetry/oteps/blob/main/text/0152-telemetry-schemas.md#schema-file-format-number
+func checkFileFormatField(fileFormat string) error {
+	// Verify that the version number in the file is a semver.
+	fileFormatParsed, err := semver.StrictNewVersion(fileFormat)
+	if err != nil {
+		return fmt.Errorf(
+			"invalid schema file format version number %q (expected semver): %w",
+			fileFormat, err,
+		)
+	}
+
+	// Check that the major version number in the file is the same as what we expect.
+	if fileFormatParsed.Major() != supportedFormatMajor {
+		return fmt.Errorf(
+			"this library cannot parse file formats with major version other than %v",
+			supportedFormatMajor,
+		)
+	}
+
+	// Check that the file minor version number is not greater than
+	// what is requested supports.
+	if fileFormatParsed.Minor() > supportedFormatMinor {
+		return fmt.Errorf(
+			"unsupported schema file format minor version number, expected no newer than %v, got %v",
+			supportedFormatMajorMinor+".x", fileFormat,
+		)
+	}
+
+	// Patch, prerelease and metadata version number does not matter, so we don't check it.
+
+	return nil
+}

schema/v1.0/parser_test.go

@@ -0,0 +1,180 @@
+// Copyright The OpenTelemetry Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package schema
+
+import (
+	"bytes"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+
+	"go.opentelemetry.io/otel/schema/v1.0/ast"
+	"go.opentelemetry.io/otel/schema/v1.0/types"
+)
+
+func TestParseSchemaFile(t *testing.T) {
+	ts, err := ParseFile("testdata/valid-example.yaml")
+	assert.NoError(t, err)
+	assert.NotNil(t, ts)
+	assert.EqualValues(t, &ast.Schema{
+		FileFormat: "1.0.0",
+		SchemaURL:  "https://opentelemetry.io/schemas/1.1.0",
+		Versions: map[types.TelemetryVersion]ast.VersionDef{
+			"1.0.0": {},
+
+			"1.1.0": {
+				All: ast.Attributes{
+					Changes: []ast.AttributeChange{
+						{RenameAttributes: &ast.AttributeMap{
+							"k8s.cluster.name":     "kubernetes.cluster.name",
+							"k8s.namespace.name":   "kubernetes.namespace.name",
+							"k8s.node.name":        "kubernetes.node.name",
+							"k8s.node.uid":         "kubernetes.node.uid",
+							"k8s.pod.name":         "kubernetes.pod.name",
+							"k8s.pod.uid":          "kubernetes.pod.uid",
+							"k8s.container.name":   "kubernetes.container.name",
+							"k8s.replicaset.name":  "kubernetes.replicaset.name",
+							"k8s.replicaset.uid":   "kubernetes.replicaset.uid",
+							"k8s.cronjob.name":     "kubernetes.cronjob.name",
+							"k8s.cronjob.uid":      "kubernetes.cronjob.uid",
+							"k8s.job.name":         "kubernetes.job.name",
+							"k8s.job.uid":          "kubernetes.job.uid",
+							"k8s.statefulset.name": "kubernetes.statefulset.name",
+							"k8s.statefulset.uid":  "kubernetes.statefulset.uid",
+							"k8s.daemonset.name":   "kubernetes.daemonset.name",
+							"k8s.daemonset.uid":    "kubernetes.daemonset.uid",
+							"k8s.deployment.name":  "kubernetes.deployment.name",
+							"k8s.deployment.uid":   "kubernetes.deployment.uid",
+							"service.namespace":    "service.namespace.name",
+						}},
+					},
+				},
+
+				Resources: ast.Attributes{
+					Changes: []ast.AttributeChange{
+						{
+							RenameAttributes: &ast.AttributeMap{
+								"telemetry.auto.version": "telemetry.auto_instr.version",
+							},
+						},
+					},
+				},
+
+				Spans: ast.Spans{
+					Changes: []ast.SpansChange{
+						{
+							RenameAttributes: &ast.RenameAttributes{
+								AttributeMap: ast.AttributeMap{
+									"peer.service": "peer.service.name",
+								},
+							},
+						},
+					},
+				},
+
+				SpanEvents: ast.SpanEvents{
+					Changes: []ast.SpanEventsChange{
+						{
+							RenameEvents: &ast.RenameSpanEvents{
+								EventNameMap: map[string]string{
+									"exception.stacktrace": "exception.stack_trace",
+								},
+							},
+						},
+						{
+							RenameAttributes: &ast.RenameSpanEventAttributes{
+								ApplyToEvents: []types.EventName{"exception.stack_trace"},
+								AttributeMap: ast.AttributeMap{
+									"peer.service": "peer.service.name",
+								},
+							},
+						},
+					},
+				},
+
+				Logs: ast.Logs{Changes: []ast.LogsChange{
+					{RenameAttributes: &ast.RenameAttributes{
+						AttributeMap: map[string]string{
+							"process.executable_name": "process.executable.name",
+						},
+					}},
+				}},
+
+				Metrics: ast.Metrics{
+					Changes: []ast.MetricsChange{
+						{
+							RenameAttributes: &ast.AttributeMapForMetrics{
+								AttributeMap: map[string]string{
+									"http.status_code": "http.response_status_code",
+								},
+							}},
+						{
+							RenameMetrics: map[types.MetricName]types.MetricName{
+								"container.cpu.usage.total":  "cpu.usage.total",
+								"container.memory.usage.max": "memory.usage.max",
+							},
+						},
+						{
+							RenameAttributes: &ast.AttributeMapForMetrics{
+								ApplyToMetrics: []types.MetricName{
+									"system.cpu.utilization",
+									"system.memory.usage",
+									"system.memory.utilization",
+									"system.paging.usage",
+								},
+								AttributeMap: map[string]string{
+									"status": "state",
+								},
+							},
+						},
+					},
+				},
+			},
+		},
+	}, ts)
+}
+
+func TestFailParseSchemaFile(t *testing.T) {
+	ts, err := ParseFile("testdata/unsupported-file-format.yaml")
+	assert.Error(t, err)
+	assert.Nil(t, ts)
+
+	ts, err = ParseFile("testdata/invalid-schema-url.yaml")
+	assert.Error(t, err)
+	assert.Nil(t, ts)
+}
+
+func TestFailParseSchema(t *testing.T) {
+	_, err := Parse(bytes.NewReader([]byte("")))
+	assert.Error(t, err)
+
+	_, err = Parse(bytes.NewReader([]byte("invalid yaml")))
+	assert.Error(t, err)
+
+	_, err = Parse(bytes.NewReader([]byte("file_format: 1.0.0")))
+	assert.Error(t, err)
+}
+
+func TestCheckFileFormatField(t *testing.T) {
+	// Invalid file format version numbers.
+	assert.Error(t, checkFileFormatField("not a semver"))
+	assert.Error(t, checkFileFormatField("2.0.0"))
+	assert.Error(t, checkFileFormatField("1.1.0"))
+
+	// Valid cases.
+	assert.NoError(t, checkFileFormatField("1.0.0"))
+	assert.NoError(t, checkFileFormatField("1.0.1"))
+	assert.NoError(t, checkFileFormatField("1.0.10000-alpha+4857"))
+}

schema/v1.0/testdata/invalid-schema-url.yaml

@@ -0,0 +1,5 @@
+file_format: 1.0.0
+
+schema_url: http://invalid url
+
+versions:

schema/v1.0/testdata/unsupported-file-format.yaml

@@ -0,0 +1,9 @@
+file_format: 1.1.0
+
+versions:
+  1.1.0:
+    all:
+      changes:
+        - rename_attributes:
+            k8s.cluster.name: kubernetes.cluster.name
+  1.0.0:

schema/v1.0/testdata/valid-example.yaml

@@ -0,0 +1,127 @@
+file_format: 1.0.0
+
+schema_url: https://opentelemetry.io/schemas/1.1.0
+
+versions:
+  1.1.0:
+    # Section "all" applies to attributes names for all data types: resources, spans, logs,
+    # span events, metric labels.
+    #
+    # The translations in "all" section are performed first (for each particular version).
+    # Only after that the translations in the specific section ("resources", "traces",
+    # "metrics" or "logs") that corresponds to the data type are applied.
+    #
+    # The only translation possible in section "all" is renaming of attributes in
+    # versions. For human readability versions are listed in reverse chronological
+    # order, however note that the translations are applied in the order defined by
+    # semver ordering.
+    all:
+      changes:
+        - rename_attributes:
+            # Mapping of attribute names (label names for metrics). The key is the old name
+            # used prior to this version, the value is the new name starting from this version.
+
+            # Rename k8s.* to kubernetes.*
+            k8s.cluster.name: kubernetes.cluster.name
+            k8s.namespace.name: kubernetes.namespace.name
+            k8s.node.name: kubernetes.node.name
+            k8s.node.uid: kubernetes.node.uid
+            k8s.pod.name: kubernetes.pod.name
+            k8s.pod.uid: kubernetes.pod.uid
+            k8s.container.name: kubernetes.container.name
+            k8s.replicaset.name: kubernetes.replicaset.name
+            k8s.replicaset.uid: kubernetes.replicaset.uid
+            k8s.cronjob.name: kubernetes.cronjob.name
+            k8s.cronjob.uid: kubernetes.cronjob.uid
+            k8s.job.name: kubernetes.job.name
+            k8s.job.uid: kubernetes.job.uid
+            k8s.statefulset.name: kubernetes.statefulset.name
+            k8s.statefulset.uid: kubernetes.statefulset.uid
+            k8s.daemonset.name: kubernetes.daemonset.name
+            k8s.daemonset.uid: kubernetes.daemonset.uid
+            k8s.deployment.name: kubernetes.deployment.name
+            k8s.deployment.uid: kubernetes.deployment.uid
+
+            service.namespace: service.namespace.name
+
+    # Like "all" the "resources" section may contain only attribute renaming translations.
+    # The only translation possible in this section is renaming of attributes in
+    # versions.
+    resources:
+      changes:
+        - rename_attributes:
+            # Mapping of attribute names. The key is the old name
+            # used prior to this version, the value is the new name starting from this version.
+            telemetry.auto.version: telemetry.auto_instr.version
+
+    spans:
+      changes:
+        # Sequence of translations to apply to convert the schema from a prior version
+        # to this version. The order in this sequence is important. Translations are
+        # applied from top to bottom in the listed order.
+        - rename_attributes:
+            # Rename attributes of all spans, regardless of span name.
+            # The keys are the old attribute name used prior to this version, the values are
+            # the new attribute name starting from this version.
+            attribute_map:
+              peer.service: peer.service.name
+
+    span_events:
+      changes:
+        # Sequence of translations to apply to convert the schema from a prior version
+        # to this version. The order in this sequence is important. Translations are
+        # applied from top to bottom in the listed order.
+        - rename_events:
+            # Rename events. The keys are old event names, the values are the new event names.
+            name_map: {exception.stacktrace: exception.stack_trace}
+
+        - rename_attributes:
+            # Rename attributes of events.
+            # The keys are the old attribute name used prior to this version, the values are
+            # the new attribute name starting from this version.
+            attribute_map:
+              peer.service: peer.service.name
+
+            apply_to_events:
+              # Optional event names to apply to. If empty applies to all events.
+              # Conditions in apply_to_spans and apply_to_events are logical AND-ed,
+              # both should match for transformation to be applied.
+              - exception.stack_trace
+
+    metrics:
+      changes:
+        # Sequence of translations to apply to convert the schema from a prior version
+        # to this version. The order in this sequence is important. Translations are
+        # applied from top to bottom in the listed order.
+
+        - rename_attributes:
+            # Rename attributes of all metrics, regardless of metric name.
+            # The keys are the old attribute name used prior to this version, the values are
+            # the new attribute name starting from this version.
+            attribute_map:
+              http.status_code: http.response_status_code
+
+        - rename_metrics:
+            # Rename metrics. The keys are old metric names, the values are the new metric names.
+            container.cpu.usage.total: cpu.usage.total
+            container.memory.usage.max: memory.usage.max
+
+        - rename_attributes:
+            apply_to_metrics:
+              # Name of the metric to apply this rule to. If empty the rule applies to all metrics.
+              - system.cpu.utilization
+              - system.memory.usage
+              - system.memory.utilization
+              - system.paging.usage
+            attribute_map:
+              # The keys are the old attribute name used prior to this version, the values are
+              # the new attribute name starting from this version.
+              status: state
+
+    logs:
+      changes:
+        - rename_attributes:
+            attribute_map:
+              process.executable_name: process.executable.name
+
+  1.0.0:

schema/v1.0/types/types.go

@@ -0,0 +1,27 @@
+// Copyright The OpenTelemetry Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package types // import "go.opentelemetry.io/otel/schema/v1.0/types"
+
+// TelemetryVersion is a version number key in the schema file (e.g. "1.7.0")
+type TelemetryVersion string
+
+// SpanName is span name string.
+type SpanName string
+
+// EventName is an event name string.
+type EventName string
+
+// MetricName is a metric name string.
+type MetricName string

sdk/export/metric/go.mod

@@ -70,3 +70,5 @@ replace go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp => ../
 replace go.opentelemetry.io/otel/bridge/opencensus/test => ../../../bridge/opencensus/test
 
 replace go.opentelemetry.io/otel/example/fib => ../../../example/fib
+
+replace go.opentelemetry.io/otel/schema => ../../../schema

sdk/go.mod

@@ -71,3 +71,5 @@ replace go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp => ../
 replace go.opentelemetry.io/otel/bridge/opencensus/test => ../bridge/opencensus/test
 
 replace go.opentelemetry.io/otel/example/fib => ../example/fib
+
+replace go.opentelemetry.io/otel/schema => ../schema

sdk/metric/go.mod

@@ -73,3 +73,5 @@ replace go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp => ../
 replace go.opentelemetry.io/otel/bridge/opencensus/test => ../../bridge/opencensus/test
 
 replace go.opentelemetry.io/otel/example/fib => ../../example/fib
+
+replace go.opentelemetry.io/otel/schema => ../../schema

trace/go.mod

@@ -69,3 +69,5 @@ replace go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp => ../
 replace go.opentelemetry.io/otel/bridge/opencensus/test => ../bridge/opencensus/test
 
 replace go.opentelemetry.io/otel/example/fib => ../example/fib
+
+replace go.opentelemetry.io/otel/schema => ../schema

versions.yaml

@@ -45,6 +45,10 @@ module-sets:
       - go.opentelemetry.io/otel/metric
       - go.opentelemetry.io/otel/sdk/export/metric
       - go.opentelemetry.io/otel/sdk/metric
+  experimental-schema:
+    version: v0.0.1
+    modules:
+      - go.opentelemetry.io/otel/schema
   bridge:
     version: v0.24.0
     modules: