How best to interpret/parse "items" with no "role" or "valType"

[hmf]

I realize this may not be the best place to ask this. If so please redirect me to a more appropriate forum.

My testing of a Scala wrapper failed on (among others) these mocks:

• gl2d_parcoords_select_first_last_enum.json
• cheater_constraint_greater_than_with_hill.json
• mocks/box-violin-x0-category-position.json
• indicator_format_extremes.json
• splom_lower-nodiag-matching.json
• bar-alignment-offset.json
• cheater_constraint_outer_range_hi_top.json
• fonts.json

I have realized that all have a schema with the following shape (example based on gl2d_parcoords_select_first_last_enum.json):

                "dimensions": {
                    "items": {
                        "dimension": {
                            "label": {
                                "valType": "string",
                                "role": "info",
                                "editType": "plot",
                                "description": "The shown name of the dimension."
                            },
                            "tickvals": {
                                "valType": "data_array",
                                "editType": "plot",
                                "description": "Sets the values at which ticks on this axis appear.",
                                "role": "data"
                            },
                           "role": "object"
                    },
                    "role": "object"
                },

Looking at the JSON documents, it seems like "items" is a JSON array that contains objects of a specific type (in the example above it would be "dimension"). But the schema does not seem to make this explicit. Trying to work out how to parse this consistently. How should I go about it - can I assume that this is always so?

I may be missing something, but this may be a candidate for another "valOjects". By tagging "items"it would make it easier to parse.

Appreciate any help.

[alexcjohnson]

Hmm that does seem confusing... @nicolaskruchten @jonmmease care to comment on how plotly.py identifies container arrays in the schema?

[hmf]

I have now found the indicator schema has the same structure:

                    "steps": {
                        "items": {
                            "step": {
                                "color": {
                                    "valType": "color",
                                    "editType": "plot",
                                    "role": "info",
                                    "description": "Sets the background color of the arc."
                                },
                                "line": {
                                    "color": {
                                        "valType": "color",
                                        "role": "info",
                                        "dflt": "#444",
                                        "editType": "plot",
                                        "description": "Sets the color of the line enclosing each sector."
                                    },
                                    "width": {
                                        "valType": "number",
                                        "role": "info",
                                        "min": 0,
                                        "dflt": 0,
                                        "editType": "plot",
                                        "description": "Sets the width (in px) of the line enclosing each sector."
                                    },
                                    "editType": "calc",
                                    "role": "object"
                                },
                                "thickness": {
                                    "valType": "number",
                                    "role": "info",
                                    "min": 0,
                                    "max": 1,
                                    "dflt": 1,
                                    "editType": "plot",
                                    "description": "Sets the thickness of the bar as a fraction of the total thickness of the gauge."
                                },
                                "editType": "calc",
                                "range": {
                                    "valType": "info_array",
                                    "role": "info",
                                    "items": [
                                        {
                                            "valType": "number",
                                            "editType": "plot"
                                        },
                                        {
                                            "valType": "number",
                                            "editType": "plot"
                                        }
                                    ],
                                    "editType": "plot",
                                    "description": "Sets the range of this axis."
                                },
                                "name": {
                                    "valType": "string",
                                    "role": "style",
                                    "editType": "none",
                                    "description": "When used in a template, named items are created in the output figure in addition to any items the figure already has in this array. You can modify these items in the output figure by making your own item with `templateitemname` matching this `name` alongside your modifications (including `visible: false` or `enabled: false` to hide it). Has no effect outside of a template."
                                },
                                "templateitemname": {
                                    "valType": "string",
                                    "role": "info",
                                    "editType": "calc",
                                    "description": "Used to refer to a named item in this array in the template. Named items from the template will be created even without a matching item in the input figure, but you can modify one by making an item with `templateitemname` matching its `name`, alongside your modifications (including `visible: false` or `enabled: false` to hide it). If there is no template or no matching item, this item will be hidden unless you explicitly show it with `visible: true`."
                                },
                                "role": "object"
                            }
                        },
                        "role": "object"
                    },

but a corresponding mock:

plotly.js/test/image/mocks/indicator_attrs.json

Line 126 in d37895b

"steps": {

does not use an array but an object.

So my question is: is this an example of what happens for a single item or is this a possibly invalid value (according to the schema)?

TIA

[nicolaskruchten]

(edited for clarity)

I think that last one is just a quirk in the indicator_attrs mock... you'll see in the baseline image that this is being ignored I think: https://github.com/plotly/plotly.js/blob/master/test/image/baselines/indicator_attrs.png (there is no blue range between -100 an 100. We should probably fix that mock and update the baseline!

Regarding the interpretation @jonmmease will be able to better speak to how we handle this in Python but yes, in general I think we treat

  "things": { 
    "role": "object",
    "items": { 
      "thing": {
        "role": "object",
        <spec>
      } 
    }
  }

to mean things is an ordered list of thing objects which have the given spec. I think in all cases there is a "role": "object" set there, so it doesn't seem all that ambiguous to me...

[nicolaskruchten]

I guess it is a little ambiguous that "having role="object" and an items key means it's a list" :)

[hmf]

@nicolaskruchten As long as it is consistent, its not ambiguous. I will change my side to look for this combination (currently not checking the "role" == "object"). As for the indicator_attrs mock, I will assume it is incorrect for now - should I report this seperately?

[nicolaskruchten]

OK, please let us know if there are any inconsistencies!

If you're able to submit a PR that just deletes the ignored attributes in any broken mocks, that would be more helpful :)

[nicolaskruchten]

@plotly/plotly_js is this mock the kind of thing that would be caught by calling our validation code? Should we fail mocks that fail validation by default, so that we don't drag around this code in mocks that does nothing?

[archmoj]

@plotly/plotly_js is this mock the kind of thing that would be caught by calling our validation code? Should we fail mocks that fail validation by default, so that we don't drag around this code in mocks that does nothing?

Tracked in #4733.

[hmf]

@nicolaskruchten Will submit a PR then.

One more question: should these consistency issues be placed here in plotly.js or in plotly.py

[nicolaskruchten]

Anything to do with the schema should be reported here in Plotly.js, as this is where the schema is maintained. The Plotly.py project auto-generates Python code based on this schema, so we can draw lessons from how we do things in Python for your Scala project, but the "single source of truth" for the structure of things is here.