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 Bluetooth Numbers Database uses two validation scripts that must both pass before any pull request can be merged. The first validates every data file against its JSON Schema; the second checks for duplicate entries and malformed UUIDs. Running both locally before opening a PR saves time and avoids unnecessary CI failures.

​
Prerequisites

You need Node.js 12 or later and npm installed on your machine. Clone the repository and install dependencies: 
git clone https://github.com/NordicSemiconductor/bluetooth-numbers-database.git
cd bluetooth-numbers-database
npm install

​
JSON Schema Validation (npm test)

The npm test command runs node validate, which loads all database files through the project’s index module and validates each one against its corresponding JSON Schema using the AJV library. 
npm test
What it checks:
Data fileSchema used
v1/company_ids.jsonv1/company_schema.json
v1/service_uuids.jsonv1/attribute_schema.json
v1/characteristic_uuids.jsonv1/attribute_schema.json
v1/descriptor_uuids.jsonv1/attribute_schema.json
v1/gap_appearance.jsonv1/appearance_schema.json
The script iterates over every key exported by the index module (excluding schemas and version), looks up the corresponding schema, and calls ajv.validate(). If all files are valid, the process exits with code 0. If any file fails, AJV prints the schema errors to stderr and the process exits with code 1: 
// validate.js (simplified)
const ajv = new require('ajv')();
const db = require('.');

const allValid = Object.keys(db)
  .filter(key => key !== 'schemas' && key !== 'version')
  .map(list => {
    if (!db.schemas[list]) {
      console.error(`Missing schema for '${list}'.`);
      return false;
    }
    if (!ajv.validate(db.schemas[list], db[list])) {
      console.error(`Failed to validate '${list}':`);
      console.error(ajv.errors);
      return false;
    }
    return true;
  })
  .every(v => v);

process.exit(allValid ? 0 : 1);
A passing run produces no output and exits silently with code 0. A failing run prints messages such as: 
Failed to validate 'serviceUuids':
[ { keyword: 'pattern', dataPath: '[42].uuid', ... } ]

​
Duplicate Check (npm run verify)

The npm run verify command runs node verify, which checks for duplicate keys and validates UUID string format across all data files. 
npm run verify
What it checks for each data type:
Data typeChecked fields
Companies (company_ids.json)No duplicate code integer values
GATT Attributes (services, characteristics, descriptors)No duplicate identifier strings; all uuid values match the format regex
Appearances (gap_appearance.json)No duplicate category integer values
For GATT attributes, the UUID format regex enforced by 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})$/
This accepts either a 4-character 16-bit UUID (for SIG-assigned entries) or a full 36-character 128-bit UUID — both in uppercase only. Any UUID containing lowercase letters, wrong grouping, or incorrect length will be flagged with its array index and file name: 
Found incorrect uuid 12345678-abcd-1234-abcd-123456789abc of item #57 in serviceUuids
Duplicate identifier errors are reported as: 
Failed to verify 'serviceUuids', duplicate identifiers found:
com.example.service.custom_sensor

​
GitHub Actions

Two CI workflows run automatically on every push and every pull request. Both must pass for a PR to be eligible for merging:
WorkflowCommandTrigger
Verify JSON Schemasnpm testEvery push and pull request
Check No Duplicatesnpm run verifyEvery push and pull request
You can see the live status of both workflows on the repository’s main page via the status badges: 
https://github.com/NordicSemiconductor/bluetooth-numbers-database/workflows/Verify%20JSON%20Schemas/badge.svg
https://github.com/NordicSemiconductor/bluetooth-numbers-database/workflows/Check%20No%20Duplicates/badge.svg
Run both npm test and npm run verify before opening your PR — the CI checks run exactly the same commands. Catching errors locally is faster than waiting for a CI run to report them.

​
Troubleshooting

The attribute_schema.json enforces this pattern for the uuid field:
^([A-F0-9]{4}|[A-F0-9]{8}-[A-F0-9]{4}-[A-F0-9]{4}-[A-F0-9]{4}-[A-F0-9]{12})$
Common causes of failure:
  • Lowercase hex letters — convert all a–f to A–F.
  • Wrong grouping — the 128-bit format must be 8-4-4-4-12 characters separated by hyphens.
  • Braces or extra characters — do not include { } around the UUID.
  • 16-bit UUID for a new entry — new proprietary entries must use 128-bit UUIDs.
Use a UUID v4 generator (e.g., uuidgen on macOS/Linux, or an online tool) and then convert the result to uppercase before adding it to the JSON file.
The verify.js script scans each GATT attribute file for duplicate identifier strings. If you see:
Failed to verify 'serviceUuids', duplicate identifiers found:
com.example.service.custom_sensor
Search the relevant file for the identifier before adding your entry:
grep "com.example.service.custom_sensor" v1/service_uuids.json
If a match is found, choose a more specific identifier that is unique to your entry — for example, append a version or a more descriptive use-case segment.
The project requires Node.js v12 or later. Check your current version:
node --version
If the output shows a version below v12, upgrade Node.js using your system package manager, nvm, or by downloading an installer from nodejs.org.After upgrading, delete node_modules and reinstall:
rm -rf node_modules
npm install
If you see:
Missing schema for 'myNewList'.
This means a key exported by the index module does not have a corresponding entry in db.schemas. This should not happen with normal contributions to the existing JSON files. If you are adding a completely new data file and index export, ensure the corresponding schema file exists and is registered in the index module.

Build docs developers (and LLMs) love

Get started for freeTalk to us