Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/nordicsemi/bluetooth-numbers-database/llms.txt

Use this file to discover all available pages before exploring further.

The appearance schema validates v1/gap_appearance.json, which contains the GAP Appearance values defined by the Bluetooth SIG. Appearance is a two-byte value that describes what type of device a Bluetooth peripheral represents — for example, a heart rate sensor, a keyboard, or a smartwatch. The schema is defined in v1/appearance_schema.json and reflects a two-level hierarchy: top-level categories and optional sub-categories nested within them. The two bytes of an Appearance value are split as follows: bits 15–6 encode the category and bits 5–0 encode the sub-category.

​
Full schema

{
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "category": {
        "type": "integer"
      },
      "name": {
        "type": "string"
      },
      "subcategory": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "value": { "type": "integer" },
            "name": { "type": "string" }
          },
          "required": ["value", "name"]
        }
      }
    },
    "required": ["category", "name"]
  }
}

​
Category fields

Each item in the top-level array represents an Appearance category and must include the following fields.
​
category
integer
required
A decimal integer identifying the Appearance category. This corresponds to the value encoded in bits 15–6 of the 2-byte Appearance value as defined in the Bluetooth Core Specification Supplement. For example, 2 is the category value for Computer. Category values must be unique across the entire gap_appearance.json file — duplicates are detected by verify.js.
​
name
string
required
The human-readable name for the Appearance category, matching the name used in the Bluetooth SIG Assigned Numbers document. Examples: "Unknown", "Phone", "Computer", "Watch".
​
subcategory
array
An optional array of sub-category objects providing finer-grained device classification within the parent category. When present, each element must conform to the sub-category schema described below. Categories with no meaningful sub-classifications (such as "Phone" or "Unknown") omit this field entirely.

​
Example

The following shows the Computer category entry (category 2) from gap_appearance.json, including its full sub-category list: 
{
  "category": 2,
  "name": "Computer",
  "subcategory": [
    { "value": 1, "name": "Desktop Workstation" },
    { "value": 2, "name": "Server-class Computer" },
    { "value": 3, "name": "Laptop" },
    { "value": 4, "name": "Handheld PC/PDA (clamshell)" },
    { "value": 5, "name": "Palm-size PC/PDA" },
    { "value": 6, "name": "Wearable computer (watch size)" },
    { "value": 7, "name": "Tablet" },
    { "value": 8, "name": "Docking Station" },
    { "value": 9, "name": "All in One" },
    { "value": 10, "name": "Blade Server" },
    { "value": 11, "name": "Convertible" },
    { "value": 12, "name": "Detachable" }
  ]
}
For comparison, the Phone and Unknown categories have no sub-categories and appear as minimal entries: 
[
  { "category": 0, "name": "Unknown" },
  { "category": 1, "name": "Phone" }
]

​
Uniqueness constraint

The verify.js duplicate checker specifically targets the category field in gap_appearance.json: 
let appearances = db[list].map(appearance => appearance.category);
numberOfItems = appearances.length;
numberOfUniques = (new Set(appearances)).size;
if (numberOfItems != numberOfUniques) {
  console.error(`Failed to verify '${list}'. Found '${numberOfItems - numberOfUniques}' duplicate items.`);
  return false;
}
Every category integer must appear exactly once in the array. The Check No Duplicates CI workflow enforces this on every push and pull request.
Some categories have no sub-categories — for example, "Phone" (category 1) and "Unknown" (category 0) are defined with only category and name. The subcategory field is entirely optional in the schema and should only be included when the Bluetooth SIG Assigned Numbers document defines sub-types for that category.

Build docs developers (and LLMs) love

Get started for freeTalk to us