[editorial] Ensure schemas section has a README, and other changes

specification/schemas/overview.md → specification/schemas/README.md

@@ -1,18 +1,32 @@
+<!--- Hugo front matter used to generate the website version of this page:
+linkTitle: Schemas
+aliases: [/docs/reference/specification/schemas/overview]
+--->
+
 # Telemetry Schemas
 
 **Status**: [Experimental](../document-status.md)
 
-* [Motivation](#motivation)
-* [How Schemas Work](#how-schemas-work)
-* [What is Out of Scope](#what-is-out-of-scope)
-* [Use Cases](#use-cases)
+<details>
+<summary>Table of Contents</summary>
+
+<!-- toc -->
+
+- [Motivation](#motivation)
+- [How Schemas Work](#how-schemas-work)
+- [What is Out of Scope](#what-is-out-of-scope)
+- [Use Cases](#use-cases)
   * [Full Schema-Aware](#full-schema-aware)
   * [Collector-Assisted Schema Transformation](#collector-assisted-schema-transformation)
-* [Schema URL](#schema-url)
-* [Schema Version Number](#schema-version-number)
-* [OTLP Support](#otlp-support)
-* [API Support](#api-support)
-* [OpenTelemetry Schema](#opentelemetry-schema)
+- [Schema URL](#schema-url)
+- [Schema Version Number](#schema-version-number)
+- [OTLP Support](#otlp-support)
+- [API Support](#api-support)
+- [OpenTelemetry Schema](#opentelemetry-schema)
+
+<!-- tocstop -->
+
+</details>
 
 ## Motivation
 
@@ -252,7 +266,8 @@ is associated with a Schema URL.
 ## OpenTelemetry Schema
 
 OpenTelemetry publishes it own schema at
-`https://opentelemetry.io/schemas/<version>`. The version number of the schema
+[opentelemetry.io/](https://opentelemetry.io/)schemas/<_version_>.
+The version number of the schema
 is the same as the specification version number which publishes the schema.
 Every time a new specification version is released a corresponding new schema
 MUST be released simultaneously. If the specification release did not introduce

specification/schemas/file_format_v1.0.0.md

@@ -1,4 +1,8 @@
-# Schema File
+<!--- Hugo front matter used to generate the website version of this page:
+linkTitle: 1.0.0
+--->
+
+# Schema File Format 1.0.0
 
 **Status**: [Experimental](../document-status.md)
 

specification/schemas/file_format_v1.1.0.md

@@ -1,4 +1,8 @@
-# Schema File
+<!--- Hugo front matter used to generate the website version of this page:
+linkTitle: 1.1.0
+--->
+
+# Schema File Format 1.1.0
 
 **Status**: [Experimental](../document-status.md)
 
@@ -266,10 +270,10 @@ Here is the structure:
       changes:
         - split:
             # Name of old metric to split.
-            apply_to_metric: 
+            apply_to_metric:
             # Name of attribute in the old metric to use for splitting. The attribute will be
             # eliminated, the new metric will not have it.
-            by_attribute: 
+            by_attribute:
             # Names of new metrics to create, one for each possible value of attribute.
             metrics_from_attributes:
               # map of key/values. The keys are the new metric name starting from this

specification/telemetry-stability.md

@@ -88,7 +88,7 @@ if all the following conditions are fulfilled:
 
 - The change is part of OpenTelemetry semantic conventions and is in a released
   version of the specification.
-- The change has a corresponding [published](schemas/overview.md#opentelemetry-schema)
+- The change has a corresponding [published](schemas/README.md#opentelemetry-schema)
   OpenTelemetry Schema File that describes the change.
 - The produced telemetry correctly specifies the respective Schema URL.
 

specification/versioning-and-stability.md

@@ -159,7 +159,7 @@ Changes to telemetry produced by OpenTelemetry instrumentation SHOULD avoid
 breaking analysis tools, such as dashboards and alerts. To achieve this, while
 allowing the evolution of telemetry and semantic conventions, OpenTelemetry
 relies on the concept of
-[Telemetry Schemas](schemas/overview.md).
+[Telemetry Schemas](schemas/README.md).
 
 Changes to semantic conventions in this specification are allowed, provided that
 the changes can be described by schema files. The following changes can be
@@ -171,7 +171,7 @@ currently described and are allowed:
 
 All such changes MUST be described in the OpenTelemetry
 [Schema File Format](schemas/file_format_v1.1.0.md) and published in this repository.
-For details see [how OpenTelemetry Schemas are published](schemas/overview.md#opentelemetry-schema).
+For details see [how OpenTelemetry Schemas are published](schemas/README.md#opentelemetry-schema).
 
 See the [Telemetry Stability](telemetry-stability.md) document for details on how
 instrumentations can use schemas to change the instrumentation they produce.