Userscript JSON

A representation of a userscript resource in JSON format.

Since: 1.0

This datatype defines the syntax and semantics to encode a userscript in the JavaScript Object Notation (JSON).

JSON is a widely used format to pass representations of entities to and retrieve entities from REST services.

The JSON file has the following format.

Userscript Descriptor in JSON

{
  "namespace": "...",
  "name": "...",
  "version": "...",

  "script": "...",

  "description": "...",
  "documentation": "...",
  "support": "...",

  "activation": {
    "space": ["...", ...],
    "category": ["...", ...],
    "label": ["...", ...],
    "group": ["...", ...],
    "user": ["...", ...]
  }
}

Identifier

The following JSON attributes identify the userscript.

Identifier	Type	Name	Short Description
`namespace`	String	Userscript Namespace	Userscripts are organized in namespaces. This way scripts of different vendors may have the same name, but are still distinguishable by their unique namespace.
`name`	String	Userscript Name	A name identifies a userscript within its namespace.
`version`	Semantic Version	Userscript Version	A version uniquely identifies a userscript within its name and namespaces.

Code

The following JSON attribute references the userscript JavaScript code.

Identifier	Type	Name	Short Description
`script`	URL	Userscript Code URL	The URL to the JavaScript code of the userscript.

Metadata

The following JSON attributes provide additional information on the userscript.

Identifier	Type	Name	Short Description
`description`	String	Userscript Description	A short description about the purpose of the userscript.
`documentation`	URL	Userscript Documentation	A reference to the online documentation of the userscript.
`support`	String	Userscript Support	Provides information about the support of the userscript.

Activation Record

The activation record is defined with the JSON attribute activation, which is a map of attributes.

The activation record provides the following JSON attributes to control in which context the referenced userscript is executed.

Identifier	Type	Name	Short Description
`space`	Strings	Activation by Space	A script is activated if the user is viewing resources on a specific space.
`category`	Strings	Activation by Space Category	A script is activated if the user is viewing resources on space tagged with a given category.
`label`	Strings	Activation by Page Label	A script is activated if the user is viewing a page, tagged with a given label.
`group`	Strings	Activation by User Group	A script is activated if the user is member of a specified group.
`user`	Strings	Activation by User Name	A script is activated if the user is explicitly referenced by its name.