All Windows Package Manager manifests in the Microsoft community repository are submitted using YAML syntax. A JSON schema is provided to aid authoring these files in editors, and in the other tooling related to the Windows Package Manager. This document provides detailed information regarding the usage of the YAML keys in the defaultLocale file for multi-file manifests.
PackageIdentifier: # The package unique identifier
PackageVersion: # The package version
PackageLocale: # The package meta-data locale
Publisher: # The publisher name
PublisherUrl: # Optional publisher home page
PublisherSupportUrl: # Optional publisher support page
PrivacyUrl: # Optional publisher privacy page
Author: # Optional author
PackageName: # The package name
PackageUrl: # Optional package home page
License: # The package license
LicenseUrl: # Optional package license page
Copyright: # Optional package copyright
CopyrightUrl: # Optional package copyright page
ShortDescription: # The short package description
Description: # Optional full package description
Moniker: # Optional most common package term
Tags: # Optional list of package terms
Agreements: # Optional package agreements
- AgreementLabel: # Optional agreement label
Agreement: # Optional agreement text
AgreementUrl: # Optional agreement URL
Documentations: # Optional documentation
- DocumentLabel: # Optional documentation label
DocumentUrl: # Optional documentation URL
ReleaseNotes: # Optional release notes
ReleaseNotesUrl: # Optional release notes URL
PurchaseUrl: # Optional purchase URL
InstallationNotes: # Optional notes displayed upon installation
ManifestType: defaultLocale # The manifest type
ManifestVersion: 1.9.0 # The manifest syntax versionPackageIdentifier - The package unique identifier
Required Field
This key is the unique identifier for a given package. This value is generally in the form of Publisher.Package. It is case sensitive, and this value must match the folder structure under the partition directory in GitHub.
PackageVersion - The package version
Required Field
This key represents the version of the package. It is related to the specific release this manifests targets. In some cases you will see a perfectly formed semantic version number, and in other cases you might see something different. These may be date driven, or they might have other characters with some package specific meaning for example.
The Windows Package Manager client uses this version to determine whether or not an upgrade for a package is available. In some cases, packages may be released with a marketing driven version, and that causes trouble with the winget upgrade command.
The current best practice for the Windows Package Manager 1.9 client is to use the value reported in Windows Apps & Features when this version of the package is installed. In some cases, packages do not report a version resulting in an upgrade loop or other unwanted behavior.
PackageLocaleThe package meta-data locale
Required Field
This key represents the locale for package meta-data. The format is BCP-47. This value identifies the language for meta-data to be displayed to a user when no locale file matching their preferences is available. The Microsoft community package repository validation pipelines also use this value to determine appropriate validation rules for this file.
References:
-
Default Input Profiles (Input Locales) in Windows
NOTE: This field is the key to determining which fields are required for the Microsoft community repository. The default locale specified in the version file must match with this value.
Publisher - The publisher name
Required Field
This key represents the name of the publisher for a given package. This field is intended to allow the full publisher's or ISV's name to be displayed as they wish.
NOTE: With the 1.9 release of the Windows Package Manager, this name affects how packages from a source are mapped to Apps installed in Windows 10 and Windows 11 via Add / Remove Programs (ARP) and Windows Apps & Features respectively. The best practice is to ensure this matches the entry for the package when it has been installed. This should be the value of the Publisher subkey for the package in the Windows registry. The impact is associated with winget upgrade and winget list.
PublisherUrl - The publisher home page
Optional Field
This key represents the web site for the publisher or ISV.
PublisherSupportUrl - The publisher support page
Optional Field
This key represents the customer support web site or specific web page provided by the publisher or ISV.
PrivacyUrl - The publisher privacy page or the package privacy page
Optional Field
This key represents the privacy web site or specific web page provided the publisher or ISV. If there is a privacy web site or specific web page for the package it is preferred over a generic privacy page for the publisher.
Author - The package author
Optional Field
This key represents the author of a package. In some cases, the author is an individual who develops and or maintains the package. In other cases this may be a URL pointing to the contributors web page for a package.
PackageName - The package name
Required Field
This key represents the name of the package. This field is intended to allow the full package name to be displayed as the publisher or ISV wishes.
NOTE: With the 1.9 release of the Windows Package Manager, this name affects how packages from a source are mapped to Apps installed in Windows 10 via Add / Remove Programs (ARP). The best practice is to ensure this matches the ARP entry for the package name when it has been installed. This should be the value of the DisplayName subkey for the package in the Windows registry. The impact is associated with winget upgrade and winget list.
PackageUrl - The package home page
Optional Field
This key represents the web site for the package.
License - The package license
Required Field
This key represents the license governing the use and or distribution for the product. This could be an open source license, or a commercial license. Please note that a copyright is not considered a license. If there is no available information on a product's license, "Proprietary" should be the value in this field.
LicenseUrl - The license page
Optional Field
This key represents the license web site or specific web page provided the publisher or ISV. If there is a license web site or specific web page for the package it is preferred over a generic license page for the publisher.
If this is a link to the license file for an open source project, it should be specific to the version for the package. Some open source projects change their license over time.
Copyright - The package copyright
Optional Field
This key represents the copyright for the package.
CopyrightUrl - The package copyright page
Optional Field
This key represents the copyright web site or specific web page provided the publisher or ISV. If there is a copyright web site or specific web page for the package it is preferred over a generic copyright page for the publisher.
If this is a link to the copyright file for an open source project, it should be specific to the version for the package. Some open source projects change their copyright over time.
ShortDescription - The short package description
Required Field
This key represents the description for a package. It is intended for use in winget show to help a user understand what the package is.
NOTE: This should be something descriptive about what the package does, and it should not simply state something like "<package name> installer" or "<package name> setup".
Description - The full package description
Optional Field
This key represents the full or long description for a package. It is not currently used in the Windows Package Manager.
NOTE: This was included for integration with the Microsoft Store source to provide the ability to display the full package description.
Moniker - The most common package term
Optional Field
This key represents the most common term users would search for when installing or upgrading a package. If only one package uses this moniker, then the install, list and upgrade command may match with this package.
NOTE: Moniker is the third property evaluated when searching for a matching package.
Tags - List of additional package search terms
Optional Field
This key represents other common term users would search for when looking for packages. Tags should be pertinent to what a user might search for when looking for a specific package.
NOTE: The best practice is to present these terms in all lower case with hyphens rather than spaces.
Agreements - List of package agreements
Optional Field
This key holds any agreements a user must accept prior to download and subsequent install or upgrade.
Windows Package Manager Community Repository
Agreements are only allowed in the community repository when the manifest is maintained by a verified developer.
AgreementLabel - The label for a package agreement
Optional Field
This key represents the label for a package agreement.
Agreement - The text for a package agreement
Optional Field
This key represents the text or body of a package agreement.
AgreementUrl - The URL for a package agreement
Optional Field
This key represents the URL for a package agreement.
Documentations - List of documentation
Optional Field
This key holds any documentation for providing software guides such as manuals and troubleshooting URLs.
DocumentLabel - The documentation label
Optional Field
This key represents the label for a documentation.
DocumentUrl - List of documentation
Optional Field
This key represents the URL for a documentation.
ReleaseNotes - The Release Notes for a package.
Optional Field
This key represents release notes for a package.
ReleaseNotesUrl - The Release Notes web page for a package.
Optional Field
This key represents release notes web page for a package.
PurchaseUrl - The Purchase URL for a package.
Optional Field
This key represents the purchase url for acquiring entitlement for a package.
InstallationNotes - The Installation Notes for a package.
Optional Field
This key represents the notes displayed to the user upon completion of a package installation.
ManifestType - The manifest type
Required Field
This key must have the value "defaultLocale". The Microsoft community package repository validation pipelines also use this value to determine appropriate validation rules when evaluating this file.
ManifestVersion - The manifest syntax version
Required Field
This key must have the value "1.9.0". The Microsoft community package repository validation pipelines also use this value to determine appropriate validation rules when evaluating this file.