Spec AS registration format

[non-Jedi]

Currently the spec leaves the format of AS registration files completely
undefined. In fact, the current verbiage doesn't even make it completely clear
that the registration is an actual on-disk file. In practice, of course, synapse
requires a yaml registration file. The spec needs to clarify that either:

1. Registration is an entirely implementation-specific thing where
   implementations should expect the following set of fields.
2. Registration is a physical file with a specific format (yaml, JSON, toml, etc.).

If we go for option 2, I would strongly push that we not enshrine any text
format other than JSON in the spec and that yaml not be an acceptable format for
this.

This issue would also be resolved by matrix-org/matrix-spec-proposals#3807.

[turt2live]

From the spec:

The registration is represented by a series of key-value pairs, which this specification will present as YAML.

It's intentionally vague here to allow for homeservers to support alternative formats if they so please, such as JSON APIs. Not all homeservers are required to use a YAML file on a disk.

Does this clear up the confusion a bit?

[non-Jedi]

Not confusion on my part; I saw that it was intentionally open-ended, but to me those registration files are part of the public AS api, so requiring AS to potentially provide multiple formats of registration for different homeservers doesn't sit right.