Page MenuHomePhabricator

REST API Developer declares JSON validation parameters
Open, LowPublic


"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:

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
eprodromou renamed this task from JSON validation in REST API to API Developer declares JSON validation parameters.Wed, Nov 6, 7:52 PM
eprodromou updated the task description. (Show Details)
eprodromou triaged this task as Low priority.Wed, Nov 6, 9:05 PM
Tgr renamed this task from API Developer declares JSON validation parameters to REST API Developer declares JSON validation parameters.Thu, Nov 7, 12:32 AM