mpackage.json

Package definition file schema

Since R2024b

Note

This page documents schemaVersion 1.1.0 for the package definition file mpackage.json, which was released as part of MATLAB^® R2025a. mpackage.json schema are both forward and backwards compatible. This means that package definition files of any schemaVersion can be used in any MATLAB release since R2024b. However, packages with schema released later than the version of MATLAB that you are using may have some features disabled.

For additional information on schema versions and corresponding MATLAB releases, see schemaVersion.

When you create a package with the MATLAB package manager, a package definition file gets created to save metadata such as the package name, version, member folders, or dependencies. The package definition file is a JSON file called mpackage.json and is stored in the resources folder located in the root folder of the package.

You can edit the package definition file directly to change the metadata. Alternatively, you can change the metadata by setting properties of the matlab.mpm.Package object corresponding to the package.

The package definition file has a form such as:

{
    "name": "SampleToolbox",
    "version": "2.0.1",
    "id": "af92112b-8b66-44d1-b4b1-848f54affa3e",+
    "displayName": "My Sample Toolkit",
    "summary": "My summary goes here.",
    "description": "My description goes here.",
    "provider": {
        "name": "John Doe",
        "organization": "The Mathworks, Inc.",
        "email": "[e-mail]",
        "url": "mathworks.com"
    },
    "folders": [
        {
            "path": "functions",
            "languages": [
                "matlab"
            ]
        }
    ],
    "dependencies": [
        {
            "name": "CornersPkg",
            "compatibleVersions": ">1.0.0",
            "id": "e6c4123e-0068-42be-aef2-00d49d1509f5"
        }
    ],
    "releaseCompatibility": ">R2025a",
    "schemaVersion": "1.1.0"
}

Properties

Package Identifiers

name — Package name (required)

JSON string

Package name, specified as a JSON string. name must be a valid MATLAB identifier. Package name can be used as a search criteria when using mpmsearch, mpmlist, and when resolving dependencies are considered valid matches.

Example: "name": "SampleToolbox"

displayName — Displayed package name

JSON string

Displayed package name, specified as a JSON string. Unlike the name property, which must be a valid MATLAB identifier, the displayName property is not used in code and does not need to be a valid MATLAB identifier. It can include spaces, special characters or even Unicode characters to enhance readability and provide a better understanding of the package's purpose.

Example: "displayName": "My Sample Toolkit"

version — Package version (required)

JSON string

Package version, specified as a JSON string.

Version syntax follows the Semantic Versioning 2.0.0 format: <major version>.<minor version>.<patch version>, where each version number must be a nonnegative integer, for example 1.2.3. You can optionally specify a pre-release version by adding -<pre-release version> to the end of the version, for example 1.2.3-alpha. Optionally specify a build version by adding +<build version>.

Example: "version": "2.0.1"

id — Package UUID (required)

JSON string

Package UUID, specified as a JSON string containing a universally unique identifier (UUID).

Example: "id": "af92112b-8b66-44d1-b4b1-848f54affa3e"

Package Description

formerNames — Previous package names

JSON string array

Previous package names, specified as a string array. Use this property to record previous names of the package and ensure backwards compatibility when updating the name of a package. Packages with FormerNames that match search criteria when using mpmsearch, mpmlist, and when resolving dependencies are considered valid matches.

Example

"formerNames": [
        "MyToolbox",
        "ExampleToolbox"
    ]

provider — Package provider

object

Package provider, specified as an object with these properties:

• name — Provider name.

• organization — Provider organization.

• email — Provider email.

• url — Provider website URL.

At least one property must be specified, other properties are optional.

Example

"provider": {
        "name": "John Doe",
        "organization": "The Mathworks, Inc.",
        "email": "[e-mail]",
        "url": "mathworks.com"
    }

summary — Package summary

JSON string

Package summary, specified as a JSON string. The summary field serves as a concise description of a MATLAB package.

Example: "summary": "A short summary of the package"

description — Package description

JSON string

Package description, specified as a JSON string. The description provides a detailed explanation of a MATLAB package, elaborating on its functionality, use cases, and any other relevant information that can help users understand what the package does and how it can be utilized.

Example: "description": "A more detailed description of the package."

releaseCompatibility — Compatible MATLAB versions

JSON string

Compatible MATLAB versions, specified as a JSON string containing a valid version range. MATLAB version can be specified as the full name of a MATLAB release version, for example, "R2024b" or as a semantic version range.

A MATLAB release name follows the format:

• Ryyyy[a|b] — Where yyyy is the year of the release and a or b. For example R2024b.

• R20yy[a|b]_[Prerelease] — Specifies the prerelease version. For example R2024b_Prerelease.

• R20yy[a|b]_Update_# — Specifies a particular update. For example R2024b_Update_1.

• R20yy[a|b]_[Prerelease]_Update_# — Specifies the prerelease version as well as a particular update. For example R2024b_Prerelease_Update1.

MATLAB release do not follow the Semantic Versioning 2.0.0 standard. For MATLAB releases versions consists of three dot-separated numbers in the format: <release year>.<first or second release>.<update number>. When specifying MATLAB version using this version syntax, the first number is equal to the last two digits of the release year. The second number is 1 for a releases and 2 for b releases. The update number corresponds to the update version. For example, R2024b would have a version of 24.2.0. The first update for R2025a would have a version of 25.1.1. Pre-release status is optional and is specified by adding -prerelease to the end of the version range, for example the prerelease version of R2025b would be 25.2.0-prerelease.

A version range can be specified using the <, <=, >, or >= operators in front of a version number. For example >24.2.0 would specify all versions later than R2024b. Multiple ranges separated by whitespace can be specified to further limit matches. For example, >24.2.0 <=24.2.2 would include versions between R2024b and R2024b update 2 but would not include R2025a or R2024b Update 3. Use the || operator to designate multiple acceptable version ranges. For example, <24.2.0 || >24.1.2 would include versions less than R2024b and greater than R2024b Update 2 but would not include R2024b Update 1.

Example: "R2024b"

Example: "R2024b_Prerelease"

Example: "R2024b_Update_1"

Example: "R2024b_Prerelease_Update_1"

Example: "24.2.0"

Example: "24.2.1"

Example: "24.2.0-prerelease"

Example: ">=R2024b"

Example: ">24.2.0"

Example: "<24.2.0 || >24.1.2"

Package Folders and Dependencies

folders — Package member folders

object array

Package member folders, specified as an array where each element represents a subfolder and has the following properties:

• path (required) — Folder path, specified as a string scalar containing the package member folder path relative to the package root folder.

• languages — Programming languages, specified as matlab(default) or java. (Introduced in schema version 1.1.0)

  Folders designated as matlab are automatically added to the MATLAB search path when the package is installed. Folders designated as java are added to the Java class path, allowing Java resources to be accessible within MATLAB.

Example

"folders": [
        {
            "path": "functions",
            "languages": [
                "matlab"
            ]
        },
        {
            "path": "objects",
            "languages": [
                "matlab"
            ]
        },
        {
            "path": "Java_Library_Folder",
            "languages": [
                "java"
            ]
        }
    ]

dependencies — Package dependencies

object array

Package dependencies, specified as a object array with the following properties:

• name (required) — Dependency name.

• compatibleVersions — Compatible versions of the dependency. If this property is empty, any release is compatible.

• id (required) — Unique identifier of the dependency.

Package dependencies are other packages that the package depends on. If a package has no dependencies, then this property contains an empty string.

Example

"dependencies": [
        {
            "name": "CornersPkg",
            "compatibleVersions": ">1.0.0",
            "id": "e6c4123e-0068-42be-aef2-00d49d1509f5"
        },
        {
            "name": "MATLABMath",
            "compatibleVersions": ">=3.1.0 <4.0.0",
            "id": "ec63e40a-8625-46d7-aae9-31a6a6c699e2"
        }
    ]

Package Status

schemaVersion — Package definition file schema version (required)

JSON string

Package definition file schema version, specified as a JSON string containing the schema version for the mpackage.json file. Package schema are both backwards and forwards compatible.

Schema Version	MATLAB Release	Changes
1.1.0 (latest)	R2025a	Add langauges property to folders field.
1.0.0	R2024b

Example: "schemaVersion": "1.1.0"

Tips

• In order for MATLAB to detect changes to mpackage.json, the package must be in editable mode. For additional information, see Create and Manage Packages.

Version History

Introduced in R2024b

R2025a: R2025a: Schema version updated to 1.1.0

The package definition file schema version has been updated to version 1.1.0, which includes a languages property in the folders field. Package schema are both backwards and forwards compatible.