[schema] Application Service Registration meta schema

[V02460]

Sets the meta schema for the Application Service Registration to https://json-schema.org/draft/2020-12/schema. Specifying the meta schema clarifies the semantics of the schema files and allows tools to consume it correctly.

It seems to me that the registration.yaml and namespace_list.yaml are completely disjunct from the other OpenAPI schemas in the data/api/application-service folder. Because the other files follow OpenAPI v3.1.0, I still chose to use JSON Schema version 2020-12, which is the version that OpenAPI v3.1.0 data types and schema objects are based on.

Relevant parts of the OpenAPI v3.1.0 spec that justify the inclusion of the $schema keyword:

[The Schema Object] is a superset of the JSON Schema Specification Draft 2020-12.

Unless stated otherwise, the property definitions follow those of JSON Schema and do not add any additional semantics.

From https://spec.openapis.org/oas/v3.1.0.html#schema-object

Pull Request Checklist

• Pull request includes a changelog file
• Pull request includes a sign off
• Pull request is classified as 'other changes'

Preview: https://pr2132--matrix-spec-previews.netlify.app

[tulir]

There don't seem to be $schemas in any of the files currently. If we add it, it should probably be consistent everywhere rather than just in 2 files

[V02460]

@tulir: I don’t think that is necessary. These two files are special in that they

a) are useful as JSON Schema files independently of OpenAPI definitions. While OpenAPI has well-defined implicit meta schemas, that’s not the case for JSON Schemas.
b) are not actually used by any of the OpenAPI files – I think they were simply snuck in there for lack of a better location.

[KitsuneRal]

I agree that OpenAPI files don't necessarily need that because they have their own schema version designator already. However, we also have event schemas written as JSON Schema files (despite them having .yaml extension); point a) certainly applies to them as well. Point b) is rather irrelevant: the rationale of adding schema to JSON Schema files (clearer semantics and tooling-friendliness) is the same regardless of where they are located.

Would you be willing to extend the PR to other JSON Schema files under data? Would actually be interesting to see if specifying the schema would break anything.

[anoadragon453]

Would you be willing to extend the PR to other JSON Schema files under data? Would actually be interesting to see if specifying the schema would break anything.

@V02460 what do you think?

[V02460]

Thanks for the ping :) Are we talking about the files under data/event-schemas and data/schemas? I could add meta schemas for them, too.

[KitsuneRal]

Both; but event-schemas are most interesting.

[V02460]

I added the meta schema to all the event schemas.

For the other files in the definition folders I did not add the meta schema for now, because they seem more OpenAPI-adjacent and imo are not as useful on their own. (E.g. they use the example keyword which, in contrast to examples, is a keyword unknown to JSON Schema.)

[V02460]

Also I found out that schemas are already checked against https://json-schema.org/draft/2020-12/schema:

matrix-spec/scripts/check-json-schemas.py

Line 139 in fb4a0d8

validator = jsonschema.validators.Draft202012Validator

matrix-spec/scripts/check-json-schemas.py

Lines 175 to 182 in fb4a0d8

	schema_dirs = [
	"api/application-service/definitions",
	"api/client-server/definitions",
	"api/identity/definitions",
	"api/server-server/definitions",
	"event-schemas/schema",
	"schemas",
	]

.

[V02460]

Do I need to add a second newsfragment somewhere for the event schema changes?

[anoadragon453]

@V02460 event definitions are currently considered to be part of the C-S API. A newsfile under changelogs/client_server/newsfragments would make sense to me.