--- title: Extension Manifest sidebar_position: 5 --- # Extension Manifest Reference The `extension.json` file defines metadata, capabilities, and configuration for a Superset extension. This file is required at the root of every extension project. ## Complete Example ```json { "name": "dataset_references", "displayName": "Dataset References", "version": "1.0.0", "description": "Display metadata about tables referenced in SQL queries", "author": "Apache Superset Contributors", "license": "Apache-2.0", "homepage": "https://github.com/apache/superset", "repository": { "type": "git", "url": "https://github.com/apache/superset.git" }, "bugs": { "url": "https://github.com/apache/superset/issues" }, "engines": { "superset": ">=4.0.0" }, "categories": ["SQL Lab", "Analytics"], "keywords": ["sql", "metadata", "tables", "references"], "icon": "database", "galleryBanner": { "color": "#1890ff", "theme": "dark" }, "frontend": { "main": "./dist/index.js", "contributions": { "views": { "sqllab.panels": [ { "id": "dataset_references.main", "name": "Dataset References", "icon": "TableOutlined", "when": "sqllab.queryExecuted" } ] }, "commands": [ { "command": "dataset_references.refresh", "title": "Refresh Dataset Metadata", "category": "Dataset References", "icon": "ReloadOutlined" } ], "menus": { "sqllab.editor": { "primary": [ { "command": "dataset_references.refresh", "group": "navigation", "when": "dataset_references.panelVisible" } ] } }, "configuration": { "title": "Dataset References", "properties": { "dataset_references.autoRefresh": { "type": "boolean", "default": true, "description": "Automatically refresh metadata on query execution" }, "dataset_references.showPartitions": { "type": "boolean", "default": true, "description": "Display partition information" }, "dataset_references.cacheTimeout": { "type": "number", "default": 300, "description": "Cache timeout in seconds" } } } }, "moduleFederation": { "name": "dataset_references", "exposes": { "./index": "./src/index" }, "shared": { "react": { "singleton": true }, "react-dom": { "singleton": true } } } }, "backend": { "main": "dataset_references.entrypoint", "entryPoints": ["dataset_references.entrypoint"], "files": ["backend/src/dataset_references/**/*.py"], "requirements": [ "sqlparse>=0.4.0", "pandas>=1.3.0" ] }, "activationEvents": [ "onView:sqllab.panels", "onCommand:dataset_references.refresh", "workspaceContains:**/*.sql" ] } ``` ## Required Fields ### name - **Type**: `string` - **Pattern**: `^[a-z0-9_]+$` - **Description**: Unique identifier for the extension. Must be lowercase with underscores. ```json "name": "my_extension" ``` ### version - **Type**: `string` - **Format**: [Semantic Versioning](https://semver.org/) - **Description**: Extension version following semver format. ```json "version": "1.2.3" ``` ### engines - **Type**: `object` - **Description**: Specifies compatible Superset versions. ```json "engines": { "superset": ">=4.0.0 <5.0.0" } ``` ## Metadata Fields ### displayName - **Type**: `string` - **Description**: Human-readable name shown in UI. ### description - **Type**: `string` - **Description**: Short description of extension functionality. ### author - **Type**: `string` | `object` - **Description**: Extension author information. ```json "author": { "name": "Jane Doe", "email": "jane@example.com", "url": "https://example.com" } ``` ### license - **Type**: `string` - **Description**: SPDX license identifier. - **Common values**: `Apache-2.0`, `MIT`, `BSD-3-Clause` ### categories - **Type**: `string[]` - **Description**: Extension categories for marketplace organization. - **Valid values**: - `"SQL Lab"` - `"Dashboard"` - `"Charts"` - `"Data Sources"` - `"Analytics"` - `"Security"` - `"Theming"` - `"Developer Tools"` ### keywords - **Type**: `string[]` - **Description**: Search keywords for extension discovery. ### icon - **Type**: `string` - **Description**: Icon identifier or path to icon file. ## Frontend Configuration ### frontend.main - **Type**: `string` - **Description**: Entry point for frontend code. ### frontend.contributions Defines how the extension extends Superset's UI. #### views Register custom views and panels: ```json "views": { "sqllab.panels": [ { "id": "extension.panel", "name": "My Panel", "icon": "icon-name", "when": "condition" } ] } ``` **View Locations**: - `sqllab.panels` - SQL Lab side panels - `sqllab.bottomPanels` - SQL Lab bottom panels - `dashboard.widgets` - Dashboard widgets (TODO: future) - `chart.toolbar` - Chart toolbar items (TODO: future) #### commands Register executable commands: ```json "commands": [ { "command": "extension.doSomething", "title": "Do Something", "category": "My Extension", "icon": "PlayCircleOutlined", "enablement": "resourceIsSelected" } ] ``` #### menus Add items to existing menus: ```json "menus": { "sqllab.editor": { "primary": [ { "command": "extension.command", "group": "navigation", "when": "editorFocus" } ], "context": [ { "command": "extension.contextAction", "group": "1_modification" } ] } } ``` **Menu Locations**: - `sqllab.editor.primary` - Main SQL Lab toolbar - `sqllab.editor.secondary` - Secondary actions - `sqllab.editor.context` - Right-click context menu - `explorer.context` - Data explorer context menu (TODO: future) #### configuration Define extension settings: ```json "configuration": { "title": "My Extension", "properties": { "myExtension.setting1": { "type": "boolean", "default": true, "description": "Enable feature X" }, "myExtension.setting2": { "type": "string", "enum": ["option1", "option2"], "default": "option1", "description": "Choose option" } } } ``` **Property Types**: - `boolean` - True/false toggle - `string` - Text input - `number` - Numeric input - `array` - List of values - `object` - Complex configuration ### frontend.moduleFederation Webpack Module Federation configuration: ```json "moduleFederation": { "name": "extension_name", "exposes": { "./index": "./src/index" }, "shared": { "react": { "singleton": true }, "react-dom": { "singleton": true }, "@apache-superset/core": { "singleton": true } } } ``` ## Backend Configuration ### backend.main - **Type**: `string` - **Description**: Main Python module entry point. ### backend.entryPoints - **Type**: `string[]` - **Description**: Python modules to load on startup. ```json "entryPoints": [ "my_extension.api", "my_extension.security", "my_extension.models" ] ``` ### backend.files - **Type**: `string[]` - **Description**: Glob patterns for backend files to include. ```json "files": [ "backend/src/**/*.py", "backend/config/*.yaml" ] ``` ### backend.requirements - **Type**: `string[]` - **Description**: Python package dependencies. ```json "requirements": [ "requests>=2.28.0", "pandas>=1.3.0,<2.0.0" ] ``` ## Activation Events Controls when the extension is activated: ```json "activationEvents": [ "onView:sqllab.panels", "onCommand:myExtension.start", "onLanguage:sql", "workspaceContains:**/*.sql", "*" ] ``` **Event Types**: - `onView:` - When specific view is opened - `onCommand:` - When command is executed - `onLanguage:` - When file type is opened - `workspaceContains:` - When workspace contains matching files - `onStartupFinished` - After Superset fully starts - `*` - Always activate (not recommended) ## Conditional Activation ("when" clauses) Control when UI elements are visible/enabled: ```json "when": "sqllab.queryExecuted && config.myExtension.enabled" ``` **Context Keys**: - `sqllab.queryExecuted` - Query has been run - `sqllab.hasResults` - Query returned results - `editorFocus` - Editor is focused - `resourceIsSelected` - Resource selected in explorer - `config.` - Configuration value check **Operators**: - `&&` - AND - `||` - OR - `!` - NOT - `==` - Equals - `!=` - Not equals - `=~` - Regex match ## Capabilities Declaration Declare required permissions and capabilities: ```json "capabilities": { "permissions": [ "database.read", "query.execute", "cache.write" ], "apis": [ "sqllab.*", "authentication.getUser" ] } ``` ## Build Configuration ### TODO: Future Fields These fields are planned for future implementation: ```json { "publisher": "organization-name", "preview": false, "contributes": { "themes": [], "languages": [], "debuggers": [], "jsonValidation": [] }, "extensionDependencies": [ "other-extension@^1.0.0" ], "extensionPack": [ "extension1", "extension2" ], "scripts": { "compile": "webpack", "test": "jest", "lint": "eslint" } } ``` ## Validation The manifest is validated against a JSON schema during: - Development (`superset-extensions dev`) - Build (`superset-extensions build`) - Installation (API upload) Common validation errors: - Missing required fields - Invalid version format - Incompatible engine version - Duplicate command IDs - Invalid activation events ## Best Practices 1. **Use semantic versioning** for the version field 2. **Declare minimum Superset version** accurately 3. **Use specific activation events** to improve performance 4. **Provide clear descriptions** for configuration options 5. **Include all required Python dependencies** in requirements 6. **Use unique IDs** for commands and views 7. **Follow naming conventions** (snake_case for name, camelCase for settings) 8. **Include complete author information** for support 9. **Specify appropriate categories** for discovery 10. **Test manifest changes** before deployment ## Migration from Legacy Format If migrating from older extension formats: ```javascript // Legacy format (deprecated) { "plugin_name": "MyPlugin", "plugin_version": "1.0" } // New format { "name": "my_plugin", "version": "1.0.0", "engines": { "superset": ">=4.0.0" } } ``` ## Related Documentation - [Extension Project Structure](/developer_portal/extensions/extension-project-structure) - [Contribution Points](/developer_portal/references/contribution-points) - [Activation Events](/developer_portal/references/activation-events) - [API Reference](/developer_portal/api/frontend)