Reasons to NOT add a list of valid services to the spec

• Adding an allow list to the spec is challenging without having 2 sources of truth. Because it is currently a static schemas.json file we'd need to keep this in sync with ExternalServices.php which would probably require some clever additional test or be fragile to developers making mistakes.
• We would need to always update the spec
• Users referring to a historic spec might have differing expectations
• It might suggest to toolbuilders to write tools that are less extensible (e.g. they might try to hardcode these values)

Reasons to add the list of services to the spec

• It makes our end-2-end test feel more solid
• It helps set the expectations of tools builders

Thoughts considered but immaterial

• It probably makes no difference for a Wikibase admin. They will be looking in the configuration docs not the spec

We concluded that “the gold plated” solution to the question “do we show the restricted list of services in the OpenApi schema?” would be: yes. We should probably do it in such a way that that source of truth is a json file that is a) added as a ref to the schemas.json and b) used in the php to validate the configuration added by the Wikibase admin.

Change 635270 had a related patch set uploaded (by Tonina Zhelyazkova; owner: Tonina Zhelyazkova):
[mediawiki/extensions/WikibaseManifest@master] Complete the example of external services in the spec

https://gerrit.wikimedia.org/r/635270

Change 635270 merged by jenkins-bot:
[mediawiki/extensions/WikibaseManifest@master] Complete the example of external services in the spec

https://gerrit.wikimedia.org/r/635270

We also added all possible external services values as an example to the open api spec file.
https://gerrit.wikimedia.org/r/plugins/gitiles/mediawiki/extensions/WikibaseManifest/+/refs/heads/master/schemas.json#101
We consider this a central place where toolbuilders might look at for more info about the manifest format.