JSON files
Note
We're working on improving the onboarding experience for AL developers. If you've input for this article, we'd love to hear from you. Please use the Feedback section at the bottom of this article to help us make improvements that you’d like to see.
We also welcome contributions to our docs. New to contributing to docs? Don't worry, read more about contributing here Contribute to the help.
When you start a new AL project, two JSON files; the app.json file and the launch.json file are generated automatically. The app.json file contains information about the extension that you're building, such as publisher information and specifies the minimum version of base application objects that the extension is built on. Often, the app.json file is referred to as the manifest. This article describes the app.json file settings in the App.json file section.
For information about the launch.json file see the article Launch JSON file.
Note
For information about data migration and creating a migration.json file, see The Migration.json File.
Important
The rad.json and the snapshots.json files should not be modified.
App.json file
The following table describes the settings in the app.json file. To see an example app.json file, go to Business Central Performance Toolkit.
| Setting | Mandatory | Value |
|---|---|---|
| id | Yes | The unique ID of the extension. When the app.json file is automatically created, the ID is set to a new GUID value. Note: The app ID is used at runtime to bind table names contained in the application. Changing the app ID results in data from old tables not being used. |
| name | Yes | The unique extension name. The name can be changed to reflect branding or acquisition, but then the version must be incremented. Note: The name might be used by other extensions to express a compile-time dependency on the extension. Changing the name of your extension forces any extensions that take a dependency to download symbols and recompile their extension. For more information, see App Identity. |
| publisher | Yes | The name of your publisher, for example: NAV Partner, LLC. Note: The publisher might be used by other extensions to express a compile-time dependency on the extension. Changing the publisher of your extension forces those extensions that take a dependency to download symbols and recompile their extension. For more information, see App Identity. |
| brief | No, but required for AppSource submission | Short description of the extension. |
| description | No, but required for AppSource submission | Longer description of the extension. |
| version | Yes | The version of the app package. |
| privacyStatement | No, but required for AppSource submission | URL to the privacy statement for the extension. |
| EULA | No, but required for AppSource submission | URL to the license terms for the extension. |
| help | No, but required for AppSource submission | URL to an online description of the extension focusing on the help and troubleshooting content. The link is used in AppSource and can be the same as the value of the contextSensitiveHelpUrl property. To learn more about help links, see Help and support links. |
| url | No, but required for AppSource submission | URL of the extension package. The link is used in Business Central, on the Extension Management page, as Website. This URL can be a link to an advertising page for your app, a page describing the features and more resources other than troubleshooting and help, or it can be a link for contacting the app support, for example, see Help and support links. |
| logo | No, but required for AppSource submission | Relative path to the app package logo from the root of the package. |
| test | No | Version of the dependent test framework in the format X.Y.U.Z. Note: This property is only supported for Business Central version 14 and earlier, where the base app is C/AL. |
| dependencies | No | List of dependencies for the extension package. For example: "dependencies": [ {"id": "00001111-aaaa-2222-bbbb-3333cccc4444", "name": "WeatherLibrary", "publisher": "Microsoft", "version": "1.0.0.0"},{}]. Note: For dependencies to the System Application and Base Application, these are no longer listed as explicit dependencies, but captured in the application setting as a reference to the application package. They must have a version number of the Application package. See application below. Note: The version specified defines the minimum version for the dependency. At runtime and when downloading symbols, the latest version of the dependency satisfying the specified name, publisher and, minimum version is returned. When runtime is set to 4.0 or earlier, use appId instead of id. |
| screenshots | No | Relative paths to any screenshots that should be in the extension package. |
| platform | Yes, if system objects are referenced in the extension | The minimum supported version of the platform package file, for example: "23.0.0.0". The file name of this reference is Microsoft_System_*.app. See the Module System reference for the list of object symbols contained in the platform package file. |
| application | Yes, if the system application or base application is referenced in the extension. Required for AppSource submission | The supported version of the system application and base application package file, for example: "23.1.0.0". The file name of this reference is Microsoft_Application_*.app. On-premises: If the base application is customized, the Microsoft_Application_*.app file can be modified to reference the code-customized base application instead. It's important to keep "name": "Application" in the extension, but information about publisher can be changed and the .app file can be renamed. For more information, see The Microsoft_Application.app File. |
| idRange | Yes | A range for application object IDs. For example: "idRange": {"from": 50100,"to": 50149}. For all objects outside the range, a compilation error is raised. When you create new objects, an ID is automatically suggested. To learn about which object ranges are allowed for your extension, see Object Ranges. |
| idRanges | Yes | A list of ranges for application object IDs. For example: "idRanges": [{"from": 50100,"to": 50200},{"from": 50202,"to": 50300}]. For all objects outside the ranges, a compilation error is raised. When you create new objects, an ID is automatically suggested. You must use either the idRange or the idRanges setting. Overlapping ranges aren't allowed and results in a compilation error. To learn about which object ranges are allowed for your extension, see Object Ranges. |
| showMyCode | No | By default, it's set to false and isn't visible in the manifest. To enable viewing the source code when debugging an extension, add the following setting: "showMyCode": true.Note: This setting will be deprecated in a future release, and replaced by the resourceExposurePolicy setting introduced with runtime 8.0. It's described in this table. |
| target | No | By default, this is Cloud. The setting currently has the following options: Internal, Extension, OnPrem, and Cloud. The Internal and Extension settings are being deprecated with runtime 4.0 and replaced by the OnPrem and Cloud respectively. For on-premises, you can set this to OnPrem to get access to otherwise restricted APIs and .NET Interop. Then, the Business Central Server setting must also be set to OnPrem. Note: System tables that have the Scope property set to Internal/OnPrem can't be accessed from extensions that have target set to Cloud/External through direct reference or through RecordRef. For more information, see Compilation Scope Overview |
| contextSensitiveHelpUrl | No, but required for AppSource submission | The URL for the website that displays context-sensitive Help for the objects in the app, such as https://mysite.com/documentation/. If the app doesn't support all locales currently supported by Business Central, then include a parameter for the locale in this URL, /{0}/, and also specify the relevant locales in the supportedLocales setting. |
| helpBaseUrl | No | The URL for the website that overtakes all Help for the specified locales. This property is intended for localization apps specifically, since the setting overwrites the default URL of /{0}/dynamics365/business-central. If you set this value, you must also specify one or more languages in the supportedLocales setting. |
| supportedLocales | No | The list of locales that are supported in your Help if different from all locales. The value on the list is entered into the URL defined in the contextSensitiveHelpUrl and helpBaseUrl properties. The first locale on the list is default. An example is "supportedLocales": ["da-DK", "en-US"] for an app that supports only Danish and English (US). |
| runtime | No | The version of the runtime that the project is targeting. The project can be published to a server that supports the same or a higher runtime version. The available options are: 1.0 - Business Central April 2018 Release 2.0 - Business Central Fall '18 Release 3.0 - Business Central Spring '19 Release 4.0 - Business Central 2019 release wave 2 5.0 - Business Central 2020 release wave 1 6.0 - Business Central 2020 release wave 2 6.1 - Business Central 2020 release wave 2 update 17.1 6.2 - Business Central 2020 release wave 2 update 17.2 6.3 - Business Central 2020 release wave 2 update 17.3 6.4 - Business Central 2020 release wave 2 update 17.4 7.0 - Business Central 2021 release wave 1 7.1 - Business Central 2021 release wave 1 update 18.17.2 - Business Central 2021 release wave 1 update 18.38.0 - Business Central 2021 release wave 28.1 - Business Central 2021 release wave 2 update 19.1 9.0 - Business Central 2022 release wave 19.1 - Business Central 2022 release wave 1 update 20.19.2 - Business Central 2022 release wave 1 update 20.410.0 - Business Central 2022 release wave 211.0 - Business Central 2023 release wave 112.0 - Business Central 2023 release wave 213.0 - Business Central 2024 release wave 114.0 - Business Central 2024 release wave 2For more information, see Choosing Runtime Version in AL. |
| features | No | Specifies a list of options. The TranslationFile option generates a \Translations folder that is populated with the .xlf file that contains all the labels, label properties, and report labels that you're using in the extension. The GenerateCaptions option depends on the TranslationFile setting. It generates captions for objects that don't have a Caption or CaptionML specified. These are then written to the .xlf file.The GenerateLockedTranslations flag is used to generate <trans-unit> elements in the XLIFF file for locked labels. The syntax is "features": [ "TranslationFile", "GenerateCaptions", "GenerateLockedTranslations" ]. For more information, see Working with Translation Files.When the NoImplicitWith flag is specified, ImplicitWith is turned off by default. This flag is useful when all code is rewritten to avoid any future use of ImplicitWith. For more information, see Pragma ImplicitWith and Deprecating Explicit and Implicit With Statements. |
| internalsVisibleTo | No | Specifies a list of modules that have access to the objects that are marked as Internal using the Access property from the current module.The syntax is {"id": "d6c3f231-08d3-4681-996f-261c06500e1a", "name": "TheConsumer", "publisher": "Microsoft"}]. For more information, see Access Property and InternalEvent Attribute.Note: Using internalsVisibleTo in Business Central online throws a warning from AppSourceCop and PTECop. Access = Internal isn't designed as a security boundary, but for API development. |
| propagateDependencies | No | Specifies whether the direct dependencies of this project should be propagated as direct dependencies of projects that depend on this one. Default is false. If, set to true then, any dependencies of the current package are visible to consumers of the package. For example, if A depends on B that depends on C, by default, A isn't able to use types defined in C. If B has "propagateDependencies" : "true", then A is able to use types defined in C without taking a direct dependency.Note: propagateDependencies applies to all direct dependencies, there's no option to exclude specific dependencies. |
| preprocessorSymbols | No | Defines any symbols to use with preprocessor directives. The syntax is "preprocessorSymbols": [ "DEBUG","PROD" ]. For more information, see Preprocessor Directives in AL. |
| applicationInsightsKey | No, is deprecated in favor of applicationInsightsConnectionString as of runtime 7.2 - Business Central 2021 release wave 1 update 18.2 |
The instrumentation key of the Azure Application Insights resource for monitoring operations, for example, like app secrets retrieval by extensions. For more information, see Monitoring and Analyzing Telemetry. |
| applicationInsightsConnectionString | No, but recommended for AppSource submission | The instrumentation key of the Azure Application Insights resource for monitoring operations, for example, like app secrets retrieval by extensions. For more information, see Monitoring and Analyzing Telemetry. |
| keyVaultUrls | No | List of URLs of key vaults that from which the extension can retrieve secrets. For example: "keyVaultUrls": [ "https://myfirstkeyvault.vault.azure.net", "https://mysecondkeyvault.vault.azure.net" ]. For more information, see App Key Vaults. |
| suppressWarnings | No | Specifies that warnings issued by, for example, a specific analyzer rule shouldn't be shown in the Output window. Syntax is "suppressWarnings": [<warning ID>,<warning ID2>,...]. For example, "suppressWarnings": [ "AL0458" ]. It's also possible to use #pragma directives for suppressing warnings for specific areas of code. For more information, see Pragma Warning Directive and Suppressing Warnings. |
| resourceExposurePolicy | No | Defines the accessibility of the resources and source code during different operations. The resourceExposurePolicy property contains four options for defining access: applyToDevExtension, allowDebugging, allowDownloadingSource, and includeSourceInSymbolFile. All defaults are false. The syntax is "resourceExposurePolicy": {"applyToDevExtension": true, "allowDebugging": true, "allowDownloadingSource": true, "includeSourceInSymbolFile": true}. For more information, see Resource Exposure Policy Setting. |
| source | No | Specifies the properties for source control. The options are: repositoryUrl, which is the URL of the repository where the source code of the project can be found.commit, which is an ID of the source code for the current version of the project, that allows getting back to the commit that triggered building the extension.The source setting can dynamically be set as part of build pipelines via command line parameters for the used alc.exe compiler executable. The values passed here overwrites any values in the app.json source file. |
| build | No | Specifies the properties for building the package. The options are:by, which is useful for tracking the build agent/system that orchestrated the build, for example AL-Go for GitHub. url, which can be used for the URL to the build system invocation where the build can be found.The build setting can dynamically be set as part of build pipelines via command line parameters for the used alc.exe compiler executable. The values passed here overwrites any values in the app.json source file. |
| alternateIds | No | The IDs of the applications, which will be replaced by this application. This property should be used by apps that replace the base application. Specified as a list of one or more IDs. |
Related information
Launch JSON file
AL development environment
App identity
Debugging in AL
Resource exposure policy setting
AL Language extension configuration
Configure context-sensitive help
App key vaults