Moving towards stronger schemas for response types

[erikjohnston]

We've recently had a number of issues with Synapse returning unspecced fields in API response that clients have ended up relying on.

There are two related questions here:

1. How do we ensure that our API responses match the spec?
2. Can we automatically detect in CI when we change an API response, so that we can flag that extra care must be taken?

Long term there is a desire to move to generating responses via swagger from the Spec.

[DMRobertson]

IIRC the swagger API has additionalProperties: true everywhere, either implicitly or explicitly. I think we'd have to change that if we wanted this enforcement to be automatic?

[richvdh]

I don't think it sets additionalProperties: true for most responses?

[DMRobertson]

additionalProperties: true is the default. To quote https://swagger.io/specification/#schema-object:

additionalProperties - Value can be boolean or object. Inline or referenced schema MUST be of a Schema Object and not a standard JSON Schema. Consistent with JSON Schema, additionalProperties defaults to true.

See also the discussion on matrix-org/matrix-spec#1162 (review)