Clarify manifest entries usage/purpose

Brief description of your issue

Some entries are a bit unclear (IMHO) and some example value annotations in the schema would be nice as well.

ProductCode

ProductCode could be used for correlation of packages across sources

is simply not descriptive enough.

I tried to add some feedback in an existing issue about this but got no response.

• A MSI product code? Then the documentation should say so and the validator should ensure that this is a GUID.
• The name of the ARP uninstall subkey? If this key is used to determine if the package is already is installed then that should be called out in the value description. Calling this a ProductCode is perhaps a misnomer because that is MSI specific terminology.

installer.md currently links to a MSDN page that starts with "The product code is a GUID ..." but the overall usage in the community repository contains free form text entries as well (and some GUIDs are missing the {} brackets).

If this is always a GUID, the schema should have a pattern: for GUID validation and include "examples": ["{MSI-GUID}"], otherwise it should include "examples": ["{MSI-GUID}", "ContosoApp", "Fabrikam.FantastikApp"]

UpgradeCode

UpgradeCode is definitely a GUID but the schema just uses "$ref": "#/definitions/ProductCode" which has the same poor description and no GUID validation.

The schema should be updated to include "examples": ["{MSI-GUID}"] and "$comment": "https://learn.microsoft.com/en-us/windows/win32/msi/upgradecode"

InstallerSwitches\Silent

The description is problematic.

Silent is the value that should be passed to the installer when user chooses a silent or quiet install

The word "quiet" is not used anywhere else in the entire schema, is this just a synonym for silent or is it a different type of install mode? If it's just a synonym, it should be removed or replaced with "silent/quiet" to remove the word "or".

Dependencies\WindowsFeatures

Should include "examples": ["ntvdm", "DirectPlay", "Microsoft-Windows-Subsystem-Linux"]

Capabilities

• Capabilities should include "examples": ["contacts", "internetClient", "globalMediaControl"]
• RestrictedCapabilities should include "examples": ["deviceUnlock", "runFullTrust", "broadFileSystemAccess"]

RequireExplicitUpgrade

The schema and installer.md descriptions vary too much, the one in installer.md is much better.

ElevationRequirement

How is elevatesSelf different from the property not being present at all in the manifest? How does one identify such an installer? Does it have a "requestedExecutionLevel requireAdministrator" node in the .exe manifest? Does it launch normally but later on requests elevation with ShellExecute(.."runas"..)?

InstallationMetadata

• DefaultInstallLocation should include "examples": ["%ProgramFiles%\ContosoApp"] (assuming environment variables are valid here).
• RelativeFilePath in the community repository has uses with no prefix, with .\ and some with / slashes. A proper example should be included and the validator should probably reject paths starting with .\?
• DisplayName, is this the name returned by IShellItem::GetDisplayName? (e.g. the filename without the extension as seen in Explorer)

Start by comparing the manifest schema descriptions with installer.md, then review the existing discussion in issue 921. Update the named entries with clearer usage, examples, comments, and validation requirements where the intended semantics are established; done means the schema and installer.md no longer contradict each other and the unresolved behavior is documented.