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

Music Assistant validates provider manifests using a pre-commit script at scripts/check_manifests.py before runtime, ensuring every 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 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.

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

from music_assistant_models.provider import ProviderManifest

Each provider's __init__.py receives the manifest in its constructor:

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 must include all five mandatory fields:

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

Validate all providers:

uv run -m scripts.check_manifests

Validate a specific provider:

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 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 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 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 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. This shared model ensures type consistency between the validation script and the running server.

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