`/schemas` is the top 404

[chalin]

Clearly folks are interested in listing the available schemas, because /schemas (or /schemas/) is the #1 legitimate 404. I think that there should be a schemas index page, and will submit a proposal soon.

@tigrannajaryan had already argued against an index page, see https://github.com/open-telemetry/opentelemetry.io/issues/1144#issuecomment-1041845740. I'd like to open this up for discussion and see if we can find a win-win solution.

---

Proposed alternative solutions:

• [ ] #3537
  • [ ] Awaiting the publication of the schema list from the OTel spec.
• ~#3508~
• ~#3469~

Related:

• https://github.com/open-telemetry/opentelemetry-specification/issues/3762

• 3256

/cc @open-telemetry/specs-semconv-maintainers @jsuereth @svrnm @MrAlias

[chalin]

Moving the discussion from https://github.com/open-telemetry/opentelemetry.io/pull/3469#issuecomment-1789588307 - @tigrannajaryan writes:

... I don't think we should publish a human-readable list at /schemas/. My previous argument still holds: if we want /schemas/ to contain anything it should be a machine-readable format defined in Otel spec. Since we don't have such format defined I think we should not publish anything at the index yet.

Note that the path /schemas/ already returns a human readable HTML page (because opentelemetry.io is a documentation website):

$ curl -sI https://opentelemetry.io/schemas/ | grep type
content-type: text/html; charset=utf-8

Are you ok with that?

What is being returned is the default 404 page. We might as well have the 404 page list the available schemas, so it would be more helpful to readers. Let's call this Option 404.

There is another option, discussed next.

---

As you might know, the server can return two different response types for any given path. That is, we can also setup the server to respond to /schemas/ with:

• A schema list in human readable form by default (as an HTML page)
• Data, such as JSON, when an application requests data

Would that serve your needs? Let's call this Option dual-response.

[tigrannajaryan]

Note that the path /schemas/ already returns a human readable HTML page (because opentelemetry.io is a documentation website):

It is a 404 and noone is going to rely on a 404 page having a particular content or format. If we make it return 200 I am worried people will make assumption about it (e.g. parse for the list of schemas). If it is a 404 we keep the option open to introduce a machine-readable format for it.

Let me flip this: why is it a problem that it returns 404?

[chalin]

why is it a problem that it returns 404?

The short answer is that it's not a problem to return a 404. What I gather from your question is that you'd be ok with the "Option 404" solution described above -- i.e., that the 404 page return the schema list?

The longer answer is that 404s over a URL usually indicate that readers are looking for a specific information at that URL, but no content has been published. It seems reasonable to believe that users are visiting /schemas/ with the hope of seeing the list of currently published schemas. That isn't being currently provided, but we can change that by implementing "Option 404" describe previously.

noone is going to rely on a 404 page having a particular content or format.

That isn't true in my experience. Folks browsing with a web browser don't care (or often know) what status code is returned. In fact, some servers use this in creative ways.

Anyhow, if you're comfortable with Option 404, I can move ahead and implement that.

---

Have you given thought to the dual-response option? Any app wanting a machine readable file should request a particular data type:

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

[chalin]

FYI, I've implemented the 404 option in #3469:

$ curl -sI https://deploy-preview-3469--opentelemetry.netlify.app/schemas 
HTTP/2 404 

But this 404 page still shows a human-readable list of schemas via the same path: https://deploy-preview-3469--opentelemetry.netlify.app/schemas/. Is this acceptable to you?

I still think that the dual-response solution would be better. Ok, let's sleep on it ;).

[chalin]

@tigrannajaryan - what's wrong with using another path for the machine-readable schema list? Here are some ideas:

• https://opentelemetry.io/schemas/index.json or .yaml
• https://opentelemetry.io/schemas/list, with or without a suffix like .json or .yaml

[svrnm]

Since @chalin and I talked about this issue during the Comms SIG meeting yesterday, here a few thoughts from my site:

There are 2 audiences we want to serve:

1. people exploring our website, 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))
2. people building automation (like #3256), that need a machine readable format to get a list.

If I understand your (@tigrannajaryan) concern correctly, you worry about people relying on the format of that site (no matter if it is html or json or ...) and going to complain if we ever decide to break it. And since we (=OpenTelemetry Community) made this experience a few times already that people rely on things that are marked "experimental" and then still complain, you are reluctant to have something like that put in place. (And I also see people crawling an HTML page listing the versions and then still complaining that their code breaks when we decide to change the format).

At the same time @chalin reported that http://opentelemetry.io/schemas is one of our top 404s, so people are looking for that thing and have a hard time to find it, so there is an urgent need to have something in place under that URL.

I think that the proposal in PR #3469 is a good common ground, it gives people a list, but still reports a 404 to say "This is not a real thing yet". I think we should also include a verbal disclaimer letting people know that this page is not intended to be consumed automatically and may change in the future.

[chalin]

Thanks for following up on our discussion with some comments here @svrnm. I felt inspired, after the Comms meeting, to further explore the separate list page solution. For an implementation, see:

• 3508

[tigrannajaryan]

The proposal sounds OK to me, but please also bring it to the spec SIG meeting to make sure there are no objections.

[chalin]

@tigrannajaryan - SIG semconv? (Since the schemas are not part of the semconv repo) Or actually SIG Spec?

[tigrannajaryan]

@tigrannajaryan - SIG semconv? (Since the schemas are not part of the semconv repo) Or actually SIG Spec?

Would be nice to do both :-)

[chalin]

Ok, I'll see to schedule that. In the meantime I'll add the SIGs as reviewers to solicit some initial feedback.

[svrnm]

Ok, I'll see to schedule that. In the meantime I'll add the SIGs as reviewers to solicit some initial feedback.

@chalin let me know if you can not attend any of the meetings and I will check my schedule to help with that.

[theletterf]

What's the status of this one?

[svrnm]

What's the status of this one?

it's complicated ;-)

[chalin]

@jsuereth had an action item to move this forward. Any updates @jsuereth?