zapier-platform-schema 18.3.0 → 18.4.0

package/exported-schema.json

@@ -1,5 +1,5 @@
 {
-  "version": "18.3.0",
+  "version": "18.4.0",
   "schemas": {
     "AppSchema": {
       "id": "/AppSchema",
@@ -202,7 +202,10 @@
       "oneOf": [
         {
           "type": "object",
-          "minProperties": 1
+          "minProperties": 1,
+          "not": {
+            "required": ["perform"]
+          }
         },
         {
           "type": "array",
@@ -252,7 +255,8 @@
             "file",
             "password",
             "copy",
-            "code"
+            "code",
+            "json"
           ]
         },
         "required": {
@@ -698,6 +702,12 @@
       "minLength": 2,
       "pattern": "^[a-zA-Z]+[a-zA-Z0-9_]*$"
     },
+    "JsonSchemaSchema": {
+      "id": "/JsonSchemaSchema",
+      "description": "A JSON Schema object that describes the expected structure of a JSON value. Validated against JSON Schema Draft 4, 6, or 7 meta-schema (based on the `$schema` field, defaulting to Draft 7) via the validateJsonFieldSchema functional constraint.",
+      "type": "object",
+      "additionalProperties": true
+    },
     "PlainInputFieldSchema": {
       "description": "Field schema specialized for input fields. In addition to the requirements below, the following keys are mutually exclusive:\n\n* `children` & `list`\n* `children` & `dict`\n* `children` & `type`\n* `children` & `placeholder`\n* `children` & `helpText`\n* `children` & `default`\n* `dict` & `list`\n* `dynamic` & `dict`\n* `dynamic` & `choices`",
       "id": "/PlainInputFieldSchema",
@@ -727,7 +737,8 @@
             "file",
             "password",
             "copy",
-            "code"
+            "code",
+            "json"
           ]
         },
         "required": {
@@ -818,6 +829,10 @@
         "group": {
           "description": "References a group key from the operation's inputFieldGroups to organize this field with others.",
           "$ref": "/KeySchema"
+        },
+        "schema": {
+          "description": "A JSON Schema object that describes the expected structure of the JSON value. Only valid when `type` is `json`.",
+          "$ref": "/JsonSchemaSchema"
         }
       },
       "additionalProperties": false
@@ -2192,7 +2207,7 @@
           "type": "boolean"
         },
         "skipThrowForStatus": {
-          "description": "Starting in `core` version `10.0.0`, `response.throwForStatus()` was called by default. We introduced a per-request way to opt-out of this behavior. This flag takes that a step further and controls that behavior integration-wide **for requests made using `z.request()`**. Unless they specify otherwise (per-request, or via middleware), [Shorthand requests](https://github.com/zapier/zapier-platform/blob/main/packages/cli/README.md#shorthand-http-requests) _always_ call `throwForStatus()`. `z.request()` calls can also ignore this flag if they set `skipThrowForStatus` directly",
+          "description": "Starting in `core` version `10.0.0`, `response.throwForStatus()` was called by default. We introduced a per-request way to opt-out of this behavior. This flag takes that a step further and controls that behavior integration-wide **for requests made using `z.request()`**. Unless they specify otherwise (per-request, or via middleware), [Shorthand requests](https://github.com/zapier/zapier-platform/blob/main/packages/cli/README.md#shorthand-http-requests) _always_ call `throwForStatus()`. `z.request()` calls can also ignore this flag if they set `skipThrowForStatus` directly. It is important to note that for oauth2 or session auths with `authRefresh:true`, `401` status codes will throw a `RefreshAuthError` regardless of `skipThrowForStatus`, and will need to be handled manually if intervention is required.",
           "type": "boolean"
         },
         "throwForThrottlingEarly": {

package/lib/functional-constraints/index.js

@@ -23,6 +23,7 @@ const checks = [
   require('./pollingThrottle'),
   require('./AuthFieldisSafe'),
   require('./inputFieldGroupsConstraints'),
+  require('./validateJsonFieldSchema'),
 ];
 
 const runFunctionalConstraints = (definition, mainSchema) => {

package/lib/functional-constraints/validateJsonFieldSchema.js

@@ -0,0 +1,254 @@
+'use strict';
+
+const _ = require('lodash');
+const jsonschema = require('jsonschema');
+
+const JSON_SCHEMA_SCHEMA_ID = '/JsonSchemaSchema';
+const PLAIN_INPUT_FIELD_SCHEMA_ID = '/PlainInputFieldSchema';
+
+const actionTypes = ['triggers', 'searches', 'creates', 'bulkReads'];
+const resourceMethods = ['get', 'list', 'hook', 'search', 'create'];
+
+// Load supported JSON Schema meta-schemas
+const draft4MetaSchema = require('json-metaschema/draft-04-schema.json');
+const draft6MetaSchema = require('json-metaschema/draft-06-schema.json');
+const draft7MetaSchema = require('json-metaschema/draft-07-schema.json');
+
+// Map of supported $schema URIs (without trailing #) to their meta-schemas
+// HTTPS supported but normalized below
+const SUPPORTED_META_SCHEMAS = {
+  'http://json-schema.org/draft-04/schema': draft4MetaSchema,
+  'http://json-schema.org/draft-06/schema': draft6MetaSchema,
+  'http://json-schema.org/draft-07/schema': draft7MetaSchema,
+};
+
+const metaValidator = new jsonschema.Validator();
+
+// Translates jsonschema ValidationError from meta-schema validation
+// into a human-readable error message.
+const formatMetaSchemaError = (error, rootPath) => {
+  const ALLOWED_TYPE_NAMES = [
+    'object',
+    'array',
+    'string',
+    'number',
+    'integer',
+    'boolean',
+    'null',
+  ];
+  const relativePath = error.property.replace(/^instance\.?/, '');
+  const fullPath = relativePath ? `${rootPath}.${relativePath}` : rootPath;
+
+  // "type" field: invalid JSON Schema type value
+  if (/\.type$/.test(error.property) || error.property === 'instance.type') {
+    if (error.name === 'anyOf') {
+      const value = error.instance;
+      if (typeof value === 'string') {
+        return `${fullPath}: invalid type "${value}". Must be one of: ${ALLOWED_TYPE_NAMES.join(', ')}`;
+      }
+      if (Array.isArray(value)) {
+        const invalid = value.filter(
+          (t) => typeof t !== 'string' || !ALLOWED_TYPE_NAMES.includes(t),
+        );
+        if (invalid.length > 0) {
+          return invalid
+            .map(
+              (t) =>
+                `${fullPath}: invalid type "${t}". Must be one of: ${ALLOWED_TYPE_NAMES.join(', ')}`,
+            )
+            .join('; ');
+        }
+        return `${fullPath}: must be a string or array of strings`;
+      }
+      return `${fullPath}: must be a string or array of strings`;
+    }
+  }
+
+  // Non-object where a JSON Schema object is expected
+  // Draft 7 allows boolean schemas, so argument may be ['object', 'boolean']
+  if (
+    error.name === 'type' &&
+    Array.isArray(error.argument) &&
+    error.argument.includes('object')
+  ) {
+    return `${fullPath}: must be a valid JSON Schema object`;
+  }
+
+  // Non-array where an array is expected (required, enum, allOf, etc.)
+  if (error.name === 'type' && _.isEqual(error.argument, ['array'])) {
+    const fieldName = fullPath.split('.').pop();
+    return `${fieldName}: must be an array`;
+  }
+
+  // anyOf failure for fields expecting a schema or specific structure
+  if (error.name === 'anyOf') {
+    const value = error.instance;
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+      return `${fullPath}: must be a valid JSON Schema object`;
+    }
+    return `${fullPath}: must be a valid JSON Schema`;
+  }
+
+  // Default fallback
+  return `${fullPath}: ${error.message}`;
+};
+
+// Resolves which meta-schema to validate against based on the $schema field.
+// Returns { metaSchema, error } where error is a string if $schema is unsupported.
+const resolveMetaSchema = (schema) => {
+  if (!schema.$schema) {
+    return { metaSchema: draft7MetaSchema, error: null };
+  }
+
+  if (typeof schema.$schema !== 'string') {
+    return { metaSchema: null, error: '`$schema` must be a string' };
+  }
+
+  const normalizedUri = schema.$schema
+    .replace(/#$/, '')
+    .replace(/^https:/, 'http:');
+  const metaSchema = SUPPORTED_META_SCHEMAS[normalizedUri];
+
+  if (!metaSchema) {
+    const supported = Object.keys(SUPPORTED_META_SCHEMAS).join(', ');
+    return {
+      metaSchema: null,
+      error: `unsupported JSON Schema version "${schema.$schema}". Supported versions: ${supported}`,
+    };
+  }
+
+  return { metaSchema, error: null };
+};
+
+// Validates that an object is a structurally valid JSON schema
+// using the appropriate meta-schema via jsonschema library.
+// Returns an array of error message strings
+const collectSchemaErrors = (schema, rootPath) => {
+  if (typeof schema !== 'object' || schema === null || Array.isArray(schema)) {
+    return [`${rootPath}: must be a valid JSON Schema object`];
+  }
+
+  const { metaSchema, error } = resolveMetaSchema(schema);
+  if (error) {
+    return [`${rootPath}: ${error}`];
+  }
+
+  const result = metaValidator.validate(schema, metaSchema);
+  return result.errors.map((err) => formatMetaSchemaError(err, rootPath));
+};
+
+const checkSchemaField = (field, path) => {
+  let errors = [];
+
+  if (_.has(field, 'schema')) {
+    if (field.type !== 'json') {
+      errors.push(
+        new jsonschema.ValidationError(
+          'must have `type` set to `json` when `schema` is provided.',
+          field,
+          '/PlainInputFieldSchema',
+          path,
+          'invalidSchema',
+          'schema',
+        ),
+      );
+    } else {
+      // Root schema type must be object or array, not primitives
+      const rootType = field.schema.type;
+      if (rootType !== undefined) {
+        const types = Array.isArray(rootType) ? rootType : [rootType];
+        const invalidTypes = types.filter(
+          (t) => t !== 'object' && t !== 'array',
+        );
+        if (invalidTypes.length > 0) {
+          errors.push(
+            new jsonschema.ValidationError(
+              `has an invalid JSON Schema in \`schema\`: schema: root \`type\` must be "object" or "array", got ${invalidTypes.map((t) => `"${t}"`).join(', ')}`,
+              field,
+              '/PlainInputFieldSchema',
+              path,
+              'invalidJsonSchema',
+              'schema',
+            ),
+          );
+          // Skip meta-schema validation if root type is invalid
+          return errors;
+        }
+      }
+
+      const schemaErrors = collectSchemaErrors(field.schema, 'schema');
+      schemaErrors.forEach((message) => {
+        errors.push(
+          new jsonschema.ValidationError(
+            `has an invalid JSON Schema in \`schema\`: ${message}`,
+            field,
+            '/PlainInputFieldSchema',
+            path,
+            'invalidJsonSchema',
+            'schema',
+          ),
+        );
+      });
+    }
+  }
+
+  // Recurse into children (nested PlainInputFieldSchema)
+  (field.children || []).forEach((child, childIndex) => {
+    errors = errors.concat(
+      checkSchemaField(child, `${path}.children[${childIndex}]`),
+    );
+  });
+
+  return errors;
+};
+
+const validateJsonFieldSchema = (definition, mainSchema) => {
+  let errors = [];
+
+  // Handle individual field validation (for auto-tests of examples/antiExamples)
+  if (mainSchema.id === PLAIN_INPUT_FIELD_SCHEMA_ID) {
+    return checkSchemaField(definition, 'instance');
+  } else if (mainSchema.id === JSON_SCHEMA_SCHEMA_ID) {
+    return checkSchemaField(
+      // Make a fake PlainInputField object so checkSchemaField detects a json type and `schema` property
+      { key: 'placeholder_field_key', type: 'json', schema: definition },
+      'instance',
+    );
+  }
+
+  // Handle full app definition validation
+  _.each(actionTypes, (actionType) => {
+    if (definition[actionType]) {
+      _.each(definition[actionType], (actionDef) => {
+        if (actionDef.operation && actionDef.operation.inputFields) {
+          _.each(actionDef.operation.inputFields, (field, index) => {
+            const path = `instance.${actionType}.${actionDef.key}.operation.inputFields[${index}]`;
+            errors = errors.concat(checkSchemaField(field, path));
+          });
+        }
+      });
+    }
+  });
+
+  // Handle resources if they exist
+  if (definition.resources) {
+    _.each(definition.resources, (resource, resourceKey) => {
+      resourceMethods.forEach((method) => {
+        if (
+          resource[method] &&
+          resource[method].operation &&
+          resource[method].operation.inputFields
+        ) {
+          _.each(resource[method].operation.inputFields, (field, index) => {
+            const path = `instance.resources.${resourceKey}.${method}.operation.inputFields[${index}]`;
+            errors = errors.concat(checkSchemaField(field, path));
+          });
+        }
+      });
+    });
+  }
+
+  return errors;
+};
+
+module.exports = validateJsonFieldSchema;

package/lib/schemas/AppFlagsSchema.js

@@ -14,7 +14,7 @@ module.exports = makeSchema({
     },
     skipThrowForStatus: {
       description:
-        'Starting in `core` version `10.0.0`, `response.throwForStatus()` was called by default. We introduced a per-request way to opt-out of this behavior. This flag takes that a step further and controls that behavior integration-wide **for requests made using `z.request()`**. Unless they specify otherwise (per-request, or via middleware), [Shorthand requests](https://github.com/zapier/zapier-platform/blob/main/packages/cli/README.md#shorthand-http-requests) _always_ call `throwForStatus()`. `z.request()` calls can also ignore this flag if they set `skipThrowForStatus` directly',
+        'Starting in `core` version `10.0.0`, `response.throwForStatus()` was called by default. We introduced a per-request way to opt-out of this behavior. This flag takes that a step further and controls that behavior integration-wide **for requests made using `z.request()`**. Unless they specify otherwise (per-request, or via middleware), [Shorthand requests](https://github.com/zapier/zapier-platform/blob/main/packages/cli/README.md#shorthand-http-requests) _always_ call `throwForStatus()`. `z.request()` calls can also ignore this flag if they set `skipThrowForStatus` directly. It is important to note that for oauth2 or session auths with `authRefresh:true`, `401` status codes will throw a `RefreshAuthError` regardless of `skipThrowForStatus`, and will need to be handled manually if intervention is required.',
       type: 'boolean',
     },
     throwForThrottlingEarly: {

package/lib/schemas/FieldChoicesSchema.js

@@ -13,6 +13,7 @@ module.exports = makeSchema(
       {
         type: 'object',
         minProperties: 1,
+        not: { required: ['perform'] },
       },
       {
         type: 'array',

package/lib/schemas/JsonSchemaSchema.js

@@ -0,0 +1,47 @@
+'use strict';
+
+const makeSchema = require('../utils/makeSchema');
+
+module.exports = makeSchema({
+  id: '/JsonSchemaSchema',
+  description:
+    'A JSON Schema object that describes the expected structure of a JSON value. Validated against JSON Schema Draft 4, 6, or 7 meta-schema (based on the `$schema` field, defaulting to Draft 7) via the validateJsonFieldSchema functional constraint.',
+  type: 'object',
+  additionalProperties: true,
+  examples: [
+    { type: 'object', properties: { name: { type: 'string' } } },
+    { type: 'array', items: { type: 'string' } },
+    {},
+    {
+      allOf: [{ type: 'object' }, { properties: { name: { type: 'string' } } }],
+      not: { type: 'array' },
+    },
+    {
+      type: 'object',
+      properties: {
+        name: { type: 'string' },
+        age: { type: 'integer' },
+      },
+      required: ['name'],
+      additionalProperties: false,
+    },
+    {
+      $schema: 'http://json-schema.org/draft-07/schema#',
+      type: 'object',
+      properties: {
+        name: { type: 'string' },
+      },
+    },
+  ],
+  antiExamples: [
+    {
+      example: ['not', 'an', 'object'],
+      reason: 'JSON Schema must be an object, not an array',
+    },
+    {
+      example: { type: 'string' },
+      reason:
+        "JSON Schema type should be an object or an array. If a primitive is needed, use `type: 'string'` on the input field directly",
+    },
+  ],
+});

package/lib/schemas/PlainFieldSchema.js

@@ -50,6 +50,7 @@ module.exports = makeSchema({
         'password',
         'copy',
         'code',
+        'json',
       ],
     },
     required: {
@@ -97,6 +98,9 @@ module.exports = makeSchema({
 
     // 6. A field with type=integer
     { key: 'abc_int', type: 'integer' },
+
+    // 7. A field with type=json
+    { key: 'abc_json', type: 'json' },
   ],
   antiExamples: [
     {

package/lib/schemas/PlainInputFieldSchema.js

@@ -7,6 +7,7 @@ const FieldDynamicChoicesSchema = require('./FieldDynamicChoicesSchema');
 const PlainFieldSchema = require('./PlainFieldSchema');
 const FieldMetaSchema = require('./FieldMetaSchema');
 const KeySchema = require('./KeySchema');
+const JsonSchemaSchema = require('./JsonSchemaSchema');
 
 module.exports = makeSchema(
   {
@@ -93,6 +94,11 @@ module.exports = makeSchema(
           "References a group key from the operation's inputFieldGroups to organize this field with others.",
         $ref: KeySchema.id,
       },
+      schema: {
+        description:
+          'A JSON Schema object that describes the expected structure of the JSON value. Only valid when `type` is `json`.',
+        $ref: JsonSchemaSchema.id,
+      },
     },
     examples: [
       { key: 'abc' },
@@ -125,6 +131,16 @@ module.exports = makeSchema(
         key: 'email',
         group: 'contact',
       },
+      {
+        key: 'payload',
+        type: 'json',
+        schema: {
+          type: 'object',
+          properties: {
+            name: { type: 'string' },
+          },
+        },
+      },
       {
         key: 'spreadsheet',
         dependsOn: ['folder'],
@@ -171,7 +187,18 @@ module.exports = makeSchema(
         reason:
           'Invalid value for key: choices (must be either object or array)',
       },
-
+      {
+        example: { key: 'abc', type: 'string', schema: { type: 'object' } },
+        reason: 'schema is only valid when type is json',
+      },
+      {
+        example: {
+          key: 'abc',
+          type: 'json',
+          schema: { type: 'foobar' },
+        },
+        reason: 'schema must contain a valid JSON Schema (invalid type)',
+      },
       {
         example: { key: 'abc', children: ['$func$2$f$'] },
         reason:
@@ -187,5 +214,6 @@ module.exports = makeSchema(
     FieldMetaSchema,
     PlainFieldSchema,
     KeySchema,
+    JsonSchemaSchema,
   ],
 );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zapier-platform-schema",
-  "version": "18.3.0",
+  "version": "18.4.0",
   "description": "Schema definition for CLI apps in the Zapier Developer Platform.",
   "repository": "zapier/zapier-platform",
   "homepage": "https://platform.zapier.com/",
@@ -13,6 +13,7 @@
     "/schema.js"
   ],
   "dependencies": {
+    "json-metaschema": "1.3.0",
     "jsonschema": "1.5.0",
     "lodash": "4.17.23"
   },
@@ -26,7 +27,7 @@
     "preversion": "git pull && pnpm test && pnpm build",
     "test": "mocha -t 10s --recursive test --exit",
     "smoke-test": "mocha -t 10s --recursive smoke-test --exit",
-    "test:debug": "mocha --recursive --inspect-brk test",
+    "test:debug": "mocha inspect --recursive test",
     "lint": "eslint lib",
     "lint:fix": "eslint --fix lib",
     "coverage": "istanbul cover _mocha -- --recursive",