feat: implement comprehensible metadata

kuzzleio · Mar 8, 2024 · bda03c0 · bda03c0
1 parent 6082008
commit bda03c0
Show file tree

Hide file tree

Showing 10 changed files with 530 additions and 22 deletions.
diff --git a/lib/modules/model/ModelService.ts b/lib/modules/model/ModelService.ts
@@ -61,14 +61,23 @@ export class ModelService extends BaseService {
     model: string,
     metadataMappings: JSONObject,
     defaultMetadata: JSONObject,
+    metadataDetails: JSONObject,
+    metadataGroups: JSONObject,
     measures: AssetModelContent["asset"]["measures"],
   ): Promise<KDocument<AssetModelContent>> {
     if (Inflector.pascalCase(model) !== model) {
       throw new BadRequestError(`Asset model "${model}" must be PascalCase.`);
     }
 
     const modelContent: AssetModelContent = {
-      asset: { defaultMetadata, measures, metadataMappings, model },
+      asset: {
+        defaultMetadata,
+        measures,
+        metadataDetails,
+        metadataGroups,
+        metadataMappings,
+        model,
+      },
       engineGroup,
       type: "asset",
     };
@@ -123,14 +132,23 @@ export class ModelService extends BaseService {
     model: string,
     metadataMappings: JSONObject,
     defaultMetadata: JSONObject,
+    metadataDetails: JSONObject,
+    metadataGroups: JSONObject,
     measures: DeviceModelContent["device"]["measures"],
   ): Promise<KDocument<DeviceModelContent>> {
     if (Inflector.pascalCase(model) !== model) {
       throw new BadRequestError(`Device model "${model}" must be PascalCase.`);
     }
 
     const modelContent: DeviceModelContent = {
-      device: { defaultMetadata, measures, metadataMappings, model },
+      device: {
+        defaultMetadata,
+        measures,
+        metadataDetails,
+        metadataGroups,
+        metadataMappings,
+        model,
+      },
       type: "device",
     };
 

diff --git a/lib/modules/model/ModelsController.ts b/lib/modules/model/ModelsController.ts
@@ -111,12 +111,16 @@ export class ModelsController {
     const metadataMappings = request.getBodyObject("metadataMappings", {});
     const defaultValues = request.getBodyObject("defaultValues", {});
     const measures = request.getBodyArray("measures", []);
+    const metadataDetails = request.getBodyObject("metadataDetails", {});
+    const metadataGroups = request.getBodyObject("metadataGroups", {});
 
     const assetModel = await this.modelService.writeAsset(
       engineGroup,
       model,
       metadataMappings,
       defaultValues,
+      metadataDetails,
+      metadataGroups,
       measures,
     );
 
@@ -130,11 +134,15 @@ export class ModelsController {
     const metadataMappings = request.getBodyObject("metadataMappings", {});
     const defaultValues = request.getBodyObject("defaultValues", {});
     const measures = request.getBodyArray("measures");
+    const metadataDetails = request.getBodyObject("metadataDetails", {});
+    const metadataGroups = request.getBodyObject("metadataGroups", {});
 
     const deviceModel = await this.modelService.writeDevice(
       model,
       metadataMappings,
       defaultValues,
+      metadataDetails,
+      metadataGroups,
       measures,
     );
 

diff --git a/lib/modules/model/ModelsRegister.ts b/lib/modules/model/ModelsRegister.ts
@@ -46,40 +46,85 @@ export class ModelsRegister {
     );
   }
 
+  /**
+   * Registers an asset model.
+   *
+   * @param engineGroup - The engine group name.
+   * @param model - The name of the asset model, which must be in PascalCase.
+   * @param measures - The measures associated with this asset model.
+   * @param metadataMappings - The metadata mappings for the model, defaults to an empty object.
+   * @param defaultMetadata - The default metadata values for the model, defaults to an empty object.
+   * @param metadataDetails - Optional detailed metadata descriptions and localizations.
+   * @param metadataGroups - Optional groups for organizing metadata, with localizations.
+   * @throws PluginImplementationError if the model name is not in PascalCase.
+   */
   registerAsset(
     engineGroup: string,
     model: string,
     measures: NamedMeasures,
     metadataMappings: JSONObject = {},
     defaultMetadata: JSONObject = {},
+    metadataDetails: JSONObject = {},
+    metadataGroups: JSONObject = {},
   ) {
+    // Check if the model name is PascalCase
     if (Inflector.pascalCase(model) !== model) {
       throw new PluginImplementationError(
         `Asset model "${model}" must be PascalCase`,
       );
     }
 
+    // Construct and push the new asset model to the assetModels array
     this.assetModels.push({
-      asset: { defaultMetadata, measures, metadataMappings, model },
+      asset: {
+        defaultMetadata,
+        measures,
+        metadataDetails,
+        metadataGroups,
+        metadataMappings,
+        model,
+      },
       engineGroup,
       type: "asset",
     });
   }
 
+  /**
+   * Registers a device model.
+   *
+   * @param model - The name of the device model, which must be in PascalCase.
+   * @param measures - The measures associated with this device model.
+   * @param metadataMappings - The metadata mappings for the model, defaults to an empty object.
+   * @param defaultMetadata - The default metadata values for the model, defaults to an empty object.
+   * @param metadataDetails - Optional detailed metadata descriptions and localizations.
+   * @param metadataGroups - Optional groups for organizing metadata, with localizations.
+   * @throws PluginImplementationError if the model name is not in PascalCase.
+   */
   registerDevice(
     model: string,
     measures: NamedMeasures,
     metadataMappings: JSONObject = {},
     defaultMetadata: JSONObject = {},
+    metadataDetails: JSONObject = {},
+    metadataGroups: JSONObject = {},
   ) {
+    // Check if the model name is PascalCase
     if (Inflector.pascalCase(model) !== model) {
       throw new PluginImplementationError(
         `Device model "${model}" must be PascalCase`,
       );
     }
 
+    // Construct and push the new device model to the deviceModels array
     this.deviceModels.push({
-      device: { defaultMetadata, measures, metadataMappings, model },
+      device: {
+        defaultMetadata,
+        measures,
+        metadataDetails,
+        metadataGroups,
+        metadataMappings,
+        model,
+      },
       type: "device",
     });
   }

diff --git a/lib/modules/model/collections/modelsMappings.ts b/lib/modules/model/collections/modelsMappings.ts
@@ -38,6 +38,14 @@ export const modelsMappings: CollectionMappings = {
           dynamic: "false",
           properties: {},
         },
+        metadataDetails: {
+          dynamic: "false",
+          properties: {},
+        },
+        metadataGroups: {
+          dynamic: "false",
+          properties: {},
+        },
         measures: {
           properties: {
             type: { type: "keyword" },
@@ -61,6 +69,14 @@ export const modelsMappings: CollectionMappings = {
           dynamic: "false",
           properties: {},
         },
+        metadataDetails: {
+          dynamic: "false",
+          properties: {},
+        },
+        metadataGroups: {
+          dynamic: "false",
+          properties: {},
+        },
         measures: {
           properties: {
             type: { type: "keyword" },

diff --git a/lib/modules/model/types/ModelContent.ts b/lib/modules/model/types/ModelContent.ts
@@ -46,7 +46,41 @@ export interface AssetModelContent extends KDocumentContent {
      * }
      */
     defaultMetadata: JSONObject;
-
+    /**
+     * Metadata details
+     * @example
+     * {
+     *   "extTemp": {
+     *     "group": "buildingEnv",
+     *     "locales": {
+     *     "en": {
+     *        "friendlyName": "External temperature",
+     *        "description": "Building external temperature"
+     *     },
+     *     "fr": {
+     *       "friendlyName": "Température extérieure",
+     *       "description": "Température à l'exterieur du building"
+     *     },
+     *   }
+     */
+    metadataDetails?: JSONObject;
+    /**
+     * Metadata groups list
+     * @example
+     * {
+     *   "buildingEnv": {
+     *     "locales": {
+     *       "en": {
+     *         "groupFriendlyName": "Building environment"
+     *       },
+     *       "fr": {
+     *         "groupFriendlyName": "Environnement du bâtiment"
+     *       }
+     *     }
+     *   }
+     * }
+     */
+    metadataGroups?: JSONObject;
     /**
      * List of accepted measures for this model
      *
@@ -84,7 +118,6 @@ export interface DeviceModelContent extends KDocumentContent {
      * }
      */
     metadataMappings: JSONObject;
-
     /**
      * Default values for metadata.
      *
@@ -94,7 +127,41 @@ export interface DeviceModelContent extends KDocumentContent {
      * }
      */
     defaultMetadata: JSONObject;
-
+    /**
+     * Metadata details
+     * @example
+     * {
+     *   "trackerType": {
+     *     "group": "sensorSpecs",
+     *     "locales": {
+     *     "en": {
+     *        "friendlyName": "Tracker version",
+     *        "description": "Firmware version of the tracker"
+     *     },
+     *     "fr": {
+     *       "friendlyName": "Version du capteur",
+     *       "description": "Version du micrologiciel du capteur"
+     *     },
+     *   }
+     */
+    metadataDetails?: JSONObject;
+    /**
+     * Metadata groups list
+     * @example
+     * {
+     *   "sensorSpecs": {
+     *     "locales": {
+     *       "en": {
+     *         "groupFriendlyName": "Sensor specifications"
+     *       },
+     *       "fr": {
+     *         "groupFriendlyName": "Spécifications techniques"
+     *       }
+     *     }
+     *   }
+     * }
+     */
+    metadataGroups?: JSONObject;
     /**
      * List of decoded measures for this model
      *