Wox Plugin JSON Schema Specification

This document defines the schema for plugin.json, the manifest file required for SDK plugins (Node.js/Python).

File Structure

The plugin.json file must be a valid JSON object located in the root of your plugin directory.

Note: Script plugins do not use plugin.json. They embed a JSON metadata block inside the script file comments.

Fields Specification

Required Fields

Optional Fields

QueryRequirements

Use QueryRequirements when a plugin query cannot run until one or more settings are configured. Wox checks these requirements before calling the plugin query() method. If a requirement fails, Wox returns a system setup result with the query_requirement_settings preview and shows a focused settings form for only the missing fields.

Do not return a custom "please configure this plugin" result from query() for these cases. Static metadata gives grid results and normal list results the same setup flow.

Scopes

If a query has a command that is not declared in QueryWithCommand, Wox checks only AnyQuery.

Requirement Shape

{
  "SettingKey": "accessKey",
  "Validators": [{ "Type": "not_empty", "Value": {} }],
  "Message": "i18n:access_key_required"
}

Rules:

• SettingKey must match a configurable setting key from SettingDefinitions.
• Validators is optional. If omitted or empty, Wox reuses the validators from the matching setting definition.
• If both the requirement and setting definition have no validators, Wox logs a metadata issue and does not block the query.
• Message is optional and supports i18n: keys. Use it for field-specific setup guidance.

Example:

{
  "SettingDefinitions": [
    {
      "Type": "textbox",
      "Value": {
        "Key": "accessKey",
        "Label": "i18n:access_key",
        "DefaultValue": "",
        "Tooltip": "i18n:access_key_tooltip",
        "Validators": [{ "Type": "not_empty", "Value": {} }],
        "Style": { "Width": 400 }
      }
    }
  ],
  "QueryRequirements": {
    "AnyQuery": [
      {
        "SettingKey": "accessKey",
        "Message": "i18n:access_key_required"
      }
    ],
    "QueryWithoutCommand": [],
    "QueryWithCommand": {
      "download": [
        {
          "SettingKey": "downloadDirectory",
          "Validators": [{ "Type": "not_empty", "Value": {} }],
          "Message": "i18n:download_directory_required"
        }
      ]
    }
  }
}

SettingDefinitions

Define a list of UI controls for user configuration. Each item is an object with Type and Value. Use this reference as the source of truth when authoring SettingDefinitions in a published plugin or skill.

Common Properties

Validators

Validators are used inside textbox/select values and table columns.

Supported validator types:

• not_empty
• is_number

Examples:

{
  "Type": "textbox",
  "Value": {
    "Key": "timeout_ms",
    "Label": "Timeout",
    "DefaultValue": "300",
    "Validators": [
      {
        "Type": "is_number",
        "Value": { "IsInteger": true, "IsFloat": false }
      }
    ]
  }
}

{
  "Type": "textbox",
  "Value": {
    "Key": "api_key",
    "Label": "API Key",
    "DefaultValue": "",
    "Validators": [
      {
        "Type": "not_empty",
        "Value": {}
      }
    ]
  }
}

1. Textbox

{
  "Type": "textbox",
  "Value": {
    "Key": "apiKey",
    "Label": "i18n:api_key",
    "DefaultValue": "",
    "Tooltip": "Enter your API key",
    "MaxLines": 1,
    "Suffix": "",
    "Validators": [],
    "Style": { "Width": 400 }
  }
}

2. Checkbox

{
  "Type": "checkbox",
  "Value": {
    "Key": "enableFeature",
    "Label": "Enable Feature",
    "DefaultValue": "true",
    "Tooltip": "Toggle this feature",
    "Style": {}
  }
}

3. Select (Dropdown)

{
  "Type": "select",
  "Value": {
    "Key": "theme",
    "Label": "Theme",
    "DefaultValue": "light",
    "Suffix": "",
    "Tooltip": "Theme selection",
    "IsMulti": false,
    "Options": [
      { "Label": "Light", "Value": "light" },
      { "Label": "Dark", "Value": "dark" },
      { "Label": "All", "Value": "all", "IsSelectAll": true }
    ],
    "Validators": [],
    "Style": {}
  }
}

select notes:

• IsMulti enables multi-select.
• Options[].Icon is supported.
• Options[].IsSelectAll is supported for multi-select flows.

4. SelectAIModel

{
  "Type": "selectAIModel",
  "Value": {
    "Key": "default_model",
    "Label": "Default model",
    "DefaultValue": "",
    "Tooltip": "Choose one configured AI model",
    "Validators": [],
    "Style": {}
  }
}

5. Table (List of Items)

{
  "Type": "table",
  "Value": {
    "Key": "shortcuts",
    "DefaultValue": "[]",
    "Title": "Shortcuts",
    "Tooltip": "Editable shortcut list",
    "SortColumnKey": "name",
    "SortOrder": "asc",
    "MaxHeight": 500,
    "Columns": [
      {
        "Label": "Name",
        "Key": "name",
        "Type": "text",
        "Width": 100,
        "Validators": [{ "Type": "not_empty", "Value": {} }]
      },
      { "Label": "Enabled", "Key": "enabled", "Type": "checkbox", "Width": 50 },
      {
        "Label": "Model",
        "Key": "model",
        "Type": "selectAIModel",
        "Width": 120
      }
    ],
    "Style": {}
  }
}

Supported table column types include:

• text
• textList
• checkbox
• dirPath
• select
• selectAIModel
• aiModelStatus
• aiMCPServerTools
• aiSelectMCPServerTools
• woxImage

Table column notes:

• Validators are supported on columns.
• SelectOptions are only used when column type is select.
• TextMaxLines is only used when column type is text.
• HideInTable hides the column in the list but keeps it in the edit dialog.
• HideInUpdate hides the column in the edit dialog but keeps it in the list.

6. Dynamic

dynamic is a placeholder setting that must be resolved at runtime through the plugin API callback:

• Node.js: API.OnGetDynamicSetting(...)
• Python: api.on_get_dynamic_setting(...)

Example:

{
  "Type": "dynamic",
  "Value": {
    "Key": "separatorPreview"
  }
}

7. Other Types

• head: Section header using Content, Tooltip, and Style
• label: Static text using Content, Tooltip, and Style
• newline: Vertical spacer with optional Style

Icon Formats

The Icon string uses a prefix:data format. Supported prefixes:

Features Specification

Enable optional capabilities by adding them to the Features array.

1. AI Integration

Allows the plugin to provide LLM-based chat interactions.

{ "Name": "ai" }

2. Query Selection

Allows the plugin to access the user's currently selected text or files from the active application.

{ "Name": "querySelection" }

3. Query Environment

Allows the plugin to access context about the active window or browser.

{
  "Name": "queryEnv",
  "Params": {
    "requireActiveWindowName": true,
    "requireActiveWindowPid": true,
    "requireActiveWindowIcon": false,
    "requireActiveWindowIsOpenSaveDialog": false,
    "requireActiveBrowserUrl": false
  }
}

4. Debounce

Delays query execution until the user stops typing for IntervalMs.

{
  "Name": "debounce",
  "Params": { "IntervalMs": 300 }
}

5. MRU (Most Recently Used)

Enables automatic boosting of frequently used results.

{
  "Name": "mru",
  "Params": { "HashBy": "title" } // Options: "title", "rawQuery", "search"
}

6. Grid Layout (Deprecated)

Displays results in a grid instead of a list.

Prefer returning QueryResponse.Layout.GridLayout from the SDK query method. The metadata feature is deprecated because it can only express static plugin or command defaults, while QueryResponse can choose the layout for each query.

{
  "Name": "gridLayout",
  "Params": {
    "Columns": 4,
    "ShowTitle": true,
    "ItemPadding": 10,
    "ItemMargin": 5,
    "Commands": [] // Empty = apply to all, or list specific trigger keywords
  }
}

7. Other Features

• deepLink: Handle custom URI schemes (e.g., wox://plugin/myplugin?arg=value).
• ignoreAutoScore: Disable Wox's default frequency-based learning for this plugin.
• resultPreviewWidthRatio (deprecated): Customize the split ratio between result list and preview panel (0.0 - 1.0). Prefer QueryResponse.Layout.ResultPreviewWidthRatio so the ratio can change per query.

Complete Example

{
  "Id": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
  "Name": "Super Search",
  "Version": "1.2.0",
  "MinWoxVersion": "2.0.0",
  "Runtime": "NODEJS",
  "Entry": "dist/index.js",
  "Icon": "emoji:🔍",
  "TriggerKeywords": ["ss", "search"],
  "SupportedOS": ["Windows", "Darwin"],
  "Features": [{ "Name": "querySelection" }, { "Name": "debounce", "Params": { "IntervalMs": 200 } }]
}