bbfmodels

Typed models and schema tooling for Broadband Forum data models (TR-181, TR-098, TR-104 and the rest), generated from the XML the Forum publishes.

The Forum defines what a broadband gateway exposes to its management system as XML in the TR-106 schema: thousands of objects and parameters, their types, ranges, enumerations, writability and multi-instance tables. Everyone who builds against those models, an ACS, a USP controller, a device simulator, an integration script, re-derives the same facts from the same XML and hand-types the same parameter paths as strings. bbfmodels does it once:

• A parser that reads the published XML into a normalised intermediate representation, published as JSON with its own schema.
• A Python runtime that works from that representation: resolve a path, validate a value against the model's constraints, convert between the flat path and value lists that CWMP and USP carry on the wire and a typed tree.
• Generated typed bindings: pydantic models for Python, shipped for TR-181 and TR-098 and the service models (TR-104 voice, TR-135 set-top box, TR-140 storage, TR-196 femtocell, TR-517 Matter), and generated on demand for any other document, a vendor's included.
• Typed paths for code that only needs correct path strings: str(Device.WiFi.SSID[1].SSID) with autocomplete over the whole model and the parameter's definition one attribute away. JSON Schema and TypeScript follow from the same representation, Go when there is a consumer.

Names stay as the Forum wrote them. Device.WiFi.SSID.{i}.SSID is a table of SSID entries indexed by instance number, and the attribute is SSID, not ssid.

Install

pip install bbfmodels

Python 3.11 or later. The one runtime dependency is pydantic.

Status

Early. The parser, the intermediate representation, the runtime and the generated Python models are in place. Commands and events in the generated models, JSON Schema and TypeScript come next. Before 1.0 a minor release may change the IR and the runtime API.

from bbfmodels.tr181_cwmp import Device

device = Device.from_flat(values_from_the_device)
radio = device.WiFi.Radio[1]
radio.Channel  # 36, an int
radio.Enable  # True
device.problems()  # every value outside the model's constraints
device.flatten()  # back to path and text pairs

The design decisions behind the code are in context/decisions/, indexed in context/README.md. Read them before changing the parser or the IR.

Development

Prerequisites: git and uv. The pinned Python is installed by uv.

scripts/bootstrap.sh
make test
make lint

make help lists the rest. Documentation is built from docs/ with make docs and published at https://docs.bbfmodels.ispx.co/.

Licence

Apache-2.0, copyright ISPX LIMITED. The Broadband Forum publishes its data models under the BSD 3-clause licence; output derived from them carries the Forum's notice.