SDK models hierarchy

The purpose of this documentation is to provide a high-level overview of models' hierarchy of an SDK generated via the @ama-sdk/schematics generator.

Overview

Models

The SDK generated via the Digital API SDK generator provides 3 levels of models:

• base: The base models are interfaces generated based on definition from the inputted Swagger specification.
• core: The core models are manually created interfaces which add additional field on top of the base models.
• custom: The custom models are manually created interfaces. Their purpose is to provide data model interface used by the front-end applications, but not provided by the Swagger specification.

Revivers

For each model a reviver is provided (automatically generated for the base models, manually created for the core and custom models). The purpose of the revivers is to convert JSON parsed object to the model the reviver is referring to.

Example of a reviver:

export function reviveMyModel<T extends MyModel = MyModel>(data: any, dictionaries?: any): T  | undefined {
  if (!data) { return ; }
  data.myField = reviverMyFieldType<MyFieldType>(data.myField, dictionaries);
  return data as T;
}

[!TIP] The reviver can help remove dictionary fields from a revived object thanks to the clearDictionaryFields option:

Example :

reviveMyModel<MyModel>(data, undefined, { clearDictionaryFields: true });

Core models (and base models extension)

To be able to use the core models in different applications, the base models must be extended the same way it is done in the generated SDKs, based on Swagger specification using the same definitions.

To do so, the SDKs exposing core models must provide factories to create core models.

Model factories

The core model factory can be defined, in the SDK creating the core model, as in this following example:

// in the models/core/my-model/my-model.ts
import type { MyModel } from '../../base/my-model/my-model';
import type { IgnoreEnum } from '@ama-sdk/core';

export type MyModelCoreIfy<T extends IgnoreEnum<MyModel>> = T & {
  /** A additional new field */
  myNewField: string;
};

[!CAUTION] The naming convention requires to suffix the core model factory with CoreIfy.

[!NOTE] The IgnoreEnum helper is used to exclude the enum values (in the base model sub models) from the constraint in case of enum extension.

And then be used in the SDKs as follows:

// in the models/base/my-model/index.ts
import type { MyModelCoreIfy } from '@airline/sdk'; // (or ../../core/my-model)
import type { MyModel as BaseModel } from './my-model';

export { reviveMyModel } from './my-model.reviver';
export type MyModel = MyModelCoreIfy<BaseModel>;
export type {BaseModel as  BaseMyModel}; // not required but useful to be used in id generator

[!IMPORTANT] This file should be listed in the .swagger-codegen-ignore file to not be regenerated by the swagger generator.

Reviver factories

The core model factory can be defined, in the SDK exposing the core model, as in this following example:

// in the models/core/my-model/my-model.reviver.ts
import type { MyModel } from '../../base/my-model/my-model';
import type { reviveMyModel } from '../../base/my-model/my-model.reviver';
import type { MyModelCoreIfy } from './my-model';

/**
 * Generate reviver for MyModel core model
 *
 * @param baseRevive
 */
export function reviveMyModelFactory<R extends typeof reviveMyModel>(baseRevive: R) {
  const reviver = <T extends MyModel = MyModel>(data: any, dictionaries?: any) => {
    const revivedData = baseRevive<MyModelCoreIfy<T>>(data, dictionaries);
    revivedData.myNewField = 'fake value';
    return revivedData;
  };

  return reviver;
}

[!WARNING] The usage of import type is mandatory for the import of the base reviver to avoid bringing an unused revivers in the final application.

And then be used in the SDKs as follows:

// in the models/base/my-model/index.ts
import type { MyModelCoreIfy, reviveMyModelFactory } from '@airline/sdk'; // (or ../../core/my-model)
import type { MyModel as BaseModel } from './my-model';
import { reviveMyModel } from './my-model.reviver';

export type MyModel = MyModelCoreIfy<BaseModel>;
export const reviveMyModel = reviveMyModelFactory(reviveMyModel);
export type {BaseModel as  MyModelBase}; // not required but useful to be used in id generator