kuzzle-device-manager-types 3.0.0-3-dev.20 → 3.0.0-3-dev.22

package/dist/lib/modules/asset/AssetService.d.ts

@@ -58,4 +58,10 @@ export declare class AssetService extends DigitalTwinService {
         [locale: string]: string;
     }, index: string, request: KuzzleRequest): Promise<KDocument<AssetContent>>;
     private refreshModel;
+    /**
+     * Lists the engines whose assets use the given model:
+     * the model indexes for a tenant-scoped model, every engine for a commons model,
+     * and the engines of the model tenantClasses otherwise.
+     */
+    private getModelEngines;
 }

package/dist/lib/modules/asset/roles/RoleAssetsAdmin.d.ts

@@ -18,6 +18,7 @@ import { KuzzleRole } from "../../shared/types/KuzzleRole";
         getAsset: true,
         writeAsset: true,
         listMeasures: true,
+        getMetadataReferential: true,
       },
     },
  */

package/dist/lib/modules/asset/roles/RoleAssetsReader.d.ts

@@ -22,6 +22,7 @@ import { KuzzleRole } from "../../shared/types/KuzzleRole";
         listAssets: true,
         listMeasures: true,
         getAsset: true,
+        getMetadataReferential: true,
       },
     },
  */

package/dist/lib/modules/device/roles/RoleDevicesAdmin.d.ts

@@ -25,6 +25,7 @@ import { KuzzleRole } from "../../shared/types/KuzzleRole";
         getDevice: true,
         writeDevice: true,
         listMeasures: true,
+        getMetadataReferential: true,
       },
     },
  */

package/dist/lib/modules/device/roles/RoleDevicesReader.d.ts

@@ -22,6 +22,7 @@ import { KuzzleRole } from "../../shared/types/KuzzleRole";
         listDevices: true,
         getDevice: true,
         listMeasures: true,
+        getMetadataReferential: true,
       },
     },
     }

package/dist/lib/modules/group/GroupsService.d.ts

@@ -9,6 +9,11 @@ import { KuzzleLogger } from "kuzzle-logger";
 export declare class GroupsService extends BaseService {
     readonly logger: KuzzleLogger;
     constructor(plugin: DeviceManagerPlugin, logger: KuzzleLogger);
+    /**
+     * Refreshes the metadata of the groups of a model, in every engine of the model scope:
+     * added metadata are set to their default value, removed metadata are deleted.
+     */
+    private refreshModel;
     create(_id: string, index: string, metadata: JSONObject, model: string, name: string, path: string, request: KuzzleRequest): Promise<KDocument<GroupContent>>;
     get(index: string, _id: string, request: KuzzleRequest): Promise<import("kuzzle").KDocument<GroupContent>>;
     update(request: KuzzleRequest, _id: string, index: string, name?: string, metadata?: Metadata): Promise<import("kuzzle").KDocument<GroupContent>>;

package/dist/lib/modules/group/index.d.ts

@@ -2,3 +2,4 @@ export * from "./collections/groupsMappings";
 export * from "./GroupsModule";
 export * from "./roles/RoleGroupsAdmin";
 export * from "./roles/RoleGroupsReader";
+export * from "./types/GroupEvents";

package/dist/lib/modules/group/roles/RoleGroupsAdmin.d.ts

@@ -18,6 +18,7 @@ import { KuzzleRole } from "../../shared/types/KuzzleRole";
         getAsset: true,
         writeAsset: true,
         listMeasures: true,
+        getMetadataReferential: true,
       },
     },
  */

package/dist/lib/modules/group/roles/RoleGroupsReader.d.ts

@@ -18,6 +18,7 @@ import { KuzzleRole } from "../../shared/types/KuzzleRole";
         getAsset: true,
         writeAsset: true,
         listMeasures: true,
+        getMetadataReferential: true,
       },
     },
  */

package/dist/lib/modules/group/types/GroupEvents.d.ts

@@ -0,0 +1,8 @@
+import { GroupModelContent } from "../../model/types/ModelContent";
+export type AskGroupRefreshModel = {
+    name: "ask:device-manager:group:refresh-model";
+    payload: {
+        groupModel: GroupModelContent;
+    };
+    result: void;
+};

package/dist/lib/modules/model/MetadataReferential.d.ts

@@ -0,0 +1,119 @@
+import { EmbeddedSDK } from "kuzzle";
+import { JSONObject, KDocument } from "kuzzle-sdk";
+import { ConflictChunk } from "./ModelsConflicts";
+import { AssetModelContent, DeviceModelContent, GroupModelContent, MetadataDetails, MetadataMappings, MetadataReferential, MetadataReferentialContent, MetadataReferentialEntry, ReferentialMetadataMapping, ResolvedMetadataMappings } from "./types/ModelContent";
+export declare const METADATA_REFERENTIAL_ID = "model-metadata-referential";
+/**
+ * Runs cb holding the metadata referential lock, taken by every write of the referential
+ * and of asset, device and group models, so their conflicts checks see each other writes
+ */
+export declare function withMetadataReferentialLock<T>(cb: () => Promise<T>): Promise<T>;
+export type MetadataModelContent = AssetModelContent | DeviceModelContent | GroupModelContent;
+export type MetadataModelType = MetadataModelContent["type"];
+/**
+ * Metadata related fields of an asset, device or group model
+ */
+export type ModelMetadataFields = {
+    metadataMappings: MetadataMappings;
+    defaultMetadata: JSONObject;
+    metadataDetails: MetadataDetails;
+};
+export type MetadataResolutionContext = {
+    modelType: MetadataModelType;
+    model: string;
+    /**
+     * Builds the error thrown on an invalid use of the referential.
+     * PluginImplementationError when registering from code, BadRequestError from the API.
+     */
+    createError: (message: string) => Error;
+};
+export type MetadataEnrichment = {
+    /**
+     * Metadata fields to store: referential markers are kept in metadataMappings,
+     * metadataDetails and defaultMetadata are enriched with the referential values
+     */
+    fields: ModelMetadataFields;
+    /**
+     * Metadata mappings with the referential markers replaced by the referential mappings
+     */
+    resolvedMappings: ResolvedMetadataMappings;
+    /**
+     * Inline metadata identical to a referential entry, which should use the referential instead
+     */
+    warnings: string[];
+};
+/**
+ * @returns true if the metadata mappings mark a metadata of the referential
+ */
+export declare function isReferentialMapping(mapping: unknown): mapping is ReferentialMetadataMapping;
+/**
+ * Lists the metadata of a model coming from the metadata referential
+ */
+export declare function getReferentialNames(metadataMappings?: MetadataMappings): string[];
+/**
+ * Replaces the referential markers of metadata mappings by the referential mappings.
+ * A marker of a metadata missing from the referential is dropped.
+ */
+export declare function resolveMetadataMappings(referential: MetadataReferential, metadataMappings?: MetadataMappings): ResolvedMetadataMappings;
+/**
+ * @returns The model with the referential markers of its metadata mappings resolved
+ */
+export declare function resolveModelMappings<T extends MetadataModelContent>(referential: MetadataReferential, content: T): T;
+/**
+ * Resolves the referential metadata of a stored model, to be read:
+ * the markers are replaced by the referential mappings, the details and default values
+ * are merged over the current referential values.
+ * A marker of a metadata missing from the referential is dropped.
+ *
+ * @returns The model with its referential metadata resolved
+ */
+export declare function resolveModelMetadata<T extends MetadataModelContent>(referential: MetadataReferential, content: T): T;
+/**
+ * Validates the shape of a metadata referential entry
+ *
+ * @throws The error built by createError if the entry is invalid
+ */
+export declare function checkMetadataReferentialEntry(name: string, entry: MetadataReferentialEntry, createError: (message: string) => Error): void;
+/**
+ * Validates the metadata mappings of a model against the metadata referential and enriches
+ * the details and default values of the metadata coming from the referential.
+ *
+ * A metadata of the referential is marked `{ referential: true }` in metadataMappings, the marker is kept.
+ * Its details are the referential locales (merged per locale), editorHint and icon, overridden by the
+ * model ones. Its default value is the referential one, unless the model defines one.
+ *
+ * An inline metadata with the name of a referential entry must have the same mappings (legacy).
+ *
+ * @throws The error built by createError on an invalid marker or an unknown metadata
+ * @throws MappingsConflictsError if an inline metadata conflicts with the referential
+ */
+export declare function enrichModelMetadata(referential: MetadataReferential, fields: Partial<ModelMetadataFields>, context: MetadataResolutionContext): MetadataEnrichment;
+/**
+ * Lists the conflicts between a referential entry and the inline metadata of the same name of models
+ */
+export declare function getEntryModelsConflicts(name: string, entry: MetadataReferentialEntry, models: MetadataModelContent[]): ConflictChunk[];
+/**
+ * Lists the inline metadata a model write adds: metadataMappings keys that neither
+ * use the referential nor are already defined inline by the stored model.
+ */
+export declare function getAddedInlineMetadata(metadataMappings: MetadataMappings, stored: MetadataModelContent | null): string[];
+/**
+ * Reads the metadata referential document
+ *
+ * @returns The referential metadata, empty if the document does not exist yet
+ */
+export declare function fetchMetadataReferential(sdk: EmbeddedSDK, platformIndex: string): Promise<MetadataReferential>;
+/**
+ * Writes the whole metadata referential document
+ */
+export declare function saveMetadataReferential(sdk: EmbeddedSDK, platformIndex: string, referential: MetadataReferential): Promise<import("kuzzle").KDocument<MetadataReferentialContent>>;
+/**
+ * Lists every stored asset, device and group model
+ */
+export declare function fetchMetadataModels(sdk: EmbeddedSDK, platformIndex: string): Promise<KDocument<MetadataModelContent>[]>;
+/**
+ * Lists every stored asset, device and group model using the given metadata of the referential.
+ *
+ * metadataMappings is not indexed, the filtering is done after fetching the models.
+ */
+export declare function fetchReferencingModels(sdk: EmbeddedSDK, platformIndex: string, name: string): Promise<KDocument<MetadataModelContent>[]>;

package/dist/lib/modules/model/ModelService.d.ts

@@ -2,11 +2,36 @@ import { KuzzleRequest } from "kuzzle";
 import { JSONObject, KDocument, KHit, SearchResult } from "kuzzle-sdk";
 import { DeviceManagerPlugin } from "../plugin";
 import { BaseService, SearchParams } from "../shared";
-import { AssetModelContent, DeviceModelContent, GroupModelContent, LocaleDetails, MeasureModelContent, MetadataDetails, MetadataGroups, MetadataMappings, TooltipModels } from "./types/ModelContent";
+import { AssetModelContent, DeviceModelContent, GroupModelContent, LocaleDetails, MeasureModelContent, MetadataDetails, MetadataGroups, MetadataMappings, MetadataReferential, MetadataReferentialEntry, TooltipModels } from "./types/ModelContent";
 import { SchemaObject } from "ajv";
 import { MeasureValuesDetails } from "../measure";
 import { NamedMeasures } from "../decoder";
 import { KuzzleLogger } from "kuzzle-logger";
+import { MetadataModelContent } from "./MetadataReferential";
+/**
+ * Fields of a group model update.
+ * Affinity and icon are kept when omitted.
+ */
+export type GroupModelUpdate = {
+    affinity?: JSONObject;
+    defaultMetadata: JSONObject;
+    icon?: string;
+    locales: {
+        [valueName: string]: LocaleDetails;
+    };
+    metadataDetails: MetadataDetails;
+    metadataGroups: MetadataGroups;
+    metadataMappings: MetadataMappings;
+};
+/**
+ * Fields of a device model update.
+ * Metadata details and default values are kept when omitted.
+ */
+export type DeviceModelUpdate = {
+    defaultMetadata?: JSONObject;
+    metadataDetails?: MetadataDetails;
+    metadataMappings: MetadataMappings;
+};
 export declare class ModelService extends BaseService {
     readonly logger: KuzzleLogger;
     constructor(plugin: DeviceManagerPlugin, logger: KuzzleLogger);
@@ -66,4 +91,81 @@ export declare class ModelService extends BaseService {
     updateAsset(tenantClasses: string[], index: string | undefined, model: string, metadataMappings: MetadataMappings, defaultMetadata: JSONObject, metadataDetails: MetadataDetails, metadataGroups: MetadataGroups, measures: AssetModelContent["asset"]["measures"], tooltipModels: TooltipModels, locales: {
         [valueName: string]: LocaleDetails;
     }, icon: string | undefined, request: KuzzleRequest): Promise<KDocument<AssetModelContent>>;
+    /**
+     * Adds metadata of the metadata referential to a device model.
+     *
+     * Device models are additive only from the API: every existing metadata must be kept unchanged,
+     * new metadata must come from the referential. Metadata details and default values can change.
+     * The engines mappings are updated and the devices get the new metadata with their default value.
+     *
+     * @throws BadRequestError if an existing metadata is missing or changed, or a new one is inline
+     * @throws MappingsConflictsError if the new metadata conflict with the existing mappings
+     */
+    updateDevice(model: string, { defaultMetadata, metadataDetails, metadataMappings }: DeviceModelUpdate): Promise<KDocument<DeviceModelContent>>;
+    /**
+     * Returns the group model available for the given tenant classes:
+     * a model of these classes first, then a commons model.
+     *
+     * @throws NotFoundError if no group model with this name is available
+     */
+    private getScopedGroup;
+    /**
+     * Updates a group model, keeping its scope.
+     * Affinity and icon are kept when omitted.
+     *
+     * The engines mappings are updated and the groups of the model are refreshed.
+     *
+     * @throws MappingsConflictsError if the new mappings conflict with the existing ones
+     */
+    updateGroup(tenantClasses: string[], model: string, { affinity, defaultMetadata, icon, locales, metadataDetails, metadataGroups, metadataMappings, }: GroupModelUpdate): Promise<KDocument<GroupModelContent>>;
+    /**
+     * Validates the metadata of a model written through the API against the metadata referential
+     * and enriches the details and default values of the metadata coming from it
+     */
+    private resolveMetadata;
+    /**
+     * Resolves the referential metadata of stored models, to be returned by the API
+     */
+    resolveModels<D extends {
+        _source: MetadataModelContent;
+    }>(documents: D[]): Promise<D[]>;
+    getMetadataReferential(): Promise<MetadataReferential>;
+    /**
+     * Creates a metadata of the metadata referential, or updates its details.
+     *
+     * The mappings of a new metadata are merged into the assets, devices and groups collections
+     * of every engine. They cannot be modified afterwards: only the locales, editor hint,
+     * default value and icon of an existing metadata can change. These are copied into the models
+     * using the metadata when they are written, the existing models are not modified.
+     *
+     * @throws BadRequestError if the mappings of an existing metadata are modified
+     * @throws MappingsConflictsError if the new metadata conflicts with an inline metadata of a model
+     *  or with the actual mappings of an engine collection
+     */
+    writeMetadata(name: string, definition: MetadataReferentialEntry): Promise<MetadataReferential>;
+    /**
+     * Deletes a metadata of the metadata referential.
+     * Its mappings stay in the engines collections, Elasticsearch cannot remove them.
+     *
+     * @throws BadRequestError if a model still uses the metadata
+     */
+    deleteMetadata(name: string): Promise<MetadataReferential>;
+    /**
+     * With the referentialOnly option, rejects the inline metadata a model write adds.
+     * The inline metadata already defined by the stored model are kept (legacy).
+     *
+     * @throws BadRequestError if new inline metadata are added
+     */
+    private checkReferentialOnly;
+    /**
+     * Updates the engines collections. If Elasticsearch rejects the new mappings, the model is
+     * restored to its previous version (or deleted if it is new), otherwise every next engines
+     * update would fail on it.
+     */
+    private updateEnginesOrRestore;
+    private getStoredModel;
+    /**
+     * @throws BadRequestError if the metadata is registered from code
+     */
+    private checkUnmanagedMetadata;
 }

package/dist/lib/modules/model/ModelsConflicts.d.ts

@@ -36,3 +36,26 @@ export declare function getGroupConflicts(measures: GroupModelContent[], additio
  * @returns An array of ConflictChunk between current measures and the new measure
  */
 export declare function getMeasureConflicts(measures: MeasureModelContent[], additional: MeasureModelContent): ConflictChunk[];
+/**
+ * Find every conflicts between two sets of fields mappings (name => field mappings),
+ * e.g. metadata mappings or the metadata properties of an ES collection.
+ *
+ * Unlike findConflicts, a field defined with a type on one side and with properties on the other
+ * is a conflict, Elasticsearch cannot change a field from a value to an object or the opposite.
+ * Fields defined on one side only are not conflicts.
+ *
+ * @param currentMappings The current fields mappings
+ * @param newMappings The new fields mappings
+ * @param basePath Optional path to be added before conflicts paths
+ * @returns An array of MappingsConflict
+ */
+export declare function findMappingsConflicts(currentMappings: any, newMappings: any, basePath?: string): MappingsConflict[];
+/**
+ * Find every conflicts between two objects.
+ * WARNING: "undefined" type of conflicts are not registered
+ * @param sourceObject The source object used to compare
+ * @param objectToCompare The target object to compare to
+ * @param basePath Optional path to be added before conflicts paths
+ * @returns An array of MappingsConflict
+ */
+export declare function findConflicts(sourceObject: any, objectToCompare: any, basePath?: string): MappingsConflict[];

package/dist/lib/modules/model/ModelsController.d.ts

@@ -1,6 +1,6 @@
 import { ControllerDefinition, KuzzleRequest } from "kuzzle";
 import { ModelService } from "./ModelService";
-import { ApiModelWriteAssetResult, ApiModelWriteDeviceResult, ApiModelWriteMeasureResult, ApiModelUpdateAssetResult, ApiModelDeleteAssetResult, ApiModelDeleteDeviceResult, ApiModelDeleteMeasureResult, ApiModelListAssetsResult, ApiModelListDevicesResult, ApiModelListMeasuresResult, ApiModelGetAssetResult, ApiModelGetDeviceResult, ApiModelGetMeasureResult, ApiModelSearchAssetsResult, ApiModelSearchDevicesResult, ApiModelSearchMeasuresResult, ApiModelDeleteGroupResult, ApiModelGetGroupResult, ApiModelListGroupsResult, ApiModelSearchGroupsResult, ApiModelWriteGroupResult } from "./types/ModelApi";
+import { ApiModelWriteAssetResult, ApiModelWriteDeviceResult, ApiModelWriteMeasureResult, ApiModelUpdateAssetResult, ApiModelDeleteAssetResult, ApiModelDeleteDeviceResult, ApiModelDeleteMeasureResult, ApiModelListAssetsResult, ApiModelListDevicesResult, ApiModelListMeasuresResult, ApiModelGetAssetResult, ApiModelGetDeviceResult, ApiModelGetMeasureResult, ApiModelSearchAssetsResult, ApiModelSearchDevicesResult, ApiModelSearchMeasuresResult, ApiModelDeleteGroupResult, ApiModelGetGroupResult, ApiModelListGroupsResult, ApiModelSearchGroupsResult, ApiModelWriteGroupResult, ApiModelUpdateGroupResult, ApiModelUpdateDeviceResult, ApiModelGetMetadataReferentialResult, ApiModelWriteMetadataResult, ApiModelDeleteMetadataResult } from "./types/ModelApi";
 import { KuzzleLogger } from "kuzzle-logger";
 export declare class ModelsController {
     private modelService;
@@ -20,7 +20,7 @@ export declare class ModelsController {
     deleteGroup(request: KuzzleRequest): Promise<ApiModelDeleteGroupResult>;
     deleteMeasure(request: KuzzleRequest): Promise<ApiModelDeleteMeasureResult>;
     listAssets(request: KuzzleRequest): Promise<ApiModelListAssetsResult>;
-    listDevices(): Promise<ApiModelListDevicesResult>;
+    listDevices(request: KuzzleRequest): Promise<ApiModelListDevicesResult>;
     listGroups(request: KuzzleRequest): Promise<ApiModelListGroupsResult>;
     listMeasures(request: KuzzleRequest): Promise<ApiModelListMeasuresResult>;
     searchAssets(request: KuzzleRequest): Promise<ApiModelSearchAssetsResult>;
@@ -28,4 +28,13 @@ export declare class ModelsController {
     searchGroups(request: KuzzleRequest): Promise<ApiModelSearchGroupsResult>;
     searchMeasures(request: KuzzleRequest): Promise<ApiModelSearchMeasuresResult>;
     updateAsset(request: KuzzleRequest): Promise<ApiModelUpdateAssetResult>;
+    updateDevice(request: KuzzleRequest): Promise<ApiModelUpdateDeviceResult>;
+    updateGroup(request: KuzzleRequest): Promise<ApiModelUpdateGroupResult>;
+    /**
+     * Resolves the referential metadata of models, unless the rawModel flag is set
+     */
+    private resolveModels;
+    getMetadataReferential(): Promise<ApiModelGetMetadataReferentialResult>;
+    writeMetadata(request: KuzzleRequest): Promise<ApiModelWriteMetadataResult>;
+    deleteMetadata(request: KuzzleRequest): Promise<ApiModelDeleteMetadataResult>;
 }

package/dist/lib/modules/model/ModelsRegister.d.ts

@@ -1,7 +1,7 @@
 import { DeviceManagerPlugin } from "../plugin";
 import { NamedMeasures } from "../decoder";
 import { MeasureDefinition } from "../measure";
-import { GroupAffinity, LocaleDetails, MetadataDetails, MetadataGroups, MetadataMappings, TooltipModels } from "./types/ModelContent";
+import { GroupAffinity, LocaleDetails, MetadataDetails, MetadataGroups, MetadataMappings, MetadataReferentialEntry, TooltipModels } from "./types/ModelContent";
 import { JSONObject } from "kuzzle-sdk";
 export declare class ModelsRegister {
     private config;
@@ -10,10 +10,42 @@ export declare class ModelsRegister {
     private deviceModels;
     private groupModels;
     private measureModels;
+    private metadataReferential;
     private logger;
     private get sdk();
     init(plugin: DeviceManagerPlugin): void;
     loadModels(): Promise<void>;
+    /**
+     * Merges the metadata registered from code over the stored metadata referential and saves it.
+     * Metadata added through the API are kept, the details of metadata registered from code win.
+     *
+     * @throws PluginImplementationError if the mappings of a stored metadata are modified, or if a new
+     *  metadata conflicts with the stored models or the engines collections mappings
+     */
+    private loadMetadataReferential;
+    /**
+     * Checks the metadata registered from code that are not in the stored referential yet
+     * against the inline metadata of the stored models and the engines collections mappings
+     *
+     * @throws PluginImplementationError on a conflict
+     */
+    private checkNewMetadata;
+    /**
+     * Validates the metadata of models registered from code against the metadata referential
+     * and enriches the details and default values of the metadata coming from it
+     */
+    private resolveModels;
+    /**
+     * Registers a metadata in the metadata referential.
+     * Asset, device and group models can then use it with `{ referential: true }` in their metadataMappings.
+     * Its mappings cannot be modified once loaded, they are merged into the engines collections.
+     * Registering again an identical definition is allowed, so several modules can share a metadata.
+     *
+     * @param name - Name of the metadata
+     * @param definition - Mappings, default translations, editor hint, default value and icon of the metadata
+     * @throws PluginImplementationError if the metadata is invalid or already registered with another definition
+     */
+    registerMetadata(name: string, definition: MetadataReferentialEntry): void;
     /**
      * Registers an asset model.
      *

package/dist/lib/modules/model/types/ModelApi.d.ts

@@ -1,5 +1,5 @@
 import { JSONObject, KDocument, KHit, SearchResult } from "kuzzle-sdk";
-import { AssetModelContent, DeviceModelContent, GroupAffinity, GroupModelContent, LocaleDetails, MeasureModelContent, MetadataDetails, MetadataGroups, MetadataMappings, TooltipModels } from "./ModelContent";
+import { AssetModelContent, DeviceModelContent, GroupAffinity, GroupModelContent, LocaleDetails, MeasureModelContent, MetadataDetails, MetadataGroups, MetadataMappings, MetadataReferential, MetadataReferentialEntry, TooltipModels } from "./ModelContent";
 import { SchemaObject } from "ajv";
 import { MeasureValuesDetails } from "../../measure/types/MeasureDefinition";
 interface ModelsControllerRequest {
@@ -9,16 +9,28 @@ export interface ApiModelGetAssetRequest extends ModelsControllerRequest {
     action: "getAsset";
     model: string;
     tenantClasses: string[];
+    /**
+     * Returns the stored model, without resolving its referential metadata
+     */
+    rawModel?: boolean;
 }
 export type ApiModelGetAssetResult = KDocument<AssetModelContent>;
 export interface ApiModelGetDeviceRequest extends ModelsControllerRequest {
     action: "getDevice";
     model: string;
+    /**
+     * Returns the stored model, without resolving its referential metadata
+     */
+    rawModel?: boolean;
 }
 export type ApiModelGetDeviceResult = KDocument<DeviceModelContent>;
 export interface ApiModelGetGroupRequest extends ModelsControllerRequest {
     action: "getGroup";
     model: string;
+    /**
+     * Returns the stored model, without resolving its referential metadata
+     */
+    rawModel?: boolean;
 }
 export type ApiModelGetGroupResult = KDocument<GroupModelContent>;
 export interface ApiModelGetMeasureRequest extends ModelsControllerRequest {
@@ -30,7 +42,10 @@ export type ApiModelGetMeasureResult = KDocument<MeasureModelContent>;
 export interface ApiModelWriteAssetRequest extends ModelsControllerRequest {
     action: "writeAsset";
     body: {
-        tenantClasses: string[];
+        /**
+         * Mutually exclusive with `indexes`
+         */
+        tenantClasses?: string[];
         indexes?: string[];
         model: string;
         icon?: string;
@@ -76,6 +91,43 @@ export interface ApiModelWriteGroupRequest extends ModelsControllerRequest {
     };
 }
 export type ApiModelWriteGroupResult = KDocument<GroupModelContent>;
+export interface ApiModelUpdateDeviceRequest extends ModelsControllerRequest {
+    action: "updateDevice";
+    model: string;
+    body: {
+        /**
+         * Full set of metadata mappings: the existing ones, unchanged, and the new ones,
+         * which must be metadata of the referential (`{ referential: true }`)
+         */
+        metadataMappings: MetadataMappings;
+        /**
+         * Replaces the metadata details when present
+         */
+        metadataDetails?: MetadataDetails;
+        /**
+         * Replaces the default values when present
+         */
+        defaultValues?: JSONObject;
+    };
+}
+export type ApiModelUpdateDeviceResult = KDocument<DeviceModelContent>;
+export interface ApiModelUpdateGroupRequest extends ModelsControllerRequest {
+    action: "updateGroup";
+    tenantClasses?: string[];
+    model: string;
+    body: {
+        affinity?: GroupAffinity;
+        icon?: string;
+        metadataDetails?: MetadataDetails;
+        metadataGroups?: MetadataGroups;
+        metadataMappings?: MetadataMappings;
+        defaultValues?: JSONObject;
+        locales?: {
+            [valueName: string]: LocaleDetails;
+        };
+    };
+}
+export type ApiModelUpdateGroupResult = KDocument<GroupModelContent>;
 export interface ApiModelWriteMeasureRequest extends ModelsControllerRequest {
     action: "writeMeasure";
     body: {
@@ -132,6 +184,10 @@ export type ApiModelDeleteMeasureResult = void;
 export interface ApiModelListAssetsRequest extends ModelsControllerRequest {
     action: "listAssets";
     tenantClasses: string[];
+    /**
+     * Returns the stored model, without resolving its referential metadata
+     */
+    rawModel?: boolean;
 }
 export type ApiModelListAssetsResult = {
     models: KDocument<AssetModelContent>[];
@@ -139,6 +195,10 @@ export type ApiModelListAssetsResult = {
 };
 export interface ApiModelListDevicesRequest extends ModelsControllerRequest {
     action: "listDevices";
+    /**
+     * Returns the stored model, without resolving its referential metadata
+     */
+    rawModel?: boolean;
 }
 export type ApiModelListDevicesResult = {
     models: KDocument<DeviceModelContent>[];
@@ -147,6 +207,10 @@ export type ApiModelListDevicesResult = {
 export interface ApiModelListGroupsRequest extends ModelsControllerRequest {
     action: "listGroups";
     tenantClasses: string[];
+    /**
+     * Returns the stored model, without resolving its referential metadata
+     */
+    rawModel?: boolean;
 }
 export type ApiModelListGroupsResult = {
     models: KDocument<GroupModelContent>[];
@@ -163,6 +227,10 @@ export type ApiModelListMeasuresResult = {
 export interface ApiModelSearchAssetsRequest extends ModelsControllerRequest {
     action: "searchAssets";
     tenantClasses: string[];
+    /**
+     * Returns the stored model, without resolving its referential metadata
+     */
+    rawModel?: boolean;
     from?: number;
     size?: number;
     scrollTTL?: string;
@@ -171,6 +239,10 @@ export interface ApiModelSearchAssetsRequest extends ModelsControllerRequest {
 export type ApiModelSearchAssetsResult = SearchResult<KHit<AssetModelContent>>;
 export interface ApiModelSearchDevicesRequest extends ModelsControllerRequest {
     action: "searchDevices";
+    /**
+     * Returns the stored model, without resolving its referential metadata
+     */
+    rawModel?: boolean;
     from?: number;
     size?: number;
     scrollTTL?: string;
@@ -180,6 +252,10 @@ export type ApiModelSearchDevicesResult = SearchResult<KHit<DeviceModelContent>>
 export interface ApiModelSearchGroupsRequest extends ModelsControllerRequest {
     action: "searchGroups";
     tenantClasses: string[];
+    /**
+     * Returns the stored model, without resolving its referential metadata
+     */
+    rawModel?: boolean;
     from?: number;
     size?: number;
     scrollTTL?: string;
@@ -195,4 +271,19 @@ export interface ApiModelSearchMeasuresRequest extends ModelsControllerRequest {
     body?: JSONObject;
 }
 export type ApiModelSearchMeasuresResult = SearchResult<KHit<MeasureModelContent>>;
+export interface ApiModelGetMetadataReferentialRequest extends ModelsControllerRequest {
+    action: "getMetadataReferential";
+}
+export type ApiModelGetMetadataReferentialResult = MetadataReferential;
+export interface ApiModelWriteMetadataRequest extends ModelsControllerRequest {
+    action: "writeMetadata";
+    name: string;
+    body: MetadataReferentialEntry;
+}
+export type ApiModelWriteMetadataResult = MetadataReferential;
+export interface ApiModelDeleteMetadataRequest extends ModelsControllerRequest {
+    action: "deleteMetadata";
+    name: string;
+}
+export type ApiModelDeleteMetadataResult = MetadataReferential;
 export {};

package/dist/lib/modules/model/types/ModelContent.d.ts

@@ -22,7 +22,20 @@ export interface MetadataObject {
         [key: string]: MetadataProperty | MetadataObject;
     };
 }
+/**
+ * Marks, in the metadataMappings of a model, a metadata defined in the metadata referential.
+ * Its mappings are the referential ones, they are already merged into the engines collections.
+ */
+export interface ReferentialMetadataMapping {
+    referential: true;
+}
 export interface MetadataMappings {
+    [key: string]: MetadataProperty | MetadataObject | ReferentialMetadataMapping;
+}
+/**
+ * Metadata mappings without referential markers, as merged into the engines collections
+ */
+export interface ResolvedMetadataMappings {
     [key: string]: MetadataProperty | MetadataObject;
 }
 export interface GroupAffinity {
@@ -95,9 +108,62 @@ export interface MetadataDetails {
          * Then add a new field in EditorHintEnum to define the type of your hint.
          * Finally add the new editor hint interface with a pipe to take in account the new type.
          */
-        editorHint?: BaseEditorHint | OptionsSelectorEditorHint | DatetimeEditorHint;
+        editorHint?: EditorHint;
+        /**
+         * Icon representing the metadata.
+         * Free-form string, e.g. a FontAwesome icon name, a URL to a PNG/SVG image, or inline SVG markup.
+         */
+        icon?: string;
     };
 }
+export type EditorHint = BaseEditorHint | OptionsSelectorEditorHint | DatetimeEditorHint;
+/**
+ * A metadata defined once in the application metadata referential.
+ * Its mappings are merged into the engines collections when it is written,
+ * models use it with `{ referential: true }` in their metadataMappings.
+ */
+export interface MetadataReferentialEntry {
+    /**
+     * Mappings of the metadata.
+     * They cannot be modified once written, as they are merged into the engines collections.
+     *
+     * @example
+     * { type: "keyword" }
+     * { properties: { name: { type: "keyword" } } }
+     */
+    mappings: MetadataProperty | MetadataObject;
+    /**
+     * Default translations of the metadata, copied into the metadataDetails of a model using it
+     */
+    locales: {
+        [locale: string]: LocaleDetails;
+    };
+    /**
+     * Default editor hint of the metadata
+     */
+    editorHint?: EditorHint;
+    /**
+     * Default value of the metadata
+     */
+    defaultValue?: unknown;
+    /**
+     * Default icon of the metadata.
+     * Free-form string, e.g. a FontAwesome icon name, a URL to a PNG/SVG image, or inline SVG markup.
+     */
+    icon?: string;
+    /**
+     * Set by the plugin: true for a metadata registered from code.
+     * It is written at every startup and cannot be modified or deleted through the API.
+     */
+    managed?: boolean;
+}
+export interface MetadataReferential {
+    [name: string]: MetadataReferentialEntry;
+}
+export interface MetadataReferentialContent extends KDocumentContent {
+    type: "metadata-referential";
+    metadata: MetadataReferential;
+}
 export interface MetadataGroupLocale {
     groupFriendlyName: string;
     description: string;

package/dist/lib/modules/model/types/ModelDefinition.d.ts

@@ -118,7 +118,8 @@ export type AssetModelDefinition = {
      */
     icon?: string;
     /**
-     * Metadata mappings definition
+     * Metadata mappings definition.
+     * Use `{ referential: true }` for a metadata of the metadata referential.
      */
     metadataMappings?: MetadataMappings;
     /**
@@ -201,7 +202,8 @@ export type DeviceModelDefinition = {
      */
     icon?: string;
     /**
-     * Metadata mappings definition
+     * Metadata mappings definition.
+     * Use `{ referential: true }` for a metadata of the metadata referential.
      */
     metadataMappings?: MetadataMappings;
     /**
@@ -296,7 +298,8 @@ export type GroupModelDefinition = {
      */
     icon?: string;
     /**
-     * Metadata mappings definition
+     * Metadata mappings definition.
+     * Use `{ referential: true }` for a metadata of the metadata referential.
      */
     metadataMappings?: MetadataMappings;
     /**

package/dist/lib/modules/model/types/ModelEvents.d.ts

@@ -1,4 +1,4 @@
-import { AssetModelContent, DeviceModelContent, GroupModelContent, MeasureModelContent } from "./ModelContent";
+import { AssetModelContent, DeviceModelContent, GroupModelContent, MeasureModelContent, MetadataReferential } from "./ModelContent";
 export type AskModelAssetGet = {
     name: "ask:device-manager:model:asset:get";
     payload: {
@@ -30,3 +30,8 @@ export type AskModelGroupGet = {
     };
     result: GroupModelContent;
 };
+export type AskModelMetadataReferentialGet = {
+    name: "ask:device-manager:model:metadata-referential:get";
+    payload: void;
+    result: MetadataReferential;
+};

package/dist/lib/modules/plugin/DeviceManagerEngine.d.ts

@@ -5,6 +5,7 @@ import { DeviceManagerPlugin } from "./DeviceManagerPlugin";
 import { DeviceManagerConfiguration } from "./types/DeviceManagerConfiguration";
 import { InternalCollection } from "./types/InternalCollection";
 import { ConflictChunk } from "../model/ModelsConflicts";
+import { MetadataMappings } from "../model/types/ModelContent";
 export type TwinType = "asset" | "device";
 export type TwinModelContent = AssetModelContent | DeviceModelContent;
 export interface EngineDocument extends KDocumentContent {
@@ -39,10 +40,42 @@ export type AskEngineUpdateConflict = {
     };
     result: ConflictChunk[];
 };
+/**
+ * Checks a metadata of the metadata referential against the actual metadata mappings
+ * of the assets, devices and groups collections of every engine
+ */
+export type AskEngineMetadataConflict = {
+    name: "ask:device-manager:engine:doesMetadataConflict";
+    payload: {
+        metadataMappings: MetadataMappings;
+    };
+    result: ConflictChunk[];
+};
 export declare class DeviceManagerEngine extends AbstractEngine<DeviceManagerPlugin> {
     config: DeviceManagerConfiguration;
     get app(): Backend;
     constructor(plugin: Plugin, platformConfigManager: ConfigManager, engineConfigManager: ConfigManager);
+    /**
+     * Returns the actual metadata mappings of an engine collection
+     *
+     * @returns The mappings of the metadata properties, empty if the collection does not exist
+     */
+    private getCollectionMetadataMappings;
+    /**
+     * Return conflicts between the metadata mappings of models and the actual mappings
+     * of their collection in an engine
+     *
+     * @param engineIndex The target engine
+     * @param modelType The models type
+     * @param models The new or updated models, with their referential metadata resolved
+     * @returns An array of ConflictChunk
+     */
+    private getModelsMetadataConflicts;
+    /**
+     * Merges the mappings of the metadata referential and of models into metadata mappings.
+     * Every referential metadata is merged, used by a model or not.
+     */
+    private mergeMetadataMappings;
     /**
      * Return conflicts between the new and already present twin models
      *

package/dist/lib/modules/plugin/DeviceManagerPlugin.d.ts

@@ -2,7 +2,7 @@ import { Plugin, PluginContext } from "kuzzle";
 import { JSONObject } from "kuzzle-sdk";
 import { MeasureDefinition } from "../measure";
 import { DecoderModule, DecodersRegister } from "../decoder";
-import { AssetModelDefinition, DeviceModelDefinition, GroupModelDefinition, ModelsRegister } from "../model";
+import { AssetModelDefinition, DeviceModelDefinition, GroupModelDefinition, MetadataReferentialEntry, ModelsRegister } from "../model";
 import { DeviceManagerConfiguration } from "./types/DeviceManagerConfiguration";
 export declare class DeviceManagerPlugin extends Plugin {
     config: DeviceManagerConfiguration;
@@ -249,6 +249,41 @@ export declare class DeviceManagerPlugin extends Plugin {
          * ```
          */
         registerMeasure: (name: string, measureDefinition: MeasureDefinition) => void;
+        /**
+         * Register a metadata in the metadata referential.
+         *
+         * Its mappings are merged into the assets, devices and groups collections of every engine,
+         * and cannot be modified afterwards.
+         * Asset, device and group models then use it with `{ referential: true }` in their
+         * metadataMappings instead of redefining its mappings.
+         * A model defining inline a metadata that conflicts with the referential is rejected.
+         *
+         * @param name Name of the metadata
+         * @param definition Mappings, default translations, editor hint, default value and icon
+         *
+         * @example
+         * ```
+         * deviceManager.models.registerMetadata("color", {
+         *   mappings: { type: "keyword" },
+         *   locales: {
+         *     en: { friendlyName: "Color", description: "Color of the asset" },
+         *     fr: { friendlyName: "Couleur", description: "Couleur de l'asset" },
+         *   },
+         *   editorHint: {
+         *     type: EditorHintEnum.OPTION_SELECTOR,
+         *     values: ["red", "blue"],
+         *   },
+         *   defaultValue: "red",
+         *   icon: "palette",
+         * });
+         *
+         * deviceManager.models.registerAsset("commons", "Container", {
+         *   measures: [],
+         *   metadataMappings: { color: { referential: true } },
+         * });
+         * ```
+         */
+        registerMetadata: (name: string, definition: MetadataReferentialEntry) => void;
     };
     constructor();
     /**

package/dist/lib/modules/plugin/types/DeviceManagerConfiguration.d.ts

@@ -15,6 +15,17 @@ export type DeviceManagerConfiguration = {
          */
         autoUpdate: true;
     };
+    models: {
+        metadata: {
+            /**
+             * Only accept new metadata referenced from the metadata referential in the models written through the API.
+             *
+             * New inline metadataMappings keys are rejected, the inline metadata already defined
+             * by a model are kept (legacy). Models registered from code are not affected.
+             */
+            referentialOnly: boolean;
+        };
+    };
     /**
      * Platform index name
      */

package/dist/lib/modules/shared/utils/lock.d.ts

@@ -1 +1,7 @@
-export declare function lock<TReturn>(lockId: string, cb: () => Promise<TReturn>): Promise<TReturn>;
+export declare function lock<TReturn>(lockId: string, cb: () => Promise<TReturn>, { ttl, }?: {
+    /**
+     * Lock TTL in milliseconds, the lock is released after it even if cb is still running
+     * (Kuzzle default: 5000)
+     */
+    ttl?: number;
+}): Promise<TReturn>;

package/dist/tests/application/assets/Pole.d.ts

@@ -0,0 +1,5 @@
+import { AssetModel } from "../../../index";
+/**
+ * Asset model using the metadata referential
+ */
+export declare const Pole: AssetModel;

package/dist/tests/application/assets/index.d.ts

@@ -3,3 +3,4 @@ export * from "./MagicHouse";
 export * from "./Room";
 export * from "./StreetLamp";
 export * from "./Warehouse";
+export * from "./Pole";

package/dist/tests/application/metadata.d.ts

@@ -0,0 +1,5 @@
+import { MetadataReferentialEntry } from "../../index";
+export declare const metadataReferential: Array<{
+    name: string;
+    definition: MetadataReferentialEntry;
+}>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kuzzle-device-manager-types",
-  "version": "3.0.0-3-dev.20",
+  "version": "3.0.0-3-dev.22",
   "description": "Shared types for Kuzzle Device Manager",
   "author": "The Kuzzle Team (support@kuzzle.io)",
   "main": "index.js",