@Halfak here is a first attempt at the API spec, based on all the notes and wire frames:
https://etherpad.wikimedia.org/p/jade_api_spec

Also, here is an updated schema with a few minor changes (mostly renaming judgement to label and adding a unique identifier):
https://etherpad.wikimedia.org/p/jade_schema_v2

I think a good next step for the updated schema is to submit a patchset to gerrit. I can review and approve there.

Otherwise, the Jade API spec looks good at first glance. I'm going to spend some time with the schema and some of the wireframes before I fully sign off.

OK. I've created a new iteration on the schema. https://etherpad.wikimedia.org/p/jade_schema_v3

I solved a few problems where we were using "oneOf"s that would have allowed for mismatched data. I also simplified situations where we get something like {"type": "contentquality", "proposals": {"schema": {"contentquality": 3 so that it is now just "contentquality": {"proposals": {"data": 3. Less duplication.

I also managed reducing some DRY issues by implementing a base "proposal" schema and then implementing the differences between contentquality and editquality (just the "data" field). Look for the use of "allOf" in #/definitions/proposals/...

Otherwise, I made an aesthetics-based judgment call to make the list of "facets" a map (object) instead.

See also updates to https://www.mediawiki.org/wiki/JADE/Glossary

Biggest change is that a collection of "proposals" is now called a facet. I like the word "facet" because it means both an aspect of a thing and also a flat surface of a gem (and Jade is a gem).

Re. the API spec. I wonder if we can limit our endpoints and handle most of the logic for the user. E.g. if a user calls action=jadePropose, there are four possible states:

1. The entity page doesn't exist at all.
   • Create the page, the relevant proposal and add an endorsement from the user.
   • Set the preferred bit to point to the new proposal.
2. The entity page exists but no matching proposed label.
   • Create the relevant proposal and add an endorsement from the user.
   • If another proposal exists for the target facet, leave the preferred bit alone otherwise, set the bit.
3. The entity page exists and there's a proposed label with matching data.
   • Add an endorsement to the relevant proposal and leave preference alone.
   • A warning is returned to the user if they specified a comment and a comment is already present in the proposal.
4. The user already has an endorsement for this facet but it is for a different proposal.
   • Move the user's endorsement from the other proposal to the target proposal, creating it if necessary.
   • If the other proposal was preferred but now has no more endorsements, move the preference bit as well.

For this endpoint, we'd need to match the data of the request with the data of proposals. We'll also need to know what facet they are aiming to affect.

action=jadePropose
description: 
@param entity_type (str) // the type of entity (revision/diff/etc.) [required]
@param entity_id (number) // the ID of the entity [required]
@param data (str) JSON encoded target data ex: {'goodfaith': (bool) 'damaging': (bool)} [required]
@param comment (string)
@param notes (string)
@param token (string) [required]
returns: entity w/ single proposed label + endorsement (json)

What do you think of this type of pattern? Is this crazy?

BTW, my main motivation for this proposal is to make work for 3rd party tool devs as easy as possible. It would be nice if they could call a single endpoint with the same data and have the most reasonable thing happen without having to implement a ton of logic.

E.g. A user is using Huggle to review edits. That user flags an edit as bad. Huggle makes a simple API call for the entity with {damaging: true, goodfaith: false} and the right thing just happens regardless of the state of the entity page.

@Halfak this approach makes sense. I believe we can implement a single API module that determines the context of each request and then calls methods to handle each case. Also, I think we'll need to include a couple more parameters to action=jadePropose for handling actions like setting a preferred label and deleting stuff. I'll try and map out all of those tomorrow.

I think the updated schema looks good as well, 'facet' seems like a good name for a collection of proposals. I'll add it as a patchset to gerrit.

https://gerrit.wikimedia.org/r/c/mediawiki/extensions/Jade/+/525699

I just made some notes on the patch and updated the etherpad with the new "created" field per our discussion.

Change 525699 had a related patch set uploaded (by Accraze; owner: Accraze):
[mediawiki/extensions/Jade@master] jsonschema: add v1 proposal schema

https://gerrit.wikimedia.org/r/525699

Change 525699 merged by Halfak:
[mediawiki/extensions/Jade@master] jsonschema: add v1 proposal schema

https://gerrit.wikimedia.org/r/525699

Looks like the above patch was really for T229355: Simplify and extend JADE content schema (based on API spec insights)