Skip to content
This repository has been archived by the owner on Jun 15, 2019. It is now read-only.

JSON: usernotes

creesch edited this page Feb 23, 2017 · 10 revisions

Usernotes are stored in /r/subreddit/wiki/usernotes

Implementation Requirements

  • Any implementation where this page is created or modified should include setting the page to be visible for moderators only.
  • Any implementation should check for the schema version used and never write an older schema than indicated in the json.
  • Usernotes as of version schema 6 also make use of zlib to increase the amount of notes that can be stored.

Current schema version is 6. Supported read-only schema versions are 4-5.

Example

{  
    "ver":6,
    "constants": {  
        "users": [  
            "creesch", "TheEnigmaBlade"
        ],
        "warnings": [  
            "none"
        ]
    },
    "blob":"eJyrVkouSk0tTs5QsqpWyitWsooGUkpWSiEZmcUKQJSokJdfkqqko1SiZGVoYmxpZGhuZmmqo5SrZGWgo5QDVJmjY2SQZp6ZA1RTDhSsja2tBQA4HBgB"
}
Decompressed blob
{
    "TheEnigmaBlade": {
        "ns": [
            {
                "n": "The coolest toolbox dev",
                "t": 1430842947,
                "m": 0,
                "l": "l,2oaecb",
                "w": 0
            }
        ]
    },
    "agentlame": {
        "ns": [
            {
                "n": "The lamest toolbox dev",
                "t": 1430856730,
                "m": 1,
                "l": "l,25kvck",
                "w": 0
            }
        ]
    }
}

Structure

Top-level structure
  • ver: The schema version used
  • constants: For storing mod names and note types
    • users: An array of mod username constants
    • warnings: An array of note type constants
  • blob: A base64-encoded and zlib-compressed json object containing note data
Matching warnings constants to note colors and warning texts.

By default toolbox will use the below array to determine the warnings constants available. Where key matches with the warnings value. When a usernote is created toolbox will offer the categories as defined in this array as available options and on saving will check if the constant is already defined in warnings array and otherwise add it.

const defaultUsernoteTypes = [
        {key: 'gooduser', color: 'green', text: 'Good Contributor'},
        {key: 'spamwatch', color: 'fuchsia', text: 'Spam Watch'},
        {key: 'spamwarn', color: 'purple', text: 'Spam Warning'},
        {key: 'abusewarn', color: 'orange', text: 'Abuse Warning'},
        {key: 'ban', color: 'red', text: 'Ban'},
        {key: 'permban', color: 'darkred', text: 'Permanent Ban'},
        {key: 'botban', color: 'black', text: 'Bot Ban'}
    ]

However subreddits can define custom types which need to be stored in the toolbox configuration. When the usernoteColors array is filled in there it will use that array instead of the default array. Note: Any usernotes implementation that supports the ability to define custom usernoteColors should use the default array as basis. For example: when the gooduser key is changed to averageuser the entire default array should be copied into the toolbox configuration json, not just the changed array value.

Blob

The blob is decompressed into the data object used in schema 5, which is the format used internally by toolbox (see the source code for more information). This object contains a set of notes objects associated with noted users' names.

Notes object structure
  • ns: A list of note objects on a user, short for "notes"
Note object structure
  • n: The note text, short for "note"
  • l: The thing information to which the note links, short for "link"
  • t: The time the note was made in seconds (schema 4 uses milliseconds), short for "time"
  • m: An index from the users constants array, short for "mod"
  • w: An index from the warnings constants array, short for "warning" ("type" used internally)

Thing information (l) has three possible formats depending on thing type:

  1. Post: l,POST_ID
  2. Comment: l,POST_ID,COMMENT_ID
  3. Modmail: m,MESSAGE_ID