Item metadata REST endpoints: don't allow adding or removing semantics by mherwege · Pull Request #5390 · openhab/openhab-core

mherwege · 2026-02-24T17:24:01Z

The PUT and DELETE /item/{itemname}/metadata/{namespace} endpoints allow adding/updating and removing metadata.

If you use this endpoint to add something in the semantics namespace when the item did not already have semantics defined, it will be stored in the managed provider.
A user identified issues when trying to use an LLM to update the item semantics (#5363 (comment)). The LLM added semantics to the metadata managed provider. Semantics metadata is auto-generated from item tags in the SemanticsMetadataProvider, and this is not a managed provider, so the REST endpoint should not write in it. The only way to remove it was to edit the JSONDB.

To avoid such issues, the REST endpoint should not allow changing anything in the semantics namespace.

An easy fix would have been to just check for the namespace in the REST API. The disadvantage would be that it then assumes the SemanticsMetadataProvider is part of the installation. If someone would ever remove or replace the SemanticsMetadataProvider, the semantics namespace would still not be available.
I therefore opted for a more general fix. I have introduce the concept of reserved namespace(s) for a provider. If there is a reserved namespace and the provider is not a managed provider, it will refuse add, update or delete operations.

This also fixes the DELETE /item/{itemname}/metadata/{namespace}. The intention in the code is to allow a null namespace to be passed. JAX-RS does not allow null path parameters and this would never have worked. I created an extra endpoint which ommits the namespace path parameter to delete all managed metadata for an item.

Signed-off-by: Mark Herwege <mark.herwege@telenet.be>

florian-h05

LGTM, thanks!

(No core maintainer though, so I cannot merge this.)

Copilot

Pull request overview

Adds a “reserved metadata namespace” mechanism to prevent REST writes to computed/non-managed metadata (notably the semantics namespace), avoiding persistence into the managed metadata store and the resulting inconsistencies.

Changes:

Introduce MetadataProvider#getReservedNamespaces() to declare reserved metadata namespaces.
Enforce reserved-namespace write restrictions in MetadataRegistryImpl (block add/update/remove when the reserving provider is not managed).
Update item metadata REST endpoints to return 405 Method Not Allowed when metadata is not editable, and adjust integration test expectations accordingly.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
itests/.../ItemResourceOSGiTest.java	Updates expected HTTP status for removing metadata provided by an unmanaged provider.
bundles/org.openhab.core/.../MetadataProvider.java	Adds API for providers to declare reserved namespaces.
bundles/org.openhab.core/.../MetadataRegistryImpl.java	Implements reserved-namespace tracking and blocks write operations for reserved namespaces owned by non-managed providers.
bundles/org.openhab.core.semantics/.../SemanticsMetadataProvider.java	Declares `semantics` as a reserved namespace.
bundles/org.openhab.core.io.rest.core/.../ItemResource.java	Maps registry write failures to `405 Method Not Allowed` for metadata endpoints (PUT/DELETE).

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-02-28T08:12:00Z

+        try {
+            MetadataKey key = new MetadataKey(namespace, itemName);
+            Metadata md = new Metadata(key, value, metadata.config);
+            if (metadataRegistry.get(key) == null) {
+                metadataRegistry.add(md);
+                return Response.status(Status.CREATED).type(MediaType.TEXT_PLAIN).build();
+            } else {
+                if (metadataRegistry.update(md) == null) {
+                    return Response.status(Status.METHOD_NOT_ALLOWED).build();
+                }
+                return Response.ok(null, MediaType.TEXT_PLAIN).build();
+            }
+        } catch (IllegalStateException e) {
+            return Response.status(Status.METHOD_NOT_ALLOWED.getStatusCode(), e.getMessage()).build();
        }


Catching all IllegalStateException here will also convert unrelated registry failures (e.g., ManagedProvider is not available thrown by AbstractRegistry.add/update/remove) into a 405, which can mask real server/configuration problems. It would be safer to throw/catch a dedicated exception type for “reserved namespace not editable” (e.g., UnsupportedOperationException or a custom runtime exception) and let other IllegalStateExceptions propagate/return a 500-style error.

I am using UnsupportedOperationException now. But looking at the previous code, while the API documentation said it was returning 405 if the metadata was not editable, it did not do that. The IllegalStateException was also never catched and not returned by the REST API. Not having a managed provider should be an acceptable state. It just means nothing can be edited through the REST API or UI. But it should be handled in my opinion.

Signed-off-by: Mark Herwege <mark.herwege@telenet.be>

Copilot

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Signed-off-by: Mark Herwege <mark.herwege@telenet.be>

Copilot

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 3 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-03T15:33:20Z

@@ -795,13 +805,22 @@ public Response removeMetadata(@PathParam("itemName") @Parameter(description = "
        if (namespace == null) {
            metadataRegistry.removeItemMetadata(itemName);
        } else {


This method is bound to @Path(.../metadata/{namespace}), so @PathParam("namespace") will never be null for real HTTP requests and the if (namespace == null) branch is effectively dead code. Consider removing @Nullable and the null-branch (or adding a separate endpoint without {namespace} if you intend to support deleting all metadata).

This is a bug that was already there, confirmed.

Signed-off-by: Mark Herwege <mark.herwege@telenet.be>

Copilot

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Signed-off-by: Mark Herwege <mark.herwege@telenet.be>

Copilot

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 3 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-03T16:58:03Z

+                metadataRegistry.add(md);
+                return Response.status(Status.CREATED).type(MediaType.TEXT_PLAIN).build();
+            } else {
+                if (metadataRegistry.update(md) == null) {


metadataRegistry.get(key) and metadataRegistry.update(md) are not atomic. If the metadata existed at the time of get but is removed concurrently before update, update can return null and this code will return 405 (“not editable”), which is misleading (it’s actually gone). A safer approach is to re-check metadataRegistry.get(key) when update returns null and return 404 if it’s now absent, reserving 405 for the “exists but not managed/editable” case.

Suggested change

if (metadataRegistry.update(md) == null) {

Metadata previous = metadataRegistry.update(md);

if (previous == null) {

// Metadata may have been removed concurrently; re-check existence

if (metadataRegistry.get(key) == null) {

return Response.status(Status.NOT_FOUND).build();

}

I don't think this is a good idea. You try to add. Responding you are not adding because the metadata does not exist is not what you would expect. You could try to add again, but you get in a potential loop. I prefer the current not allowed.

Signed-off-by: Mark Herwege <mark.herwege@telenet.be>

Copilot

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 3 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Signed-off-by: Mark Herwege <mark.herwege@telenet.be>

Copilot

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-04T09:11:52Z

+    public Metadata add(Metadata element) {
+        String namespace = element.getUID().getNamespace();
+        Set<MetadataProvider> providers = reservedNamespaces.get(namespace);
+        MetadataProvider managedProvider = (MetadataProvider) getManagedProvider().orElse(null);
+        if (providers == null || providers.isEmpty() || providers.stream().anyMatch(p -> p.equals(managedProvider))) {
+            return super.add(element);
+        }
+        throw new UnsupportedOperationException("Cannot add metadata to '" + namespace + "' namespace");
+    }


MetadataRegistryImpl.add/update/remove now throw UnsupportedOperationException for reserved namespaces. There are existing callers that invoke metadataRegistry.remove(...)/update(...) without handling this (e.g., the REST /items/metadata/purge implementation and the metadata console commands), which will now fail with an uncaught runtime exception whenever they touch reserved namespaces like semantics. Consider avoiding exceptions here (e.g., return null for update/remove and block add via a separate check) or update all internal callers to catch UnsupportedOperationException and handle it gracefully.

I was throwing IllegalStateException before, which was also not handled.
I handle it now, and also updated the console commands to handle this properly.

Signed-off-by: Mark Herwege <mark.herwege@telenet.be>

Copilot

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Signed-off-by: Mark Herwege <mark.herwege@telenet.be>

Copilot

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated no new comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

mherwege · 2026-03-04T11:37:24Z

copilot is fully happy now.

holgerfriedrich

LGTM, thanks!

reserve semantics namespace

da78b82

Signed-off-by: Mark Herwege <mark.herwege@telenet.be>

mherwege requested a review from a team as a code owner February 24, 2026 17:24

mherwege added 3 commits February 24, 2026 20:48

spotless

abab090

Signed-off-by: Mark Herwege <mark.herwege@telenet.be>

fix test

2648c75

Signed-off-by: Mark Herwege <mark.herwege@telenet.be>

fix javadoc

8b392f7

Signed-off-by: Mark Herwege <mark.herwege@telenet.be>

mherwege marked this pull request as draft February 24, 2026 22:12

fix javadoc

fcb7522

Signed-off-by: Mark Herwege <mark.herwege@telenet.be>

mherwege marked this pull request as ready for review February 25, 2026 05:42

florian-h05 approved these changes Feb 26, 2026

View reviewed changes

wborn requested a review from Copilot February 28, 2026 08:06

Copilot started reviewing on behalf of wborn February 28, 2026 08:07 View session

Copilot AI reviewed Feb 28, 2026

View reviewed changes

mherwege marked this pull request as draft March 3, 2026 11:43

mherwege added 3 commits March 3, 2026 12:43

copilot review adjustments

0178239

Signed-off-by: Mark Herwege <mark.herwege@telenet.be>

fix test

355e1d3

Signed-off-by: Mark Herwege <mark.herwege@telenet.be>

fix test

6f1ea7c

Signed-off-by: Mark Herwege <mark.herwege@telenet.be>

mherwege requested a review from Copilot March 3, 2026 15:06

Copilot started reviewing on behalf of mherwege March 3, 2026 15:06 View session

Copilot AI reviewed Mar 3, 2026

View reviewed changes

Comment thread ...re.tests/src/main/java/org/openhab/core/io/rest/core/internal/item/ItemResourceOSGiTest.java

Comment thread ...les/org.openhab.core/src/main/java/org/openhab/core/internal/items/MetadataRegistryImpl.java

copilot feedback

97da6e1

Signed-off-by: Mark Herwege <mark.herwege@telenet.be>

mherwege requested a review from Copilot March 3, 2026 15:26

Copilot started reviewing on behalf of mherwege March 3, 2026 15:27 View session

Copilot AI reviewed Mar 3, 2026

View reviewed changes

mherwege added 2 commits March 3, 2026 17:11

fix deleting all item metadata

1301f56

Signed-off-by: Mark Herwege <mark.herwege@telenet.be>

add tests remove all metadata

5e3a4a0

Signed-off-by: Mark Herwege <mark.herwege@telenet.be>

mherwege requested a review from Copilot March 3, 2026 16:21

Copilot started reviewing on behalf of mherwege March 3, 2026 16:22 View session

Copilot AI reviewed Mar 3, 2026

View reviewed changes

Comment thread ...ore.io.rest.core/src/main/java/org/openhab/core/io/rest/core/internal/item/ItemResource.java Outdated

fix update for unmanaged and unreserved

5b25110

Signed-off-by: Mark Herwege <mark.herwege@telenet.be>

eliminate compiler warnings

6c4d37d

Signed-off-by: Mark Herwege <mark.herwege@telenet.be>

mherwege requested a review from Copilot March 3, 2026 16:50

Copilot started reviewing on behalf of mherwege March 3, 2026 16:51 View session

Copilot AI reviewed Mar 3, 2026

View reviewed changes

mherwege added 2 commits March 4, 2026 09:36

handle multiple reservations for same namespace

9ba5b7f

Signed-off-by: Mark Herwege <mark.herwege@telenet.be>

Change log level to debug

f962ed2

Signed-off-by: Mark Herwege <mark.herwege@telenet.be>

mherwege requested a review from Copilot March 4, 2026 08:38

Copilot started reviewing on behalf of mherwege March 4, 2026 08:38 View session

Copilot AI reviewed Mar 4, 2026

View reviewed changes

copilot feedback

10267ae

Signed-off-by: Mark Herwege <mark.herwege@telenet.be>

mherwege requested a review from Copilot March 4, 2026 09:06

Copilot started reviewing on behalf of mherwege March 4, 2026 09:06 View session

Copilot AI reviewed Mar 4, 2026

View reviewed changes

mherwege added 2 commits March 4, 2026 11:42

handle exceptions in metadata console commands

de19943

Signed-off-by: Mark Herwege <mark.herwege@telenet.be>

update javadoc

39e195a

Signed-off-by: Mark Herwege <mark.herwege@telenet.be>

mherwege requested a review from Copilot March 4, 2026 11:02

Copilot started reviewing on behalf of mherwege March 4, 2026 11:02 View session

Copilot AI reviewed Mar 4, 2026

View reviewed changes

Comment thread ...ain/java/org/openhab/core/io/console/internal/extension/MetadataConsoleCommandExtension.java

Comment thread bundles/org.openhab.core/src/main/java/org/openhab/core/items/MetadataRegistry.java

fix console remove return text

81b14fd

Signed-off-by: Mark Herwege <mark.herwege@telenet.be>

mherwege requested a review from Copilot March 4, 2026 11:20

Copilot started reviewing on behalf of mherwege March 4, 2026 11:20 View session

Copilot AI reviewed Mar 4, 2026

View reviewed changes

mherwege marked this pull request as ready for review March 4, 2026 11:35

holgerfriedrich approved these changes Mar 21, 2026

View reviewed changes

holgerfriedrich merged commit 6956a62 into openhab:main Mar 21, 2026
8 of 9 checks passed

holgerfriedrich added the enhancement An enhancement or new feature of the Core label Mar 21, 2026

holgerfriedrich added this to the 5.2 milestone Mar 21, 2026

mherwege deleted the semantics_rest branch March 21, 2026 12:58

-                if (metadataRegistry.update(md) == null) {
+                Metadata previous = metadataRegistry.update(md);
+                if (previous == null) {
+                    // Metadata may have been removed concurrently; re-check existence
+                    if (metadataRegistry.get(key) == null) {
+                        return Response.status(Status.NOT_FOUND).build();
+                    }

Uh oh!

Uh oh!

Conversation

mherwege commented Feb 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

florian-h05 left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Feb 28, 2026

Choose a reason for hiding this comment

Uh oh!

mherwege Mar 3, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI Mar 3, 2026

Choose a reason for hiding this comment

Uh oh!

mherwege Mar 3, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI Mar 3, 2026

Choose a reason for hiding this comment

Uh oh!

mherwege Mar 3, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

mherwege Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

mherwege commented Feb 24, 2026 •

edited

Loading