starred/terminal
1
0
Fork 0
mirror of https://github.com/microsoft/terminal.git synced 2026-02-03 21:25:34 +00:00
Code Issues 19.0k Packages Projects Releases 20 Wiki Activity

[PR #3904] [MERGED] Improve keybinding JSON schema #25549

New Issue
Open
opened 2026-01-31 09:10:15 +00:00 by claunia · 0 comments
claunia commented 2026-01-31 09:10:15 +00:00
Owner
Copy Link

📋 Pull Request Information

Original PR: https://github.com/microsoft/terminal/pull/3904
Author: @davidwin
Created: 12/10/2019
Status: ✅ Merged
Merged: 3/24/2020
Merged by: @carlos-zamora

Base: master ← Head: keychords_schema

📝 Commits (1)

  • 37f861d Improve Keybinding JSON schema

📊 Changes

1 file changed (+3 additions, -2 deletions)

View changed files

📝 doc/cascadia/profiles.schema.json (+3 -2)

📄 Description

Summary of the Pull Request

The pattern regex in profiles.schema.json now correctly disallows keybindings consisting of only modifiers, modifiers not separated by +, and unknown key names. Certain shift+numpad combinations are also not allowed.

The description lists allowed key names in tabular format (assuming the client renders \t correctly):
image

PR Checklist

  • Closes #3856 and Feature Request: Admistrator shell in new tab (#2967)
  • CLA signed.
  • Tests added/passed (only manual validation in VSCode)
  • Requires documentation to be updated (this is documentation)
  • I've discussed this with core contributors already. If not checked, I'm ready to accept this work might be rejected in favor of a different grand plan. Issue number where discussion took place: #3856

Detailed Description of the Pull Request / Additional comments

The problem with the current keybinding schema is primarily that it accepts invalid key combinations.
Also, there is no accessible documentation of valid keys and modifiers. Now the regular expression
should be much closer to what the parser in KeyChordSerialization.cpp actually accepts, and the associated description explains the allowed string format.

One possible difference between the regexp and the parser is that the former accepts any single character except + and whitespace (e.g. }) for the key part while the latter relies on the VkKeyScanW Windows API for validation of single-character keys.

The regular expression might be a bit difficult to digest, so here it is with some added whitespace and no JSON string escapes:

^
 (?<modifier> (ctrl|alt|shift) 
              (?:\+(ctrl|alt|shift)(?<!\2))? 
              (?:\+(ctrl|alt|shift)(?<!\2|\3))?
              \+
 )?
 (?<key> [^\s+]
         |backspace|tab|enter|esc|escape|space|pgup|pageup|pgdn|pagedown|end|home|left|up|right|down|insert|delete
         |(?<!shift.+)(?:numpad_?[0-9]|numpad_(?:period|decimal))
         |numpad_(?:multiply|plus|minus|divide)
         |f[1-9]|f1[0-9]|f2[0-4]
         |plus
 )
$

Q: Is named captures a good idea? It was used by the previous regular expression, but an alternative approach would be to use numbered captures and only capture the individual modifiers (1 to 3) and the key (4).

Q: Would it be better to not list key names and descriptions in an attempted table, which currently isn't rendered very nicely in VS Code? The names are, after all, rather self explanatory.

Validation Steps Performed

I have performed validation of the new schema in VS Code v1.43 by opening the profiles.json settings file and changing the $schema property to https://raw.githubusercontent.com/davidwin/terminal/keychords_schema/doc/cascadia/profiles.schema.json. I'm then able to see that I get a description of how to format the globals.keybingings[].keys strings if I hover over a keys item, and a yellow squiggly if I enter an invalid key combination. All the default key combinations pass without error, and examples of strings that don't validate are: alt, shift+, ctrl++, +, shiftalt+up.

You can try the regular expression and get a deeper understanding of it at Regex101.

🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.

## 📋 Pull Request Information **Original PR:** https://github.com/microsoft/terminal/pull/3904 **Author:** [@davidwin](https://github.com/davidwin) **Created:** 12/10/2019 **Status:** ✅ Merged **Merged:** 3/24/2020 **Merged by:** [@carlos-zamora](https://github.com/carlos-zamora) **Base:** `master` ← **Head:** `keychords_schema` --- ### 📝 Commits (1) - [`37f861d`](https://github.com/microsoft/terminal/commit/37f861d9b96c055b21808e7aedd0466aaae55132) Improve Keybinding JSON schema ### 📊 Changes **1 file changed** (+3 additions, -2 deletions) <details> <summary>View changed files</summary> 📝 `doc/cascadia/profiles.schema.json` (+3 -2) </details> ### 📄 Description ## Summary of the Pull Request The pattern regex in [profiles.schema.json](https://raw.githubusercontent.com/davidwin/terminal/keychords_schema/doc/cascadia/profiles.schema.json) now correctly disallows keybindings consisting of only modifiers, modifiers not separated by `+`, and unknown key names. Certain `shift+numpad` combinations are also not allowed. The description lists allowed key names in tabular format (assuming the client renders `\t` correctly): ![image](https://user-images.githubusercontent.com/9844625/70371759-8fee0f00-18d7-11ea-85c2-b9f739252129.png) ## PR Checklist * [x] Closes #3856 and #2967 * [x] CLA signed. * [ ] Tests added/passed _(only manual validation in VSCode)_ * [ ] Requires documentation to be updated _(this is documentation)_ * [x] I've discussed this with core contributors already. If not checked, I'm ready to accept this work might be rejected in favor of a different grand plan. Issue number where discussion took place: #3856 ## Detailed Description of the Pull Request / Additional comments The problem with the current keybinding schema is primarily that it accepts invalid key combinations. Also, there is no accessible documentation of valid keys and modifiers. Now the regular expression should be much closer to what the parser in [KeyChordSerialization.cpp](https://github.com/microsoft/terminal/blob/master/src/cascadia/TerminalApp/KeyChordSerialization.cpp) actually accepts, and the associated description explains the allowed string format. One possible difference between the regexp and the parser is that the former accepts any single character except `+` and whitespace (e.g. `}`) for the key part while the latter relies on the `VkKeyScanW` Windows API for validation of single-character keys. The regular expression might be a bit difficult to digest, so here it is with some added whitespace and no JSON string escapes: ```regexp ^ (?<modifier> (ctrl|alt|shift) (?:\+(ctrl|alt|shift)(?<!\2))? (?:\+(ctrl|alt|shift)(?<!\2|\3))? \+ )? (?<key> [^\s+] |backspace|tab|enter|esc|escape|space|pgup|pageup|pgdn|pagedown|end|home|left|up|right|down|insert|delete |(?<!shift.+)(?:numpad_?[0-9]|numpad_(?:period|decimal)) |numpad_(?:multiply|plus|minus|divide) |f[1-9]|f1[0-9]|f2[0-4] |plus ) $ ``` **Q**: Is named captures a good idea? It was used by the previous regular expression, but an alternative approach would be to use numbered captures and only capture the individual modifiers (1 to 3) and the key (4). **Q**: Would it be better to not list key names _and_ descriptions in an attempted table, which currently isn't rendered very nicely in VS Code? The names are, after all, rather self explanatory. ## Validation Steps Performed I have performed validation of the new schema in VS Code v1.43 by opening the `profiles.json` settings file and changing the `$schema` property to https://raw.githubusercontent.com/davidwin/terminal/keychords_schema/doc/cascadia/profiles.schema.json. I'm then able to see that I get a description of how to format the `globals.keybingings[].keys` strings if I hover over a `keys` item, and a yellow squiggly if I enter an invalid key combination. All the default key combinations pass without error, and examples of strings that don't validate are: `alt`, `shift+`, `ctrl++`, `+`, `shiftalt+up`. You can try the regular expression and get a deeper understanding of it at [Regex101](https://regex101.com/r/mqlYhr/4). --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
claunia added the pull-request label 2026-01-31 09:10:15 +00:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
⛺ Reserved
A11yCO
A11yMAS
A11ySev1
A11ySev2
A11ySev3
A11yTTValidated
A11yUsable
A11yVoiceAccess
A11yWCAG
Area-Accessibility
Area-AtlasEngine
Area-AzureShell
Area-Build
Area-Build
Area-Chat
Area-CmdPal
Area-CodeHealth
Area-Commandline
Area-CookedRead
Area-DefApp
Area-Extensibility
Area-Fonts
Area-GroupPolicy
Area-i18n
Area-Input
Area-Interaction
Area-Interop
Area-Localization
Area-Output
Area-Performance
Area-Portable
Area-Quality
Area-Remoting
Area-Rendering
Area-Schema
Area-Server
Area-Settings
Area-SettingsUI
Area-ShellExtension
Area-ShellExtension
Area-ShellExtension
Area-Suggestions
Area-Suggestions
Area-TerminalConnection
Area-TerminalControl
Area-Theming
Area-UserInterface
Area-VT
Area-Windowing
Area-WPFControl
AutoMerge
Blocking-Ingestion
Culprit-Centennial
Culprit-WinUI
Disability-All
Disability-Blind
Disability-LowVision
Disability-Mobility
External-Blocked-WinUI3
Fixed
Gathering-Data
good first issue
HCL-E+D
HCL-WindowsTerminal
Help Wanted
Impact-Compatibility
Impact-Compliance
Impact-Correctness
Impact-Visual
In-PR
InclusionBacklog
InclusionBacklog-Windows TerminalWin32
InclusionCommitted-202206
Issue-Bug
Issue-Docs
Issue-Feature
Issue-Feature
Issue-Question
Issue-Samples
Issue-Scenario
Issue-Task
Needs-Attention
Needs-Author-Feedback
Needs-Bisect
Needs-Discussion
Needs-Repro
Needs-Tag-Fix
Needs-Tag-Fix
Needs-Triage
No-Recent-Activity
Priority-0
Priority-1
Priority-2
Priority-3
Product-Cmd.exe
Product-Colortool
Product-Colortool
Product-Colortool
Product-Conhost
Product-Conpty
Product-Meta
Product-Powershell
Product-Terminal
Product-WSL
pull-request
Mirrored from GitHub Pull Request
 Resolution-Answered
Resolution-By-Design
Resolution-Duplicate
Resolution-External
Resolution-Fix-Available
Resolution-Fix-Committed
Resolution-No-Repro
Resolution-Won't-Fix
Severity-Blocking
Severity-Crash
Severity-DataLoss
spam
this-will-be-a-breaking-change
Tracking-External
WindowsTerminal_Win32
Work-Item
zAskModeBug
zInbox-Bug
No Label pull-request
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
claunia
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: starred/terminal#25549
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?