JADE/Integration

This page describes what data can be included in JADE content. It is intended for developers and integrators. Support is provided by the JADE MediaWiki extension, only available on the Beta Cluster until further notice.

Judgments
A user can make judgments about three types of wiki entities:


 * Diff - Any edit to a page, for example https://en.wikipedia.org/?diff=12345678
 * Revision - Snapshot of a page's content, for example https://en.wikipedia.org/wiki/Sinharaja_Forest_Reserve?oldid=12345678
 * Page - Attributes of a page which won't change as the page evolves. For example, categories or WikiProjects it might be associated with, or whether the subject is notable.

Judgments are stored together on a wiki page, with one page per entity. Each page contains judgment schemas, and a list of judgments for each schema. Schemas and their data formats are documented in JADE/Labels, and summarized here:


 * damaging - boolean. Is this diff damaging to the content?  false.
 * goodfaith - boolean. Was this diff made in good faith?  true.
 * drafttopic - list of page topics: ["Hobo stories", "Biography"]
 * itemquality - string. Wikidata item quality: "A"
 * wp10 - string. Wikipedia 1.0 assessment (but without lists for some reason): "Stub"

To endorse a judgment, either post a signed comment to its talk page or create another judgment with supporting data and your own comments.

To challenge a judgment, you may use its talk page, or create and endorse an alternative judgment.

These mechanisms should support both Wikipedia's Bold-Revert-Discuss and !vote standards for building consensus, as needed.

We encourage users and integrators to offer free-text justifications or other explanations in the judgment  field. These notes are stored publicly as part of the judgment page and can be edited later.

API
We recommend going through the API for most tasks, since it hides some of the complexities of translation and data structure. There will be two API methods supplied through MediaWiki:


 * createjudgment - Create a single judgment about an entity.

Signature:$\text{entity-type, entity-id, schema, data, [notes], [summary], [tags]} \rightarrow \text{status}$ "Example (must also post a token):"


 * getjudgments - Get the page for all judgments about an entity. Can be called as a generator.

Signature: $\text{entity-type, entity-id} \rightarrow \text{judgment-page}$ "Example:"

Wiki, namespace, and title
Judgments are stored on the same wiki as the page being judged, in the  namespace. Permissions for this namespace should be the same as for regular content namespaces. There is also a  namespace for discussion about each JADE page.

The title must correspond to the entity being judged. For example, judgments about the edit https://en.wikipedia.org/?diff=12345678 must appear at https://en.wikipedia.org/wiki/Jade:Diff/12345678. Each type of wiki entity has its own page title structure:


 * Jade:Diff/12345678
 * Jade:Revision/12345678
 * Jade:Page/582115

Note that page titles are translated, for example Russian Wikipedia would have "Суждение:Версия/12345678". These translations are managed in configuration, and ideally are not changed after deployment. See  in mediawiki-config to translate.

Data structure
For more sophisticated integrations, you might want to read and manipulate the judgment structure directly. JADE pages are organized by schema, contain a list of judgments for each schema.

Scoring schemas can only be used on a specific entity type, configure  if you need to change the allowed schemas for any entity type. Wikidata overrides the default  quality scale with , implementing its own quality scale.

One judgment per schema may be chosen as the  value, which should be used to indicate consensus.

The minimum valid  judgment page:

A more interesting example, with conflicting judgments (this is fine), some notes, and both  schemas represented.

Each wiki entity type supports different schemas, here is a  judgment.

Page judgments aren't specific to a revision, for example a page should address the same, mostly stable set of topics over its entire lifetime.

Validation
JADE pages are validated before they are saved to the database, and if the data format is incorrect the edit will be aborted. Internally, we specify most of our validation rules as a JSON schema, which you can read here. You can run your own validation locally using the JSON schema libraries available for many programming languages.

Judgment content must refer to a real revision or page.

An additional validation is done on the page title, which must match the entity being judged as described above.

Detailed validation errors are generated internally, but aren't made available to frustrated users—please follow progress in https://phabricator.wikimedia.org/T197653

Bots, abuse, notability
The JADE service can only handle a small volume of judgments at the moment, so we ask that discretion is used when writing any automation against it. There is storage available for judgments, but only for a human-scale magnitude of them. Please do not create judgments for any type of "autopatrolled" predictions.

Beyond this initial holding-back of bot opinions, we don't have notability requirements for JADE. Enjoy!

Interface translation
To support your language, please help translate at https://translatewiki.net/wiki/Special:MessageGroupStats?group=ext-jade