Dossier API – updateSchemaSpecification

updateSchemaSpecification is used to make changes to the schema. Most changes can be made by defining the intended changed schema (i.e. the API is declarative, not imperative). However, for some changes (e.g. renaming a type or a field) you need to also define a migration for Dossier to make the intended changes.

interface DossierClient {
  updateSchemaSpecification(
    schemaSpec: SchemaSpecificationUpdate,
    options?: { includeMigrations: boolean },
  ): PromiseResult<SchemaSpecificationUpdatePayload, "BadRequest" | "Generic">;
}

interface SchemaSpecificationUpdate {
  version?: number;
  entityTypes?: EntityTypeSpecificationUpdate[];
  componentTypes?: ComponentTypeSpecificationUpdate[];
  patterns?: SchemaPatternSpecification[];
  indexes?: SchemaIndexSpecification[];
  migrations?: SchemaVersionMigration[];
  transientMigrations?: SchemaTransientMigrationAction[];
}

interface EntityTypeSpecificationUpdate {
  name: string;
  publishable?: boolean;
  authKeyPattern?: string | null;
  nameField?: string | null;
  fields: FieldSpecificationUpdate[];
}

interface ComponentTypeSpecificationUpdate {
  name: string;
  adminOnly?: boolean;
  fields: FieldSpecificationUpdate[];
}

interface SchemaPatternSpecification {
  name: string;
  pattern: string;
}

interface SchemaIndexSpecification {
  name: string;
  type: "unique";
}

interface SchemaVersionMigration {
  version: number;
  actions: SchemaMigrationAction[];
}

type SchemaMigrationAction =
  | { action: "renameType"; entityType: string; newName: string }
  | { action: "renameType"; componentType: string; newName: string }
  | {
      action: "renameField";
      entityType: string;
      field: string;
      newName: string;
    }
  | {
      action: "renameField";
      componentType: string;
      field: string;
      newName: string;
    }
  | { action: "deleteType"; entityType: string }
  | { action: "deleteType"; componentType: string }
  | { action: "deleteField"; entityType: string; field: string }
  | { action: "deleteField"; componentType: string; field: string };

type SchemaTransientMigrationAction =
  | { action: "renameIndex"; index: string; newName: string }
  | { action: "deleteIndex"; index: string };

interface SchemaSpecificationUpdatePayload {
  effect: "updated" | "none";
  schemaSpecification: SchemaSpecification | SchemaSpecificationWithMigrations;
}

Updating the schema generates an updateSchema event.