improve TSDoc for model version types (#158799)

## Summary

Just add some more documentation and examples to the model version types

packages/core/saved-objects/core-saved-objects-server/index.ts

@@ -136,6 +136,7 @@ export type {
   SavedObjectModelDataBackfillFn,
   SavedObjectsModelVersionSchemaDefinitions,
   SavedObjectModelVersionForwardCompatibilityFn,
+  SavedObjectModelVersionForwardCompatibilityObjectSchema,
   SavedObjectModelVersionForwardCompatibilitySchema,
 } from './src/model_version';
 

packages/core/saved-objects/core-saved-objects-server/src/model_version/index.ts

@@ -31,5 +31,6 @@ export type {
 export type {
   SavedObjectsModelVersionSchemaDefinitions,
   SavedObjectModelVersionForwardCompatibilitySchema,
+  SavedObjectModelVersionForwardCompatibilityObjectSchema,
   SavedObjectModelVersionForwardCompatibilityFn,
 } from './schemas';

packages/core/saved-objects/core-saved-objects-server/src/model_version/model_change.ts

@@ -27,6 +27,21 @@ export type SavedObjectsModelChange =
 /**
  * A {@link SavedObjectsModelChange | model change} adding new mappings.
  *
+ * @example
+ * ```ts
+ * let change: SavedObjectsModelMappingsAdditionChange = {
+ *   type: 'mappings_addition',
+ *   addedMappings: {
+ *     newField: { type: 'text' },
+ *     existingNestedField: {
+ *       properties: {
+ *         newNestedProp: { type: 'keyword' },
+ *       },
+ *     },
+ *   },
+ * };
+ * ```
+ *
  * @remark when adding mappings, {@link SavedObjectsType.mappings | the type mappings} must also be updated accordingly.
  *         Overall, the type's mapping represents the latest version of the mappings, where the model changes
  *         represent the changes of mappings between two versions.
@@ -42,8 +57,17 @@ export interface SavedObjectsModelMappingsAdditionChange {
 }
 
 /**
- * A {@link SavedObjectsModelChange | model change} flagging mappings as being deprecated.
- * Deprecated mappings should no longer be used and will eventually be deleted later.
+ * A {@link SavedObjectsModelChange | model change} flagging mappings as being no longer used.
+ *
+ * @example
+ * ```ts
+ * let change: SavedObjectsModelMappingsDeprecationChange = {
+ *   type: 'mappings_deprecation',
+ *   deprecatedMappings: ['someDeprecatedField', 'someNested.deprecatedField'],
+ * };
+ * ```
+ *
+ * @remark Deprecated mappings will eventually be deleted later.
  */
 export interface SavedObjectsModelMappingsDeprecationChange {
   type: 'mappings_deprecation';
@@ -56,6 +80,17 @@ export interface SavedObjectsModelMappingsDeprecationChange {
 /**
  * A {@link SavedObjectsModelChange | model change} used to backfill fields introduced in the same model version.
  *
+ * @example
+ * ```
+ * let change: SavedObjectsModelDataBackfillChange = {
+ *   type: 'data_backfill',
+ *   transform: (document) => {
+ *     document.attributes.someAddedField = 'defaultValue';
+ *     return { document };
+ *   },
+ * };
+ * ```
+ *
  * @remark This type of model change should only be used to backfill newly introduced fields.
  *         Even if no check is performed to ensure that, using such transformations to mutate
  *         existing data of the document can lead to data corruption or inconsistency.

packages/core/saved-objects/core-saved-objects-server/src/model_version/model_version.ts

@@ -19,7 +19,34 @@ import type { SavedObjectsModelChange } from './model_change';
  */
 export interface SavedObjectsModelVersion {
   /**
-   * The list of {@link SavedObjectsModelChange | changes} associated with this version.
+   * The list of changes associated with this version.
+   *
+   * Model version changes are defined via low-level components, allowing to use composition
+   * to describe the list of changes bound to a given version. Composition also allows to more
+   * easily merge changes from multiple source when needed.
+   *
+   * @example Adding a new indexed field with a default value
+   * ```ts
+   * const version1: SavedObjectsModelVersion = {
+   *   changes: [
+   *     {
+   *       type: 'mappings_addition',
+   *       addedMappings: {
+   *         someNewField: { type: 'text' },
+   *       },
+   *     },
+   *     {
+   *       type: 'data_backfill',
+   *       transform: (doc) => {
+   *         doc.attributes.someNewField = 'some default value';
+   *         return { document: doc };
+   *       },
+   *     },
+   *   ],
+   * };
+   * ```
+   *
+   * See {@link SavedObjectsModelChange | changes} for more information and examples.
    */
   changes: SavedObjectsModelChange[];
   /**
@@ -37,9 +64,9 @@ export interface SavedObjectsModelVersion {
  * @example
  * ```typescript
  * const modelVersionMap: SavedObjectsModelVersionMap = {
- *   '1': modelVersion1,
- *   '2': modelVersion2,
- *   '3': modelVersion3,
+ *   1: modelVersion1,
+ *   2: modelVersion2,
+ *   3: modelVersion3,
  * }
  * ```
  *

packages/core/saved-objects/core-saved-objects-server/src/model_version/schemas.ts

@@ -9,7 +9,7 @@
 import type { ObjectType } from '@kbn/config-schema';
 
 /**
- * The schemas associated with this model version.
+ * The validation and conversion schemas associated with this model version.
  *
  * @public
  */
@@ -31,14 +31,6 @@ export interface SavedObjectsModelVersionSchemaDefinitions {
   forwardCompatibility?: SavedObjectModelVersionForwardCompatibilitySchema;
 }
 
-/**
- * Plain javascript function alternative for {@link SavedObjectModelVersionForwardCompatibilitySchema}
- * @public
- */
-export type SavedObjectModelVersionForwardCompatibilityFn<InAttrs = unknown, OutAttrs = unknown> = (
-  attributes: InAttrs
-) => OutAttrs;
-
 /**
  * Schema used when retrieving a document of a higher version to convert them to the older version.
  *
@@ -46,7 +38,7 @@ export type SavedObjectModelVersionForwardCompatibilityFn<InAttrs = unknown, Out
  * - A `@kbn/config-schema`'s Object schema, that will receive the document's attributes
  * - An arbitrary function that will receive the document's attributes as parameter and should return the converted attributes
  *
- * @remark These conversion mechanism shouldn't assert the data itself, only strip unknown fields to convert
+ * @remark These conversion mechanism shouldn't assert the data itself, and only strip unknown fields to convert
  * the document to the *shape* of the document at the given version.
  *
  * @example using a function:
@@ -73,4 +65,39 @@ export type SavedObjectModelVersionForwardCompatibilityFn<InAttrs = unknown, Out
 export type SavedObjectModelVersionForwardCompatibilitySchema<
   InAttrs = unknown,
   OutAttrs = unknown
-> = ObjectType | SavedObjectModelVersionForwardCompatibilityFn<InAttrs, OutAttrs>;
+> =
+  | SavedObjectModelVersionForwardCompatibilityObjectSchema
+  | SavedObjectModelVersionForwardCompatibilityFn<InAttrs, OutAttrs>;
+
+/**
+ * Object-schema (from `@kbn/config-schema`) alternative for {@link SavedObjectModelVersionForwardCompatibilitySchema}
+ *
+ * @example
+ * ```ts
+ * const versionSchema = schema.object(
+ *   {
+ *     someField: schema.maybe(schema.string()),
+ *     anotherField: schema.maybe(schema.string()),
+ *   },
+ *   { unknowns: 'ignore' }
+ * );
+ * ```
+ * @public
+ */
+export type SavedObjectModelVersionForwardCompatibilityObjectSchema = ObjectType;
+
+/**
+ * Plain javascript function alternative for {@link SavedObjectModelVersionForwardCompatibilitySchema}
+ *
+ * @example
+ * ```ts
+ * const versionSchema: SavedObjectModelVersionForwardCompatibilityFn = (attributes) => {
+ *   const knownFields = ['someField', 'anotherField'];
+ *   return pick(attributes, knownFields);
+ * }
+ * ```
+ * @public
+ */
+export type SavedObjectModelVersionForwardCompatibilityFn<InAttrs = unknown, OutAttrs = unknown> = (
+  attributes: InAttrs
+) => OutAttrs;

packages/core/saved-objects/core-saved-objects-server/src/saved_objects_type.ts

@@ -20,6 +20,8 @@ import type {
 } from './model_version';
 
 /**
+ * Definition of a type of savedObject.
+ *
  * @public
  */
 export interface SavedObjectsType<Attributes = any> {
@@ -142,9 +144,9 @@ export interface SavedObjectsType<Attributes = any> {
    * Model versioning is decoupled from Kibana versioning, and isolated between types.
    * Model versions are identified by a single numeric value, starting at `1` and without gaps.
    *
-   * Please refer to {@link SavedObjectsModelVersion} for details on the API's usages.
+   * Please refer to {@link SavedObjectsModelVersion} for more details on the model version API.
    *
-   * A **valid** versioning would be:
+   * @example A **valid** versioning would be:
    *
    * ```ts
    * {
@@ -158,7 +160,7 @@ export interface SavedObjectsType<Attributes = any> {
    * }
    * ```
    *
-   * A **invalid** versioning would be:
+   * @example An **invalid** versioning would be:
    *
    * ```ts
    * {
@@ -171,8 +173,6 @@ export interface SavedObjectsType<Attributes = any> {
    *   }
    * }
    * ```
-   *
-   * @alpha experimental and subject to change.
    */
   modelVersions?: SavedObjectsModelVersionMap | SavedObjectsModelVersionMapProvider;
 
@@ -184,9 +184,9 @@ export interface SavedObjectsType<Attributes = any> {
    * When specified, the type will switch from using the {@link SavedObjectsType.migrations | legacy migration API}
    * to use the {@link SavedObjectsType.modelVersions | modelVersion API} after the specified version.
    *
-   * When opted in, it will no longer be possible to use the legacy migration API after the specified version.
+   * Once opted in, it will no longer be possible to use the legacy migration API after the specified version.
    *
-   * A **valid** usage example would be:
+   * @example A **valid** usage example would be:
    *
    * ```ts
    * {
@@ -203,7 +203,7 @@ export interface SavedObjectsType<Attributes = any> {
    * }
    * ```
    *
-   * An **invalid** usage example would be:
+   * @example An **invalid** usage example would be:
    *
    * ```ts
    * {
@@ -224,8 +224,8 @@ export interface SavedObjectsType<Attributes = any> {
    * Please refer to the {@link SavedObjectsType.modelVersions | modelVersion API} for more documentation on
    * the new API.
    *
-   * @remarks All types will be forced to switch to use the new API in a later version. This switch is
-   *          allowing types owners to switch their types before the milestone.
+   * @remarks All types will be forced to switch to use the new API during `8.10.0`. This switch is
+   *          allowing types owners to switch their types before the milestone (and for testing purposes).
    */
   switchToModelVersionAt?: string;
 }