openHAB FormatKit is an independently maintained Visual Studio Code extension for formatting, syntax highlighting, snippets, code suggestions, and a local outline tree for openHAB configuration files such as .items, .rules, .sitemap, .script, .things, and .persist files.
This is an independently maintained project. It is not affiliated with, endorsed by, or published by the original openHAB Alignment Tool author or project. The codebase began as a maintained fork of the inactive open-source project by Maximilian Beckenbauer, and that origin is credited here for transparency. All marketplace branding, icon artwork, package identity, README wording, and command/settings namespace have been changed for this independent release.
Support & Credits
If this maintained fork helps you, please consider supporting Manuel Miethe, author and maintainer of this add-in:
If you also want to thank the original developer of the openHAB Alignment Tool:
What changed for the independent release
- Extension display name changed to openHAB FormatKit.
- Marketplace package ID changed to
openhab-formatkit under the existing publisher account.
- Extension icon and README wordmark replaced with newly created artwork under
images/formatkit-*.
- Commands and settings moved to the
openhab-formatkit.* namespace.
- README and extension messaging rewritten to make the independent maintenance status clear.
- Attribution to the original open-source project is kept without implying affiliation or endorsement.
Features
The extension uses the standard Visual Studio Code formatter API. You can format files with Format Document, Format Selection, or VS Code's format-on-save setting.
It also contributes openHAB DSL syntax highlighting, snippets, code suggestions, semantic diagnostics, and a local outline tree for common textual configuration files.
Supported formatting styles for openHAB item files:
- Column style
- Channel-column style
- Multiline style
Supported openHAB file types:
.items — column formatter, syntax highlighting, snippets, suggestions, local outline.sitemap — beta formatter, syntax highlighting, snippets, suggestions, local outline.things — structured indentation formatter with Type / State / implicit state / Trigger channel alignment, syntax highlighting, suggestions, local outline.rules — structured indentation formatter, syntax highlighting, snippets, suggestions, local outline.script — structured indentation formatter, syntax highlighting, suggestions, local outline.persist — syntax highlighting, suggestions, local outline.rrd — native read/write RRD inspector table for rrd4j files, opened directly in VS Code without Javatransform/*.map, transform/*.scale — local transformation suggestionsservices/*.cfg — local service/add-on/runtime suggestions
Column style
Column-channel style
Multiline style
Sitemap formatting
Maintained fixes
This maintained version includes fixes for openHAB item channel binding configurations where curly braces inside quoted strings could break formatting. Example affected cases are channel parameters that contain JSON-like values or text with {...} inside quotes.
It also corrects space-based column padding when editor.insertSpaces is enabled, so aligned columns stay consistent with the configured tab size.
Group aggregation functions with regex parameters are preserved correctly, for example:
Group:Number:COUNT(.*) gL_gO_gGd_gMain_Appliances_Count <appliances> (gL_gO_gGd_gMain_Appliance)
The formatter keeps Group:Number:COUNT(.*) intact instead of misreading COUNT as a Number subtype.
RRD Inspector
FormatKit includes a native .rrd inspector for openHAB/rrd4j persistence files. Clicking a *.rrd file opens a table view instead of the binary file.
Current capabilities:
- Runs natively inside the VS Code extension; no local Java runtime is required.
- Reads rrd4j
version 0.1 and version 0.2 file layouts.
- Shows datasources, archives, timestamps, raw ring-buffer indexes, and values.
- Lets you edit existing archive values directly in the table.
- Lets you map a timestamp to the selected archive row and add/update a value there.
- Writes are protected by an automatic
.formatkit-backup-YYYYMMDDHHMMSSmmm file before saving.
- Saving is blocked if the
.rrd changed on disk after the inspector loaded it, so openHAB updates are not silently overwritten.
Important: the current write support edits stored archive values directly. It does not yet emulate the full rrd4j Sample.update() consolidation pipeline for creating new live samples.
Diagnostics
FormatKit marks common semantic-model and group-structure issues in .items files with VS Code diagnostics:
- duplicate tags on the same Item
- more than one semantic Location tag on one Item
- more than one semantic Equipment tag on one Item
- more than one semantic Point tag on one Item
- more than one semantic Property tag on one Item
- mixed primary semantic roles on one Item, e.g. Location + Equipment or Equipment + Point
- Property tags without a Point tag, e.g.
Temperature without Measurement
- direct Group cycles, e.g.
Group gA ... (gA)
- indirect Group cycles, e.g.
gA -> gB -> gC -> gA
Diagnostics are intentionally conservative and local-only. They do not require an openHAB server and do not try to validate binding-specific runtime data.
Code suggestions
FormatKit contributes local VS Code completion suggestions for openHAB textual configuration files. These suggestions are static and file-based, so they do not require an openHAB REST connection.
Included suggestions cover:
.items — Item types, common Number:<dimension> examples, Group aggregation functions, semantic model tags/snippets, Item and channel-link snippets.things — Bridge, Thing, Channels, Type, State, implicit state, and Trigger channel snippets.rules / .script — rule skeletons, Item/Member/Time/System/Thing/Channel trigger snippets, common Actions such as sendCommand, postUpdate, and createTimer.sitemap — Sitemap element keywords and common widget snippets.persist — Strategies, Filters, Items, Aliases, predefined strategies, and section snippetstransform/*.map, transform/*.scale — MAP entries, SCALE ranges, common openHAB states, and transformation usage helpersservices/*.cfg — addons.cfg package/binding/UI/persistence/transformation snippets plus runtime.cfg audio/voice defaults- Item/Sitemap label helpers — common transformation expressions such as
MAP(...), SCALE(...), JS(...), JSONPATH(...), REGEX(...)
- Item/Sitemap icon helpers — common openHAB classic icon names
- Rules multimedia helpers — audio/voice actions such as
playSound, playStream, say, interpret, and volume helpers
- Semantic model helpers — Location, Equipment, Point, and Property tags plus snippets for Location Groups, Equipment Groups, Point Items, light models, temperature measurements, and battery badge points
- Rules semantic helpers —
isLocation, isEquipment, isPoint, getLocation, getEquipment, getPointType, getPropertyType, and getSemanticType
Local outline tree
FormatKit adds an openHAB FormatKit activity-bar view with a local outline for the active openHAB file.
The outline is file-based and does not require an openHAB REST connection:
.items — lists Items, including complex Group types such as Group:Number:COUNT(.*).rules / .script — lists rules, imports, and global val / var declarations.things — lists Bridges, Things, and Type / State / implicit state / Trigger Channels.sitemap — lists sitemap elements such as Frames, Groups, Switches, Buttongrids, Buttons, Inputs, Text entries, etc..persist — lists Strategies, Filters, Items, and Aliases
Clicking an outline entry jumps to its source location.
FormatKit uses a conservative structured formatter for these files:
- keeps existing line structure intact
- normalizes indentation around
{}, [], and openHAB DSL rule / when / then / end blocks
- ignores braces inside quoted strings and line comments
- avoids semantic rewrites or aggressive line splitting
For .things files, consecutive Type ... : ..., State ... : ..., implicit state channels such as String : ..., and Trigger ... : ... channel definitions are also aligned and inline comments are normalized.
This is intentionally safer than a full parser-based formatter.
Extension settings
New Line After Item
Insert a new line after each item unless a single empty line already exists.
"openhab-formatkit.newLineAfterItem": true
Preserve Whitespace
Preserve leading whitespace in front of items while reformatting.
"openhab-formatkit.preserveWhitespace": true
Minimum Indent Amount
Control the minimum separation between formatted item columns.
"openhab-formatkit.minimumIndentAmount": 2
Choose the formatter style:
ColumnChannelColumnMultiline
"openhab-formatkit.formatStyle": "Column"
New Group Tag
// #OHNG#
Starts a new formatting group for an item section. Tracking of the longest item parts is reset for the new group.
// #OHFS#%FORMATTING_STYLE%#OHFS#
Changes formatting for the following item definitions. Replace %FORMATTING_STYLE% with Column, ChannelColumn, or Multiline.
Attribution
This project originated as a maintained fork of the inactive open-source project maxbec/openHAB-Alignment-Tool by Maximilian Beckenbauer. The current extension is independently maintained and uses distinct marketplace identity, branding, and documentation.
Original formatter project: https://github.com/maxbec/openHAB-Alignment-Tool
Syntax grammar and snippets are adapted from the official openHAB Visual Studio Code extension under EPL-2.0:
https://github.com/openhab/openhab-vscode
See NOTICE.md for details.
Support
If this maintained project helps you, stars, issues, and pull requests are welcome.
Enjoy!
