Page MenuHomePhabricator

JSON validation in REST API
Open, Needs TriagePublic

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:

Event Timeline

Tgr created this task.May 26 2019, 5:21 PM
Restricted Application added a subscriber: Aklapper. · View Herald TranscriptMay 26 2019, 5:21 PM
Tgr renamed this task from JSON validation in REST API and MediaWiki in general to JSON validation in REST API.May 26 2019, 5:37 PM

OpenAPI 3 (which we want to be able to express our API specifications in) uses draft 5 with some extensions.

It uses what they call an 'extended subset' - thus they have not only added certain properties but also dropped support for some and redefined the meaning of some keywords. From practical experience with swagger, we've mostly used simple-enough cases to conform to both Open API flavor and canonical JSON-schema. However, we probably shouldn't standardize on the OpenAPI flavour as it's much less widely used as canonical JSON schemas.

our analytics-related extensions (EventLogging ...

Draft-05 based events in EventLogging are being deprecated and moved to draft-07 and eventgate. Main kafka cluster events will also be moved to draft-07.

Draft-07 please! :)

For event schemas, we will be developing a WMF event meta schema that we will use to validate the event schemas themselves. This will allow us to enforce certain conventions during schema development with CI. See T214093: Modern Event Platform: Schema Guidelines and Conventions and T201063: Modern Event Platform: Schema Registry

Tgr removed Tgr as the assignee of this task.Jul 14 2019, 4:01 PM