The Bluetooth Numbers Database is a community project. Nordic Semiconductor does not view it as their property, but as a shared endeavour with the rest of the developer and Bluetooth communities. All listings — Company IDs, Services, Characteristics, Descriptors, and GAP Appearances — are designed to be extended by the community, as long as contributions are Bluetooth SIG-compliant.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.
What Can Be Contributed
✅ Allowed Contributions
- 128-bit proprietary Service UUIDs
- 128-bit proprietary Characteristic UUIDs
- 128-bit proprietary Descriptor UUIDs
- GAP Appearance additions or corrections
- Missing 16-bit UUIDs with
gsssource (if you are the SIG-assigned owner and can supply proper name and identifier info)
❌ Not Allowed
- New 16-bit UUIDs for proprietary services (all 16-bit identifiers are assigned by Bluetooth SIG)
- New Company IDs (registration must go through official Bluetooth SIG channels)
- Duplicate 128-bit UUIDs or identifiers within a GATT Attribute category
- UUIDs you do not own or are not authorized to register
Core Rules
128-bit UUIDs only for new proprietary entries
Only new 128-bit UUIDs can be freely contributed. All 16-bit identifiers are assigned by the Bluetooth SIG itself and cannot be added as new proprietary entries. Exceptions are handled on a case-by-case basis and only under very special circumstances.
No duplicates
No duplicate 128-bit UUIDs or identifiers are allowed within each GATT Attribute category (Services, Characteristics, and Descriptors). If a conflict exists, it will be managed on a case-by-case basis.
Bluetooth SIG compliance
All entries must be Bluetooth SIG-compliant. Entries that do not conform to the specification will be rejected during review.
Missing SIG-assigned 16-bit UUIDs
Many 16-bit UUIDs assigned to Bluetooth SIG members are currently missing from the database because the official listing does not provide enough information (name and identifier). If you own one of these UUIDs, you are welcome to submit a pull request supplying the correct name and identifier. The
source field for these entries must be gss.Identifier Naming Convention
Every entry in the database requires a uniqueidentifier field that follows a reverse-dot UTI (Uniform Type Identifier) format. This convention mirrors Apple’s UTI system and provides a structured, collision-resistant namespace for each attribute.
The pattern is:
| Identifier | Breakdown |
|---|---|
com.example.service.my_custom_service | Domain com.example · type service · use case my_custom_service |
com.company.characteristic.sensor_data | Domain com.company · type characteristic · use case sensor_data |
org.bluetooth.service.heart_rate | SIG domain · type service · use case heart_rate |
com.nordicsemi, com.apple, com.philips-hue) to guarantee global uniqueness across the database.
Contribution Process
Fork the repository
Fork NordicSemiconductor/bluetooth-numbers-database on GitHub and create a feature branch for your changes.
Add your entry to the correct JSON file
Add your new entry as a JSON object to the appropriate file under
v1/:- Service UUIDs →
v1/service_uuids.json - Characteristic UUIDs →
v1/characteristic_uuids.json - Descriptor UUIDs →
v1/descriptor_uuids.json - Company IDs →
v1/company_ids.json(SIG-assigned corrections only) - GAP Appearances →
v1/gap_appearance.json
Run JSON Schema validation
Install dependencies and run the schema validator locally:This validates all data files against their corresponding JSON Schemas using AJV. The command exits with code
0 on success and 1 on failure, printing schema errors to stderr.Run the duplicate checker
Run the duplicate and UUID format checker:This checks for duplicate
code values (companies), duplicate identifier strings (GATT attributes), and validates that all UUID strings match the required format.