.keyboard_info 2.0 Specification

---

This file is generated by the compiler and provides metadata for a keyboard. It is a JSON file, with the following members. The .keyboard_info file will be used primarily by Keyman Cloud Services. During CI deployment, it will be built from the source package and keyboard metadata, and pushed with the compiled resources to the download store.

KeyboardInfo Object

• id

  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

  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

  string, the name of the author

  Generation: from .kmp info

• authorEmail

  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).

  Generation: from .kmp info

• license

  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".

  Generation: from LICENSE.md

• languages

  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: From .kmp info.

• lastModifiedDate

  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

• packageFilename

  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, for keyboard id, id/build/id.kmp.

  Generation: always id.js.

• packageFileSize

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

  Generation: From .kmp.

• jsFilename

  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: always id.js.

• jsFileSize

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

  Generation: From .js.

• isRTL

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

  Generation: From .kmx, .js.

• encodings

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

  Generation: from .kmx, .js.

• packageIncludes

  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

  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

  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

  A [KeyboardPlatformInfo] object.

  Generation: from .kmp

• sourcePath

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

  Generation: from path in repository.

• related

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

• deprecated

  boolean, true if the keyboard has been deprecated.

  Generation: Always generated from related keyboards, currently only visible on api.keyman.com/search.

KeyboardLanguageInfo Object

• font

  [KeyboardFontInfo] object containing information about a recommended display font for use with text produced by the keyboard.

  Generation: This will be generated automatically from the .kmp file.

• 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.

  Generation: This will be generated automatically from the .kmp file.

• examples

  Array of [KeyboardExampleInfo] objects containing sample text that the user can type to give them an idea of how to start to use the keyboard. This replaces example field from version 1.0, and is less restrictive in its set of allowed key identifiers.

  Generation: This will be generated automatically from the .kmp file.

• 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.

KeyboardPlatformInfo Object

• windows, macos, desktopWeb, ios, android, mobileWeb, linux members

  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

KeyboardFontInfo Object

• family

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

• source

  string[], 1 or more filenames, relative to .keyboard_info file.

KeyboardExampleInfo Object

• keys

  string, a list of keystrokes to type to produce a short sample text using this keyboard, space-separated. Modifiers indicated with "+". Spacebar with "space". Plus key with "plus". 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.

KeyboardRelatedInfo Object

• 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.

Schema

A validating schema for the object is online at https://api.keyman-staging.com/schemas/keyboard_info.schema.json.

Validation

The kmc compiler generates the .keyboard_info file from the package and keyboard metadata, into the build/ folder.

Examples

The following is a reasonably comprehensive example .keyboard_info file for a Tibetan keyboard.

{
  "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",
  "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"
          ]
      },
      "examples" : [{
        "keys" : "b o d space s K d",
        "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
    }
  }
}

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.).

2.0, 2023-08-16

A number of changes, in order to simplify the format and make it 100% generated from .kmp metadata. This also means the distinction between keyboard_info.source.json and keyboard_info.distribution.json has been removed, and the schema file is now called keyboard_info.schema.json. The following changes have been made to the JSON structure:

• Removed legacyId, documentationFilename, documentationFileSize, links, related[].note, language.[osk]font.size fields
• language.[osk]font.source is now always an array.
• language.examples replaces language.example, and structure has been simplified