zapier-platform-schema 17.2.0 → 17.3.0

package/exported-schema.json

@@ -1,5 +1,5 @@
 {
-  "version": "17.2.0",
+  "version": "17.3.0",
   "schemas": {
     "AppSchema": {
       "id": "/AppSchema",
@@ -669,6 +669,13 @@
         }
       }
     },
+    "KeySchema": {
+      "id": "/KeySchema",
+      "description": "A unique identifier for this item.",
+      "type": "string",
+      "minLength": 2,
+      "pattern": "^[a-zA-Z]+[a-zA-Z0-9_]*$"
+    },
     "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",
@@ -765,6 +772,10 @@
         "meta": {
           "description": "Allows for additional metadata to be stored on the field. Supports simple key-values only (no sub-objects or arrays).",
           "$ref": "/FieldMetaSchema"
+        },
+        "group": {
+          "description": "References a group key from the operation's inputFieldGroups to organize this field with others.",
+          "$ref": "/KeySchema"
         }
       },
       "additionalProperties": false
@@ -875,6 +886,31 @@
         ]
       }
     },
+    "InputFieldGroupsSchema": {
+      "id": "/InputFieldGroupsSchema",
+      "description": "An array or collection of input field groups.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["key"],
+        "properties": {
+          "key": {
+            "description": "The unique identifier for this group.",
+            "$ref": "/KeySchema"
+          },
+          "label": {
+            "description": "The human-readable name for the group.",
+            "type": "string",
+            "minLength": 1
+          },
+          "emphasize": {
+            "description": "Whether this group should be visually emphasized in the UI.",
+            "type": "boolean"
+          }
+        }
+      },
+      "additionalProperties": false
+    },
     "OutputFieldsSchema": {
       "id": "/OutputFieldsSchema",
       "description": "An array or collection of output fields.",
@@ -890,13 +926,6 @@
         ]
       }
     },
-    "KeySchema": {
-      "id": "/KeySchema",
-      "description": "A unique identifier for this item.",
-      "type": "string",
-      "minLength": 2,
-      "pattern": "^[a-zA-Z]+[a-zA-Z0-9_]*$"
-    },
     "LockObjectSchema": {
       "id": "/LockObjectSchema",
       "description": "Zapier uses this configuration to ensure this action is performed one at a time per scope (avoid concurrency).",
@@ -1046,6 +1075,10 @@
           "description": "What should the form a user sees and configures look like?",
           "$ref": "/InputFieldsSchema"
         },
+        "inputFieldGroups": {
+          "description": "Defines groups for organizing input fields in the UI. Each group can have a key, label, and emphasis styling.",
+          "$ref": "/InputFieldGroupsSchema"
+        },
         "outputFields": {
           "description": "What fields of data will this return? Will use resource outputFields if missing, will also use sample if available.",
           "$ref": "/OutputFieldsSchema"
@@ -1156,6 +1189,10 @@
           "description": "What should the form a user sees and configures look like?",
           "$ref": "/InputFieldsSchema"
         },
+        "inputFieldGroups": {
+          "description": "Defines groups for organizing input fields in the UI. Each group can have a key, label, and emphasis styling.",
+          "$ref": "/InputFieldGroupsSchema"
+        },
         "outputFields": {
           "description": "What fields of data will this return? Will use resource outputFields if missing, will also use sample if available.",
           "$ref": "/OutputFieldsSchema"
@@ -1209,6 +1246,10 @@
           "description": "What should the form a user sees and configures look like?",
           "$ref": "/InputFieldsSchema"
         },
+        "inputFieldGroups": {
+          "description": "Defines groups for organizing input fields in the UI. Each group can have a key, label, and emphasis styling.",
+          "$ref": "/InputFieldGroupsSchema"
+        },
         "outputFields": {
           "description": "What fields of data will this return? Will use resource outputFields if missing, will also use sample if available.",
           "$ref": "/OutputFieldsSchema"
@@ -1271,6 +1312,10 @@
           "description": "What should the form a user sees and configures look like?",
           "$ref": "/InputFieldsSchema"
         },
+        "inputFieldGroups": {
+          "description": "Defines groups for organizing input fields in the UI. Each group can have a key, label, and emphasis styling.",
+          "$ref": "/InputFieldGroupsSchema"
+        },
         "outputFields": {
           "description": "What fields of data will this return? Will use resource outputFields if missing, will also use sample if available.",
           "$ref": "/OutputFieldsSchema"
@@ -1513,6 +1558,10 @@
           "description": "What should the form a user sees and configures look like?",
           "$ref": "/InputFieldsSchema"
         },
+        "inputFieldGroups": {
+          "description": "Defines groups for organizing input fields in the UI. Each group can have a key, label, and emphasis styling.",
+          "$ref": "/InputFieldGroupsSchema"
+        },
         "outputFields": {
           "description": "What fields of data will this return? Will use resource outputFields if missing, will also use sample if available.",
           "$ref": "/OutputFieldsSchema"
@@ -1615,6 +1664,10 @@
           "description": "What should the form a user sees and configures look like?",
           "$ref": "/InputFieldsSchema"
         },
+        "inputFieldGroups": {
+          "description": "Defines groups for organizing input fields in the UI. Each group can have a key, label, and emphasis styling.",
+          "$ref": "/InputFieldGroupsSchema"
+        },
         "outputFields": {
           "description": "What fields of data will this return? Will use resource outputFields if missing, will also use sample if available.",
           "$ref": "/OutputFieldsSchema"
@@ -1731,6 +1784,10 @@
           "description": "What should the form a user sees and configures look like?",
           "$ref": "/InputFieldsSchema"
         },
+        "inputFieldGroups": {
+          "description": "Defines groups for organizing input fields in the UI. Each group can have a key, label, and emphasis styling.",
+          "$ref": "/InputFieldGroupsSchema"
+        },
         "outputFields": {
           "description": "What fields of data will this return? Will use resource outputFields if missing, will also use sample if available.",
           "$ref": "/OutputFieldsSchema"

package/lib/functional-constraints/index.js

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

package/lib/functional-constraints/inputFieldGroupsConstraints.js

@@ -0,0 +1,144 @@
+'use strict';
+
+const _ = require('lodash');
+const jsonschema = require('jsonschema');
+
+const actionTypes = ['triggers', 'searches', 'creates', 'bulkReads'];
+const resourceMethods = ['get', 'list', 'hook', 'search', 'create'];
+
+const validateInputFieldGroups = (
+  inputFields,
+  inputFieldGroups,
+  basePath,
+  schemaName,
+) => {
+  const errors = [];
+
+  // Check for duplicate group keys in inputFieldGroups
+  const groupKeys = inputFieldGroups.map((group) => group.key);
+  const duplicateKeys = groupKeys.filter(
+    (key, index) => groupKeys.indexOf(key) !== index,
+  );
+
+  if (duplicateKeys.length > 0) {
+    duplicateKeys.forEach((duplicateKey) => {
+      const duplicateIndex = groupKeys.lastIndexOf(duplicateKey);
+      errors.push(
+        new jsonschema.ValidationError(
+          `Duplicate group key "${duplicateKey}" found in inputFieldGroups. Group keys must be unique.`,
+          inputFieldGroups[duplicateIndex],
+          schemaName,
+          `${basePath}.inputFieldGroups[${duplicateIndex}].key`,
+          'duplicateGroupKey',
+          'inputFieldGroups',
+        ),
+      );
+    });
+  }
+
+  // Create a set of valid group keys
+  const validGroupKeys = new Set(groupKeys);
+
+  inputFields.forEach((inputField, index) => {
+    // Check children fields first - groups are not allowed in children
+    (inputField.children || []).forEach((childField, childIndex) => {
+      if (childField.group) {
+        errors.push(
+          new jsonschema.ValidationError(
+            `Group fields are not allowed in children fields. Remove the group property from this field.`,
+            childField.group,
+            '/PlainInputFieldSchema',
+            `${basePath}.inputFields[${index}].children[${childIndex}].group`,
+            'groupInChildren',
+            'group',
+          ),
+        );
+      }
+    });
+
+    // Check if group reference is valid
+    if (inputField.group) {
+      if (!validGroupKeys.has(inputField.group)) {
+        const availableGroups =
+          Array.from(validGroupKeys).length > 0
+            ? `[${Array.from(validGroupKeys).join(', ')}]`
+            : '[]';
+        errors.push(
+          new jsonschema.ValidationError(
+            `Group "${inputField.group}" is not defined in inputFieldGroups. Available groups: ${availableGroups}`,
+            inputField.group,
+            '/PlainInputFieldSchema',
+            `${basePath}.inputFields[${index}].group`,
+            'invalidGroupReference',
+            'group',
+          ),
+        );
+      }
+    }
+  });
+
+  return errors;
+};
+
+const inputFieldGroupsConstraints = (definition) => {
+  const errors = [];
+
+  // Validate action types (triggers, searches, creates, bulkReads)
+  for (const actionType of actionTypes) {
+    const group = definition[actionType] || {};
+    _.each(group, (action, actionKey) => {
+      const inputFields = _.get(action, ['operation', 'inputFields'], []);
+      const inputFieldGroups = _.get(
+        action,
+        ['operation', 'inputFieldGroups'],
+        [],
+      );
+
+      const basePath = `instance.${actionType}.${actionKey}.operation`;
+      const schemaName = '/BasicOperationSchema';
+
+      const actionErrors = validateInputFieldGroups(
+        inputFields,
+        inputFieldGroups,
+        basePath,
+        schemaName,
+      );
+      errors.push(...actionErrors);
+    });
+  }
+
+  // Validate resources
+  if (definition.resources) {
+    _.each(definition.resources, (resource, resourceKey) => {
+      resourceMethods.forEach((method) => {
+        if (resource[method] && resource[method].operation) {
+          const inputFields = _.get(
+            resource[method],
+            ['operation', 'inputFields'],
+            [],
+          );
+          const inputFieldGroups = _.get(
+            resource[method],
+            ['operation', 'inputFieldGroups'],
+            [],
+          );
+
+          const basePath = `instance.resources.${resourceKey}.${method}.operation`;
+          const schemaName = '/BasicOperationSchema';
+
+          const resourceErrors = validateInputFieldGroups(
+            inputFields,
+            inputFieldGroups,
+            basePath,
+            schemaName,
+          );
+          errors.push(...resourceErrors);
+        }
+      });
+    });
+  }
+
+  return errors;
+};
+
+module.exports = inputFieldGroupsConstraints;

package/lib/schemas/BasicActionOperationSchema.js

@@ -31,6 +31,7 @@ BasicActionOperationSchema.properties = {
     oneOf: [{ $ref: RequestSchema.id }, { $ref: FunctionSchema.id }],
   },
   inputFields: BasicActionOperationSchema.properties.inputFields,
+  inputFieldGroups: BasicActionOperationSchema.properties.inputFieldGroups,
   outputFields: BasicActionOperationSchema.properties.outputFields,
   sample: BasicActionOperationSchema.properties.sample,
   lock: BasicActionOperationSchema.properties.lock,

package/lib/schemas/BasicHookOperationSchema.js

@@ -81,6 +81,7 @@ BasicHookOperationSchema.properties = {
     },
   },
   inputFields: BasicHookOperationSchema.properties.inputFields,
+  inputFieldGroups: BasicHookOperationSchema.properties.inputFieldGroups,
   outputFields: BasicHookOperationSchema.properties.outputFields,
   sample: BasicHookOperationSchema.properties.sample,
 };

package/lib/schemas/BasicHookToPollOperationSchema.js

@@ -59,6 +59,7 @@ BasicHookToPollOperationSchema.properties = {
     oneOf: [{ $ref: RequestSchema.id }, { $ref: FunctionSchema.id }],
   },
   inputFields: BasicHookToPollOperationSchema.properties.inputFields,
+  inputFieldGroups: BasicHookToPollOperationSchema.properties.inputFieldGroups,
   outputFields: BasicHookToPollOperationSchema.properties.outputFields,
   sample: BasicHookToPollOperationSchema.properties.sample,
   maxPollingDelay: {

package/lib/schemas/BasicOperationSchema.js

@@ -10,6 +10,7 @@ const KeySchema = require('./KeySchema');
 const LockObjectSchema = require('./LockObjectSchema');
 const ThrottleObjectSchema = require('./ThrottleObjectSchema');
 const InputFieldsSchema = require('./InputFieldsSchema');
+const InputFieldGroupsSchema = require('./InputFieldGroupsSchema');
 const OutputFieldsSchema = require('./OutputFieldsSchema');
 
 module.exports = makeSchema(
@@ -35,6 +36,11 @@ module.exports = makeSchema(
           'What should the form a user sees and configures look like?',
         $ref: InputFieldsSchema.id,
       },
+      inputFieldGroups: {
+        description:
+          'Defines groups for organizing input fields in the UI. Each group can have a key, label, and emphasis styling.',
+        $ref: InputFieldGroupsSchema.id,
+      },
       outputFields: {
         description:
           'What fields of data will this return? Will use resource outputFields if missing, will also use sample if available.',
@@ -84,6 +90,7 @@ module.exports = makeSchema(
   },
   [
     InputFieldsSchema,
+    InputFieldGroupsSchema,
     OutputFieldsSchema,
     FunctionSchema,
     KeySchema,

package/lib/schemas/BasicPollingOperationSchema.js

@@ -31,6 +31,7 @@ BasicPollingOperationSchema.properties = {
     type: 'boolean',
   },
   inputFields: BasicPollingOperationSchema.properties.inputFields,
+  inputFieldGroups: BasicPollingOperationSchema.properties.inputFieldGroups,
   outputFields: BasicPollingOperationSchema.properties.outputFields,
   sample: BasicPollingOperationSchema.properties.sample,
   throttle: BasicPollingOperationSchema.properties.throttle,

package/lib/schemas/BasicSearchOperationSchema.js

@@ -31,6 +31,7 @@ BasicSearchOperationSchema.properties = {
     oneOf: [{ $ref: RequestSchema.id }, { $ref: FunctionSchema.id }],
   },
   inputFields: BasicSearchOperationSchema.properties.inputFields,
+  inputFieldGroups: BasicSearchOperationSchema.properties.inputFieldGroups,
   outputFields: BasicSearchOperationSchema.properties.outputFields,
   sample: BasicSearchOperationSchema.properties.sample,
   lock: BasicSearchOperationSchema.properties.lock,

package/lib/schemas/InputFieldGroupsSchema.js

@@ -0,0 +1,40 @@
+'use strict';
+
+const makeSchema = require('../utils/makeSchema');
+
+const KeySchema = require('./KeySchema');
+
+module.exports = makeSchema(
+  {
+    id: '/InputFieldGroupsSchema',
+    description: 'An array or collection of input field groups.',
+    type: 'array',
+    items: {
+      type: 'object',
+      required: ['key'],
+      properties: {
+        key: {
+          description: 'The unique identifier for this group.',
+          $ref: KeySchema.id,
+        },
+        label: {
+          description: 'The human-readable name for the group.',
+          type: 'string',
+          minLength: 1,
+        },
+        emphasize: {
+          description:
+            'Whether this group should be visually emphasized in the UI.',
+          type: 'boolean',
+        },
+      },
+    },
+    examples: [[{ key: 'abc' }]],
+    antiExamples: [
+      { example: {}, reason: 'Must be an array' },
+      { example: [{ label: 'test label' }], reason: 'key is required' },
+    ],
+    additionalProperties: false,
+  },
+  [KeySchema],
+);

package/lib/schemas/PlainInputFieldSchema.js

@@ -5,6 +5,7 @@ const RefResourceSchema = require('./RefResourceSchema');
 const FieldChoicesSchema = require('./FieldChoicesSchema');
 const PlainFieldSchema = require('./PlainFieldSchema');
 const FieldMetaSchema = require('./FieldMetaSchema');
+const KeySchema = require('./KeySchema');
 
 module.exports = makeSchema(
   {
@@ -70,6 +71,11 @@ module.exports = makeSchema(
           'Allows for additional metadata to be stored on the field. Supports simple key-values only (no sub-objects or arrays).',
         $ref: FieldMetaSchema.id,
       },
+      group: {
+        description:
+          "References a group key from the operation's inputFieldGroups to organize this field with others.",
+        $ref: KeySchema.id,
+      },
     },
     examples: [
       { key: 'abc' },
@@ -90,6 +96,14 @@ module.exports = makeSchema(
           display_order: 1,
         },
       },
+      {
+        key: 'name',
+        group: 'contact',
+      },
+      {
+        key: 'email',
+        group: 'contact',
+      },
     ],
     antiExamples: [
       {
@@ -132,5 +146,11 @@ module.exports = makeSchema(
     ],
     additionalProperties: false,
   },
-  [RefResourceSchema, FieldChoicesSchema, FieldMetaSchema, PlainFieldSchema],
+  [
+    RefResourceSchema,
+    FieldChoicesSchema,
+    FieldMetaSchema,
+    PlainFieldSchema,
+    KeySchema,
+  ],
 );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zapier-platform-schema",
-  "version": "17.2.0",
+  "version": "17.3.0",
   "description": "Schema definition for CLI apps in the Zapier Developer Platform.",
   "repository": "zapier/zapier-platform",
   "homepage": "https://platform.zapier.com/",