Keyboard Support

Contact and Search

Keyman.com Homepage

Header bottom

Keyman.com

Other versions
Version 2.0 (current version)Version 1.0

Index

On this page

.keyboard_info 1.0 Specification

This file will be created by the PR submitter of the keyboard, for new pull requests. It is a JSON file, with the following members. The .keyboard_info file will be used when building keyboard layouts for deployment; the master version of the file lives in the keyboard repository. During CI deployment, it will be read from the source repository, extended with the required generated fields and this new version pushed with the compiled resources to the download store.

KeyboardInfo Object

Note: The Generated column indicates if the field will be generated if it is not present in the source repository during the CI deployment process. Fields that are Required and not Generated must be completed by the keyboard author.

Member Required in source? Required in distribution Generated? Notes
id yes yes

string, the same as the name of the folder, lower case. In the release/ folder, this name must be a valid Javascript identifier, and follow the rules in the Keyboard Cloud Repository documentation.

Example: "id": "fv_blackfoot"

Generation: from folder name.

name yes yes

string, the human readable name of the keyboard. This will usually differ from the id.

Generation: from .kmp info, package name. If a .kmp is not included, it is sourced from the .js with a regular expression.

authorName yes

string, the name of the author

Generation: from .kmp info

authorEmail yes

string, the email address of the author

Generation: from .kmp info

description

string, a textual description of the keyboard. This may contain some minimal HTML (p, b, i, u, span, a, ul, ol, li, br, hr, h1-h4 tags).

No Automatic Generation: this information is not consistently available elsewhere. If not specified, then a description will be generated based on the supported languages at runtime by the consumer of the json.

license yes yes

string, the possible values for license vary by location in the repository:

  • release/ and experimental/ keyboards must be "mit".
  • legacy/ keyboards will be "freeware", "shareware" or "commercial".

This must always be specified, even for release/ and experimental/ keyboards, because this must be an explicit decision by the keyboard author for legal reasons.

languages yes yes

array or objects; an array of BCP 47 codes, or an object with its member names being BCP 47 codes and values being KeyboardLanguageInfo objects.

Generation: There is now some automatic generation of language names. The font and example information in the keyboard list is not available elsewhere.

lastModifiedDate yes yes

string, the last time the keyboard was modified, in RFC3339, UTC YYYY-MM-DDThh:mm:ss[.nnn]Z

Generation: the time that the .keyboard_info file is generated

links

array, of KeyboardLinkInfo objects

packageFilename yes (1) yes (1)

string, filename of the .kmp file that will be distributed, relative to the keyboard base folder, including extension, required for experimental/ and legacy/ folders. If no .kmp exists, then keyboard is js only. For release/ folders, this must be id/build/id.kmp.

Generation: if more than one .kmp exists, then fail.

packageFileSize yes

number, integer size of the .kmp file that will be distributed.

Generation: This will normally be generated automatically.

jsFilename yes (2) yes (2)

string, filename of the .js file that will be distributed,  e.g. "gff_amh.js".

packageFilename and/or jsFilename must be specified for legacy and experimental keyboards.

Generation: for release, must be id.js.

jsFileSize yes

number, integer size of the .js file that will be distributed.

Generation: This will normally be generated automatically.

documentationFilename

string, filename of the .pdf or .rtf format documentation file associated with the keyboard, relative to the keyboard base folder.

No Automatic Generation: This may be difficult to ascertain as the file loses path when compiled into a .kmp.

documentationFileSize yes

number, integer size of the documentationFileName file that will be distributed.

Generation: This will normally be generated automatically.

isRTL yes

boolean, true if the .js keyboard should be right-to-left.

Generation: This can usually be generated automatically from the .js file, by heuristic. If the heuristic is not working, add the appropriate value to the source .keyboard_info file.

encodings yes

array, of up to 2 strings, "unicode" and/or "ansi".

Generation: from .kmx, .js.

packageIncludes yes (1) yes (1)

array, of strings. Metadata used mostly by legacy keyboards. This flags whether a package includes:

  • "fonts" - one or more fonts
  • "documentation" - documentation, in PDF, RTF or HTML format, excluding welcome.htm and readme
  • "visualKeyboard" - a KVK file
  • "welcome" - a welcome.htm file

Generation: from .kmp

version yes

string, the file version of the keyboard / package.

Generation: from .kmp, .js. If no version number is present in the compiled file, assumes "1.0"

minKeymanVersion yes yes

string. The minimum version of Keyman that can read this keyboard. If present, must be a two part version string, starting from "6.0" and up. Note: for versions below 10.0, this value is used in KeymanWeb, but the version mapping is based on Keyman Desktop version numbers. For versions 10.0 and above, all platforms have a synchronized version number. See KeymanWeb Versioning for more detail.

Generation: from .kmp, .js.

helpLink

string. If present, the link to this keyboard's help page on help.keyman.com.

Generation: if id/source/help/id.php exists.

platformSupport yes yes

A KeyboardPlatformInfo object.

Generation: from .kmp, .js existence. Assumes, if .kmp exists, that "macos", "windows" are supported; if .js exists, "ios", "android", "web" are supported.

legacyId

number, the integer identifier for the keyboard in the legacy Tavultesoft keyboard database.

sourcePath yes

string, the relative path of the keyboard in the /keymanapp/keyboards GitHub repository, starting with release/, experimental/ or legacy/.

Generation: This will normally be generated automatically.

related

object, with each property an id of a keyboard and corresponding value is a KeyboardRelatedInfo.

deprecated yes

boolean, true if the keyboard has been deprecated.

Generation: Always generated automatically, currently only visible on api.keyman.com/search.

KeyboardLanguageInfo Object

Member Required? Notes
font

KeyboardFontInfo object containing information about a  recommended font for use with the keyboard.

oskFont

KeyboardFontInfo object containing information about a  recommended font for use with the on screen keyboard. If not present, uses font. If both are not present, then Keyman uses the default system font.

example

KeyboardExampleInfo object containing a sample text that the user can type to give them an idea of how to start to use the keyboard.

displayName

string, a descriptive name of the language to display to users in the format: language (script, region). If the BCP 47 code does not contain script or region subtags, only the language name is displayed.

Example: "displayName": "Central Atlas Tamazight (Tifinagh, Morocco)"

Generation:This will be generated automatically from the BCP 47 code.

languageName

string, the name of the language subtag in the BCP 47 code.

Example:"languageName": "Central Atlas Tamazight"

Generation:This will be generated automatically from the BCP 47 code.

scriptName

string, the name of the script subtag in the BCP 47 code.

Example:"scriptName": "Tifinagh"

Generation:This will be generated automatically from the BCP 47 code.

regionName

string, the name of the region subtag in the BCP 47 code.

Example:"regionName": "Morocco"

Generation:This will be generated automatically from the BCP 47 code.

KeyboardLinkInfo Object

Member Required? Notes
name yes

string, the text to be shown in the link

url yes

string, the fully qualified url of the link.

KeyboardPlatformInfo Object

Member Required? Notes
windows

string, for all members: one of "dictionary", "full", "basic", or "none". If member is missing, "none".

  • "dictionary": keyboard includes dictionary, e.g. IME or suggestion/autocompletion support.
  • "full": keyboard is designed and optimised for the platform, and works well with it.
  • "basic": keyboard compiles for the platform but has not been optimised for it (e.g. a Windows keyboard compiled to web, with no touch-specific support, will still work on a touch platform but will have a desktop-shaped touch keyboard with too many keys on it).
  • "none": keyboard does not work on the platform
macos
desktopWeb
ios
android
mobileWeb
linux

KeyboardFontInfo Object

Member Required? Notes
family yes

string, family name of the font; can be used by Keyman Engine to locate an already installed font of the same name.

source yes

string, filename, relative to .keyboard_info file.

size

string, in CSS Units, default 100%.

KeyboardExampleInfo Object

Member Required? Notes
keys

One of the following types:

  • string, a list of keystrokes to type to produce a short sample text using this keyboard, must be plain text US English keycaps, e.g. "Tiena ysTlN", cannot use modifiers other than Shift.
  • array of strings and/or KeyboardExampleKeyInfo objects, e.g. ["Tiena", { "modifiers": ["shift"], "key": "K_SPACE" }, "ysTlN" ].

This is not intended to give a full description of the keyboard but rather a simple example that introduces the user to the way the keyboard works.

text

string, the result of the keystrokes typed, i.e. a Unicode string.

note

string, a text note that helps to explain the example to the user.

KeyboardExampleKeyInfo Object

Member Required? Notes
modifiers

array of "shift", "ctrl", "alt", "left-ctrl", "left-alt", "right-ctrl", "right-alt" strings.

key yes

string. A valid K_ identifier, from the first two lists in https://help.keyman.com/developer/language/guide/virtual-keys (i.e., excluding reserved virtual key codes). Touch-specific keys such as T_xxx or U_abcd are not permitted.

KeyboardRelatedInfo Object

Member Required? Notes
deprecates

boolean, if true, then this keyboard is intended to deprecate another keyboard with the parent member name, and Keyman will upgrade it to this keyboard if found, ignoring version numbers.

deprecatedBy

boolean, if true, then this keyboard has been deprecated by the keyboard referred to. This member should not be set in the source .keyboard_info but will be returned from queries to api.keyman.com.

note

string, a textual description of the relationship between the keyboards.

1: Required for desktop distributions, not for web distributions.

2: Required for web distributions, not for desktop distributions.

Schema

A validating schema for the object is online at https://api.keyman.com/schemas/keyboard_info.source.json and https://api.keyman.com/schemas/keyboard_info.distribution.json. .keyboard_info files in the repository must validate against the source json; after build, the resulting .keyboard_info will validate against the distribution json.

Validation

The keyboard repository build process validates the JSON schema, then copies the .keyboard_info into the build/ folder and populates missing generated fields. If a field is already present, it will be validated for correctness against the compiled keyboard files, but will not be overridden.

Any errors in a .keyboard_info file will cause the build to fail.

Examples

This is a sample minimal source .keyboard_info file. Note that as you can see, only two fields are required for the source file. The build process will generate any missing fields that it can. Generally speaking, it is better to keep the file minimal to avoid duplication.


{
  "license": "mit",
  "languages": ["crl", "crj"]
}

The following is a reasonably comprehensive example .keyboard_info file for a Tibetan keyboard. This illustrates deprecated keyboards; many of these fields will typically be generated automatically from the compiled keyboard data:


{
  "id" : "tibetan_unicode_direct_input",
  "name" : "Tibetan Unicode Direct Input",
  "description" : "Tibetan Unicode Direct Input is designed to type all Tibetan characters and stacks directly. You get a Tibetan character every time you press a key, without having to use the Alt key or complex transliteration combinations. The keyboard types in a phonetic style based on the English (QWERTY) layout.\r\n\r\nThis keyboard also features special menus for Tibetan symbols and lets you type Latin and Cyrillic letters. ",
  "jsFilename" : "tibetan_unicode_direct_input-1.1.js",
  "documentationFilename" : "tibetan unicode direct input help.pdf",
  "packageFilename" : "tibetan_unicode_direct_input.kmp",
  "authorEmail" : "[email protected]",
  "platformSupport" : {
    "desktopWeb" : "full",
    "ios" : "basic",
    "android" : "basic"
  },
  "minKeymanVersion" : "7.0",
  "packageIncludes" : [
    "fonts",
    "documentation",
    "visualKeyboard",
    "welcome"
    ],
  "version" : "1.1",
  "license" : "mit",
  "languages" : {
    "adi" : {
      "font" : {
        "family" : "TibetanWeb",
        "source" : "DDC_Uchen.ttf"
      },
      "oskFont" : {
        "family" : "TibetanWebOsk",
        "source" : [
          "DDC_Uchen.ttf",
          "ddc_uchen-webfont.svg#ddc_uchenregular"
          ]
      }
    },
    "bod" : {
      "font" : {
        "family" : "TibetanWeb",
        "source" : "DDC_Uchen.ttf"
      },
      "oskFont" : {
        "family" : "TibetanWebOsk",
        "source" : [
          "DDC_Uchen.ttf",
          "ddc_uchen-webfont.svg#ddc_uchenregular"
          ]
      },
      "example" : {
        "keys" : "bod sKd",
        "text" : "\u0F56\u0F7C\u0F51\u0F0B\u0F66\u0F90\u0F51",
        "note" : "Name of language"
      }
    }
  },
  "lastModifiedDate" : "2015-02-16T07:34:55Z",
  "encodings" : [
    "unicode"
    ],
  "related" : {
    "tibetan unicode direct input" : {
      "deprecates" : true
    }
  },
  "legacyId" : 364
}

Version History

1.0, 2017-09-14
Initial version
1.0.1, 2018-01-31
Add file sizes, isRTL, sourcePath fields so we can supply these to the legacy KeymanWeb Cloud API endpoints. Remove references to .kmx being a valid package format.
1.0.2, 2018-02-10
Add dictionary to platform support choices. Fixed default for platform to 'none'.
1.0.3, 2018-02-12
Renamed minKeymanDesktopVersion to minKeymanVersion to clarify that this version information applies to all platforms.
1.0.4 2018-11-26
Add helpLink field that contains the link to a keyboard help page on help.keyman.com.
1.0.5 2018-12-18
Deprecate languages[] array. Update KeyboardLanguageInfo object to include subtag names.
1.0.6 2019-09-06
No changes (originally in #36 removed some unused fields but these are still in use. Reverted in 2020-06-10.).