Tags are, well, tags. Single word tokens you can add to an Item to help identify it as something. For example, Google Assistant and Alexa use tags to identify Items as Lighting, Temperature, etc.
Metadata allows more structure and dynamism. There is actually a hierarchy (which I admit I don’t fully understand).
- Namespace: top of the hierarchy
- Value: middle of the hierarchy
- List of key value pairs
I don’t think all three are strictly required but I haven’t explored metadata thoroughly yet and, important for you, the REST API for metadata is pretty crappy, only supporting adding and removal but not query (unless you already know the metadata that you want to retrieve in which case you can query for it in the GET /items/{itemname} endpoint).
You can see both in use in HABot Walkthrough (2/n): Semantic Tagging & Item Resolving. Groups are used for location. Tags are used for semantic type. Metadata is used for synonyms.
I’ve moved my Rules over to JSR223 and because you can access, add, and change metadata in Rules (can’t do so from Rules DSL) it becomes a handy place to store stuff like flags, initialization data, and metadata.
For example, I have a bunch of Items that monitor some of the services that are important to my home automation. If they go offline (i.e. OFF) I generate an alert if they remain offline for too long. And once I alert, I want to make sure I don’t alert that it’s offline again but do alert when it comes back online. And I want a nice friendly name for the service in that alert rather than the Item name.
The Rules DSL version uses Design Pattern: Human Readable Names in Messages with a map file for the names and Design Pattern: Associated Items to keep track of whether I’ve sent the alert of not in another Item.
In the JSR223 version of the Rule I replaced both with metadata. I statically define metadata for the name in my .items files and the Rules set the alerted flag in metadata dynamically.
So, the tl;dr is metadata is much more flexible and easier to use in more situations.
I don’t know what it’s “real” purpose is but it does seem to be used mainly by bindings and other add-ons (probably because it’s not easy to access in Rules DSL) to get additional information about an Item that isn’t possible to define with the existing Item’s syntax. JSR223 Rules users also use it to store stuff that would otherwise end up in a global dict or Associated Item.