feature request: Input validation for spawned apps

[wejendorp]

Problem

Calling third party applications seems potentially error prone, since data
is not standardized in any way. The best case scenario, an app will have good
documentation, and a way to report back when called with missing values.

Proposal

To provide a clear API to consumers of an app, when triggering it from a remote
via .spawn. This can be done via runtime validation of the call options,
basically allowing the hub or io on the app side to verify the payload as soon
as the app calls .define.

From the spawned app point of view, it should be possible to define a validation
schema (in some form), for the options with types, default values and descriptions.

From the consumer point of view, the validation errors should be made available
as an easily understandable error object. This puts some requirements on the
validation library / functions being used.

Example:

io()
	.spawn('Tradeshift.UserSelector', { internalOnly: 'true' })
	.then(
		([err, res]) => {
			// err: internalOnly should be boolean
			// err: companyId is required
		},
		err => {
			// Should it be a "system" error, since it can be compared to a TypeError?
		}
	);

Potential validation solutions:

Emphasis should be on the human readability of the errors, such that it's easy
to correct your mistakes, without needing to rely on (out of sync) documentation.

• JSON schema based; ajv
• Joi / Hapijs ecosystem: joi
• Sinde Sorhus based: ow

Exploring the API, this could be something like

app.define({
	// JSON Schema:
	schema: {
		type: 'object',
		additionalProperties: false,
		properties: {
			companyId: { type: 'string', minLength: 32, maxLength: 32 }
		},
		required: ['companyId']
	},
	// or HapiJS style:
	validate: {
		companyId: Joi.string()
			.min(32)
			.max(32)
			.required()
	},
	spawn(data, submit, parent) {
		// ...
	}
});

I like the plain object style, since it doesn't impose more libraries.
For ajv we have some formatters in v4 to make the errors more user friendly.