@itwin/core-backend 5.0.0-dev.9 → 5.0.0-dev.92

package/lib/esm/workspace/Settings.d.ts

@@ -0,0 +1,216 @@
+/** @packageDocumentation
+ * @module Workspace
+ */
+import { BeEvent, JSONSchemaType } from "@itwin/core-bentley";
+import { LocalDirName, LocalFileName } from "@itwin/core-common";
+import { WorkspaceDb } from "./Workspace";
+import { _implementationProhibited } from "../internal/Symbols";
+/** The value of a single named parameter within a [[Workspace.settings]] that configures some aspect of the applications run-time behavior.
+ * Settings are stored in a [[SettingsDictionary]]. A setting is described by its [[SettingSchema]].
+ * @beta
+ */
+export type Setting = JSONSchemaType;
+/** @beta */
+export declare namespace Setting {
+    /** Create a deep copy of a [[Setting]]. */
+    function clone<T extends Setting>(setting: T): T;
+    /** Returns true if `a` and `b` are considered equivalent [[Setting]] values.
+     * Settings of primitive types like `number` and `string` are compared using `===`.
+     * Settings of type "object" are compared by comparing each property using `areEqual`; the objects are considered
+     * equal if they have the exact same set of property names with equivalent values.
+     * Settings of type "array" are compared by comparing each element of the arrays use `areEqual`; the arrays are considered
+     * equal if they have the same number of elements with equivalent values in the same exact order.
+     */
+    function areEqual(a: Setting | undefined, b: Setting | undefined): boolean;
+}
+/**
+ * The name of a [[Setting]].
+ * Setting names must be [valid JavaScript property names](https://developer.mozilla.org/en-US/docs/Glossary/property/JavaScript) containing no spaces or periods.
+ * The name of a setting begins with the schema prefix of the [[SettingGroupSchema]] in which its [[SettingSchema]] is defined.
+ * A setting name therefore forms a path like file names in a file system.
+ * For example, the following are setting names defined in the `energyAnalysis`, `iot-scan-visualization`, and `vibration-map` schemas.
+ *
+ * ```ts
+ * "energyAnalysis/formats/totalWork"
+ * "energyAnalysis/formats/totalHours"
+ * "energyAnalysis/units/power"
+ * "energyAnalysis/units/temperature"
+ * "energyAnalysis/startupMode"
+ * "iot-scan-visualization/ports/cameras"
+ * "vibration-map/filters/scope"
+ * "vibration-map/filters/prefabricated"
+ * ```
+ *
+ * @beta
+ */
+export type SettingName = string;
+/** An object that defines the values for any number of [[Setting]]s. Each of its properties' names must conform to the semantics of a [[SettingName]].
+ * @beta
+ */
+export interface SettingsContainer {
+    /** Accesses settings by their names. */
+    [name: SettingName]: Setting | undefined;
+}
+/** Defines the precedence of a [[SettingsDictionary]].
+ * [[Settings]] may contain multiple dictionaries containing different values for the same [[SettingName]].
+ * When resolving the value of a [[Setting]], the value from the highest-priority dictionary is used.
+ * Priorities are grouped into coarse categories like [[SettingsPriority.application]] and [[SettingsPriority.iModel]].
+ * Settings with priorities less than or equal to [[SettingsPriority.application]] are stored in [[IModelHost.appWorkspace]], while
+ * those with priorities higher than [[SettingsPriority.application]] are stored inside [[IModelDb.workspace]].
+ * @beta
+ */
+export type SettingsPriority = number;
+/** @beta */
+export declare namespace SettingsPriority {
+    /** Settings that originate from default setting files loaded automatically at the start of a session. */
+    const defaults = 100;
+    /** Settings supplied by an application at runtime. */
+    const application = 200;
+    /** Settings that apply to all iTwins for an organization. */
+    const organization = 300;
+    /** Settings that apply to all iModels in an iTwin. */
+    const iTwin = 400;
+    /** Settings that apply to all branches of an iModel. */
+    const branch = 500;
+    /** Settings that apply to a specific iModel. */
+    const iModel = 600;
+}
+/** A named container that supplies values for [[Setting]]s.
+ * @see [[Settings.addDictionary]] to register a new settings dictionary.
+ * @beta
+ */
+export interface SettingsDictionary {
+    /** @internal */
+    [_implementationProhibited]: unknown;
+    /** Metadata describing the dictionary. */
+    readonly props: SettingsDictionaryProps;
+    /** Obtain a copy of the value of the setting named `settingName` stored in this dictionary, or `undefined` if no such setting exists.
+     * The returned value is always cloned using [[Setting.clone]].
+     * @note Generally, applications use methods like [[Settings.getString]] and [[Setting.getArray]] to resolve a setting value from multiple
+     * dictionaries. Those methods - unlike this one - also validate that `settingName` is of type `T` as defined by its [[SettingSchema]].
+     */
+    getSetting<T extends Setting>(settingName: SettingName): T | undefined;
+}
+/** Uniquely identifies a [[SettingsDictionary]].
+ * @beta
+ */
+export interface SettingsDictionarySource {
+    /** The name of the dictionary, which must be unique within its [[workspaceDb]], or - if [[workspaceDb]] is undefined - unique among all dictionaries not associated with any [[WorkspaceDb]]. */
+    readonly name: string;
+    /** The [[WorkspaceDb]] from which the dictionary originated. */
+    readonly workspaceDb?: WorkspaceDb;
+}
+/** Properties of a [[SettingsDictionary]], defining its name, the [[WorkspaceDb]] (if any) from which it originated, and its [[priority]] relative to other dictionaries.
+ * @beta
+ */
+export interface SettingsDictionaryProps extends SettingsDictionarySource {
+    /** Precedence value determining which setting value to use when multiple dictionaries supply values for the same [[SettingName]]. */
+    readonly priority: SettingsPriority;
+}
+/**
+ * The collection of [[Setting]]s that supply the run-time configuration of a [[Workspace]].
+ * The `Settings` object comprises a collection of named [[SettingsDictionary]] objects.
+ * Methods like [[getSetting]], [[getString]], and [[getArray]] provide access to the value of an individual [[Setting]] by searching
+ * the [[dictionaries]] in order by their [[SettingsPriority]] to find the highest-priority setting with the requested [[SettingName]].
+ * Most methods that retrieve [[Setting]] values validate them against their [[SettingSchema]]s to ensure that they are of the correct type.
+ * A [[SettingsDictionary]] can be added or removed using [[addDictionary]] and [[dropDictionary]].
+ * Because [[Setting]]s can change at any time during the session, you should avoid caching their values wherever possible.
+ * If you must cache them (for example, to display in a user interface), you should listen for the [[onSettingsChanged]] event to be
+ * notified of potential changes.
+ *
+ * Settings are accessed via [[Workspace.settings]]. They are defined at the application level by [[IModelHost.appWorkspace]], but individual iModels may supply
+ * additional iModel-specific settings or overrides for application-level settings. When working in the context of a specific iModel, use [[IModelDb.workspace]]'s `settings`
+ * property. Any settings not overridden by the iModel will fall back to the settings defined in [[IModelHost.appWorkspace]].
+ *
+ * Application settings are loaded into [[IModelHost.appWorkspace]] when the session begins (i.e., when [[IModelHost.startup]] is invoked), and unloaded when it ends (in [[IModelHost.shutdown]]).
+ * They are read from [JSON5](https://json5.org/) files delivered with the application. The application should register any additional [[SettingsDictionary]]'s '(and their corresponding
+ * [[SettingGroupSchema]]s) at this time.
+ *
+ * iModel-specific settings are stored in the iModel's property table and loaded into [[IModelDb.workspace]] when the iModel is first opened.
+ * You can add and remove a [[SettingsDictionary]] from the property table using [[IModelDb.saveSettingDictionary]] and [[IModelDb.deleteSettingDictionary]].
+ *
+ * See the [learning article]($docs/learning/backend/Workspace) for a detailed overiew and examples.
+ *
+ * @see [[IModelHost.appWorkspace]] application-wide settings, and [[IModelDb.workspace]] for settings specific to a given iModel.
+ * @beta
+ */
+export interface Settings {
+    /** @internal */
+    [_implementationProhibited]: unknown;
+    /** @internal */
+    close(): void;
+    /** The set of settings dictionaries from which [[Setting]] values are obtained, sorted by [[SettingsPriority]].
+     * The set can contain at most one dictionary for each unique combination of name and [[WorkspaceDb]].
+     * @see [[addDictionary]], [[addFile]], [[addJson]], and [[addDirectory]] to add a new dictionary.
+     * @see [[dropDictionary]] to remove a dictionary.
+     * @see [[getDictionary]] to look up a dictionary.
+     */
+    readonly dictionaries: readonly SettingsDictionary[];
+    /** Event raised whenever a [[SettingsDictionary]] is added or removed. */
+    readonly onSettingsChanged: BeEvent<() => void>;
+    /** Parses the contents of a local [JSON5](https://json5.org/) file as a [[SettingsContainer]] and invokes [[addDictionary]] to
+     * add a [[SettingsDictionary]] named `fileName` with the specified priority.
+     * @param fileName the name of a local settings file containing the dictionary.
+     * @param priority the priority for the dictionary.
+     */
+    addFile(fileName: LocalFileName, priority: SettingsPriority): void;
+    /** Invokes [[addFile]] for all files in `directory` with the extension ".json" or ".json5". */
+    addDirectory(directory: LocalDirName, priority: SettingsPriority): void;
+    /** Parses `settingsJson` as a [[SettingsContainer]] and invokes [[addDictionary]] to add a [[SettingsDictionary]] with the specified `props`.
+     * This is typically used when reading dictionaries out of a [[WorkspaceDb]], where they are stored as stringified JSON.
+     */
+    addJson(props: SettingsDictionaryProps, settingsJson: string): void;
+    /** Find a [[SettingsDictionary]] with the same name and [[WorkspaceDb]] as `source`. */
+    getDictionary(source: SettingsDictionarySource): SettingsDictionary | undefined;
+    /** Add a new [[SettingsDictionary]] with the priority, name, and [[WorkspaceDb]] specified by `props` and setting values supplied by `settings`.
+     * @note If a dictionary with the same name and [[WorkspaceDb]] already exists, it will be replaced.
+     * @see [[addFile]], [[addJson]], and [[addDirectory]] for convenient ways to add dictionaries from various sources.
+     */
+    addDictionary(props: SettingsDictionaryProps, settings: SettingsContainer): void;
+    /** Removes a previously-added [[SettingsDictionary]]. */
+    dropDictionary(props: SettingsDictionarySource): void;
+    /** Looks up the highest priority setting value for a SettingName, falling back to a default value if no value for the setting is found.
+     * The [[dictionaries]] are searched in order by [[SettingsPriority]]; the first one that provides a value for `settingName` wins.
+     * @param settingName The name of the setting.
+     * @param defaultValue value returned if settingName is not present in any [[SettingsDictionary]].
+     * @note This method is generic on [[Setting]] type, but no type checking is actually performed at run time. So, if you
+     * use this method to get a setting with an expected type, but its value is a different type, the return type of this method will be wrong.
+     * You must always type check the result. Use the non-generic "get" methods like [[getString]] and [[getArray]] if you only want the value
+     * if its type is correct.
+     * @note Unlike [[getArray]], this method does not combine arrays - it ignores [[SettingsSchema.combineArrays]].
+     */
+    getSetting<T extends Setting>(settingName: SettingName, defaultValue?: T): T | undefined;
+    /** Obtain an iterator over all of the values in the [[dictionaries]] for the [[Setting]] identified by `settingName`, ordered by [[SettingsPriority]]. */
+    getSettingEntries<T extends Setting>(settingName: SettingName): Iterable<{
+        value: T;
+        dictionary: SettingsDictionary;
+    }>;
+    /** Obtain an iterator over all of the values in the [[dictionaries]] for the [[Setting]] identified by `settingName`, ordered by [[SettingsPriority]]. */
+    getSettingValues<T extends Setting>(settingName: SettingName): Iterable<T>;
+    /** Look up the value of a string [[Setting]] named `settingName`, returning `defaultValue` if no such value is defined.
+     * @throws Error if the setting exists but is not a string.
+     */
+    getString(settingName: SettingName, defaultValue: string): string;
+    getString(settingName: SettingName, defaultValue?: string): string | undefined;
+    /** Look up the value of a boolean [[Setting]] named `settingName`, returning `defaultValue` if no such value is defined.
+     * @throws Error if the setting exists but is not a boolean.
+     */
+    getBoolean(settingName: SettingName, defaultValue: boolean): boolean;
+    getBoolean(settingName: SettingName, defaultValue?: boolean): boolean | undefined;
+    /** Look up the value of a numeric [[Setting]] named `settingName`, returning `defaultValue` if no such value is defined.
+     * @throws Error if the setting exists but is not a number.
+     */
+    getNumber(settingName: SettingName, defaultValue: number): number;
+    getNumber(settingName: SettingName): number | undefined;
+    /** Look up the value of an object [[Setting]] named `settingName`, returning `defaultValue` if no such value is defined.
+     * @throws Error if the setting exists but is not an object.
+     */
+    getObject<T extends object>(settingName: SettingName, defaultValue: T): T;
+    getObject<T extends object>(settingName: SettingName): T | undefined;
+    /** Look up the value of an array [[Setting]] named `settingName`, returning `defaultValue` if no such value is defined.
+     * @throws Error if the setting exists but is not an array.
+     */
+    getArray<T extends Setting>(settingName: SettingName, defaultValue: Array<T>): Array<T>;
+    getArray<T extends Setting>(settingName: SettingName): Array<T> | undefined;
+}
+//# sourceMappingURL=Settings.d.ts.map

package/lib/esm/workspace/Settings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Settings.d.ts","sourceRoot":"","sources":["../../../src/workspace/Settings.ts"],"names":[],"mappings":"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"}

package/lib/esm/workspace/Settings.js

@@ -0,0 +1,83 @@
+/*---------------------------------------------------------------------------------------------
+* Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+* See LICENSE.md in the project root for license terms and full copyright notice.
+*--------------------------------------------------------------------------------------------*/
+/** @packageDocumentation
+ * @module Workspace
+ */
+import { _implementationProhibited } from "../internal/Symbols";
+/** @beta */
+export var Setting;
+(function (Setting) {
+    /** Create a deep copy of a [[Setting]]. */
+    function clone(setting) {
+        if (!setting || typeof setting !== "object")
+            return setting;
+        const result = Array.isArray(setting) ? [] : {};
+        Object.keys(setting).forEach((key) => result[key] = clone(setting[key]));
+        return result;
+    }
+    Setting.clone = clone;
+    /** Returns true if `a` and `b` are considered equivalent [[Setting]] values.
+     * Settings of primitive types like `number` and `string` are compared using `===`.
+     * Settings of type "object" are compared by comparing each property using `areEqual`; the objects are considered
+     * equal if they have the exact same set of property names with equivalent values.
+     * Settings of type "array" are compared by comparing each element of the arrays use `areEqual`; the arrays are considered
+     * equal if they have the same number of elements with equivalent values in the same exact order.
+     */
+    function areEqual(a, b) {
+        if (a === b) {
+            return true;
+        }
+        // For primitive types, === suffices.
+        if (typeof a !== "object" || typeof b !== "object") {
+            return false;
+        }
+        if (Array.isArray(a) || Array.isArray(b)) {
+            if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) {
+                return false;
+            }
+            for (let i = 0; i < a.length; i++) {
+                if (!areEqual(a[i], b[i])) {
+                    return false;
+                }
+            }
+            return true;
+        }
+        const aKeys = Object.keys(a);
+        const bKeys = Object.keys(b);
+        if (aKeys.length !== bKeys.length) {
+            return false;
+        }
+        aKeys.sort();
+        bKeys.sort();
+        for (let i = 0; i < aKeys.length; i++) {
+            const key = aKeys[i];
+            if (key !== bKeys[i]) {
+                return false;
+            }
+            if (!areEqual(a[key], b[key])) {
+                return false;
+            }
+        }
+        return true;
+    }
+    Setting.areEqual = areEqual;
+})(Setting || (Setting = {}));
+/** @beta */
+export var SettingsPriority;
+(function (SettingsPriority) {
+    /** Settings that originate from default setting files loaded automatically at the start of a session. */
+    SettingsPriority.defaults = 100;
+    /** Settings supplied by an application at runtime. */
+    SettingsPriority.application = 200;
+    /** Settings that apply to all iTwins for an organization. */
+    SettingsPriority.organization = 300;
+    /** Settings that apply to all iModels in an iTwin. */
+    SettingsPriority.iTwin = 400;
+    /** Settings that apply to all branches of an iModel. */
+    SettingsPriority.branch = 500;
+    /** Settings that apply to a specific iModel. */
+    SettingsPriority.iModel = 600;
+})(SettingsPriority || (SettingsPriority = {}));
+//# sourceMappingURL=Settings.js.map

package/lib/esm/workspace/Settings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Settings.js","sourceRoot":"","sources":["../../../src/workspace/Settings.ts"],"names":[],"mappings":"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","sourcesContent":["/*---------------------------------------------------------------------------------------------\n* Copyright (c) Bentley Systems, Incorporated. All rights reserved.\n* See LICENSE.md in the project root for license terms and full copyright notice.\n*--------------------------------------------------------------------------------------------*/\n/** @packageDocumentation\n * @module Workspace\n */\n\nimport { BeEvent, JSONSchemaType } from \"@itwin/core-bentley\";\nimport { LocalDirName, LocalFileName } from \"@itwin/core-common\";\nimport { WorkspaceDb } from \"./Workspace\";\nimport { _implementationProhibited } from \"../internal/Symbols\";\n\n/** The value of a single named parameter within a [[Workspace.settings]] that configures some aspect of the applications run-time behavior.\n * Settings are stored in a [[SettingsDictionary]]. A setting is described by its [[SettingSchema]].\n * @beta\n */\nexport type Setting = JSONSchemaType;\n\n/** @beta */\nexport namespace Setting { // eslint-disable-line @typescript-eslint/no-redeclare\n  /** Create a deep copy of a [[Setting]]. */\n  export function clone<T extends Setting>(setting: T): T {\n    if (!setting || typeof setting !== \"object\")\n      return setting;\n\n    const result = Array.isArray(setting) ? [] : {} as any;\n    Object.keys(setting).forEach((key: string) => result[key] = clone((setting as any)[key]));\n    return result;\n  }\n\n  /** Returns true if `a` and `b` are considered equivalent [[Setting]] values.\n   * Settings of primitive types like `number` and `string` are compared using `===`.\n   * Settings of type \"object\" are compared by comparing each property using `areEqual`; the objects are considered\n   * equal if they have the exact same set of property names with equivalent values.\n   * Settings of type \"array\" are compared by comparing each element of the arrays use `areEqual`; the arrays are considered\n   * equal if they have the same number of elements with equivalent values in the same exact order.\n   */\n  export function areEqual(a: Setting | undefined, b: Setting | undefined): boolean {\n    if (a === b) {\n      return true;\n    }\n\n    // For primitive types, === suffices.\n    if (typeof a !== \"object\" || typeof b !== \"object\") {\n      return false;\n    }\n\n    if (Array.isArray(a) || Array.isArray(b)) {\n      if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) {\n        return false;\n      }\n\n      for (let i = 0; i < a.length; i++) {\n        if (!areEqual(a[i], b[i])) {\n          return false;\n        }\n      }\n\n      return true;\n    }\n\n    const aKeys = Object.keys(a);\n    const bKeys = Object.keys(b);\n    if (aKeys.length !== bKeys.length) {\n      return false;\n    }\n\n    aKeys.sort();\n    bKeys.sort();\n    for (let i = 0; i < aKeys.length; i++) {\n      const key = aKeys[i];\n      if (key !== bKeys[i]) {\n        return false;\n      }\n\n      if (!areEqual((a as SettingsContainer)[key], (b as SettingsContainer)[key])) {\n        return false;\n      }\n    }\n\n    return true;\n  }\n}\n\n/**\n * The name of a [[Setting]].\n * Setting names must be [valid JavaScript property names](https://developer.mozilla.org/en-US/docs/Glossary/property/JavaScript) containing no spaces or periods.\n * The name of a setting begins with the schema prefix of the [[SettingGroupSchema]] in which its [[SettingSchema]] is defined.\n * A setting name therefore forms a path like file names in a file system.\n * For example, the following are setting names defined in the `energyAnalysis`, `iot-scan-visualization`, and `vibration-map` schemas.\n *\n * ```ts\n * \"energyAnalysis/formats/totalWork\"\n * \"energyAnalysis/formats/totalHours\"\n * \"energyAnalysis/units/power\"\n * \"energyAnalysis/units/temperature\"\n * \"energyAnalysis/startupMode\"\n * \"iot-scan-visualization/ports/cameras\"\n * \"vibration-map/filters/scope\"\n * \"vibration-map/filters/prefabricated\"\n * ```\n *\n * @beta\n */\nexport type SettingName = string;\n\n/** An object that defines the values for any number of [[Setting]]s. Each of its properties' names must conform to the semantics of a [[SettingName]].\n * @beta\n */\nexport interface SettingsContainer {\n  /** Accesses settings by their names. */\n  [name: SettingName]: Setting | undefined;\n}\n\n/** Defines the precedence of a [[SettingsDictionary]].\n * [[Settings]] may contain multiple dictionaries containing different values for the same [[SettingName]].\n * When resolving the value of a [[Setting]], the value from the highest-priority dictionary is used.\n * Priorities are grouped into coarse categories like [[SettingsPriority.application]] and [[SettingsPriority.iModel]].\n * Settings with priorities less than or equal to [[SettingsPriority.application]] are stored in [[IModelHost.appWorkspace]], while\n * those with priorities higher than [[SettingsPriority.application]] are stored inside [[IModelDb.workspace]].\n * @beta\n */\nexport type SettingsPriority = number;\n\n/** @beta */\nexport namespace SettingsPriority { // eslint-disable-line @typescript-eslint/no-redeclare\n  /** Settings that originate from default setting files loaded automatically at the start of a session. */\n  export const defaults = 100;\n  /** Settings supplied by an application at runtime. */\n  export const application = 200;\n  /** Settings that apply to all iTwins for an organization. */\n  export const organization = 300;\n  /** Settings that apply to all iModels in an iTwin. */\n  export const iTwin = 400;\n  /** Settings that apply to all branches of an iModel. */\n  export const branch = 500;\n  /** Settings that apply to a specific iModel. */\n  export const iModel = 600;\n}\n\n/** A named container that supplies values for [[Setting]]s.\n * @see [[Settings.addDictionary]] to register a new settings dictionary.\n * @beta\n */\nexport interface SettingsDictionary {\n  /** @internal */\n  [_implementationProhibited]: unknown;\n\n  /** Metadata describing the dictionary. */\n  readonly props: SettingsDictionaryProps;\n\n  /** Obtain a copy of the value of the setting named `settingName` stored in this dictionary, or `undefined` if no such setting exists.\n   * The returned value is always cloned using [[Setting.clone]].\n   * @note Generally, applications use methods like [[Settings.getString]] and [[Setting.getArray]] to resolve a setting value from multiple\n   * dictionaries. Those methods - unlike this one - also validate that `settingName` is of type `T` as defined by its [[SettingSchema]].\n   */\n  getSetting<T extends Setting>(settingName: SettingName): T | undefined;\n}\n\n/** Uniquely identifies a [[SettingsDictionary]].\n * @beta\n */\nexport interface SettingsDictionarySource {\n  /** The name of the dictionary, which must be unique within its [[workspaceDb]], or - if [[workspaceDb]] is undefined - unique among all dictionaries not associated with any [[WorkspaceDb]]. */\n  readonly name: string;\n  /** The [[WorkspaceDb]] from which the dictionary originated. */\n  readonly workspaceDb?: WorkspaceDb;\n}\n\n/** Properties of a [[SettingsDictionary]], defining its name, the [[WorkspaceDb]] (if any) from which it originated, and its [[priority]] relative to other dictionaries.\n * @beta\n */\nexport interface SettingsDictionaryProps extends SettingsDictionarySource {\n  /** Precedence value determining which setting value to use when multiple dictionaries supply values for the same [[SettingName]]. */\n  readonly priority: SettingsPriority;\n}\n\n/**\n * The collection of [[Setting]]s that supply the run-time configuration of a [[Workspace]].\n * The `Settings` object comprises a collection of named [[SettingsDictionary]] objects.\n * Methods like [[getSetting]], [[getString]], and [[getArray]] provide access to the value of an individual [[Setting]] by searching\n * the [[dictionaries]] in order by their [[SettingsPriority]] to find the highest-priority setting with the requested [[SettingName]].\n * Most methods that retrieve [[Setting]] values validate them against their [[SettingSchema]]s to ensure that they are of the correct type.\n * A [[SettingsDictionary]] can be added or removed using [[addDictionary]] and [[dropDictionary]].\n * Because [[Setting]]s can change at any time during the session, you should avoid caching their values wherever possible.\n * If you must cache them (for example, to display in a user interface), you should listen for the [[onSettingsChanged]] event to be\n * notified of potential changes.\n *\n * Settings are accessed via [[Workspace.settings]]. They are defined at the application level by [[IModelHost.appWorkspace]], but individual iModels may supply\n * additional iModel-specific settings or overrides for application-level settings. When working in the context of a specific iModel, use [[IModelDb.workspace]]'s `settings`\n * property. Any settings not overridden by the iModel will fall back to the settings defined in [[IModelHost.appWorkspace]].\n *\n * Application settings are loaded into [[IModelHost.appWorkspace]] when the session begins (i.e., when [[IModelHost.startup]] is invoked), and unloaded when it ends (in [[IModelHost.shutdown]]).\n * They are read from [JSON5](https://json5.org/) files delivered with the application. The application should register any additional [[SettingsDictionary]]'s '(and their corresponding\n * [[SettingGroupSchema]]s) at this time.\n *\n * iModel-specific settings are stored in the iModel's property table and loaded into [[IModelDb.workspace]] when the iModel is first opened.\n * You can add and remove a [[SettingsDictionary]] from the property table using [[IModelDb.saveSettingDictionary]] and [[IModelDb.deleteSettingDictionary]].\n *\n * See the [learning article]($docs/learning/backend/Workspace) for a detailed overiew and examples.\n *\n * @see [[IModelHost.appWorkspace]] application-wide settings, and [[IModelDb.workspace]] for settings specific to a given iModel.\n * @beta\n */\nexport interface Settings {\n  /** @internal */\n  [_implementationProhibited]: unknown;\n\n  /** @internal */\n  close(): void;\n\n  /** The set of settings dictionaries from which [[Setting]] values are obtained, sorted by [[SettingsPriority]].\n   * The set can contain at most one dictionary for each unique combination of name and [[WorkspaceDb]].\n   * @see [[addDictionary]], [[addFile]], [[addJson]], and [[addDirectory]] to add a new dictionary.\n   * @see [[dropDictionary]] to remove a dictionary.\n   * @see [[getDictionary]] to look up a dictionary.\n   */\n  readonly dictionaries: readonly SettingsDictionary[];\n\n  /** Event raised whenever a [[SettingsDictionary]] is added or removed. */\n  readonly onSettingsChanged: BeEvent<() => void>;\n\n  /** Parses the contents of a local [JSON5](https://json5.org/) file as a [[SettingsContainer]] and invokes [[addDictionary]] to\n   * add a [[SettingsDictionary]] named `fileName` with the specified priority.\n   * @param fileName the name of a local settings file containing the dictionary.\n   * @param priority the priority for the dictionary.\n   */\n  addFile(fileName: LocalFileName, priority: SettingsPriority): void;\n\n  /** Invokes [[addFile]] for all files in `directory` with the extension \".json\" or \".json5\". */\n  addDirectory(directory: LocalDirName, priority: SettingsPriority): void;\n\n  /** Parses `settingsJson` as a [[SettingsContainer]] and invokes [[addDictionary]] to add a [[SettingsDictionary]] with the specified `props`.\n   * This is typically used when reading dictionaries out of a [[WorkspaceDb]], where they are stored as stringified JSON.\n   */\n  addJson(props: SettingsDictionaryProps, settingsJson: string): void;\n\n  /** Find a [[SettingsDictionary]] with the same name and [[WorkspaceDb]] as `source`. */\n  getDictionary(source: SettingsDictionarySource): SettingsDictionary | undefined;\n\n  /** Add a new [[SettingsDictionary]] with the priority, name, and [[WorkspaceDb]] specified by `props` and setting values supplied by `settings`.\n   * @note If a dictionary with the same name and [[WorkspaceDb]] already exists, it will be replaced.\n   * @see [[addFile]], [[addJson]], and [[addDirectory]] for convenient ways to add dictionaries from various sources.\n   */\n  addDictionary(props: SettingsDictionaryProps, settings: SettingsContainer): void;\n\n  /** Removes a previously-added [[SettingsDictionary]]. */\n  dropDictionary(props: SettingsDictionarySource): void;\n\n  /** Looks up the highest priority setting value for a SettingName, falling back to a default value if no value for the setting is found.\n   * The [[dictionaries]] are searched in order by [[SettingsPriority]]; the first one that provides a value for `settingName` wins.\n   * @param settingName The name of the setting.\n   * @param defaultValue value returned if settingName is not present in any [[SettingsDictionary]].\n   * @note This method is generic on [[Setting]] type, but no type checking is actually performed at run time. So, if you\n   * use this method to get a setting with an expected type, but its value is a different type, the return type of this method will be wrong.\n   * You must always type check the result. Use the non-generic \"get\" methods like [[getString]] and [[getArray]] if you only want the value\n   * if its type is correct.\n   * @note Unlike [[getArray]], this method does not combine arrays - it ignores [[SettingsSchema.combineArrays]].\n   */\n  getSetting<T extends Setting>(settingName: SettingName, defaultValue?: T): T | undefined;\n\n  /** Obtain an iterator over all of the values in the [[dictionaries]] for the [[Setting]] identified by `settingName`, ordered by [[SettingsPriority]]. */\n  getSettingEntries<T extends Setting>(settingName: SettingName): Iterable<{ value: T, dictionary: SettingsDictionary}>;\n\n  /** Obtain an iterator over all of the values in the [[dictionaries]] for the [[Setting]] identified by `settingName`, ordered by [[SettingsPriority]]. */\n  getSettingValues<T extends Setting>(settingName: SettingName): Iterable<T>;\n\n  /** Look up the value of a string [[Setting]] named `settingName`, returning `defaultValue` if no such value is defined.\n   * @throws Error if the setting exists but is not a string.\n   */\n  getString(settingName: SettingName, defaultValue: string): string;\n  getString(settingName: SettingName, defaultValue?: string): string | undefined;\n\n  /** Look up the value of a boolean [[Setting]] named `settingName`, returning `defaultValue` if no such value is defined.\n   * @throws Error if the setting exists but is not a boolean.\n   */\n  getBoolean(settingName: SettingName, defaultValue: boolean): boolean;\n  getBoolean(settingName: SettingName, defaultValue?: boolean): boolean | undefined;\n\n  /** Look up the value of a numeric [[Setting]] named `settingName`, returning `defaultValue` if no such value is defined.\n   * @throws Error if the setting exists but is not a number.\n   */\n  getNumber(settingName: SettingName, defaultValue: number): number;\n  getNumber(settingName: SettingName): number | undefined;\n\n  /** Look up the value of an object [[Setting]] named `settingName`, returning `defaultValue` if no such value is defined.\n   * @throws Error if the setting exists but is not an object.\n   */\n  getObject<T extends object>(settingName: SettingName, defaultValue: T): T;\n  getObject<T extends object>(settingName: SettingName): T | undefined;\n\n  /** Look up the value of an array [[Setting]] named `settingName`, returning `defaultValue` if no such value is defined.\n   * @throws Error if the setting exists but is not an array.\n   */\n  getArray<T extends Setting>(settingName: SettingName, defaultValue: Array<T>): Array<T>;\n  getArray<T extends Setting>(settingName: SettingName): Array<T> | undefined;\n}\n"]}

package/lib/esm/workspace/SettingsSchemas.d.ts

@@ -0,0 +1,135 @@
+/** @packageDocumentation
+ * @module Workspace
+ */
+import { BeEvent, JSONSchema, JSONSchemaTypeName } from "@itwin/core-bentley";
+import { LocalDirName, LocalFileName } from "@itwin/core-common";
+import { _implementationProhibited } from "../internal/Symbols";
+import { SettingName } from "./Settings";
+/** Metadata describing a single [[Setting]] as part of a [[SettingGroupSchema]].
+  * Every setting has a [[type]], which can be one of the following:
+  * - A primitive type like `string` or `number`;
+  * - An object containing any number of named properties, each with their own types; or
+  * - An array of elements, all of the same type.
+  * This metadata is used to validate setting values against the schema, and to enable user interfaces by which
+  * users can view and modify their settings.
+  * @beta
+  */
+export interface SettingSchema extends Readonly<JSONSchema> {
+    /** For arrays only, the metadata describing every element in the array. */
+    readonly items?: SettingSchema;
+    /** The name of the [[Setting]]'s data type. */
+    readonly type: JSONSchemaTypeName;
+    /** For objects and arrays only, the name of a [[SettingSchema]] that provides a base definition for this type.
+     * The name is expected to refer to a type definition registered with [[SettingsSchema.typeDefs]].
+     * Therefore, it must be the full name, including the [[SettingGroupSchema.schemaPrefix]].
+     */
+    readonly extends?: string;
+    /** For objects only, the name and metadata of each of the object's properties. */
+    readonly properties?: {
+        [name: SettingName]: SettingSchema;
+    };
+    /** For arrays only, specifies how [[SettingsDictionary.getArray]] resolves the value of the setting.
+     * By default, like other types of settings, the setting uses the value of the setting from the highest-priority dictionary.
+     * If `combineArray` is `true`, then the value of the setting is computed by combining the elements of every array from every dictionary,
+     * ordered by priority and eliminating duplicate elements.
+     * Two elements are considered duplicates of one another if [[Setting.areEqual]] returns `true`.
+     */
+    readonly combineArray?: boolean;
+}
+/** Metadata describing a group of related [[SettingSchema]]s. You can register setting schema groups via [[SettingsSchemas.addGroup]] and
+  * remove them via [[SettingsSchemas.removeGroup]].
+  *
+  * All of the settings share the same [[schemaPrefix]], which must be unique amongst all other groups.
+  * The prefix is combined with the name of each [[SettingSchema]] in the group to form the fully-qualified name used to refer
+  * to the setting outside of the group, e.g., when accessing [[SettingsSchemas.settingDefs]] or in [[SettingSchema.extends]].
+  * In the following example, the fully-qualified name of the setting named "metric" is "format/units/metric".
+  *
+  * ```json
+  *  {
+  *    "schemaPrefix": "format/units",
+  *    "settingDefs": {
+  *      "metric": { "type": "boolean" }
+  *    }
+  *  }
+  * ```
+  *
+  * A group can also define [[SettingSchema]]s that, rather than describing actual [[Setting]]s, instead describe types that can be extended by [[Setting]]s via
+  * [[SettingSchema.extends]]. A [[SettingSchema]] can refer to type definitions defined in its own group or any other group.
+  * @beta
+  */
+export interface SettingGroupSchema {
+    /** Uniquely identifies this group amongst all other groups.
+     * The prefix can use forward-slashes to define logical subgroups - for example, two related groups with the prefixes "units/metric" and "units/imperial".
+     * The user interface may parse these prefixes to display both groups under a "units" tab or expandable tree view node.
+     *
+     * @note Schema prefixes beginning with "itwin" are reserved for use by iTwin.js.
+     */
+    readonly schemaPrefix: string;
+    /** Metadata for each [[Setting]] in this group. */
+    readonly settingDefs?: {
+        [name: string]: SettingSchema | undefined;
+    };
+    /** Metadata for types that can be extended by other [[Setting]]s via [[SettingSchema.extends]]. */
+    readonly typeDefs?: {
+        [name: string]: SettingSchema | undefined;
+    };
+    /** An integer used when displaying a list of schemas in a user interface, to sort schemas with a lower `order` before those with a `higher` order. */
+    readonly order?: number;
+    /** A description of this group suitable for displaying to a user. */
+    readonly description: string;
+}
+/**
+ * The registry of available [[SettingGroupSchema]]s.
+ * The registry is used for editing Settings files and for finding default values for settings.
+ * @beta
+ */
+/** The registry of metadata describing groups of [[SettingSchema]]s available to the current session.
+  * The schemas are used to look up the default values of [[Setting]]s, validate that their values are of the type dictated by the schema, and
+  * query metadata like [[SettingsSchema.combineArray]] that modify their behavior.
+  * They can also be used to drive a user interface that enables end users to edit [[Settings]].
+  *
+  * When [[IModelHost.startup]] is invoked at the beginning of a session, schemas delivered with the application - like those describing
+  * [[Workspace]]s - are automatically loaded.
+  * The application can manually register additional schemas using methods like [[addGroup]], [[addFile]], [[addDirectory]], and [[addJson]].
+  * When [[IModelHost.shutdown]] is invoked at the end of a session, all registered schemas are unregistered.
+  *
+  * See the [learning article]($docs/learning/backend/Workspace) for a detailed overiew and examples.
+  *
+  * @see [[IModelHost.settingsSchemas]] to access the registry for the current session.
+  * @beta
+  */
+export interface SettingsSchemas {
+    /** @internal */
+    readonly [_implementationProhibited]: unknown;
+    /** The map of each individual registered [[SettingSchema]] defining a [[Setting]], accessed by its fully-qualified name (including its [[SettingGroupSchema.schemaPrefix]]). */
+    readonly settingDefs: ReadonlyMap<SettingName, SettingSchema>;
+    /** The map of each individual registered [[SettingSchema]] defining a type that can be extended by other [[SettingSchema]]s via [[SettingSchema.extends]],
+     * accessed by its fully-qualified name (including its [[SettingGroupSchema.schemaPrefix]]).
+     */
+    readonly typeDefs: ReadonlyMap<SettingName, SettingSchema>;
+    /** An event raised whenever schemas are added or removed. */
+    readonly onSchemaChanged: BeEvent<() => void>;
+    /**
+     * Ensure that the setting value supplied is valid according to its [[SettingSchema]].
+     * If no schema has been registered for the setting, no validation is performed.
+     * @param value The value of the setting to validate against the schema.
+     * @param settingName The fully-qualified setting name.
+     * @returns `value` if `value` matches the schema corresponding to `settingName`, or if no such schema has been registered.
+     * @throws Error if `value` is invalid according to the schema.
+     */
+    validateSetting<T>(value: T, settingName: SettingName): T;
+    /** Register one or more [[SettingGroupSchema]]s.
+     * If a group with the same [[SettingGroupSchema.prefix]] was previously registered, it will be replaced.
+     * Each [[SettingSchema]] in the group will be added to [[settingDefs]] or [[typeDefs]].
+     */
+    addGroup(settingsGroup: SettingGroupSchema | SettingGroupSchema[]): void;
+    /** Invokes [[addGroup]] for a [[SettingGroupSchema]] supplied as stringified json5. */
+    addJson(settingSchema: string): void;
+    /** Invokes [[addGroup]] for a json5 file containiner a [[SettingGroupSchema]]. */
+    addFile(fileName: LocalFileName): void;
+    /** Invokes [[addFile]] for every json and json5 file in the specified directory. */
+    addDirectory(dirName: LocalDirName): void;
+    /** Unregisters all [[settingDefs]] and [[typeDefs]] with the specified [[SettingGroupSchema.schemaPrefix]]. */
+    removeGroup(schemaPrefix: string): void;
+}
+//# sourceMappingURL=SettingsSchemas.d.ts.map

package/lib/esm/workspace/SettingsSchemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SettingsSchemas.d.ts","sourceRoot":"","sources":["../../../src/workspace/SettingsSchemas.ts"],"names":[],"mappings":"AAIA;;GAEG;AAEH,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAC9E,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACjE,OAAO,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AAChE,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEzC;;;;;;;;IAQI;AACJ,MAAM,WAAW,aAAc,SAAQ,QAAQ,CAAC,UAAU,CAAC;IACzD,2EAA2E;IAC3E,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC;IAC/B,+CAA+C;IAC/C,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,kFAAkF;IAClF,QAAQ,CAAC,UAAU,CAAC,EAAE;QAAE,CAAC,IAAI,EAAE,WAAW,GAAG,aAAa,CAAA;KAAE,CAAC;IAC7D;;;;;OAKG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;;;;IAoBI;AACJ,MAAM,WAAW,kBAAkB;IACjC;;;;;OAKG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,mDAAmD;IACnD,QAAQ,CAAC,WAAW,CAAC,EAAE;QAAE,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAAA;KAAE,CAAC;IACrE,mGAAmG;IACnG,QAAQ,CAAC,QAAQ,CAAC,EAAE;QAAE,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAAA;KAAE,CAAC;IAClE,sJAAsJ;IACtJ,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,qEAAqE;IACrE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;;;GAIG;AAEH;;;;;;;;;;;;;;IAcI;AACJ,MAAM,WAAW,eAAe;IAC9B,gBAAgB;IAChB,QAAQ,CAAC,CAAC,yBAAyB,CAAC,EAAE,OAAO,CAAC;IAE9C,gLAAgL;IAChL,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC,WAAW,EAAE,aAAa,CAAC,CAAC;IAE9D;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,WAAW,EAAE,aAAa,CAAC,CAAC;IAE3D,6DAA6D;IAC7D,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC,MAAM,IAAI,CAAC,CAAC;IAE9C;;;;;;;OAOG;IACH,eAAe,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,WAAW,EAAE,WAAW,GAAG,CAAC,CAAC;IAE1D;;;OAGG;IACH,QAAQ,CAAC,aAAa,EAAE,kBAAkB,GAAG,kBAAkB,EAAE,GAAG,IAAI,CAAC;IAEzE,uFAAuF;IACvF,OAAO,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAErC,kFAAkF;IAClF,OAAO,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI,CAAC;IAEvC,oFAAoF;IACpF,YAAY,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI,CAAC;IAE1C,+GAA+G;IAC/G,WAAW,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CACzC"}

package/lib/esm/workspace/SettingsSchemas.js

@@ -0,0 +1,9 @@
+/*---------------------------------------------------------------------------------------------
+* Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+* See LICENSE.md in the project root for license terms and full copyright notice.
+*--------------------------------------------------------------------------------------------*/
+/** @packageDocumentation
+ * @module Workspace
+ */
+import { _implementationProhibited } from "../internal/Symbols";
+//# sourceMappingURL=SettingsSchemas.js.map

package/lib/esm/workspace/SettingsSchemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SettingsSchemas.js","sourceRoot":"","sources":["../../../src/workspace/SettingsSchemas.ts"],"names":[],"mappings":"AAAA;;;+FAG+F;AAC/F;;GAEG;AAIH,OAAO,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC","sourcesContent":["/*---------------------------------------------------------------------------------------------\n* Copyright (c) Bentley Systems, Incorporated. All rights reserved.\n* See LICENSE.md in the project root for license terms and full copyright notice.\n*--------------------------------------------------------------------------------------------*/\n/** @packageDocumentation\n * @module Workspace\n */\n\nimport { BeEvent, JSONSchema, JSONSchemaTypeName } from \"@itwin/core-bentley\";\nimport { LocalDirName, LocalFileName } from \"@itwin/core-common\";\nimport { _implementationProhibited } from \"../internal/Symbols\";\nimport { SettingName } from \"./Settings\";\n\n/** Metadata describing a single [[Setting]] as part of a [[SettingGroupSchema]].\n  * Every setting has a [[type]], which can be one of the following:\n  * - A primitive type like `string` or `number`;\n  * - An object containing any number of named properties, each with their own types; or\n  * - An array of elements, all of the same type.\n  * This metadata is used to validate setting values against the schema, and to enable user interfaces by which\n  * users can view and modify their settings.\n  * @beta\n  */\nexport interface SettingSchema extends Readonly<JSONSchema> {\n  /** For arrays only, the metadata describing every element in the array. */\n  readonly items?: SettingSchema;\n  /** The name of the [[Setting]]'s data type. */\n  readonly type: JSONSchemaTypeName;\n  /** For objects and arrays only, the name of a [[SettingSchema]] that provides a base definition for this type.\n   * The name is expected to refer to a type definition registered with [[SettingsSchema.typeDefs]].\n   * Therefore, it must be the full name, including the [[SettingGroupSchema.schemaPrefix]].\n   */\n  readonly extends?: string;\n  /** For objects only, the name and metadata of each of the object's properties. */\n  readonly properties?: { [name: SettingName]: SettingSchema };\n  /** For arrays only, specifies how [[SettingsDictionary.getArray]] resolves the value of the setting.\n   * By default, like other types of settings, the setting uses the value of the setting from the highest-priority dictionary.\n   * If `combineArray` is `true`, then the value of the setting is computed by combining the elements of every array from every dictionary,\n   * ordered by priority and eliminating duplicate elements.\n   * Two elements are considered duplicates of one another if [[Setting.areEqual]] returns `true`.\n   */\n  readonly combineArray?: boolean;\n}\n\n/** Metadata describing a group of related [[SettingSchema]]s. You can register setting schema groups via [[SettingsSchemas.addGroup]] and\n  * remove them via [[SettingsSchemas.removeGroup]].\n  *\n  * All of the settings share the same [[schemaPrefix]], which must be unique amongst all other groups.\n  * The prefix is combined with the name of each [[SettingSchema]] in the group to form the fully-qualified name used to refer\n  * to the setting outside of the group, e.g., when accessing [[SettingsSchemas.settingDefs]] or in [[SettingSchema.extends]].\n  * In the following example, the fully-qualified name of the setting named \"metric\" is \"format/units/metric\".\n  *\n  * ```json\n  *  {\n  *    \"schemaPrefix\": \"format/units\",\n  *    \"settingDefs\": {\n  *      \"metric\": { \"type\": \"boolean\" }\n  *    }\n  *  }\n  * ```\n  *\n  * A group can also define [[SettingSchema]]s that, rather than describing actual [[Setting]]s, instead describe types that can be extended by [[Setting]]s via\n  * [[SettingSchema.extends]]. A [[SettingSchema]] can refer to type definitions defined in its own group or any other group.\n  * @beta\n  */\nexport interface SettingGroupSchema {\n  /** Uniquely identifies this group amongst all other groups.\n   * The prefix can use forward-slashes to define logical subgroups - for example, two related groups with the prefixes \"units/metric\" and \"units/imperial\".\n   * The user interface may parse these prefixes to display both groups under a \"units\" tab or expandable tree view node.\n   *\n   * @note Schema prefixes beginning with \"itwin\" are reserved for use by iTwin.js.\n   */\n  readonly schemaPrefix: string;\n  /** Metadata for each [[Setting]] in this group. */\n  readonly settingDefs?: { [name: string]: SettingSchema | undefined };\n  /** Metadata for types that can be extended by other [[Setting]]s via [[SettingSchema.extends]]. */\n  readonly typeDefs?: { [name: string]: SettingSchema | undefined };\n  /** An integer used when displaying a list of schemas in a user interface, to sort schemas with a lower `order` before those with a `higher` order. */\n  readonly order?: number;\n  /** A description of this group suitable for displaying to a user. */\n  readonly description: string;\n}\n\n/**\n * The registry of available [[SettingGroupSchema]]s.\n * The registry is used for editing Settings files and for finding default values for settings.\n * @beta\n */\n\n/** The registry of metadata describing groups of [[SettingSchema]]s available to the current session.\n  * The schemas are used to look up the default values of [[Setting]]s, validate that their values are of the type dictated by the schema, and\n  * query metadata like [[SettingsSchema.combineArray]] that modify their behavior.\n  * They can also be used to drive a user interface that enables end users to edit [[Settings]].\n  *\n  * When [[IModelHost.startup]] is invoked at the beginning of a session, schemas delivered with the application - like those describing\n  * [[Workspace]]s - are automatically loaded.\n  * The application can manually register additional schemas using methods like [[addGroup]], [[addFile]], [[addDirectory]], and [[addJson]].\n  * When [[IModelHost.shutdown]] is invoked at the end of a session, all registered schemas are unregistered.\n  *\n  * See the [learning article]($docs/learning/backend/Workspace) for a detailed overiew and examples.\n  *\n  * @see [[IModelHost.settingsSchemas]] to access the registry for the current session.\n  * @beta\n  */\nexport interface SettingsSchemas {\n  /** @internal */\n  readonly [_implementationProhibited]: unknown;\n\n  /** The map of each individual registered [[SettingSchema]] defining a [[Setting]], accessed by its fully-qualified name (including its [[SettingGroupSchema.schemaPrefix]]). */\n  readonly settingDefs: ReadonlyMap<SettingName, SettingSchema>;\n\n  /** The map of each individual registered [[SettingSchema]] defining a type that can be extended by other [[SettingSchema]]s via [[SettingSchema.extends]],\n   * accessed by its fully-qualified name (including its [[SettingGroupSchema.schemaPrefix]]).\n   */\n  readonly typeDefs: ReadonlyMap<SettingName, SettingSchema>;\n\n  /** An event raised whenever schemas are added or removed. */\n  readonly onSchemaChanged: BeEvent<() => void>;\n\n  /**\n   * Ensure that the setting value supplied is valid according to its [[SettingSchema]].\n   * If no schema has been registered for the setting, no validation is performed.\n   * @param value The value of the setting to validate against the schema.\n   * @param settingName The fully-qualified setting name.\n   * @returns `value` if `value` matches the schema corresponding to `settingName`, or if no such schema has been registered.\n   * @throws Error if `value` is invalid according to the schema.\n   */\n  validateSetting<T>(value: T, settingName: SettingName): T;\n\n  /** Register one or more [[SettingGroupSchema]]s.\n   * If a group with the same [[SettingGroupSchema.prefix]] was previously registered, it will be replaced.\n   * Each [[SettingSchema]] in the group will be added to [[settingDefs]] or [[typeDefs]].\n   */\n  addGroup(settingsGroup: SettingGroupSchema | SettingGroupSchema[]): void;\n\n  /** Invokes [[addGroup]] for a [[SettingGroupSchema]] supplied as stringified json5. */\n  addJson(settingSchema: string): void;\n\n  /** Invokes [[addGroup]] for a json5 file containiner a [[SettingGroupSchema]]. */\n  addFile(fileName: LocalFileName): void;\n\n  /** Invokes [[addFile]] for every json and json5 file in the specified directory. */\n  addDirectory(dirName: LocalDirName): void;\n\n  /** Unregisters all [[settingDefs]] and [[typeDefs]] with the specified [[SettingGroupSchema.schemaPrefix]]. */\n  removeGroup(schemaPrefix: string): void;\n}\n"]}