matrix-org / matrix-org/matrix-spec

Client `.well-known` spec should explicitly specify that `Content-Type` isn't strict

Open
#1,202 1 comment 0 reactions 0 assignees View on GitHub
clarification
Dominant language
HTML
Stars
330
Forks
150
Avg merge
2h 21m
Merged PRs (30d)
3

Description

**Link to problem area**: https://spec.matrix.org/v1.3/client-server-api/#well-known-uri

**Issue**

While the [server-server .well-known spec](https://spec.matrix.org/v1.3/server-server-api/#getwell-knownmatrixserver) explicitly says

> The `Content-Type` for this response SHOULD be `application/json`, however servers parsing the response should assume that the body is JSON regardless of type.

the client .well-known spec doesn't have that sentence, which may lead people to believe that the content-type must be `application/json` as per the [API standards](https://spec.matrix.org/v1.3/server-server-api/#api-standards) section.

I don't think there's any reason for the rules to be different, since clients don't need to care about the content-type either. CORS is more important, but there are plenty of ways to host .well-known where CORS headers are set, but `Content-Type` can't be customized (e.g. GitHub pages)

Related: #1025

Contributor guide

Open the contributing guide

Research direction

Open the client-server API `.well-known` URI section linked in the issue and compare its Content-Type wording with the server-server specification quoted there. Update the client specification to state that responses should be treated as JSON regardless of Content-Type, then verify the rendered section clearly includes the new guidance.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
1/5
Estimated time
Under an hour
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.