BMLT Semantic OpenAPI

OpenAPI 3.1 description of the BMLT (Basic Meeting List Toolbox) Semantic Interface for the JSON data format.

Rendered docs: https://bmlt-enabled.github.io/bmlt-semantic-openapi/

What's in here

• src/Swagger/ — PHP 8 attribute classes that are the source of truth for the spec. Uses zircote/swagger-php — same pattern as bmlt-server's admin API documentation.
• bin/generate.php — calls \OpenApi\Generator::scan() directly so we control error_reporting (silences zircote/swagger-php's PHP 8.4/8.5 deprecation noise).
• bmlt-semantic-openapi.json — the OpenAPI 3.1 spec, generated from the PHP classes. Checked in so consumers can fetch it without running PHP.
• index.html — a Swagger UI loader that renders the spec. This is what GitHub Pages serves.
• Makefile — entry point for all the build/lint/serve tasks (see below).
• composer.json — declares the zircote/swagger-php dependency.
• redocly.yaml — lint configuration for @redocly/cli.

Make targets

make help        # list all targets
make composer    # install PHP dependencies (PROD=1 for --no-dev)
make generate    # scan src/ and write bmlt-semantic-openapi.json
make lint        # validate the spec with @redocly/cli
make check       # generate + lint
make serve       # serve Swagger UI locally on PORT (default 8765)
make clean       # remove vendor/ and composer.lock

After editing any PHP attribute, run make generate (or make check) and commit the resulting JSON.

Scope

• Covers the JSON data format only (not JSONP, TSML, or CSV).
• All 8 JSON-supporting switcher operations: GetSearchResults, GetFormats, GetServiceBodies, GetChanges, GetFieldKeys, GetFieldValues, GetServerInfo, GetCoverageArea.
• Includes aggregator-mode parameters (root_server_ids) since the default servers: entry points at https://aggregator.bmltenabled.org/main_server.
• GetNAWSDump is intentionally omitted (CSV-only).

Things that don't map cleanly onto OpenAPI

The BMLT semantic interface has a few shapes that OpenAPI can't express precisely. These are documented per-operation in the spec, but they're worth knowing up front:

1. Single endpoint, switcher-dispatched. Every operation hits /client_interface/json/ with a switcher= query parameter. OpenAPI keys operations by URL + HTTP method, so this spec uses one path entry per switcher with the query string baked into the path key. Swagger UI, Redoc, and openapi-generator handle this cleanly; strict linters flag it (see redocly.yaml).
2. PHP [] array params. Repeatable array parameters use trailing [] in their names (e.g. weekdays[]=2&weekdays[]=3). The spec exposes both forms — the scalar CSV (weekdays) and the bracketed array (weekdays[]).
3. Sign-as-operator. Filters such as formats, services, weekdays, venue_types, meeting_ids, root_server_ids, and format_ids use positive values to include and negative values to exclude. JSON Schema can't enforce that distinction; it's documented per parameter.
4. Switcher × format compatibility matrix. Some switchers are valid only for certain formats (TSML only for GetSearchResults, CSV only for GetNAWSDump). Not expressible in the schema.
5. Aggregator-mode constraints. In aggregator mode, GetSearchResults requires at least one filter parameter or the response is an empty array. OpenAPI can't express "one-of-N required".
6. Empty-array errors. Many endpoints return [] for invalid input rather than a 4xx response body.

Source

Generated from the upstream Markdown reference at bmlt-enabled/bmlt-mcp-server.

Local preview

python3 -m http.server 8000
# then open http://localhost:8000/

License

MIT