Skip to Content
ScriptsSchema

Schema

The schema provides metadata of the script and should be placed at the top of the script file.

Every script needs to conform to the schema.

/*
@okjson.schemaVersion 1
@okjson.name Copy As Minified JSON
@okjson.description Copy input string as minified JSON.
@okjson.icon square.on.circle
@okjson.keyboardShortcut ⌥⌘m
@okjson.preprocessInput yes
@okjson.openResultInNewWindow no
@okjson.author OK JSON
@okjson.authorURL https://okjson.app
*/
PropertyRequiredDefault Value
schemaVersion✅
name✅
description❌
icon❌curlybraces
keyboardShortcut❌
preprocessInput❌yes
openResultInNewWindow❌yes
author❌
authorURL❌

The schema can be as minimal as:

/*
@okjson.schemaVersion 1
@okjson.name Copy As Minified JSON
*/

schemaVersion

  • Required.
  • Available option: 1

Reserved for future use.

name

  • Required.

The name of the script.

description

  • Optional.

The detailed description of the script.

icon

  • Optional.

  • Default: curlybraces

The icon of the script. It’s SF Symbols  from Apple.

keyboardShortcut

  • Optional.

Assign keyboard shortcut to the script. The shortcut needs to have at least one modifier and one key.

The available modifiers are Control ⌃, Option ⌥, Shift ⇧, and Command ⌘.

For example, ⌘b, ⇧⌘k, and ⌃⌥⌘2 are valid keyboard shortcuts.

Before assigning keyboard shortcut, you need to check the main menu for conflicts. Otherwise the keyboard shortcut will not take effect.

If you really need the conflicting keyboard shortcut for your script, you can change the keyboard shortcut of the original menu item .

preprocessInput

  • Optional.

  • Available options: yes | no

  • Default: yes

OK JSON passes the string as the input to the script. But in most cases, you want to deal with JSON object. Hence the preprocess.

The exact preprocess OK JSON does here is:

preprocess-script.js
function entry(string, tabSize) {
  let input = string;
  try {
    input = JSON.parse(string);
  } catch {
    // Not JSON: main gets the string as it is.
  }
  let result = main(input);
  if (result && typeof result === 'object') {
    return JSON.stringify(result, null, tabSize);
  }
  return result;
}

With this preprocess you can get the JSON object in the main function immediately. If the input is not valid JSON, main gets the string as it is.

main runs only once. If it throws an error, OK JSON shows the error in an alert.

If you want the type of main function’s parameter remains string, set this option to no. Scripts that work with text, such as XML or timestamps, should do so: text like 42 or true is valid JSON too, so it would arrive as a number or a boolean.

Earlier versions of OK JSON ran main a second time with the string when it threw an error. If your script relied on that to get text, set this option to no.

OK JSON also processes the return value of the script with JSON.stringify.

OK JSON always assumes the type of the return value of the scripts is string.

So if you set preprocessInput to no and the return value is not string, you need to convert it with JSON.stringify in your script.

openResultInNewWindow

  • Optional.

  • Available options: yes | no

  • Default: yes

If OK JSON should open the result window after the script is finished running.

In the result window, the input will be shown in left pane while the output in right pane.

author

  • Optional.

The author of the script.

authorURL

  • Optional.

The website of the author of the script.

ScriptsAPI