feat(core): implement Thing-level data schema mapping extraction (#1499)

siddharthbaleja7 · relu91 · danielpeintner · web-flow · commit 45d3cfb63351 · 2026-03-05T09:56:04.000+01:00
* feat(core): implement Thing-level data schema mapping extraction

* refactor(core/consumed-thing): simplify valuePath extraction

* refactor(core/comsumed-thing): derive type interactionType from Thing

* refactor(core): introduce DataSchemaMapping type

Make InteractionOutput accepts a DataSchemaMapping object instead of a
strig for the value path. This allows to extend the mapping in the future
with more properties if needed.

* refactor(core/interaction-output): clean up comments and un-wanted cast

* refactor(servient): use type from Thing for dataSchemaMapping property

* refactor(core/wot-impl): simplify mapping handling in consume

* refactor(core/helpers): remove any references in extractDataFromPath

* refactor(core/wot-impl): simplify mapping handling in produce

* test(core/client-test): avoid using any casting

* test(core/server-test): avoid using any casting

* refactor(core/interaction-output): use consistency in arg ordering for ActionInteractionOutput

* docs: minor fixes as requested from code review

Co-authored-by: danielpeintner &lt;daniel.peintner@gmail.com&gt;

* chore: remove leftover files from other branches

---------

Co-authored-by: reluc &lt;relu.cri@gmail.com&gt;
Co-authored-by: Cristiano Aguzzi &lt;relu91@users.noreply.github.com&gt;
Co-authored-by: danielpeintner &lt;daniel.peintner@gmail.com&gt;
diff --git a/README.md b/README.md
@@ -319,6 +319,51 @@ Below are small explanations of what they can be used for:
 -   Smart Clock: It simply has a property affordance for the time. However, it runs 60 times faster than real-time to allow time-based decisions that can be easily tested.
 -   Simple Coffee Machine: This is a simpler simulation of the coffee machine above.
 
+## Experimental Features
+
+### Data Mapping per Thing
+
+node-wot allows configuration of "Data Mapping" which extracts specific values from a Thing's response object (e.g., getting `123` from a wrapper `{ value: 123, timestamp: ... }`). This is useful when the Interaction only cares about an inner value but the Thing returns a wrapper object.
+
+This is configured using the experimental node-wot `nw:dataSchemaMapping` vocabulary in the Thing Description. It can be defined at the Thing level or globally injected via the `Servient` configuration:
+
+```json
+{
+    "title": "MyThing",
+    "properties": {
+        "status": {
+            "type": "integer",
+            "forms": [{ "href": "/status" }]
+        }
+    },
+    "nw:dataSchemaMapping": {
+        "nw:property": {
+            "nw:valuePath": "/value"
+        },
+        "nw:action": {
+            "nw:valuePath": "/value"
+        },
+        "nw:event": {
+            "nw:valuePath": "/value"
+        }
+    }
+}
+```
+
+The `nw:valuePath` supports simple JSON Pointer-like notation (e.g., `/value` or `value/nested`) or dot-notation (e.g., `value.nested`) and is evaluated _after_ content deserialization but _before_ JSON Schema validation. Currently, the `nw:` vocabulary is hardcoded internally and doesn't explicitly require an `@context` definition for node-wot to process it.
+
+Servient-level configuration can be added to naturally inject this vocabulary to any consumed or exposed Thing Descriptions without the application needing to do it manually. In the `wot-servient.conf.json` file, you can specify this parameter under the `"servient"` key:
+
+```json
+{
+    "servient": {
+        "dataSchemaMapping": {
+            "nw:property": { "nw:valuePath": "/value" }
+        }
+    }
+}
+```
+
 ## Documentation
 
 > [!WARNING]
diff --git a/packages/cli/src/cli-default-servient.ts b/packages/cli/src/cli-default-servient.ts
@@ -122,6 +122,10 @@ export default class DefaultServient extends Servient {
             Helpers.setStaticAddress(this.config.servient.staticAddress);
         }
 
+        if (this.config.servient.dataSchemaMapping) {
+            this.dataSchemaMapping = this.config.servient.dataSchemaMapping;
+        }
+
         let coapServer: CoapServer | undefined;
         if (this.config.servient.clientOnly === false) {
             if (this.config.http != null) {
diff --git a/packages/core/src/consumed-thing.ts b/packages/core/src/consumed-thing.ts
@@ -584,7 +584,7 @@ export default class ConsumedThing extends Thing implements IConsumedThing {
 
         const content = await client.readResource(formWithUriVariables);
         try {
-            return this.handleInteractionOutput(content, formWithUriVariables, tp);
+            return this.handleInteractionOutput(content, formWithUriVariables, tp, "nw:property");
         } catch (e) {
             const error = e instanceof Error ? e : new Error(JSON.stringify(e));
             throw new Error(`Error while processing property for ${tp.title}. ${error.message}`);
@@ -594,13 +594,17 @@ export default class ConsumedThing extends Thing implements IConsumedThing {
     private handleInteractionOutput(
         content: Content,
         form: Form,
-        outputDataSchema: WoT.DataSchema | undefined
+        outputDataSchema: WoT.DataSchema | undefined,
+        interactionType: keyof Required<Exclude<Thing["nw:dataSchemaMapping"], undefined>>
     ): InteractionOutput {
         // infer media type from form if not in response metadata
         content.type ??= form.contentType ?? "application/json";
         // check if returned media type is the same as expected media type (from TD)
         this.checkMediaTypeOrThrow(content, form);
-        return new InteractionOutput(content, form, outputDataSchema);
+
+        const mapping = this["nw:dataSchemaMapping"]?.[interactionType];
+
+        return new InteractionOutput(content, form, outputDataSchema, mapping);
     }
 
     // check if returned media type is the same as expected media type (from TD)
@@ -620,13 +624,17 @@ export default class ConsumedThing extends Thing implements IConsumedThing {
         content: Content,
         form: Form,
         outputDataSchema: WoT.DataSchema | undefined,
+        interactionType: keyof Required<Exclude<Thing["nw:dataSchemaMapping"], undefined>>,
         synchronous?: boolean
     ): ActionInteractionOutput {
         // infer media type from form if not in response metadata
         content.type ??= form.contentType ?? "application/json";
         // check if returned media type is the same as expected media type (from TD)
         this.checkMediaTypeOrThrow(content, form);
-        return new ActionInteractionOutput(content, form, outputDataSchema, synchronous);
+
+        const mapping = this["nw:dataSchemaMapping"]?.[interactionType];
+
+        return new ActionInteractionOutput(content, form, outputDataSchema, mapping, synchronous);
     }
 
     async _readProperties(propertyNames: string[]): Promise<WoT.PropertyReadMap> {
@@ -745,7 +753,13 @@ export default class ConsumedThing extends Thing implements IConsumedThing {
 
         const content = await client.invokeResource(formWithUriVariables, input);
         try {
-            return this.handleActionInteractionOutput(content, formWithUriVariables, ta.output, ta.synchronous);
+            return this.handleActionInteractionOutput(
+                content,
+                formWithUriVariables,
+                ta.output,
+                "nw:action",
+                ta.synchronous
+            );
         } catch (e) {
             const error = e instanceof Error ? e : new Error(JSON.stringify(e));
             throw new Error(`Error while processing action for ${ta.title}. ${error.message}`);
@@ -788,7 +802,7 @@ export default class ConsumedThing extends Thing implements IConsumedThing {
             // next
             (content) => {
                 try {
-                    listener(this.handleInteractionOutput(content, form, tp));
+                    listener(this.handleInteractionOutput(content, form, tp, "nw:property"));
                 } catch (e) {
                     const error = e instanceof Error ? e : new Error(JSON.stringify(e));
                     warn(`Error while processing observe property for ${tp.title}. ${error.message}`);
@@ -844,7 +858,7 @@ export default class ConsumedThing extends Thing implements IConsumedThing {
             formWithoutURITemplates,
             (content) => {
                 try {
-                    listener(this.handleInteractionOutput(content, form, te.data));
+                    listener(this.handleInteractionOutput(content, form, te.data, "nw:event"));
                 } catch (e) {
                     const error = e instanceof Error ? e : new Error(JSON.stringify(e));
                     warn(`Error while processing event for ${te.title}. ${error.message}`);
diff --git a/packages/core/src/helpers.ts b/packages/core/src/helpers.ts
@@ -218,6 +218,37 @@ export default class Helpers implements Resolver {
         }
     }
 
+    /**
+     * Extracts a value from an object based on a JSON path.
+     * Supports dot-notation or JSON Pointer-like notation (e.g., "/value", "value", "state.status").
+     * @param data The object to extract from
+     * @param path The path string
+     * @returns The extracted value, or undefined if the path is not found
+     */
+    public static extractDataFromPath(data: unknown, path: string): DataSchemaValue | undefined {
+        if (data == null) {
+            return undefined;
+        }
+
+        let cleanPath = path;
+        if (cleanPath.startsWith("/")) {
+            cleanPath = cleanPath.substring(1);
+        }
+
+        const parts = cleanPath.split(/[./]/);
+        let current: unknown = data;
+
+        for (const part of parts) {
+            if (current != null && typeof current === "object" && part in current) {
+                current = (current as Record<string, unknown>)[part];
+            } else {
+                return undefined;
+            }
+        }
+
+        return current as DataSchemaValue;
+    }
+
     /**
      * Helper function to remove reserved keywords in required property of TD JSON Schema
      */
diff --git a/packages/core/src/interaction-output.ts b/packages/core/src/interaction-output.ts
@@ -15,7 +15,8 @@
 import * as util from "util";
 import * as WoT from "wot-typescript-definitions";
 import { ContentSerdes } from "./content-serdes";
-import { ProtocolHelpers } from "./core";
+import { DataSchemaMapping, ProtocolHelpers } from "./core";
+import Helpers from "./helpers";
 import { DataSchemaError, NotReadableError, NotSupportedError } from "./errors";
 import { Content } from "./content";
 import Ajv from "ajv";
@@ -44,6 +45,8 @@ export class InteractionOutput implements WoT.InteractionOutput {
     form?: WoT.Form;
     schema?: WoT.DataSchema;
 
+    mapping?: DataSchemaMapping;
+
     public get data(): ReadableStream {
         if (this.#stream) {
             return this.#stream;
@@ -58,10 +61,11 @@ export class InteractionOutput implements WoT.InteractionOutput {
         return (this.#stream = ProtocolHelpers.toWoTStream(this.#content.body) as ReadableStream);
     }
 
-    constructor(content: Content, form?: WoT.Form, schema?: WoT.DataSchema) {
+    constructor(content: Content, form?: WoT.Form, schema?: WoT.DataSchema, mapping?: DataSchemaMapping) {
         this.#content = content;
         this.form = form;
         this.schema = schema;
+        this.mapping = mapping;
         this.dataUsed = false;
     }
 
@@ -128,7 +132,11 @@ export class InteractionOutput implements WoT.InteractionOutput {
         this.dataUsed = true;
         this.#valueBuffer = bytes;
 
-        const json = ContentSerdes.get().contentToValue({ type: this.#content.type, body: bytes }, this.schema);
+        let json = ContentSerdes.get().contentToValue({ type: this.#content.type, body: bytes }, this.schema);
+
+        if (this.mapping !== undefined) {
+            json = Helpers.extractDataFromPath(json, this.mapping["nw:valuePath"]);
+        }
 
         // validate the schema
         const validate = ajv.compile<T>(this.schema);
@@ -152,8 +160,14 @@ export class InteractionOutput implements WoT.InteractionOutput {
 export class ActionInteractionOutput extends InteractionOutput implements WoT.ActionInteractionOutput {
     synchronous?: boolean;
 
-    constructor(content: Content, form?: WoT.Form, schema?: WoT.DataSchema, synchronous?: boolean) {
-        super(content, form, schema);
+    constructor(
+        content: Content,
+        form?: WoT.Form,
+        schema?: WoT.DataSchema,
+        mapping?: DataSchemaMapping,
+        synchronous?: boolean
+    ) {
+        super(content, form, schema, mapping);
         this.synchronous = synchronous;
     }
 
diff --git a/packages/core/src/servient.ts b/packages/core/src/servient.ts
@@ -21,7 +21,7 @@ import { ProtocolClientFactory, ProtocolServer, ProtocolClient } from "./protoco
 import ContentManager, { ContentCodec } from "./content-serdes";
 import { v4 } from "uuid";
 import { createLoggers } from "./logger";
-import { Helpers } from "./core";
+import { Helpers, Thing } from "./core";
 
 const { debug, warn } = createLoggers("core", "servient");
 
@@ -31,6 +31,12 @@ export default class Servient {
     private things: Map<string, ExposedThing> = new Map<string, ExposedThing>();
     private credentialStore: Map<string, Array<unknown>> = new Map<string, Array<unknown>>();
 
+    /**
+     * Data schema mapping for extracting values from nested response objects.
+     * @experimental
+     */
+    public dataSchemaMapping: Thing["nw:dataSchemaMapping"];
+
     #wotInstance?: typeof WoT;
     #shutdown = false;
 
diff --git a/packages/core/src/thing-description.ts b/packages/core/src/thing-description.ts
@@ -33,6 +33,16 @@ export class Thing implements TDT.ThingDescription {
 
     "@context": TDT.ThingContext;
 
+    /**
+     * Data schema mapping for extracting values from nested response objects.
+     * @experimental
+     */
+    "nw:dataSchemaMapping"?: {
+        "nw:property"?: DataSchemaMapping;
+        "nw:action"?: DataSchemaMapping;
+        "nw:event"?: DataSchemaMapping;
+    };
+
     // eslint-disable-next-line  @typescript-eslint/no-explicit-any
     [key: string]: any;
 
@@ -253,3 +263,4 @@ export abstract class ThingEvent {
     // eslint-disable-next-line  @typescript-eslint/no-explicit-any
     [key: string]: any;
 }
+export type DataSchemaMapping = { "nw:valuePath": string };
diff --git a/packages/core/src/wot-impl.ts b/packages/core/src/wot-impl.ts
@@ -107,6 +107,13 @@ export default class WoTImpl {
     async consume(td: WoT.ThingDescription): Promise<WoT.ConsumedThing> {
         try {
             const thing = parseTD(JSON.stringify(td), true);
+            const mapping = { ...(this.srv.dataSchemaMapping ?? {}), ...(thing["nw:dataSchemaMapping"] ?? {}) };
+
+            // If no mapping is configured, the property will be left undefined
+            if (Object.keys(mapping).length > 0) {
+                thing["nw:dataSchemaMapping"] = mapping;
+            }
+
             const newThing: ConsumedThing = new ConsumedThing(this.srv, thing as ThingModel);
 
             debug(
@@ -134,6 +141,13 @@ export default class WoTImpl {
                     throw new Error("Thing Description JSON schema validation failed:\n" + validated.errors);
                 }
 
+                const mapping = { ...(this.srv.dataSchemaMapping ?? {}), ...(init["nw:dataSchemaMapping"] ?? {}) };
+
+                // If none mapping is configured, the property will be left undefined
+                if (Object.keys(mapping).length > 0) {
+                    init["nw:dataSchemaMapping"] = mapping;
+                }
+
                 const newThing = new ExposedThing(this.srv, init);
 
                 debug(`WoTImpl producing new ExposedThing '${newThing.title}'`);
diff --git a/packages/core/test/client-test.ts b/packages/core/test/client-test.ts
diff --git a/packages/core/test/interaction-output-test.ts b/packages/core/test/interaction-output-test.ts
diff --git a/packages/core/test/server-test.ts b/packages/core/test/server-test.ts
