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.

Every Bluetooth application — whether a mobile app, a browser-based scanner, or a firmware tool — eventually needs to display a UUID or a Company ID to a user in a readable form. Without a shared resource, every team ends up writing the same lookup code, copy-pasting tables from Bluetooth SIG PDFs, and then scrambling to keep those tables in sync as new identifiers are registered. The Bluetooth Numbers Database puts a stop to that cycle. It is a single, versioned, open-source repository of Bluetooth Assigned Numbers — Company IDs, GATT Service UUIDs, Characteristic UUIDs, Descriptor UUIDs, and GAP Appearances — maintained by Nordic Semiconductor ASA and the broader Bluetooth developer community so that no one ever has to hand-roll these tables again.

​
What’s in the database

The database ships five JSON collections under the v1/ folder, covering the most commonly needed Bluetooth Assigned Numbers:
CollectionFileEntriesContents
companiescompany_ids.json~3,998Every company registered with Bluetooth SIG, identified by integer code and name
servicesservice_uuids.json~126GATT Service UUIDs — both SIG-defined and proprietary
characteristicscharacteristic_uuids.json~682GATT Characteristic UUIDs with reverse-dot identifiers
descriptorsdescriptor_uuids.json18GATT Descriptor UUIDs (e.g. Client Characteristic Configuration)
appearancesgap_appearance.json52 categoriesGAP Appearance categories and sub-categories for device type display
Every UUID entry carries four fields: uuid, name, identifier (reverse-dot notation), and source (e.g. gss for GATT Specification Supplement, nordic for Nordic-defined). Company entries carry two fields: code (integer) and name (string).

​
Background

During the development of various Bluetooth tools inside Nordic Semiconductor, many of the same assigned numbers were ingested independently into different products. Teams were downloading the same Bluetooth SIG PDFs, transforming them into usable data structures, and then maintaining those structures in isolation — with no guarantee that any two tools agreed on the same name for the same UUID. The solution was to apply a Single Source of Truth principle: one canonical repository that all tools pull from, open to community contributions, and protected by automated schema validation and duplicate-detection on every CI run. The result is the Bluetooth Numbers Database, first published by Nordic Semiconductor and since grown through contributions from the global Bluetooth developer community.

​
Who is this for?

Mobile App Developers

Resolve Company IDs and Service UUIDs to human-readable names so users see “Heart Rate Monitor” instead of raw hex values in your iOS or Android Bluetooth app.

Web & Desktop Tool Builders

Fetch the JSON collections directly from GitHub or import the npm package to power browser-based BLE scanners, nRF tools, and debugging dashboards.

Firmware & IoT Developers

Look up or cross-reference UUIDs at build time to ensure your custom 128-bit UUIDs do not collide with existing registrations in the community database.

​
How it works

The database is published as a versioned npm package named bluetooth-numbers-database, currently at v1.0.x. All data lives in the v1/ directory as plain JSON arrays. The Node.js entry point (index.js) exports each collection directly: 
const {
  version,
  companies,
  services,
  characteristics,
  descriptors,
  appearances,
  schemas,
} = require('bluetooth-numbers-database');
In addition to the five data arrays, the package also exports version (the package version string, e.g. "1.0.4") and schemas (an object containing the JSON Schema definitions for each collection, keyed by collection name). Data quality is enforced on every commit through two automated GitHub Actions workflows:
  • Verify JSON Schemas — every entry in every collection is validated against its JSON Schema definition (company_schema.json, attribute_schema.json, appearance_schema.json).
  • Check No Duplicates — a separate workflow confirms that no uuid or code value appears more than once in any collection.
Because the JSON files are plain arrays without any runtime dependency, they can also be consumed directly in any language or platform by fetching the raw files from GitHub.
All 16-bit UUIDs are assigned by Bluetooth SIG. Only new 128-bit UUIDs can be contributed by the community.

Build docs developers (and LLMs) love

Get started for freeTalk to us