matrix-org / matrix-org/matrix-spec
Data type of `url` field within Application Service registration file is confusing
Nobody has claimed this yet.
- Dominant language
- HTML
- Stars
- 330
- Forks
- 150
- Avg merge
- 2h 21m
- Merged PRs (30d)
- 3
Description
**Suggestion**
The `url` field, defined [here](https://spec.matrix.org/v1.14/application-service-api/#definition-registration_registration), within an application service registration file can either be set to a `string` representing the URL of an application service, or `null`. But the field cannot be omitted. If the field is `null`, then the homeserver should not send events to the application service.
This is a subtle, yet important difference. The subtlety of it has caused implementations to accidentally make the field optional: https://github.com/matrix-org/matrix-spec/pull/2130#issuecomment-2903813243
Even when those implementations were fixed, it required a [relatively complex change](https://github.com/ruma/ruma/issues/2074) to realise.
I believe this behaviour should be deprecated, and instead we should use a simpler mechanism to indicate that the Application Service should not receive events. Regardless of the `url` field (which should remain required), a new boolean field `send_events` would control that behaviour.
`url: null` would then be interpreted the same as the field being missing altogether.
To aid with the transition, homeserver implementations could follow the old rules if the `send_events` field were missing. Or, we could add a `version` field to application service files, to allow for breaking changes to go out without deployments immediately needing to update to them.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the Application Service registration definition in the linked Matrix specification section, then review the referenced Matrix spec pull request discussion and Ruma issue for compatibility concerns. Establish the agreed migration and field semantics before updating the specification; done means the behavior and transition rules are unambiguous for implementations.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100