"As an API Developer, I want to declare my JSON parameter expectations once, so they can be validated by the REST infrastructure."
We need a mechanism for API developers to declare the properties of JSON objects they expect to receive in requests.
(Original description)
Most handlers in the MediaWiki REST API will use JSON. Validation of JSON structure is thus a shared concern the API needs to provide some utility for. To avoid duplication of effort, it should probably be the same utility that generates documentation, since that's also mostly about describing what structure is expected.
As the future of MediaWiki (especially with multi-content revisions) probably involves a lot of structured data, which shares validation concerns, we should look for a mechanism that can be reused for validating revision content objects.
The obvious candidate is JSON Schema, which almost everyone has standardized on by now. The main question would be which version to choose (there are two main flavors, draft 4/5 and draft 6/7).
- Spec compatibility: OpenAPI 3 (which we want to be able to express our API specifications in) uses draft 5 with some extensions.
- Software support: there are three popular PHP JSON Schema validators: justinrainbow/json-schema (by far the most popular one) seems to support draft 4, the Opis validator supports draft 7, Swaggest supports both 5 and 7. At a glance the 4/6 differences (6 and 7 are mostly the same) are pretty minor.
- Uniformity within MediaWiki: per T147137: Decide on JSON validation library, our analytics-related extensions (EventLogging, FileAnnotations, CollaborationKit, UploadWizard (Campaigns)) use v3-ish with a homegrown validator, Kartographer and extension.json use justinrainbow/json-schema (schema version not specified).
See also: