matrix-org / matrix-org/matrix-spec

Data type of `url` field within Application Service registration file is confusing

Open
#2,155 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

improvement
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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.