Extension:Jade/Entity data

From MediaWiki.org
Jump to navigation Jump to search

Jade data exists on wiki pages, as JSON documented here.

Entity targets[edit]

A Jade entity applies to a single wiki entity, given by the Jade entity page's title: "Jade:Diff/543210", which targets a diff with ID 543210 on the wiki.

There are currently two possible target types,

Timeline of edits and how various proposal schemas can be applied.

Jade Entity page title[edit]

Page titles correspond to their target entity like,

en:Special:Diff/12345678 is labeled at en:Jade:Diff/12345678.

Each target entity type has its own page title keyword:

  • Jade:Diff/12345678
  • Jade:Revision/12345678

Note that both namespace and keyword may be translated. For example a revision proposal in Russian Wikipedia might have the title "Суждение:Версия/12345678". The Jade API provides a mechanism for providing "entitydata" in an untranslated format. E.g. in Russian Wikipedia, you can reference title=Суждение:Версия/12345678 with entitydata={"type": "revision", "id": 12345678}.

See $wgJadeEntityTypeNames in mediawiki-config to translate.

Proposal scoring schema[edit]

Schemas and their data formats are documented in JADE/Labels, and we summarize here:

  • damaging - boolean. Is this diff damaging to the content? false.
  • goodfaith - boolean. Was this diff made in good faith? true.
  • contentquality - integer. Generally, this refers to a quality scale that looks like the Wikipedia 1.0 assessment in English Wikipedia or the item quality scale in Wikidata.

Namespaces[edit]

Jade entity pages are stored on the same wiki as the page being judged, in the Jade namespace. Permissions for this namespace should be the same as for regular content namespaces. There is also a Jade_talk namespace for discussion about each Jade page.

Data structure[edit]

For more sophisticated integrations, you might want to read and manipulate the Jade entity structure directly. Jade pages are organized by facet, contain a list of proposals for each facet.

Scoring schemas can only be used on a specific entity type, configure $wgJadeAllowedScoringSchemas if you need to change the allowed schemas for any entity type. Wikidata for example overrides the default contentquality quality scale with $wgJadeAllowedScoringSchemas['revision'] = [ 'itemquality' ], implementing its own quality scale.

One proposal per facet must be chosen as the preferred value, this indicates the current consensus opinion.

The minimum valid Jade entity page:

 1 {
 2     "facets": {
 3         "editquality": {
 4             "proposals": [
 5                 {
 6                     "labeldata": {
 7                         "damaging": false,
 8                         "goodfaith": true
 9                     },
10                     "notes": "this makes more sense",
11                     "preferred": true,
12                     "author": {
13                         "ip": "10.0.2.2"
14                     },
15                     "endorsements": [
16                         {
17                             "author": {
18                                 "ip": "10.0.2.2"
19                             },
20                             "comment": "As proposer",
21                             "origin": "mw-api-sandbox",
22                             "created": "2019-12-20T15:58:42+00:00",
23                             "touched": "2019-12-20T15:58:42+00:00"
24                         }
25                     ]
26                 }
27             ]
28         }
29     }
30 }

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

 1 {
 2     "facets": {
 3         "editquality": {
 4             "proposals": [
 5                 {
 6                     "labeldata": {
 7                         "damaging": false,
 8                         "goodfaith": true
 9                     },
10                     "notes": "this-makes-more-sense",
11                     "preferred": true,
12                     "author": {
13                         "ip": "10.0.2.2"
14                     },
15                     "endorsements": [
16                         {
17                             "author": {
18                                 "ip": "10.0.2.2"
19                             },
20                             "comment": "As proposer",
21                             "origin": "mw-api-sandbox",
22                             "created": "2019-12-20T15:58:42+00:00",
23                             "touched": "2019-12-20T15:58:42+00:00"
24                         }
25                     ]
26                 },
27                 {
28                     "labeldata": {
29                         "damaging": true,
30                         "goodfaith": false
31                     },
32                     "notes": "this is vandalism!",
33                     "preferred": false,
34                     "author": {
35                         "id": 1,
36                         "cid": 1
37                     },
38                     "endorsements": [
39                         {
40                             "author": {
41                                 "id": 1,
42                                 "cid": 1
43                             },
44                             "comment": "As proposer.",
45                             "origin": "mw-api",
46                             "created": "2020-01-03T21:18:49+00:00",
47                             "touched": "2020-01-03T21:18:49+00:00"
48                         }
49                     ]
50                 }
51             ]
52         }
53     }
54 }

Endorsements[edit]

Each proposal may have zero or more endorsements. A user may only endorse one proposal within a facet. An endorsement is identified by: entity data, facet, and user data. (Note that label data is implied because a user can only endorse one proposal per facet). Users can add a comment to their endorsement, otherwise it will default to "As Proposer".

Validation[edit]

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.

Jade entity 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 will appear on save, if there are problems with your syntax. Feel free to reach out to us for debugging help.