Contenuto principale

mpackage.json

Package definition file schema

Since R2024b

Note

This page documents schemaVersion 1.1.0 for the package definition file mpackage.json. This schema version was released as part of MATLAB® R2025a. Because the mpackage.json schema is both forward and backward compatible, package definition files of any schemaVersion can be used in any MATLAB release since R2024b, when mpackage.json was introduced. However, package definition files with schema released later than your version of MATLAB might have some features disabled.

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

When you create a package using mpmcreate, the MATLAB Package Manager creates a package definition file named mpackage.json. The file saves package metadata, such as the package name, version, member folders, and dependencies. The mpackage.json file is stored in the resources folder located in the root folder of the package.

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

Here is a sample package definition file:

{
    "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": "jdoe@mathworks.com",
        "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

expand all

Package Identifiers

Use these properties to identify your package. The MATLAB Package Manager uses three pieces of information to identify and distinguish between packages: name, version, and id. Some package management functions accept a package identifier or package specifier as an input. A package identifier uniquely identifies a specific package and version and presents package identifying information in the format name@version@id. A package specifier specifies a range of versions for given package. Package specifiers have a similar format to package identifiers but include a way to express a range of versions rather than one specific version. For additional information, see Distinguish Between Packages Using Package Identifiers.

Package name, specified as a JSON string. name must be a valid MATLAB identifier.

When searching for packages, such as with mpmsearch or mpmlist, or when resolving dependencies, the MATLAB Package Manager searches the names in both this names property and the formerNames property for valid matches.

Example: "name": "SampleToolbox"

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, and Unicode characters to enhance readability and provide a better understanding of the package's purpose.

Example: "displayName": "My Sample Toolkit"

Package version, specified as a JSON string.

Version syntax follows the Semantic Versioning 2.0.0 format: <major>.<minor>.<patch>, 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"

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

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

Package Description

Previous package names, specified as a JSON string array. Use this property to record previous names of the package and ensure backward compatibility when updating the name of a package. When searching for packages, such as with mpmsearch or mpmlist, or when resolving dependencies, the MATLAB Package Manager searches the names in both this formerNames property and the names property for valid matches.

Example

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

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": "jdoe@mathworks.com",
        "url": "mathworks.com"
    }

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"

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

Compatible MATLAB versions, specified as a JSON string containing a valid version range. Specify a MATLAB version as the full name of a MATLAB release (for example, "R2024b"), a range of MATLAB releases (for example, "R2024b - R2025b"), or as a semantic version range (for example, ">R2024b").

A MATLAB release name follows the format:

  • The release, where R20yy[a|b] — Where 20yy is the year of the release and either a or b. For example, R2024b.

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

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

  • R20yy[a|b]_[Prerelease]_Update_# — The prerelease version as well as a particular update. For example, R2024b_Prerelease_Update_1.

MATLAB releases do not follow the Semantic Versioning 2.0.0 standard. Instead, specify a MATLAB release using three dot-separated numbers in the format <release year>.<first or second release>.<update number>.

  • 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 third number corresponds to the update version.

For example, R2024b has a version of 24.2.0. The first update for R2025a has a version of 25.1.1. Optionally specify a prerelease status by adding -prerelease to the end of the version. For example, the prerelease version of R2025b is 25.2.0-prerelease.

You can specify a version range by using the <, <=, >, or >= operators in front of a version number. For example, >24.2.0 specifies all versions later than R2024b. You can specify multiple ranges separated by white space to further limit matches. For example, >24.2.0 <=24.2.2 includes versions between R2024b and R2024b Update 2 but does not include R2024b or R2024b Update 3. Use the || operator to designate multiple acceptable version ranges. For example, <24.2.0 || >24.2.2 includes versions earlier than R2024b and later than R2024b Update 2 but does not include R2024b Update 1.

Example: "R2024b"

Example: "R2024b_Prerelease"

Example: "R2024b_Update_1"

Example: "R2024b_Prerelease_Update_1"

Example: "R2024b - R2025b"

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

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"
            ]
        }
    ]

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

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 VersionMATLAB ReleaseChanges
1.1.0 (latest)R2025aAdd langauges property to folders field.
1.0.0R2024b 

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 Turn Your Code Into a Package.

Version History

Introduced in R2024b

expand all