PowerToys/doc/specs/WinGet Manifest Keyboard Shortcuts schema.md

WinGet Manifest Keyboard Shortcuts schema

1 What this spec is about

This spec provides an extension to the existing WinGet manifest schema in form of an additional yaml file, that describes keyboard shortcuts the application provides.

These yaml files are saved on a per-user base and so called manifest interpreters can then display these manifests in a human-friendly version.

1.1 What this spec is not about

This spec does not provide a way to back up or save user-defined keyboard shortcuts.

2 Save location of manifests

2.1 WinGet

These files are saved online along with the other manifest files in the WinGet Package repository.

2.2 Locally

All manifests and one index file are saved locally under %LocalAppData%/Microsoft/WinGet/KeyboardShortcuts. All apps are allowed to add their manifest files there. In addition Package Managers (like WinGet) and manifest interpreters (like PowerToys Shortcut Guide) can control and add other manifests themselves.

2.2.1 Downloading manifests

When WinGet or other package managers download a package, they should also download the corresponding keyboard shortcuts manifest file and save it in the local directory, given such a file exists in the WinGet repository.

The downloader is also responsible for updating the local index.yaml file, which contains all the information about the different manifest files that are saved in the same directory.

2.2.2 Updating manifests

When a manifest interpreter starts, it should download the latest version of the manifests from the WinGet repository and save them in the local directory. If a manifest interpreter is not able to download the manifests or they do not exist, it should use the locally saved manifests.

The updater is also responsible for updating the local index.yaml file, which contains all the information about the different manifest files that are saved in the same directory.

Note: WinGet must provide a way to update the keyboard shortcuts manifests given a package id.

2.3 File names

The file name of a keyboard shortcuts file is the WinGet package identifier, plus the locale of the strings of the file and at last the .KBSC.yaml file extension.

For example the package "test.bar" saves its manifest with en-US strings in test.bar.en-US.KBSC.yaml.

2.3.1 No winget package available

If an application has no corresponding WinGet package its name starts with a plus (+) symbol.

2.4 Reserved namespaces

Every name starting with +WindowsNT is reserved for the Windows OS and its components.

3 File syntax

All relevant files are written in YAML.

Note: A JSON schema will be provided as soon as the spec reaches a further step

3.1 Manifest Schema vNext Keyboard Shortcuts File

PackageName:                # The package unique identifier
WindowFilter:               # The filter of window processes to which the shortcuts apply to
BackgroundProcess:          # Optionally allows applying WindowFilter to background processes
Shortcuts:                  # List of sections with keyboard shortcuts
  - SectionName:            # Name of the category of shortcuts
    Properties:             # List of shortcuts in the category
      - Name:               # Name of the shortcut
        Description:        # Optional description of the shortcut
        AdditionalInfo:     # Optional additional information about the shortcut
        Recommended:        # Optionally determines if the shortcut is displayed in a designated recommended area
        Shortcut:           # An array of shortcuts that need to be pressed
          - Win:            # Determines if the Windows Key is part of the shortcut
            Ctrl:           # Determines if the Ctrl Key is part of the shortcut
            Shift:          # Determines if the Shift Key is part of the shortcut
            Alt:            # Determines if the Alt Key is part of the shortcut
            Keys:           # Array of keys that need to be pressed

Per Application/Package one or more Keyboard manifests can be declared. Every manifest must have a different locale and the same PackageName, WindowFilter and BackgroundProcess fields.

PackageName - The package unique identifier

Package identifier (see 2.1 for more information on the package identifier).

WindowFilter - The filter of window processes to which the shortcuts apply to

This field declares for which process name the shortcuts should be shown (To rephrase: For which processes the shortcut will have an effect if pressed). The value can be either an exact process executable name, for example explorer.exe or chrome.exe, or a single asterisk (*) to apply to any process. No other wildcard patterns are supported by this specification.

BackgroundProcess - Optionally allows applying WindowFilter to background processes.

Optional field

Defaults to False. Determines if WindowFilter should apply to background processes as well (Rephrased: When the process is running, the shortcuts will apply).

Shortcuts - List of sections with keyboard shortcuts

List of different section (also called categories) of shortcuts.

SectionName - Name of the category of shortcuts

Name of the section of shortcuts. Use sentence case, the same convention described under Name below.

Special sections:

Special sections start with an identifier enclosed between < and >. This declares the category as a special display. If the interpreter of the manifest file can't understand the content this section should be left out.

Properties - List of shortcuts in the category

Name - Name of the shortcut

Name of the shortcut. This is the name that will be displayed in the interpreter.

Casing:

By convention, shortcut names (and SectionName values) use sentence case: capitalize only the first word plus any proper nouns or product/feature names. For example, prefer Reopen last closed tab over Reopen Last Closed Tab, but keep Open History, Quit Slack, and Show Quick Access capitalized because those are application feature names. Match the casing the application uses for its own features rather than copying the title-case styling some apps apply to their entire shortcut list.

Description - Optional description of the shortcut

Optional description of the shortcut. This is the description that will be displayed by the interpreter.

AdditionalInfo - Optional additional information about the shortcut

Array of additional information about the shortcut. This is the additional information that will be displayed by the interpreter and are not part of this manifest.

Example:

For example, if the shortcut is only available on a certain Windows version, this information could be added here.

 AdditionalInfo:
   - MinWindowsVersion: "10.0.19041.0"

Shortcut - An array of shortcuts that need to be pressed

An array of shortcuts that need to be pressed. This allows defining sequential shortcuts that need to be pressed in order to trigger the action.

Win - Determines if the Windows Key is part of the shortcut

Refers to the left Windows Key on the keyboard.

Ctrl - Determines if the Ctrl Key is part of the shortcut

Refers to the left Ctrl Key on the keyboard.

Shift - Determines if the Shift Key is part of the shortcut

Refers to the left Shift Key on the keyboard.

Alt - Determines if the Alt Key is part of the shortcut

Refers to the left Alt Key on the keyboard.

Recommended - Optionally determines if the shortcut is displayed in a designated recommended area

Optional field

Defaults to False. Determines if the shortcut should be displayed in a designated recommended area. This is a visual hint for the user that this shortcut is important.

Keys - Array of keys that need to be pressed

A string array of all the keys that need to be pressed. If a number is supplied, it should be read as a KeyCode and displayed accordingly (based on the Keyboard Layout of the user).

Literal digit keys:

Because a bare number is interpreted as a virtual-key code, a literal digit key must be authored using the <N> notation (the digit enclosed between < and >), where N is 0–9. For example, <9> represents the literal 9 key (as in the "switch to the last tab" shortcut), not the virtual-key code 9 (which is Tab). The interpreter strips the brackets and displays just the digit.

This applies only to a single literal digit. A range such as 1 - 8 is a free-form label, not a key, and is supplied verbatim (the brackets would only be trimmed from the ends, so <1> - <8> would not render as intended).

Special keys:

Special keys are enclosed between < and > and correspond to a key that should be displayed in a certain way. If the interpreter of the manifest file can't understand the content, the brackets should be left out.

By convention these tokens are written as double-quoted strings in the YAML (for example "<Enter>" and "<9>"), matching the quoting used for punctuation key values. YAML treats the quoted and unquoted forms identically, so quoting is for consistency rather than a strict requirement for bracketed tokens.

Name	Description
<Office>	Corresponds to the Office key on some Windows keyboards
<Copilot>	Corresponds to the Copilot key on some Windows keyboards
<Left>	Corresponds to the left arrow key
<Right>	Corresponds to the right arrow key
<Up>	Corresponds to the up arrow key
<Down>	Corresponds to the down arrow key
<Enter>	Corresponds to the Enter key
<Space>	Corresponds to the Space key
<Tab>	Corresponds to the Tab key
<Backspace>	Corresponds to the Backspace key
<Delete>	Corresponds to the Delete key
<Insert>	Corresponds to the Insert key
<Home>	Corresponds to the Home key
<End>	Corresponds to the End key
<PrtScr>	Corresponds to the Print Screen key
<Pause>	Corresponds to the pause key
<PageUp>	Corresponds to the Page Up key
<PageDown>	Corresponds to the Page Down key
<Escape>	Corresponds to the Escape key
<Arrow>	Corresponds to either the left, right, up or down arrow key
<ArrowLR>	Corresponds to either the left or right arrow key
<ArrowUD>	Corresponds to either the up or down arrow key
<LessThan>	Corresponds to the < key
<GreaterThan>	Corresponds to the > key
<Underlined letter>	Corresponds to any letter that is underlined in the UI

3.2.2 Example

PackageName: Microsoft.PowerToys
WindowFilter: "*"
BackgroundProcess: True
Shortcuts:
  - SectionName: General
    Properties:
      - Name: Advanced Paste
        Shortcut:
          - Win: True
            Ctrl: False
            Alt: False
            Shift: False
            Keys:
              - 86
        Description: Open Advanced Paste window
      - Name: Advanced Paste
        Shortcut:
          - Win: True
            Ctrl: True
            Alt: True
            Shift: False
            Keys:
              - 86
        Description: Paste as plain text directly

3.2 index.yaml file

The index.yaml file is a file that contains all the information about the different manifest files that are saved in the same directory. This file is only available locally and is not saved in the WinGet repository as it is specific to the user.

DefaultShellName:           # The package identifier of the default shell used in Windows
Index:                      # List of all manifest files
  - WindowFilter:           # The filter of window processes to which the shortcuts apply to
    BackgroundProcess:      # Optionally allows applying WindowFilter to background processes
    Apps:                   # List of all manifest files for the filter

DefaultShellName - The package identifier of the default shell used in Windows

This declares the package identifier of the default shell used in Windows. Most commonly it is +WindowsNT.Shell. Although not enforced, only the shell declared in the registry key HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Winlogon\Shell should be used here.

Index - List of all manifest files

WindowFilter - The filter of window processes to which the shortcuts apply to

See the WindowFilter field in the manifest file for more information.

BackgroundProcess - Optionally allows applying WindowFilter to background processes

Optional field

See the BackgroundProcess field in the manifest file for more information.

Apps - List of all the package identifiers applying for the filter

3.2.1 Example

DefaultShellName: "+WindowsNT.Shell"
Index:
  - Filter: "*"
    BackgroundProcess: True
    Apps: ["+WindowsNT.Shell", "Microsoft.PowerToys"]
  - Filter: "explorer.exe"
    Apps: ["+WindowsNT.WindowsExplorer"]
  - Filter: "taskmgr.exe"
    Apps: ["+WindowsNT.TaskManager"]
  - Filter: "msedge.exe"
    Apps: ["+WindowsNT.Edge"]