# Loading and Validating Provider Manifests in Music Assistant: A Complete Guide

> Learn to load and validate provider manifests in Music Assistant. This guide covers the pre-commit script and essential manifest fields for seamless integration.

- Repository: [Music Assistant/server](https://github.com/music-assistant/server)
- Tags: how-to-guide
- Published: 2026-06-21

---

**Music Assistant validates provider manifests using a pre-commit script at [`scripts/check_manifests.py`](https://github.com/music-assistant/server/blob/main/scripts/check_manifests.py) before runtime, ensuring every [`manifest.json`](https://github.com/music-assistant/server/blob/main/manifest.json) contains mandatory fields like `type`, `domain`, `name`, `description`, and `codeowners` that match the provider folder structure.**

Loading and validating provider manifests in Music Assistant is a critical pipeline that ensures every plugin conforms to a strict metadata contract before the server boots. The `music-assistant/server` repository uses a dedicated validation script combined with runtime type safety to guarantee that each provider in `music_assistant/providers/<provider_name>/` exposes uniform metadata required by the core system and UI.

## What Is a Provider Manifest?

Every provider ships with a [`manifest.json`](https://github.com/music-assistant/server/blob/main/manifest.json) file located at `music_assistant/providers/<provider_name>/manifest.json`. This JSON file describes the provider's basic metadata and capabilities, serving as the contract between the provider implementation and the Music Assistant core. The manifest enables the server to discover providers, display human-readable information in the UI, and enforce security policies through code ownership tracking.

## How Music Assistant Validates Provider Manifests

The validation process runs automatically as a **pre-commit hook** and CI check, catching errors before they reach production. The validation logic resides in [`scripts/check_manifests.py`](https://github.com/music-assistant/server/blob/main/scripts/check_manifests.py).

### Locating Provider Manifests

The `find_violations` function iterates over the providers directory using `PROVIDERS_PATH.glob("*/manifest.json")` to discover every manifest file. This glob pattern ensures that any folder containing a [`manifest.json`](https://github.com/music-assistant/server/blob/main/manifest.json) under `music_assistant/providers/` is a candidate for validation.

### Structural and Syntax Checks

Each manifest file is loaded using `Path.read_text()` and parsed with `json.loads`. The internal `_validate` function then enforces the presence of five mandatory keys:

- **`type`** – Must be a value from the `VALID_TYPES` constant
- **`domain`** – Unique identifier that must match the provider folder name
- **`name`** – Human-readable provider name
- **`description`** – Brief explanation of the provider's functionality
- **`codeowners`** – List of GitHub usernames responsible for maintenance

JSON syntax errors or missing keys trigger immediate validation failures.

### Consistency Validation

Beyond structural checks, the validator enforces consistency between the filesystem and metadata. The folder name must exactly match the `domain` value in the manifest, and the `codeowners` field must be a non-empty list of strings where each entry starts with the "@" symbol.

Violations are collected as `path: message` strings and printed to stderr, causing the script to exit with status 1 and fail the CI pipeline.

## Runtime Loading of Provider Manifests

Once validation passes, manifests become available at runtime through the `music_assistant_models` package. Provider implementations receive a typed `ProviderManifest` instance via constructor injection.

The `ProviderManifest` class is imported from `music_assistant_models.provider`:

```python
from music_assistant_models.provider import ProviderManifest

```

Each provider's [`__init__.py`](https://github.com/music-assistant/server/blob/main/__init__.py) receives the manifest in its constructor:

```python
class SpotifyProvider:
    def __init__(self, mass: MusicAssistant, manifest: ProviderManifest, config: ProviderConfig) -> None:
        self.mass = mass
        self.manifest = manifest  # Validated manifest data

        self.config = config

```

Because the manifest has already passed validation, runtime code can safely access fields like `manifest.name`, `manifest.domain`, and `manifest.description` without defensive checks.

## Required Manifest Schema

A minimal valid [`manifest.json`](https://github.com/music-assistant/server/blob/main/manifest.json) must include all five mandatory fields:

```json
{
  "type": "music",
  "domain": "myprovider",
  "name": "My Provider",
  "description": "A demo music source",
  "codeowners": ["@yourname"]
}

```

The `type` field must align with the provider's capabilities as defined in `VALID_TYPES`, while `codeowners` ensures clear maintenance responsibility for security and bug tracking.

## Running the Manifest Validator

Developers can trigger validation manually using the script in [`scripts/check_manifests.py`](https://github.com/music-assistant/server/blob/main/scripts/check_manifests.py).

Validate all providers:

```bash
uv run -m scripts.check_manifests

```

Validate a specific provider:

```bash
uv run -m scripts.check_manifests music_assistant/providers/spotify/manifest.json

```

Because the script runs as a pre-commit hook (`pre-commit run --all-files`), every commit is automatically verified before merging.

## Summary

- **Validation location**: [`scripts/check_manifests.py`](https://github.com/music-assistant/server/blob/main/scripts/check_manifests.py) contains the `find_violations` and `_validate` functions that enforce manifest correctness
- **Mandatory fields**: Every manifest must include `type`, `domain`, `name`, `description`, and `codeowners`
- **Consistency rules**: The provider folder name must match the `domain` value, and `codeowners` entries must start with "@"
- **Runtime access**: Validated manifests are injected as `ProviderManifest` instances from `music_assistant_models.provider`
- **CI integration**: The validation script exits with code 1 on violations, blocking malformed manifests from entering the codebase

## Frequently Asked Questions

### What happens if a provider manifest is missing a mandatory field?

The `_validate` function in [`scripts/check_manifests.py`](https://github.com/music-assistant/server/blob/main/scripts/check_manifests.py) detects missing fields and reports them as violations. The script exits with status 1, causing the CI pipeline to fail and preventing the affected provider from loading at runtime.

### How does Music Assistant ensure the provider domain matches the folder structure?

The validation script performs a consistency check that compares the `domain` value in [`manifest.json`](https://github.com/music-assistant/server/blob/main/manifest.json) against the actual folder name containing the file. If they do not match exactly, the validator reports a violation and the build fails.

### Can I validate a single provider manifest without checking all providers?

Yes. While the default behavior validates all manifests in `music_assistant/providers/`, you can pass a specific file path as an argument to [`scripts/check_manifests.py`](https://github.com/music-assistant/server/blob/main/scripts/check_manifests.py) to validate only that manifest.

### Where is the ProviderManifest class defined that gets injected at runtime?

The `ProviderManifest` class is defined in the external `music_assistant_models` package within [`music_assistant_models/provider.py`](https://github.com/music-assistant/server/blob/main/music_assistant_models/provider.py). This shared model ensures type consistency between the validation script and the running server.