Merge pull request #611 from JupiterOne/add-schema-to-graph-object-me…

…tadata

Add optional `schema` property to graph object metadata

CHANGELOG.md

@@ -11,6 +11,14 @@ and this project adheres to
 
 ### Added
 
+- Added optional `schema` property to `StepGraphObjectMetadata`. This allows
+  developers to provide the property schema to expect on entities,
+  relationships, and mapped relationships. This serves two uses:
+  1. Schemas can be used at runtime or test-time to verify that an entity has
+     the correct properties
+  2. The `j1-integration document` command could automatically produce consumer
+     documentation about the properties that an entity / relationship is
+     expected to have
 - Added `executeStepWithDependencies` utility to
   `@jupiterone/integration-sdk-testing` package. This allows developers to test
   specific integration steps in isolation, while assuring that all of its

packages/integration-sdk-core/src/types/step.ts

@@ -1,4 +1,7 @@
-import { RelationshipClass } from '@jupiterone/data-model';
+import {
+  RelationshipClass,
+  IntegrationEntitySchema,
+} from '@jupiterone/data-model';
 
 import {
   ExecutionContext,
@@ -81,9 +84,28 @@ export interface GraphObjectIndexMetadata {
   enabled: boolean;
 }
 
+export interface GraphObjectSchema extends IntegrationEntitySchema {
+  $schema?: string;
+  $id?: string;
+  description?: string;
+  additionalProperties?: boolean;
+}
+
 export interface StepGraphObjectMetadata {
   _type: string;
 
+  /**
+   * An optional extension to the JSON schemas defined by the `_class` of this entity
+   * in the @jupiterone/data-model.
+   *
+   * Extensions defined by this schema are in addition to the schemas referenced by the
+   * `_class` values of the entity. These should be considered unique properties for
+   * this integration. Ask yourself, should a property here be considered for promotion
+   * to the @jupiterone/data-model to benefit normalization of all integrations producing
+   * this class of entity?
+   */
+  schema?: GraphObjectSchema;
+
   /**
    * Indicates the set of data represented by this `_type` should always be
    * considered a partial dataset.

packages/integration-sdk-testing/src/__tests__/jest.test.ts

@@ -3,6 +3,7 @@ import {
   createMappedRelationship,
   Entity,
   ExplicitRelationship,
+  GraphObjectSchema,
   IntegrationInvocationConfig,
   IntegrationSpecConfig,
   RelationshipClass,
@@ -11,7 +12,6 @@ import {
   toMatchGraphObjectSchema,
   toMatchDirectRelationshipSchema,
   toTargetEntities,
-  GraphObjectSchema,
   registerMatchers,
   toImplementSpec,
 } from '../jest';

packages/integration-sdk-testing/src/jest.ts

@@ -3,6 +3,7 @@ import * as deepmerge from 'deepmerge';
 import {
   Entity,
   ExplicitRelationship,
+  GraphObjectSchema,
   IntegrationInstanceConfig,
   IntegrationInvocationConfig,
   IntegrationSpecConfig,
@@ -222,13 +223,6 @@ function graphObjectClassToSchemaRef(_class: string) {
   return `#${_class}`;
 }
 
-export interface GraphObjectSchema extends dataModel.IntegrationEntitySchema {
-  $schema?: string;
-  $id?: string;
-  description?: string;
-  additionalProperties?: boolean;
-}
-
 export interface ToMatchGraphObjectSchemaParams {
   /**
    * The JupiterOne hierarchy class or classes from the data model that will be used to generate a new schema to be validated against. See: https://github.com/JupiterOne/data-model/tree/main/src/schemas