Introducing Plotly.validate(data, layout)

[etpinard]

resolves #598

based off plotly-validate and lib-validate.

Example

var data = [{
  type: 'bar',
  y: [2, 1, 2],
  orientation: 'horizontal'
}];

var out = Plotly.validate(data);

console.log(out[0].msg));
// "In data trace 0, key orientation is set to an invalid value (horizontal)"

In brief

This PR expose a top-level method allowing users to validate their input data and layout.

Plotly.validate calls Plots.supplyDefaults and PlotSchema.get and a new Lib.validate method internally to determine if:

• [code 'object'] a container key isn't linked to an object
• [code 'array'] an array container key isn't linked to an array
• [code 'schema'] a key was found in a trace or layout object that is not part of the plot schema
• [code 'unused'] a key was found in user input but isn't used in the plotting code (i.e. the key isn't found fullData or fullLayout )
• [code 'value'] a value is invalid
• [code 'invisible'] a trace was made visible = false by an invalid set of attributes

Some remaining questions

• How to handle non-array data and non-object layout input? Error out?, Output with different other error code?
• When no validate errors found, should Plotly.validate return true? More generally, should Plotly.validate always return the a { data: [], layout: [] } object?

Those questions ⏫ were resolved in 54a6ed0

[etpinard]

@mdtusz Plotly.validate returns an array of nested keys, as you suggested.

Maybe we should also return the .join('.') version for folks using Lib.nestedProperty ?

Moreover, I thought also about writing paths to _isLinkedToArray attributes as e.g.

['xaxis', 'rangeselector', 'buttons', 1 'title']

// instead of
['xaxis', 'rangeselector', 'buttons[1]', 'title']

Thoughts?

[alexcjohnson]

Moreover, I thought also about writing paths to _isLinkedToArray attributes as e.g.

['xaxis', 'rangeselector', 'buttons', 1, 'title']

// instead of
['xaxis', 'rangeselector', 'buttons[1]', 'title']

I added your missing comma, but yes, if you're going to return an array like that, integers for array indices is the way to go so you could just loop through with container = container[path[i]]. I would think though that, aside from our own internal uses (which can certainly use Lib.nestedProperty unless we export these results to another language), folks will rarely want programmatic access to these items. Mostly they'd just want something easy to look at and spot their error, in which case I'd think the single string version is nicer.

[mdtusz]

I'd say go with the more split-up integer notation.

folks will rarely want programmatic access to these items

Chelsea will attest that they always want programmatic access. I don't think that the non-string version is really any more difficult to grok, and the all string version just adds more complexity to programatic usage for when the case arises.

[etpinard]

Why not output both then?

I think the workspace (cc @chriddyp) uses Lib.nestedProperty (or some in-house version of it), so outputing an attribute string might be best for them.

But, I agree, an array of path parts is best for users just wanting to spot their errors.

[etpinard]

I decided to output both an array path and an attribute string astr field. The path field should be more readable while the astr field will be useful for compatibility with Plotly.restyle and Plotly.relayout.

See tests here.

[bpostlethwaite]

so the

failed = {}
out = failed
coerce(() => out = v)
out !== failed

dance is just checking to see if if propMock is fired by checking to see if the exising out === failed reference is no longer valid?

[etpinard]

Exactly.

[bpostlethwaite]

would something like

var called = false;
var propMock = {set: function() { called = true }

 valObject.coerceFunction(value, propMock, failed, opts);

return called;

also work?

[etpinard]

No. Because we want coerced values to be considered valid.

For example,

Lib.validate('1', { valType: 'number' });  // => true

even though 1 will be inserted in fullData.

In other words, out and failed will be linked to different refs when the coerce function makes propMock execute propMock.set(dflt).

[bpostlethwaite]

right makes sense

[bpostlethwaite]

Looks good from my view! 💃