Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(schema): Add reasons to anti-examples, update README, rearrange individual schema layout #287

Merged
merged 8 commits into from
Nov 3, 2020
16 changes: 10 additions & 6 deletions packages/schema/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,12 +6,16 @@

## Development

- `npm install` for getting started
- `npm test` for running tests
- `npm run export` for updating the exported-schema (even if only the version changes)
- `npm run docs` for updating docs (even if only the version changes)
- `npm run coverage` for running tests and displaying test coverage
- `yarn` to install packages and get started
- `yarn lint` to lint code
- `yarn test` to run tests
- `yarn smoke-test` to run smoke tests
- `yarn coverage` to run tests and display test coverage
- `yarn validate` to run tests, smoke tests, and linter
- `yarn export` to update the exported-schema (even if only the version changes)
- `yarn docs` to update docs (even if only the version changes)
- `yarn build` to update docs and the exported-schema (even if only the version changes)

## Publishing (after merging)

- `npm version [patch|minor|major]` will pull, test, update exported-schema, update docs, increment version in package.json, push tags, and publish to npm
- `yarn version --[patch|minor|major]` will pull, test, update exported-schema, update docs, increment version in package.json, push tags, and publish to npm
1,387 changes: 935 additions & 452 deletions packages/schema/docs/build/schema.md

Large diffs are not rendered by default.

8 changes: 4 additions & 4 deletions packages/schema/exported-schema.json
Original file line number Diff line number Diff line change
Expand Up @@ -240,19 +240,18 @@
"id": "/FunctionRequireSchema",
"description": "A path to a file that might have content like `module.exports = (z, bundle) => [{id: 123}];`.",
"type": "object",
"additionalProperties": false,
"required": ["require"],
"properties": {
"require": {
"type": "string"
}
}
},
"additionalProperties": false
},
"FunctionSourceSchema": {
"id": "/FunctionSourceSchema",
"description": "Source code like `{source: \"return 1 + 2\"}` which the system will wrap in a function for you.",
"type": "object",
"additionalProperties": false,
"required": ["source"],
"properties": {
"source": {
Expand All @@ -267,7 +266,8 @@
},
"description": "Function signature. Defaults to `['z', 'bundle']` if not specified."
}
}
},
"additionalProperties": false
},
"FlatObjectSchema": {
"id": "/FlatObjectSchema",
Expand Down
11 changes: 9 additions & 2 deletions packages/schema/lib/schemas/AppFlagsSchema.js
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,13 @@ module.exports = makeSchema({
},
},
additionalProperties: false,
examples: [{ skipHttpPatch: true }, { skipHttpPatch: false }, {}],
antiExamples: [{ blah: true }, { skipHttpPatch: 'yes' }],
examples: [
{ skipHttpPatch: true },
{ skipHttpPatch: false },
{},
],
antiExamples: [
{ example: { foo: true }, reason: 'Invalid key.' },
{ example: { skipHttpPatch: 'yes' }, reason: 'Invalid value.' },
],
});
13 changes: 13 additions & 0 deletions packages/schema/lib/schemas/AppSchema.js
Original file line number Diff line number Diff line change
Expand Up @@ -118,6 +118,19 @@ module.exports = makeSchema(
},
},
additionalProperties: false,
examples: [
{ version: '1.0.0', platformVersion: '10.1.1' },
],
antiExamples: [
{
example: { version: 'v1.0.0', platformVersion: '10.1.1' },
reason: 'Invalid value for version.',
},
{
example: { version: '1.0.0', platformVersion: 'v10.1.1' },
reason: 'Invalid value for platformVersion.',
},
],
},
[
AuthenticationSchema,
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -9,4 +9,8 @@ module.exports = makeSchema({
type: 'object',
properties: {},
additionalProperties: false,
examples: [{}],
antiExamples: [
{ example: { foo: true }, reason: 'Invalid key.' },
],
});
Original file line number Diff line number Diff line change
Expand Up @@ -9,4 +9,8 @@ module.exports = makeSchema({
type: 'object',
properties: {},
additionalProperties: false,
examples: [{}],
antiExamples: [
{ example: { foo: true }, reason: 'Invalid key.' },
],
});
Original file line number Diff line number Diff line change
Expand Up @@ -9,4 +9,8 @@ module.exports = makeSchema({
type: 'object',
properties: {},
additionalProperties: false,
examples: [{}],
antiExamples: [
{ example: { foo: true }, reason: 'Invalid key.' },
],
});
16 changes: 16 additions & 0 deletions packages/schema/lib/schemas/AuthenticationOAuth1ConfigSchema.js
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,22 @@ module.exports = makeSchema(
},
},
additionalProperties: false,
examples: [
{
getRequestToken: { require: 'some/path/to/file.js' },
authorizeUrl: { require: 'some/path/to/file2.js' },
getAccessToken: { require: 'some/path/to/file3.js' },
},
],
antiExamples: [
{
example: {
getRequestToken: { require: 'some/path/to/file.js' },
authorizeUrl: { require: 'some/path/to/file2.js' },
},
reason: 'Missing required key.',
},
],
},
[FunctionSchema, RedirectRequestSchema, RequestSchema]
);
21 changes: 21 additions & 0 deletions packages/schema/lib/schemas/AuthenticationOAuth2ConfigSchema.js
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,27 @@ module.exports = makeSchema(
},
},
additionalProperties: false,
examples: [
{
authorizeUrl: { require: 'some/path/to/file.js' },
getAccessToken: { require: 'some/path/to/file2.js' },
},
{
authorizeUrl: { require: 'some/path/to/file.js' },
getAccessToken: { require: 'some/path/to/file2.js' },
refreshAccessToken: { require: 'some/path/to/file3.js' },
scope: 'read/write',
autoRefresh: true,
},
],
antiExamples: [
{
example: {
authorizeUrl: { require: 'some/path/to/file.js' },
},
reason: 'Missing required key getAccessToken.',
},
],
},
[FunctionSchema, RedirectRequestSchema, RequestSchema]
);
73 changes: 51 additions & 22 deletions packages/schema/lib/schemas/AuthenticationSchema.js
Original file line number Diff line number Diff line change
Expand Up @@ -16,28 +16,6 @@ module.exports = makeSchema(
{
id: '/AuthenticationSchema',
description: 'Represents authentication schemes.',
examples: [
{ type: 'basic', test: '$func$2$f$' },
{ type: 'custom', test: '$func$2$f$', fields: [{ key: 'abc' }] },
{
type: 'custom',
test: '$func$2$f$',
connectionLabel: '{{bundle.inputData.abc}}',
},
{ type: 'custom', test: '$func$2$f$', connectionLabel: '$func$2$f$' },
{ type: 'custom', test: '$func$2$f$', connectionLabel: { url: 'abc' } },
],
antiExamples: [
{},
'$func$2$f$',
{ type: 'unknown', test: '$func$2$f$' },
{ type: 'custom', test: '$func$2$f$', fields: '$func$2$f$' },
{
type: 'custom',
test: '$func$2$f$',
fields: [{ key: 'abc' }, '$func$2$f$'],
},
],
type: 'object',
required: ['type', 'test'],
properties: {
Expand Down Expand Up @@ -74,6 +52,57 @@ module.exports = makeSchema(
sessionConfig: { $ref: AuthenticationSessionConfigSchema.id },
},
additionalProperties: false,
examples: [
{
type: 'basic',
test: '$func$2$f$',
},
{
type: 'custom',
test: '$func$2$f$',
fields: [{ key: 'abc' }],
},
{
type: 'custom',
test: '$func$2$f$',
connectionLabel: '{{bundle.inputData.abc}}',
},
{
type: 'custom',
test: '$func$2$f$',
connectionLabel: '$func$2$f$',
},
{
type: 'custom',
test: '$func$2$f$',
connectionLabel: { url: 'abc' },
},
],
antiExamples: [
{
example: {},
reason: 'Missing required keys: type and test',
},
{
example: '$func$2$f$',
reason: 'Must be object',
},
{
example: {
type: 'unknown',
test: '$func$2$f$',
},
reason: 'Invalid value for key: type',
},
{
example: {
type: 'custom',
test: '$func$2$f$',
fields: '$func$2$f$',
},
reason: 'Invalid value for key: fields',
},
],
},
[
FieldsSchema,
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,15 @@ module.exports = makeSchema(
},
},
additionalProperties: false,
examples: [
{ perform: { require: 'some/path/to/file.js' }, },
],
antiExamples: [
{
example: {},
reason: 'Missing required key: perform',
},
],
},
[FunctionSchema, RequestSchema]
);
19 changes: 19 additions & 0 deletions packages/schema/lib/schemas/BasicActionOperationSchema.js
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
'use strict';

const makeSchema = require('../utils/makeSchema');
const { SKIP_KEY } = require('../constants');

const BasicOperationSchema = require('./BasicOperationSchema');
const FunctionSchema = require('./FunctionSchema');
Expand Down Expand Up @@ -34,6 +35,24 @@ BasicActionOperationSchema.properties = {
sample: BasicActionOperationSchema.properties.sample,
};

BasicActionOperationSchema.examples = [
{
perform: { require: 'some/path/to/file.js' },
sample: { id: 42, name: 'Hooli' },
},
];

BasicActionOperationSchema.antiExamples = [
{
[SKIP_KEY]: true, // Cannot validate that sample is only required if display isn't true / top-level resource doesn't have sample
example: {
perform: { require: 'some/path/to/file.js' },
},
reason:
'Missing required key: sample. Note - This is only invalid if `display` is not explicitly set to true and if it does not belong to a resource that has a sample.',
},
];

module.exports = makeSchema(
BasicActionOperationSchema,
BasicOperationSchema.dependencies
Expand Down
55 changes: 38 additions & 17 deletions packages/schema/lib/schemas/BasicDisplaySchema.js
Original file line number Diff line number Diff line change
@@ -1,28 +1,12 @@
'use strict';

const makeSchema = require('../utils/makeSchema');
const { SKIP_KEY } = require('../constants');

module.exports = makeSchema({
id: '/BasicDisplaySchema',
description: 'Represents user information for a trigger, search, or create.',
type: 'object',
examples: [
{ label: 'New Thing', description: 'Gets a new thing for you.' },
{
label: 'New Thing',
description: 'Gets a new thing for you.',
directions: 'This is how you use the thing.',
hidden: false,
important: true,
},
],
antiExamples: [
{
label: 'New Thing',
description: 'Gets a new thing for you.',
important: 1,
},
],
properties: {
label: {
description:
Expand Down Expand Up @@ -68,4 +52,41 @@ module.exports = makeSchema({
},
},
additionalProperties: false,
examples: [
{ hidden: true },
{ label: 'New Thing', description: 'Gets a new thing for you.' },
{
label: 'New Thing',
description: 'Gets a new thing for you.',
directions: 'This is how you use the thing.',
hidden: false,
important: true,
},
],
antiExamples: [
{
[SKIP_KEY]: true, // Cannot validate that description is required if hidden is false
example: {
label: 'New Thing',
hidden: false,
},
reason: 'Missing required key: description',
},
{
[SKIP_KEY]: true, // Cannot validate that description is required if hidden is false
example: {
description: 'Gets a new thing for you.',
hidden: false,
},
reason: 'Missing required key: label',
},
{
example: {
label: 'New Thing',
description: 'Gets a new thing for you.',
important: 1,
},
reason: 'Invalid value for key: important',
},
],
});
Loading