plugin-manifest.schema.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://databricks.github.io/appkit/schemas/plugin-manifest.schema.json",
  "title": "AppKit Plugin Manifest",
  "description": "Schema for Databricks AppKit plugin manifest files. Defines plugin metadata, resource requirements, and configuration options.",
  "type": "object",
  "required": ["name", "displayName", "description", "resources"],
  "properties": {
    "$schema": {
      "type": "string",
      "description": "Reference to the JSON Schema for validation"
    },
    "name": {
      "type": "string",
      "pattern": "^[a-z][a-z0-9-]*$",
      "description": "Plugin identifier. Must be lowercase, start with a letter, and contain only letters, numbers, and hyphens.",
      "examples": ["analytics", "server", "my-custom-plugin"]
    },
    "displayName": {
      "type": "string",
      "minLength": 1,
      "description": "Human-readable display name for UI and CLI",
      "examples": ["Analytics Plugin", "Server Plugin"]
    },
    "description": {
      "type": "string",
      "minLength": 1,
      "description": "Brief description of what the plugin does",
      "examples": ["SQL query execution against Databricks SQL Warehouses"]
    },
    "resources": {
      "type": "object",
      "required": ["required", "optional"],
      "description": "Databricks resource requirements for this plugin",
      "properties": {
        "required": {
          "type": "array",
          "description": "Resources that must be available for the plugin to function",
          "items": {
            "$ref": "#/$defs/resourceRequirement"
          }
        },
        "optional": {
          "type": "array",
          "description": "Resources that enhance functionality but are not mandatory",
          "items": {
            "$ref": "#/$defs/resourceRequirement"
          }
        }
      },
      "additionalProperties": false
    },
    "config": {
      "type": "object",
      "description": "Configuration schema for the plugin",
      "properties": {
        "schema": {
          "$ref": "#/$defs/configSchema"
        }
      },
      "additionalProperties": false
    },
    "author": {
      "type": "string",
      "description": "Author name or organization"
    },
    "version": {
      "type": "string",
      "pattern": "^\\d+\\.\\d+\\.\\d+(-[a-zA-Z0-9.]+)?$",
      "description": "Plugin version (semver format)",
      "examples": ["1.0.0", "2.1.0-beta.1"]
    },
    "repository": {
      "type": "string",
      "format": "uri",
      "description": "URL to the plugin's source repository"
    },
    "keywords": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Keywords for plugin discovery"
    },
    "license": {
      "type": "string",
      "description": "SPDX license identifier",
      "examples": ["Apache-2.0", "MIT"]
    },
    "onSetupMessage": {
      "type": "string",
      "description": "Message displayed to the user after project initialization. Use this to inform about manual setup steps (e.g. environment variables, resource provisioning)."
    },
    "hidden": {
      "type": "boolean",
      "default": false,
      "description": "When true, this plugin is excluded from the template plugins manifest (appkit.plugins.json) during sync."
    },
    "postScaffold": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/postScaffoldStep"
      },
      "description": "Ordered list of post-scaffolding instructions shown to the user after project initialization. Array position determines display order."
    }
  },
  "additionalProperties": false,
  "$defs": {
    "resourceType": {
      "type": "string",
      "enum": [
        "secret",
        "job",
        "sql_warehouse",
        "serving_endpoint",
        "volume",
        "vector_search_index",
        "uc_function",
        "uc_connection",
        "database",
        "postgres",
        "genie_space",
        "experiment",
        "app"
      ],
      "description": "Type of Databricks resource"
    },
    "secretPermission": {
      "type": "string",
      "enum": ["READ", "WRITE", "MANAGE"],
      "description": "Permission for secret resources (order: weakest to strongest)"
    },
    "jobPermission": {
      "type": "string",
      "enum": ["CAN_VIEW", "CAN_MANAGE_RUN", "CAN_MANAGE"],
      "description": "Permission for job resources (order: weakest to strongest)"
    },
    "sqlWarehousePermission": {
      "type": "string",
      "enum": ["CAN_USE", "CAN_MANAGE"],
      "description": "Permission for SQL warehouse resources (order: weakest to strongest)"
    },
    "servingEndpointPermission": {
      "type": "string",
      "enum": ["CAN_VIEW", "CAN_QUERY", "CAN_MANAGE"],
      "description": "Permission for serving endpoint resources (order: weakest to strongest)"
    },
    "volumePermission": {
      "type": "string",
      "enum": ["READ_VOLUME", "WRITE_VOLUME"],
      "description": "Permission for Unity Catalog volume resources"
    },
    "vectorSearchIndexPermission": {
      "type": "string",
      "enum": ["SELECT"],
      "description": "Permission for vector search index resources"
    },
    "ucFunctionPermission": {
      "type": "string",
      "enum": ["EXECUTE"],
      "description": "Permission for Unity Catalog function resources"
    },
    "ucConnectionPermission": {
      "type": "string",
      "enum": ["USE_CONNECTION"],
      "description": "Permission for Unity Catalog connection resources"
    },
    "databasePermission": {
      "type": "string",
      "enum": ["CAN_CONNECT_AND_CREATE"],
      "description": "Permission for database resources"
    },
    "postgresPermission": {
      "type": "string",
      "enum": ["CAN_CONNECT_AND_CREATE"],
      "description": "Permission for Postgres resources"
    },
    "genieSpacePermission": {
      "type": "string",
      "enum": ["CAN_VIEW", "CAN_RUN", "CAN_EDIT", "CAN_MANAGE"],
      "description": "Permission for Genie Space resources (order: weakest to strongest)"
    },
    "experimentPermission": {
      "type": "string",
      "enum": ["CAN_READ", "CAN_EDIT", "CAN_MANAGE"],
      "description": "Permission for MLflow experiment resources (order: weakest to strongest)"
    },
    "appPermission": {
      "type": "string",
      "enum": ["CAN_USE"],
      "description": "Permission for Databricks App resources"
    },
    "resourceFieldEntry": {
      "type": "object",
      "description": "Defines a single field for a resource. Each field has its own environment variable and optional description. Single-value types use one key (e.g. id); multi-value types (database, secret) use multiple (e.g. instance_name, database_name or scope, key).",
      "properties": {
        "env": {
          "type": "string",
          "pattern": "^[A-Z][A-Z0-9_]*$",
          "description": "Environment variable name for this field",
          "examples": ["DATABRICKS_CACHE_INSTANCE", "SECRET_SCOPE"]
        },
        "description": {
          "type": "string",
          "description": "Human-readable description for this field"
        },
        "bundleIgnore": {
          "type": "boolean",
          "default": false,
          "description": "When true, this field is excluded from Databricks bundle configuration (databricks.yml) generation."
        },
        "examples": {
          "type": "array",
          "items": { "type": "string" },
          "description": "Example values showing the expected format for this field"
        },
        "localOnly": {
          "type": "boolean",
          "default": false,
          "description": "When true, this field is only generated for local .env files. The Databricks Apps platform auto-injects it at deploy time."
        },
        "value": {
          "type": "string",
          "description": "Static value for this field. Used when no prompted or resolved value exists."
        },
        "resolve": {
          "type": "string",
          "pattern": "^[a-z_]+:[a-zA-Z]+$",
          "description": "Named resolver prefixed by resource type (e.g., 'postgres:host'). The CLI resolves this value during the init prompt flow."
        },
        "discovery": {
          "$ref": "#/$defs/discoveryDescriptor",
          "description": "How the CLI discovers values for this field via a Databricks CLI command."
        }
      },
      "additionalProperties": false
    },
    "resourceRequirement": {
      "type": "object",
      "description": "Declares a resource requirement for a plugin. Can be defined statically in a manifest or dynamically via getResourceRequirements().",
      "required": ["type", "alias", "resourceKey", "description", "permission"],
      "properties": {
        "type": {
          "$ref": "#/$defs/resourceType"
        },
        "alias": {
          "type": "string",
          "minLength": 1,
          "description": "Human-readable label for UI/display only. Deduplication uses resourceKey, not alias.",
          "examples": ["SQL Warehouse", "Secret", "Vector search index"]
        },
        "resourceKey": {
          "type": "string",
          "pattern": "^[a-z][a-z0-9-]*$",
          "description": "Stable key for machine use: deduplication, env naming, composite keys, app.yaml. Required for registry lookup.",
          "examples": ["sql-warehouse", "database", "secret"]
        },
        "description": {
          "type": "string",
          "minLength": 1,
          "description": "Human-readable description of why this resource is needed"
        },
        "permission": {
          "type": "string",
          "description": "Required permission level. Validated per resource type by the allOf/if-then rules below."
        },
        "fields": {
          "type": "object",
          "additionalProperties": {
            "$ref": "#/$defs/resourceFieldEntry"
          },
          "minProperties": 1,
          "description": "Map of field name to env and optional description. Single-value types use one key (e.g. id); multi-value (database, secret) use multiple (e.g. instance_name, database_name or scope, key)."
        }
      },
      "additionalProperties": false,
      "allOf": [
        {
          "if": {
            "properties": { "type": { "const": "secret" } },
            "required": ["type"]
          },
          "then": {
            "properties": {
              "permission": { "$ref": "#/$defs/secretPermission" }
            }
          }
        },
        {
          "if": {
            "properties": { "type": { "const": "job" } },
            "required": ["type"]
          },
          "then": {
            "properties": { "permission": { "$ref": "#/$defs/jobPermission" } }
          }
        },
        {
          "if": {
            "properties": { "type": { "const": "sql_warehouse" } },
            "required": ["type"]
          },
          "then": {
            "properties": {
              "permission": { "$ref": "#/$defs/sqlWarehousePermission" }
            }
          }
        },
        {
          "if": {
            "properties": { "type": { "const": "serving_endpoint" } },
            "required": ["type"]
          },
          "then": {
            "properties": {
              "permission": { "$ref": "#/$defs/servingEndpointPermission" }
            }
          }
        },
        {
          "if": {
            "properties": { "type": { "const": "volume" } },
            "required": ["type"]
          },
          "then": {
            "properties": {
              "permission": { "$ref": "#/$defs/volumePermission" }
            }
          }
        },
        {
          "if": {
            "properties": { "type": { "const": "vector_search_index" } },
            "required": ["type"]
          },
          "then": {
            "properties": {
              "permission": { "$ref": "#/$defs/vectorSearchIndexPermission" }
            }
          }
        },
        {
          "if": {
            "properties": { "type": { "const": "uc_function" } },
            "required": ["type"]
          },
          "then": {
            "properties": {
              "permission": { "$ref": "#/$defs/ucFunctionPermission" }
            }
          }
        },
        {
          "if": {
            "properties": { "type": { "const": "uc_connection" } },
            "required": ["type"]
          },
          "then": {
            "properties": {
              "permission": { "$ref": "#/$defs/ucConnectionPermission" }
            }
          }
        },
        {
          "if": {
            "properties": { "type": { "const": "database" } },
            "required": ["type"]
          },
          "then": {
            "properties": {
              "permission": { "$ref": "#/$defs/databasePermission" }
            }
          }
        },
        {
          "if": {
            "properties": { "type": { "const": "postgres" } },
            "required": ["type"]
          },
          "then": {
            "properties": {
              "permission": { "$ref": "#/$defs/postgresPermission" }
            }
          }
        },
        {
          "if": {
            "properties": { "type": { "const": "genie_space" } },
            "required": ["type"]
          },
          "then": {
            "properties": {
              "permission": { "$ref": "#/$defs/genieSpacePermission" }
            }
          }
        },
        {
          "if": {
            "properties": { "type": { "const": "experiment" } },
            "required": ["type"]
          },
          "then": {
            "properties": {
              "permission": { "$ref": "#/$defs/experimentPermission" }
            }
          }
        },
        {
          "if": {
            "properties": { "type": { "const": "app" } },
            "required": ["type"]
          },
          "then": {
            "properties": { "permission": { "$ref": "#/$defs/appPermission" } }
          }
        }
      ]
    },
    "configSchemaProperty": {
      "type": "object",
      "required": ["type"],
      "properties": {
        "type": {
          "type": "string",
          "enum": ["object", "array", "string", "number", "boolean", "integer"]
        },
        "description": {
          "type": "string"
        },
        "default": {},
        "enum": {
          "type": "array"
        },
        "properties": {
          "type": "object",
          "additionalProperties": {
            "$ref": "#/$defs/configSchemaProperty"
          }
        },
        "items": {
          "$ref": "#/$defs/configSchemaProperty"
        },
        "minimum": {
          "type": "number"
        },
        "maximum": {
          "type": "number"
        },
        "minLength": {
          "type": "integer",
          "minimum": 0
        },
        "maxLength": {
          "type": "integer",
          "minimum": 0
        },
        "required": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "configSchema": {
      "type": "object",
      "required": ["type"],
      "properties": {
        "type": {
          "type": "string",
          "enum": ["object", "array", "string", "number", "boolean"]
        },
        "properties": {
          "type": "object",
          "additionalProperties": {
            "$ref": "#/$defs/configSchemaProperty"
          }
        },
        "items": {
          "$ref": "#/$defs/configSchema"
        },
        "required": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "additionalProperties": {
          "type": "boolean"
        }
      }
    },
    "discoveryDescriptor": {
      "type": "object",
      "description": "Describes how the CLI discovers values for a resource field via a Databricks CLI command.",
      "required": ["cliCommand", "selectField"],
      "properties": {
        "cliCommand": {
          "type": "string",
          "description": "Databricks CLI command that lists resources. Must include <PROFILE> placeholder.",
          "examples": [
            "databricks warehouses list --profile <PROFILE> --output json"
          ]
        },
        "selectField": {
          "type": "string",
          "description": "jq-style path to the field used as the selected value (e.g., '.id', '.name').",
          "examples": [".id", ".name", ".catalog_name"]
        },
        "displayField": {
          "type": "string",
          "description": "jq-style path to the field shown to the user in selection UI. Defaults to selectField if omitted.",
          "examples": [".name", ".display_name"]
        },
        "dependsOn": {
          "type": "string",
          "description": "Name of a sibling field within the same resource that must be resolved first. Used to express ordering dependencies between resource fields.",
          "examples": ["branch", "catalog"]
        },
        "shortcut": {
          "type": "string",
          "description": "Single-value fast-path command that returns exactly one value, skipping interactive selection.",
          "examples": [
            "databricks warehouses get <ID> --profile <PROFILE> --output json"
          ]
        }
      },
      "additionalProperties": false
    },
    "postScaffoldStep": {
      "type": "object",
      "description": "A post-scaffolding instruction shown to the user after project initialization.",
      "required": ["instruction"],
      "properties": {
        "instruction": {
          "type": "string",
          "description": "Human-readable instruction for the user to follow after scaffolding."
        },
        "required": {
          "type": "boolean",
          "default": true,
          "description": "Whether this step is required for the plugin to function correctly."
        }
      },
      "additionalProperties": false
    }
  }
}