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 data file in the v1/ directory of the Bluetooth Numbers Database is validated against a corresponding JSON Schema on every push and pull request via GitHub Actions CI. This ensures that all contributions conform to the expected structure, that no duplicate entries slip through, and that UUID strings match the exact uppercase hexadecimal format required by the Bluetooth Core Specification.

​
Three schemas

The v1/ directory contains three JSON Schemas, each corresponding to a specific data file type:
  1. attribute_schema.json — Validates the arrays in service_uuids.json, characteristic_uuids.json, and descriptor_uuids.json. Every GATT attribute entry must have a uuid, identifier, name, and source field, with the UUID matching a strict uppercase hex pattern.
  2. company_schema.json — Validates the array in company_ids.json. Every company entry must have an integer code and a string name, mirroring the official Bluetooth SIG Company Identifiers list.
  3. appearance_schema.json — Validates the array in gap_appearance.json. Every appearance entry must have an integer category and a string name, with an optional subcategory array of sub-category objects.

​
CI validation

Two GitHub Actions workflows run automatically on every push and pull request to ensure data integrity.

​
Verify JSON Schemas (verify_json.yml)

This workflow runs npm test, which executes node validate. The validate.js script uses AJV (Another JSON Validator) to load every data list from the package index and validate it against its registered schema. If any entry in any file fails schema validation, the workflow exits with a non-zero code and the CI check fails. 
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);

​
Check No Duplicates (verify_no_duplicates.yml)

This workflow runs npm run verify, which executes node verify. The verify.js script performs additional semantic checks that go beyond what JSON Schema can express:
  • Company entries — checks that all code values are unique.
  • Appearance entries — checks that all category values are unique.
  • GATT attribute entries — checks that all identifier values are unique and that every uuid string matches the strict uppercase regex pattern.
const uuidtest = db[list].map(({ uuid }, i) => {
  if (! /^([A-F0-9]{4}|[A-F0-9]{8}-[A-F0-9]{4}-[A-F0-9]{4}-[A-F0-9]{4}-[A-F0-9]{12})$/.test(uuid)) {
    console.error(`Found incorrect uuid ${uuid} of item #${i} in ${list}`);
    return false;
  }
  return true;
}).every(v => v);

​
Schema reference pages

Attribute Schema

JSON Schema for GATT Service, Characteristic, and Descriptor UUID entries.

Company Schema

JSON Schema for Bluetooth SIG Company Identifier entries.

Appearance Schema

JSON Schema for GAP Appearance category and sub-category entries.

​
Running validation locally

Clone the repository and install dependencies, then run either validation command: 
# Install dependencies
npm install

# Run JSON Schema validation (npm test → node validate)
npm test

# Run duplicate and UUID format checks (npm run verify → node verify)
npm run verify
Both commands exit with code 0 on success and 1 on failure, making them suitable for use in any CI pipeline.
The validate.js script uses AJV (Another JSON Validator) v6 to perform structural schema validation. The verify.js script additionally checks UUID format with the following regex applied to every GATT attribute UUID:
^([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 regex is evaluated at runtime by verify.js and is separate from the identical pattern already declared inside attribute_schema.json.

Build docs developers (and LLMs) love

Get started for freeTalk to us