Specify the result of `/schemas` URL in the telemetry schema portion of the specification.

[svrnm]

What are you trying to achieve?

Context:

• https://github.com/open-telemetry/opentelemetry.io/issues/3468
• https://github.com/open-telemetry/opentelemetry.io/issues/3256

We see many users looking for a page that provides them with a list of available schemas, either because they want to know what the latest version is or they want to create some automation to crawl the list of published schemas and do something with them.

As of today opentelemetry.io/schemas gives a 404.

What did you expect to see?

There are 2 audiences we want to serve:

• people exploring our website opentelemetry.io, looking for the list of available schemas (I have been there myself, trying to figure out what the current version is, and it takes some time to find that, because the obvious place (http://opentelemetry.io/schemas) gives me nothing))
• people building automation (like https://github.com/open-telemetry/opentelemetry.io/issues/3256), that need a machine readable format to get a list.

@chalin proposed that https://opentelemetry.io/schemas/ provides a response based on the HTTP request:

This means, someone who wants a machine readable format would go to:

$ curl -H "Accept: application/json" https://opentelemetry.io/schemas/
... # JSON data response

Someone who wants a human readable format goes to

$ curl -H "Accept: text/html" https://opentelemetry.io/schemas/
... # HTML data response

As discussed in the SIG SemConv call today, we would like to see this "list of available schemas" being specified and then later implemented by us (@open-telemetry/docs-approvers) on the website.

Ideally this starts with a simple JSON (or YAML?) file that just lists the available schemas + their URL.

Additional context.

We have a proposal for an intermediate solution at https://github.com/open-telemetry/opentelemetry.io/pull/3469, this would still give a 404 but that specific 404-page would contain the information people are looking for.

cc @chalin @jsuereth @MrAlias @tigrannajaryan

[chalin]

@jsuereth et al. - we can generate the machine-reable format (maybe in YAML given that the schemas are in YAML) on the OTel website side, from the list of schemas obtained from the semconv repo. This is now the human-readable list is produced: https://deploy-preview-3508--opentelemetry.netlify.app/schemas/list/

[chalin]

@jsuereth, @tigrannajaryan, @open-telemetry/specs-semconv-approvers, et al. - here's an implementation of the schema list in YAML:

• https://github.com/open-telemetry/opentelemetry.io/pull/3537

Is this the format you wanted?

[svrnm]

@jsuereth, @tigrannajaryan, @open-telemetry/specs-semconv-approvers, et al. - here's an implementation of the schema list in YAML:

* [Add `/schemas` in YAML, `/schemas/list` in HTML, and a 404 page for the rest opentelemetry.io#3537](https://github.com/open-telemetry/opentelemetry.io/pull/3537)

Is this the format you wanted?

Thanks, @chalin! @open-telemetry/specs-approvers / @open-telemetry/specs-semconv-approvers the current implementation is a basic list with the version numbers (see the PR), so what we need from you are some suggestions what this list should look like:

• Do we need the URLs alongside the versions or can they remain implicit?
• Should that list be contained in some object

[chalin]

During today's Spec SIG meeting, @jsuereth kindly offered to champion an OTEP for the addition of the schema-list to the OTel spec. Thanks Josh! Please cc @svrnm and me on the OTEP so that I can track progress, and link to it here.

[chalin]

@tigrannajaryan @jsuereth: it is my understanding that to move forward we need two things:

• An OTEP requesting an addition to the OTel spec of a formal description of the format of the schema-list file, akin to the schema file format specification (v1.1.0).
• An actual schema-list file.

While it makes sense to have the schema-list format as part of the OTel spec, IMHO, the actual schema-list file needs to live in the semantic-conventions repo along with the schemas that it lists. Does that make sense?

[svrnm]

using the new labelling, @jsuereth I assume that you are the sponsor of this?

[svrnm]

any updates on this?