JSON fragment extensions in Windows Terminal

JSON fragment extensions are snippets of JSON that application developers can write to add new profiles to users' settings, or even modify certain existing profiles. They can also be used to add new color schemes to users' settings.

Structure of the JSON files

The JSON file should be split up into 2 lists, one for profiles and one for schemes. Here is an example of a json file that adds a new profile, modifies an existing profile, and creates a new color scheme:

{
  "profiles": [
    {
      // update the profile with the GUID below
      "updates": "{2c4de342-38b7-51cf-b940-23e9ae97f518}",
      "fontSize": 16,
      "fontWeight": "thin"
    },
    {
      // create a new profile
      "name": "Cool Profile",
      "commandline": "powershell.exe",
      "antialiasingMode": "aliased",
      "fontWeight": "bold",
      "colorScheme": "Postmodern Tango Light"
    }
  ],
  "schemes": [
    {
      // create a new color scheme
      "name": "Postmodern Tango Light",

      "black": "#0C0C0C",
      "red": "#C50F1F",
      "green": "#13A10E",
      "yellow": "#C19C00",
      "blue": "#0037DA",
      "purple": "#881798",
      "cyan": "#3A96DD",            
      "white": "#CCCCCC",
      "brightBlack": "#767676",
      "brightRed": "#E74856",
      "brightGreen": "#16C60C",
      "brightYellow": "#F9F1A5",
      "brightBlue": "#3B78FF",
      "brightPurple": "#B4009E",
      "brightCyan": "#61D6D6",
      "brightWhite": "#F2F2F2"
    }
  ]
}

The first item in the "profiles" list updates an existing profile, identifying the profile it wishes to update via the GUID provided to the "updates" field (details on how to obtain the GUID are in the next section). The second item in that list creates a new profile called "Cool Profile".

In the "schemes" list, a new color scheme called "Postmodern Tango Light" is defined, and can be subsequently referenced by the user in their settings file or in this JSON file itself (notice that "Cool Profile" uses this newly defined color scheme).

Of course, if the developer only wishes to add/modify profiles without adding color schemes (and vice-versa), only the relevant list needs to be present and the other list can be omitted.

How to determine the GUID of an existing profile

The only profiles that can be modified through fragments are the default profiles, Command Prompt and PowerShell, as well as dynamic profiles. To determine the GUID of the profile to be updated, use a Version 5 UUID generator with the following namespace GUID and name:

  • The namespace GUID: {2BDE4A90-D05F-401C-9492-E40884EAD1D8}
  • The name of the profile to be updated

As a sanity check, a profile called 'Ubuntu' will get the generated GUID: {2C4DE342-38B7-51CF-B940-2309A097F518}

Minimum requirements for settings added with fragments

There are some minimal restrictions on what can be added to user settings using JSON fragments:

  • For new profiles added via fragments, the new profile must, at a minimum, define a name for itself.
  • For new color schemes added via fragments, the new color scheme must define a name for itself, as well as define every color in the color table (i.e. the colors "black" through "brightYellow" in the example image above).

Where to place the JSON fragment files

The location to place the JSON fragment files varies depending on the installation method of the application that wishes to place them.

Microsoft Store applications

For applications installed through the Microsoft Store (or similar), the application must declare itself to be an app extension. More details on app extensions can be found in the Microsoft Docs and the necessary section is replicated here. The appxmanifest file of the package must include:

<Package
  ...
  xmlns:uap3="http://schemas.microsoft.com/appx/manifest/uap/windows10/3"
  IgnorableNamespaces="uap uap3 mp">
  ...
    <Applications>
      <Application Id="App" ... >
        ...
        <Extensions>
          ...
          <uap3:Extension Category="windows.appExtension">
            <uap3:AppExtension Name="com.microsoft.windows.terminal.settings"
                               Id="<id>"
                               PublicFolder="Public">
            </uap3:AppExtension>
          </uap3:Extension>
        </Extensions>
      </Application>
    </Applications>
    ...
</Package>

Key things to note:

  • The "Name" field must be com.microsoft.windows.terminal.settings for Windows Terminal to be able to detect the extension.
  • The "Id" field can be filled out as the developer wishes.
  • The "PublicFolder" field should have the name of the folder, relative to the package root, where the JSON files are stored (this folder is typically called "Public" but can be named something else if the developer wishes).
  • Inside the public folder, a subdirectory called "Fragments" should be created, and the JSON files should be stored in that subdirectory.

Applications installed from the web

For applications installed from the web, there are 2 cases.

The first is that the installation is for all the users on the system. In this case, the JSON files should be added to the folder:

C:\ProgramData\Microsoft\Windows Terminal\Fragments\{app-name}

In the second case, the installation is only for the current user. In this case, the JSON files should be added to the folder:

C:\Users\<user>\AppData\Local\Microsoft\Windows Terminal\Fragments\{app-name}

Note that both the ProgramData and LocalAppData folders are known folders that the installer should be able to access. If in either case, if the Windows Terminal\Fragments directory does not exist, the installer should create it.