add doc annotations so the doc better reflects functional constraints

docs/build/schema.md

@@ -242,7 +242,7 @@ Key | Required | Type | Description
 `performGet` | no | oneOf([/RequestSchema](#requestschema), [/FunctionSchema](#functionschema)) | How will Zapier get a single record? If you find yourself reaching for this - consider resources and their built-in get methods.
 `inputFields` | no | [/DynamicFieldsSchema](#dynamicfieldsschema) | What should the form a user sees and configures look like?
 `outputFields` | no | [/DynamicFieldsSchema](#dynamicfieldsschema) | What fields of data will this return? Will use resource outputFields if missing, will also use sample if available.
-`sample` | no | `object` | What does a sample of data look like? Will use resource sample if missing. Required, if the display is not hidden.
+`sample` | **yes** (with exceptions, see description) | `object` | What does a sample of data look like? Will use resource sample if missing. Requirement waived if `display.hidden` is true or if this belongs to a resource that has a top-level sample
 
 -----
 
@@ -267,7 +267,7 @@ Key | Required | Type | Description
 `performGet` | no | oneOf([/RequestSchema](#requestschema), [/FunctionSchema](#functionschema)) | How will Zapier get a single record? If you find yourself reaching for this - consider resources and their built-in get methods.
 `inputFields` | no | [/DynamicFieldsSchema](#dynamicfieldsschema) | What should the form a user sees and configures look like?
 `outputFields` | no | [/DynamicFieldsSchema](#dynamicfieldsschema) | What fields of data will this return? Will use resource outputFields if missing, will also use sample if available.
-`sample` | no | `object` | What does a sample of data look like? Will use resource sample if missing. Required, if the display is not hidden.
+`sample` | **yes** (with exceptions, see description) | `object` | What does a sample of data look like? Will use resource sample if missing. Requirement waived if `display.hidden` is true or if this belongs to a resource that has a top-level sample
 `shouldLock` | no | `boolean` | Should this action be performed one at a time (avoid concurrency)?
 
 -----
@@ -334,7 +334,7 @@ Key | Required | Type | Description
 `performUnsubscribe` | no | oneOf([/RequestSchema](#requestschema), [/FunctionSchema](#functionschema)) | Takes a URL and data from a previous subscribe call and unsubscribes.
 `inputFields` | no | [/DynamicFieldsSchema](#dynamicfieldsschema) | What should the form a user sees and configures look like?
 `outputFields` | no | [/DynamicFieldsSchema](#dynamicfieldsschema) | What fields of data will this return? Will use resource outputFields if missing, will also use sample if available.
-`sample` | no | `object` | What does a sample of data look like? Will use resource sample if missing. Required, if the display is not hidden.
+`sample` | **yes** (with exceptions, see description) | `object` | What does a sample of data look like? Will use resource sample if missing. Requirement waived if `display.hidden` is true or if this belongs to a resource that has a top-level sample
 
 -----
 
@@ -358,7 +358,7 @@ Key | Required | Type | Description
 `perform` | **yes** | oneOf([/RequestSchema](#requestschema), [/FunctionSchema](#functionschema)) | How will Zapier get the data? This can be a function like `(z) => [{id: 123}]` or a request like `{url: 'http...'}`.
 `inputFields` | no | [/DynamicFieldsSchema](#dynamicfieldsschema) | What should the form a user sees and configures look like?
 `outputFields` | no | [/DynamicFieldsSchema](#dynamicfieldsschema) | What fields of data will this return? Will use resource outputFields if missing, will also use sample if available.
-`sample` | no | `object` | What does a sample of data look like? Will use resource sample if missing. Required, if the display is not hidden.
+`sample` | **yes** (with exceptions, see description) | `object` | What does a sample of data look like? Will use resource sample if missing. Requirement waived if `display.hidden` is true or if this belongs to a resource that has a top-level sample
 
 -----
 
@@ -384,7 +384,7 @@ Key | Required | Type | Description
 `canPaginate` | no | `boolean` | Does this endpoint support a page offset?
 `inputFields` | no | [/DynamicFieldsSchema](#dynamicfieldsschema) | What should the form a user sees and configures look like?
 `outputFields` | no | [/DynamicFieldsSchema](#dynamicfieldsschema) | What fields of data will this return? Will use resource outputFields if missing, will also use sample if available.
-`sample` | no | `object` | What does a sample of data look like? Will use resource sample if missing. Required, if the display is not hidden.
+`sample` | **yes** (with exceptions, see description) | `object` | What does a sample of data look like? Will use resource sample if missing. Requirement waived if `display.hidden` is true or if this belongs to a resource that has a top-level sample
 
 -----
 

exported-schema.json

@@ -563,9 +563,15 @@
         },
         "sample": {
           "description":
-            "What does a sample of data look like? Will use resource sample if missing. Required, if the display is not hidden.",
+            "What does a sample of data look like? Will use resource sample if missing. Requirement waived if `display.hidden` is true or if this belongs to a resource that has a top-level sample",
           "type": "object",
-          "minProperties": 1
+          "minProperties": 1,
+          "docAnnotation": {
+            "required": {
+              "type": "replace",
+              "value": "**yes** (with exceptions, see description)"
+            }
+          }
         }
       },
       "additionalProperties": false
@@ -642,9 +648,15 @@
         },
         "sample": {
           "description":
-            "What does a sample of data look like? Will use resource sample if missing. Required, if the display is not hidden.",
+            "What does a sample of data look like? Will use resource sample if missing. Requirement waived if `display.hidden` is true or if this belongs to a resource that has a top-level sample",
           "type": "object",
-          "minProperties": 1
+          "minProperties": 1,
+          "docAnnotation": {
+            "required": {
+              "type": "replace",
+              "value": "**yes** (with exceptions, see description)"
+            }
+          }
         }
       },
       "additionalProperties": false
@@ -695,9 +707,15 @@
         },
         "sample": {
           "description":
-            "What does a sample of data look like? Will use resource sample if missing. Required, if the display is not hidden.",
+            "What does a sample of data look like? Will use resource sample if missing. Requirement waived if `display.hidden` is true or if this belongs to a resource that has a top-level sample",
           "type": "object",
-          "minProperties": 1
+          "minProperties": 1,
+          "docAnnotation": {
+            "required": {
+              "type": "replace",
+              "value": "**yes** (with exceptions, see description)"
+            }
+          }
         }
       },
       "additionalProperties": false
@@ -749,9 +767,15 @@
         },
         "sample": {
           "description":
-            "What does a sample of data look like? Will use resource sample if missing. Required, if the display is not hidden.",
+            "What does a sample of data look like? Will use resource sample if missing. Requirement waived if `display.hidden` is true or if this belongs to a resource that has a top-level sample",
           "type": "object",
-          "minProperties": 1
+          "minProperties": 1,
+          "docAnnotation": {
+            "required": {
+              "type": "replace",
+              "value": "**yes** (with exceptions, see description)"
+            }
+          }
         }
       },
       "additionalProperties": false
@@ -1023,9 +1047,15 @@
         },
         "sample": {
           "description":
-            "What does a sample of data look like? Will use resource sample if missing. Required, if the display is not hidden.",
+            "What does a sample of data look like? Will use resource sample if missing. Requirement waived if `display.hidden` is true or if this belongs to a resource that has a top-level sample",
           "type": "object",
-          "minProperties": 1
+          "minProperties": 1,
+          "docAnnotation": {
+            "required": {
+              "type": "replace",
+              "value": "**yes** (with exceptions, see description)"
+            }
+          }
         },
         "shouldLock": {
           "description":

lib/schemas/BasicOperationSchema.js

@@ -38,10 +38,16 @@ module.exports = makeSchema(
       },
       sample: {
         description:
-          'What does a sample of data look like? Will use resource sample if missing. Required, if the display is not hidden.',
+          'What does a sample of data look like? Will use resource sample if missing. Requirement waived if `display.hidden` is true or if this belongs to a resource that has a top-level sample',
         type: 'object',
         // TODO: require id, ID, Id property?
-        minProperties: 1
+        minProperties: 1,
+        docAnnotation: {
+          required: {
+            type: 'replace', // replace or append
+            value: '**yes** (with exceptions, see description)'
+          }
+        }
       }
     },
     additionalProperties: false

lib/utils/buildDocs.js

@@ -90,6 +90,24 @@ ${examples
 `;
 };
 
+const processProperty = (key, property, propIsRequired) => {
+  let isRequired = propIsRequired ? '**yes**' : 'no';
+  if (_.get(property, 'docAnnotation.required')) {
+    // can also support keys besides "required"
+    const annotation = property.docAnnotation.required;
+    if (annotation.type === 'replace') {
+      isRequired = annotation.value;
+    } else if (annotation.type === 'append') {
+      isRequired += annotation.value;
+    } else {
+      throw new Error(`unrecognized docAnnotation type: ${annotation.type}`);
+    }
+  }
+  return `${quoteOrNa(key)} | ${isRequired} | ${typeOrLink(
+    property
+  )} | ${property.description || NO_DESCRIPTION}`;
+};
+
 // Enumerate the properties as a table.
 const makePropertiesSection = Schema => {
   const properties =
@@ -106,10 +124,7 @@ Key | Required | Type | Description
 ${Object.keys(properties)
     .map(key => {
       const property = properties[key];
-      const isRequired = required.indexOf(key) !== -1 ? '**yes**' : 'no';
-      return `${quoteOrNa(key)} | ${isRequired} | ${typeOrLink(
-        property
-      )} | ${property.description || NO_DESCRIPTION}`;
+      return processProperty(key, property, required.includes(key));
     })
     .join('\n')}
 `;