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

A Music-Assistant provider's 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 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. 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.

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

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 template demonstrates the smallest valid manifest:

{
  "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:

{
  "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) 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 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 files found.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}