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 open-telemetry/oteps#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