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.
Adding a new UUID to the Bluetooth Numbers Database means editing a JSON file under the v1/ directory. Each type of GATT attribute has its own file, and every entry must include all four required fields: name, identifier, uuid, and source. This guide walks through exactly what to edit and how to format each field correctly.
Adding a Service UUID
Open the service UUIDs file
Open v1/service_uuids.json in your editor. The file contains a single JSON array of service objects.
Add a new object to the array
Append your entry to the array. All four fields are required: name, identifier, uuid, and source.
Use the correct format
A valid new service entry looks like this:{
"name": "My Custom Sensor Service",
"identifier": "com.example.service.custom_sensor",
"uuid": "12345678-1234-1234-1234-123456789ABC",
"source": "example"
}
Check UUID length and case
The UUID must be a 128-bit UUID in XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX format. All hex characters must be uppercase (A–F, 0–9). Do not use 16-bit (4-character) UUIDs for new proprietary services — those are reserved for Bluetooth SIG-assigned entries.
Adding a Characteristic UUID
Open the characteristic UUIDs file
Open v1/characteristic_uuids.json. The structure is identical to the services file — a single JSON array.
Add your entry to the array
Append a new object with all four required fields. Change service to characteristic in the identifier type segment.
Example entry
{
"name": "Sensor Data",
"identifier": "com.example.characteristic.sensor_data",
"uuid": "12345678-1234-1234-1234-123456789ABD",
"source": "example"
}
Ensure the identifier is unique
The identifier field must be unique across the entire characteristic_uuids.json file. Run npm run verify after adding your entry to confirm there are no collisions.
Adding a Descriptor UUID
Open the descriptor UUIDs file
Open v1/descriptor_uuids.json. Same array structure as the other GATT attribute files.
Add your entry
Append a new object using descriptor as the attribute type segment in the identifier.
Example entry
{
"name": "Custom Measurement Config",
"identifier": "com.example.descriptor.measurement_config",
"uuid": "12345678-1234-1234-1234-123456789ABE",
"source": "example"
}
Run validation
Run npm test and npm run verify to confirm the entry passes JSON Schema validation and has no duplicate identifiers.
attribute_schema.json) and the duplicate checker (verify.js):
| Rule | Detail |
|---|
| Length | 36 characters including four hyphens |
| Pattern | XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX |
| Character set | Uppercase hex only: A–F and 0–9 |
| 16-bit exception | A 4-character hex string (e.g., 1800) is only valid for correcting existing SIG-defined entries with gss source |
verify.js is:
/^([A-F0-9]{4}|[A-F0-9]{8}-[A-F0-9]{4}-[A-F0-9]{4}-[A-F0-9]{4}-[A-F0-9]{12})$/
npm run verify to fail with an error identifying the offending entry by index.
Identifier Naming Convention
The identifier field uses a reverse-domain UTI format to create a globally unique, human-readable name for the attribute. The structure is:
(reverse domain).(attribute type).(generic use case).(specific use case)
Use your company’s reverse domain as the prefix to avoid collisions with other contributors. For example, Nordic Semiconductor uses com.nordicsemi.service.dfu for their DFU (Device Firmware Update) service. Similarly, Apple uses com.apple.service.notification_center for the Apple Notification Center Service.
What NOT to Do
- Do not add 16-bit UUIDs for new proprietary services. All 16-bit UUIDs in the database are assigned by Bluetooth SIG. New proprietary entries must use 128-bit UUIDs only.
- Do not use lowercase hex in UUIDs. The schema regex only accepts uppercase
A–F. A UUID like 12345678-abcd-1234-abcd-123456789abc will fail validation.
- Do not duplicate identifiers. Before adding an entry, search the relevant file for your intended identifier string. The
verify.js script will catch duplicates, but checking ahead of time saves CI time.
- Do not register UUIDs you do not own. Only submit entries for UUIDs your organization created and controls.
Real-World Source Examples
Here are several real entries from v1/service_uuids.json to show what correctly formatted entries look like in practice:
[
{ "name": "Generic Access", "identifier": "org.bluetooth.service.generic_access", "uuid": "1800", "source": "gss" },
{ "name": "Battery Service", "identifier": "org.bluetooth.service.battery_service", "uuid": "180F", "source": "gss" },
{ "name": "Philips Hue Light Control Service", "identifier": "com.philips-hue.service.light_control", "uuid": "932C32BD-0000-47A2-835A-A8D455B859DD", "source": "philips-hue" },
{ "name": "Apple Notification Center Service", "identifier": "com.apple.service.notification_center", "uuid": "7905F431-B5CE-4E99-A40F-4B1E122D00D0", "source": "apple" }
]
1800, 180F with gss source) and the proprietary 128-bit entries (Philips Hue and Apple with their own source strings). New community contributions should always follow the 128-bit pattern with an appropriate source value matching your organization or project name.
