# Music-Assistant Provider Manifest.json Structure: Configuration Schema Explained

> Understand the Music-Assistant provider manifest.json structure. Learn about its mandatory fields, optional declarations, and the JSON-Schema for UI generation to configure your provider effectively.

- Repository: [Music Assistant/server](https://github.com/music-assistant/server)
- Tags: api-reference
- Published: 2026-06-13

---

**A Music-Assistant provider's [`manifest.json`](https://github.com/music-assistant/server/blob/main/manifest.json) file requires five mandatory fields—`type`, `domain`, `stage`, `name`, and `description`—and optionally declares dependencies, metadata, and a JSON-Schema configuration object that the core uses to auto-generate setup UI.**

The `music-assistant/server` repository uses manifest files to discover and register providers at runtime. Each provider ships a [`manifest.json`](https://github.com/music-assistant/server/blob/main/manifest.json) next to its implementation module that tells the core how to load the integration, what Python packages to install, and how to render configuration options in the frontend.

## Required and Optional Manifest Fields

Every provider manifest shares a common structure defined in the core loader at [`music_assistant/providers/__init__.py`](https://github.com/music-assistant/server/blob/main/music_assistant/providers/__init__.py). The core validates that mandatory keys exist before registering the provider, while optional keys enable automatic dependency resolution and documentation linking.

### Mandatory Fields

The **only mandatory fields** are `type`, `domain`, `stage`, `name`, and `description`. The core raises an error if any are missing.

- **`type`** – Category string: `music`, `player`, `metadata`, or `plugin`. Determines how the core routes media and commands.
- **`domain`** – Unique identifier used in configuration files and URI paths (e.g., `"spotify"`).
- **`stage`** – Release stability: `stable`, `beta`, or `alpha`. Non-stable providers may be hidden from end-users.
- **`name`** – Human-readable label displayed in the UI (e.g., `"Spotify"`).
- **`description`** – Short summary shown in the provider list and documentation.

### Optional Metadata and Dependencies

Optional keys provide metadata for maintenance and automatic setup:

- **`codeowners`** – Array of GitHub usernames or teams responsible for the provider.
- **`credits`** – Array of acknowledgment strings for third-party libraries.
- **`requirements`** – Array of Python package specs (e.g., `["pkce==1.0.3"]`) added to the core’s dependency resolver.
- **`documentation`** – URL to provider-specific docs.
- **`multi_instance`** – Boolean flag; when `true`, the provider can be instantiated multiple times with different configurations (e.g., multiple Spotify accounts).

## Configuration Schema Definition

When a provider needs user input (server addresses, API tokens, device IPs), the manifest includes a **`configuration`** object following the **JSON-Schema draft-07** format. The core validates this schema at load time and uses it to generate dynamic configuration forms in the UI.

Each property inside `configuration.properties` defines a field with standard JSON-Schema attributes:

- **`title`** – Label for the UI input.
- **`type`** – Data type: `string`, `integer`, `boolean`, etc.
- **`default`** – Pre-filled value.
- **`enum`** – Restricted list of allowed values.
- **`format`** – Validation hint such as `"ipv4"` or `"uri"`.

The schema is validated using the core’s built-in JSON-Schema validator when the manifest is loaded.

## File Location and Runtime Loading

The manifest must reside next to the provider’s implementation module. For example, the Spotify provider stores its manifest at [`music_assistant/providers/spotify/manifest.json`](https://github.com/music-assistant/server/blob/main/music_assistant/providers/spotify/manifest.json).

At startup, the core discovers provider directories and loads manifests via `json.load()`:

```python
import json
from jsonschema import validate

def load_provider_manifest(path: str) -> dict:
    with open(path) as f:
        manifest = json.load(f)

    # Basic validation – ensure mandatory keys exist

    required = {"type", "domain", "stage", "name", "description"}
    missing = required - manifest.keys()
    if missing:
        raise ValueError(f"Missing required manifest fields: {missing}")

    # If a configuration schema is supplied, validate it once

    if "configuration" in manifest:
        schema = manifest["configuration"]
        # The schema itself must be a valid JSON-Schema; we validate with a dummy dict

        validate(instance={}, schema=schema)

    return manifest

```

## Complete Manifest Examples

### Minimal Provider Manifest

The [`music_assistant/providers/_demo_music_provider/manifest.json`](https://github.com/music-assistant/server/blob/main/music_assistant/providers/_demo_music_provider/manifest.json) template demonstrates the smallest valid manifest:

```json
{
  "type": "music",
  "domain": "mycoolmusic",
  "stage": "alpha",
  "name": "MyCoolMusic",
  "description": "A demo music provider that streams from MyCoolMusic service.",
  "codeowners": ["@my-github-handle"],
  "requirements": ["mycoolmusic-api==2.1.0"],
  "documentation": "https://github.com/myuser/mycoolmusic/blob/dev/README.md"
}

```

### Advanced Configuration with Schema

Player providers often require network settings. This example includes a full JSON-Schema configuration object:

```json
{
  "type": "player",
  "domain": "myplayer",
  "stage": "beta",
  "name": "MyPlayer",
  "description": "Control MyPlayer devices on the local network.",
  "codeowners": ["@my-github-handle"],
  "requirements": ["myplayer-sdk==0.9.0"],
  "documentation": "https://github.com/myuser/myplayer/blob/dev/README.md",
  "multi_instance": true,
  "configuration": {
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "object",
    "properties": {
      "host": {
        "title": "Device IP address",
        "type": "string",
        "format": "ipv4"
      },
      "port": {
        "title": "TCP port",
        "type": "integer",
        "default": 8080,
        "minimum": 1,
        "maximum": 65535
      },
      "use_ssl": {
        "title": "Use SSL",
        "type": "boolean",
        "default": false
      }
    },
    "required": ["host"]
  }
}

```

## Summary

- The **five mandatory fields** are `type`, `domain`, `stage`, `name`, and `description`.
- The **`configuration`** object follows **JSON-Schema draft-07** and drives the UI generation for provider setup.
- The manifest lives next to the provider module (e.g., [`music_assistant/providers/spotify/manifest.json`](https://github.com/music-assistant/server/blob/main/music_assistant/providers/spotify/manifest.json)) and is loaded via `json.load()`.
- **`multi_instance`** allows multipleprovider configurations, while **`requirements`** triggers automatic package installation.

## Frequently Asked Questions

### What are the required fields in a Music-Assistant manifest.json?

The core requires `type`, `domain`, `stage`, `name`, and `description`. All other keys are optional. If any mandatory field is missing, the provider loader raises a `ValueError` and skips registration.

### How does the configuration schema work in the manifest?

The optional `configuration` key contains a JSON-Schema draft-07 object. The core validates this schema at startup and uses it to render dynamic configuration forms in the frontend. You can define field types, defaults, validation rules, and required fields using standard JSON-Schema syntax.

### Can a provider have multiple instances?

Yes. Set `"multi_instance": true` in the manifest. This allows users to add the same provider multiple times with different configurations, such as connecting to separate Spotify accounts or multiple local media servers.

### Where should the manifest.json file be located?

Place [`manifest.json`](https://github.com/music-assistant/server/blob/main/manifest.json) in the provider’s root directory alongside the implementation module, following the pattern `music_assistant/providers/{domain}/manifest.json`. The core scans subdirectories of `music_assistant/providers/` and automatically loads any [`manifest.json`](https://github.com/music-assistant/server/blob/main/manifest.json) files found.