feat(repository-json-schema): add an option to exclude properties from schema

Add a new option `exclude: []` so that `getJsonSchema` and related helpers can request a model schema that excludes specified properties

Author: nabdelgadir

packages/openapi-v3/src/controller-spec.ts

@@ -373,9 +373,9 @@ export function getControllerSpec(constructor: Function): ControllerSpec {
  * @param modelCtor - The model constructor (e.g. `Product`)
  * @param options - Additional options
  */
-export function getModelSchemaRef(
+export function getModelSchemaRef<T extends object>(
   modelCtor: Function,
-  options?: JsonSchemaOptions,
+  options?: JsonSchemaOptions<T>,
 ): SchemaRef {
   const jsonSchema = getJsonSchemaRef(modelCtor, options);
   return jsonToSchemaObject(jsonSchema) as SchemaRef;

packages/repository-json-schema/src/__tests__/integration/build-schema.integration.ts

@@ -932,5 +932,74 @@ describe('build-schema', () => {
       expect(partialSchema.required).to.equal(undefined);
       expect(partialSchema.title).to.equal('ProductPartial');
     });
+
+    context('exclude properties when option "exclude" is set', () => {
+      @model()
+      class Product extends Entity {
+        @property({id: true, required: true})
+        id: number;
+
+        @property()
+        name: string;
+
+        @property()
+        description: string;
+      }
+
+      it('excludes one property when the option "exclude" is set to exclude one property', () => {
+        const originalSchema = getJsonSchema(Product);
+        expect(originalSchema.properties).to.deepEqual({
+          id: {type: 'number'},
+          name: {type: 'string'},
+          description: {type: 'string'},
+        });
+        expect(originalSchema.title).to.equal('Product');
+
+        const excludeIdSchema = getJsonSchema(Product, {exclude: ['id']});
+        expect(excludeIdSchema.properties).to.deepEqual({
+          name: {type: 'string'},
+          description: {type: 'string'},
+        });
+        expect(excludeIdSchema.title).to.equal('ProductExcluding[id]');
+      });
+
+      it('excludes multiple properties when the option "exclude" is set to exclude multiple properties', () => {
+        const originalSchema = getJsonSchema(Product);
+        expect(originalSchema.properties).to.deepEqual({
+          id: {type: 'number'},
+          name: {type: 'string'},
+          description: {type: 'string'},
+        });
+        expect(originalSchema.title).to.equal('Product');
+
+        const excludeIdAndNameSchema = getJsonSchema(Product, {
+          exclude: ['id', 'name'],
+        });
+        expect(excludeIdAndNameSchema.properties).to.deepEqual({
+          description: {type: 'string'},
+        });
+        expect(excludeIdAndNameSchema.title).to.equal(
+          'ProductExcluding[id,name]',
+        );
+      });
+
+      it('doesn\'t exclude properties when the option "exclude" is set to exclude no properties', () => {
+        const originalSchema = getJsonSchema(Product);
+        expect(originalSchema.properties).to.deepEqual({
+          id: {type: 'number'},
+          name: {type: 'string'},
+          description: {type: 'string'},
+        });
+        expect(originalSchema.title).to.equal('Product');
+
+        const excludeNothingSchema = getJsonSchema(Product, {exclude: []});
+        expect(excludeNothingSchema.properties).to.deepEqual({
+          id: {type: 'number'},
+          name: {type: 'string'},
+          description: {type: 'string'},
+        });
+        expect(excludeNothingSchema.title).to.equal('Product');
+      });
+    });
   });
 });

packages/repository-json-schema/src/__tests__/unit/build-schema.unit.ts

@@ -232,13 +232,28 @@ describe('build-schema', () => {
       expect(key).to.equal('modelPartial');
     });
 
+    it('returns "excluding[id,_rev]" when a single option "exclude" is set', () => {
+      const key = buildModelCacheKey({exclude: ['id', '_rev']});
+      expect(key).to.equal('modelExcluding[id,_rev]');
+    });
+
+    it('does not include "exclude" in concatenated option names if it is empty', () => {
+      const key = buildModelCacheKey({
+        partial: true,
+        exclude: [],
+        includeRelations: true,
+      });
+      expect(key).to.equal('modelPartialWithRelations');
+    });
+
     it('returns concatenated option names otherwise', () => {
       const key = buildModelCacheKey({
         // important: object keys are defined in reverse order
         partial: true,
+        exclude: ['id', '_rev'],
         includeRelations: true,
       });
-      expect(key).to.equal('modelPartialWithRelations');
+      expect(key).to.equal('modelPartialExcluding[id,_rev]WithRelations');
     });
   });
 });

packages/repository-json-schema/src/build-schema.ts

@@ -15,7 +15,7 @@ import {
 import {JSONSchema6 as JSONSchema} from 'json-schema';
 import {JSON_SCHEMA_KEY, MODEL_TYPE_KEYS} from './keys';
 
-export interface JsonSchemaOptions {
+export interface JsonSchemaOptions<T extends object> {
   /**
    * Set this flag if you want the schema to define navigational properties
    * for model relations.
@@ -28,6 +28,11 @@ export interface JsonSchemaOptions {
    */
   partial?: boolean;
 
+  /**
+   * List of model properties to exclude from the schema.
+   */
+  exclude?: (keyof T)[];
+
   /**
    * @internal
    */
@@ -37,7 +42,9 @@ export interface JsonSchemaOptions {
 /**
  * @internal
  */
-export function buildModelCacheKey(options: JsonSchemaOptions = {}): string {
+export function buildModelCacheKey<T extends object>(
+  options: JsonSchemaOptions<T> = {},
+): string {
   // Backwards compatibility: preserve cache key "modelOnly"
   if (Object.keys(options).length === 0) {
     return MODEL_TYPE_KEYS.ModelOnly;
@@ -54,9 +61,9 @@ export function buildModelCacheKey(options: JsonSchemaOptions = {}): string {
  * in a cache. If not, one is generated and then cached.
  * @param ctor - Contructor of class to get JSON Schema from
  */
-export function getJsonSchema(
+export function getJsonSchema<T extends object>(
   ctor: Function,
-  options?: JsonSchemaOptions,
+  options?: JsonSchemaOptions<T>,
 ): JSONSchema {
   // In the near future the metadata will be an object with
   // different titles as keys
@@ -107,9 +114,9 @@ export function getJsonSchema(
  * @param modelCtor - The model constructor (e.g. `Product`)
  * @param options - Additional options
  */
-export function getJsonSchemaRef(
+export function getJsonSchemaRef<T extends object>(
   modelCtor: Function,
-  options?: JsonSchemaOptions,
+  options?: JsonSchemaOptions<T>,
 ): JSONSchema {
   const schemaWithDefinitions = getJsonSchema(modelCtor, options);
   const key = schemaWithDefinitions.title;
@@ -255,14 +262,18 @@ export function getNavigationalPropertyForRelation(
   }
 }
 
-function getTitleSuffix(options: JsonSchemaOptions = {}) {
+function getTitleSuffix<T extends object>(options: JsonSchemaOptions<T> = {}) {
   let suffix = '';
   if (options.partial) {
     suffix += 'Partial';
   }
+  if (options.exclude && options.exclude.length) {
+    suffix += 'Excluding[' + options.exclude + ']';
+  }
   if (options.includeRelations) {
     suffix += 'WithRelations';
   }
+
   return suffix;
 }
 
@@ -274,9 +285,9 @@ function getTitleSuffix(options: JsonSchemaOptions = {}) {
  * reflection API
  * @param ctor - Constructor of class to convert from
  */
-export function modelToJsonSchema(
+export function modelToJsonSchema<T extends object>(
   ctor: Function,
-  jsonSchemaOptions: JsonSchemaOptions = {},
+  jsonSchemaOptions: JsonSchemaOptions<T> = {},
 ): JSONSchema {
   const options = {...jsonSchemaOptions};
   options.visited = options.visited || {};
@@ -300,6 +311,10 @@ export function modelToJsonSchema(
   }
 
   for (const p in meta.properties) {
+    if (options.exclude && options.exclude.includes(p as keyof T)) {
+      continue;
+    }
+
     if (!meta.properties[p].type) {
       continue;
     }