Vega-lite: Improve docs for dots in signal name

[Folcon]

Hi, firstly thanks for the library =)... It's great and really usable, I did however have a surprising interaction which I'll detail below.

I rendered a longer version of the vega-lite spec below and it generated no output, I pulled up the warnings and saw No error or warnings. I only realised the problem after digging into this issue on the vega issues list.

It would be helpful if any labels are not valid/may not be valid would throw up a warning? As that's not something I would expect to normally be a problem...

I doubt I personally will trip over this in the future, but it would be a nice addition to the already existing suit of feedback you get when you mess up.

{
  "data": {
    "values": [
      {
        "day": 1,
        "measurement": -45.681350765351375,
        "estimate-0.1": -0.06813507653513806,
        "estimate-0.4": -15.272540306140552,
        "estimate-0.8": -35.545080612281104
      },
      {
        "day": 2,
        "measurement": 47.13935530761721,
        "estimate-0.1": 3.7403496481037726,
        "estimate-0.4": 9.084041730178338,
        "estimate-0.8": 30.399742720576143
      },
      {
        "day": 3,
        "measurement": -12.085906115629815,
        "estimate-0.1": 2.1134398711443576,
        "estimate-0.4": 0.7689926542196375,
        "estimate-0.8": -3.4567094997092127
      }
    ]
  },
  "transform": [
    {"fold": ["measurement", "estimate-0.1", "estimate-0.4", "estimate-0.8"]}
  ],
  "width": 800,
  "height": 600,
  "mark": {"type": "line", "tooltip": {"content": "data"}, "point": true},
  "encoding": {
    "x": {"field": "day", "type": "quantitative"},
    "y": {
      "field": "value",
      "type": "quantitative",
      "scale": {"domain": [-45, 310]}
    },
    "color": {"field": "key", "type": "nominal"}
  }
}

this clearly does:

{
  "data": {
    "values": [
      {
        "day": 1,
        "measurement": -45.681350765351375,
        "estimate-01": -0.06813507653513806,
        "estimate-04": -15.272540306140552,
        "estimate-08": -35.545080612281104
      },
      {
        "day": 2,
        "measurement": 47.13935530761721,
        "estimate-01": 3.7403496481037726,
        "estimate-04": 9.084041730178338,
        "estimate-08": 30.399742720576143
      },
      {
        "day": 3,
        "measurement": -12.085906115629815,
        "estimate-01": 2.1134398711443576,
        "estimate-04": 0.7689926542196375,
        "estimate-08": -3.4567094997092127
      }
    ]
  },
  "transform": [
    {"fold": ["measurement", "estimate-01", "estimate-04", "estimate-08"]}
  ],
  "width": 800,
  "height": 600,
  "mark": {"type": "line", "tooltip": {"content": "data"}, "point": true},
  "encoding": {
    "x": {"field": "day", "type": "quantitative"},
    "y": {
      "field": "value",
      "type": "quantitative",
      "scale": {"domain": [-45, 310]}
    },
    "color": {"field": "key", "type": "nominal"}
  }
}

[domoritz]

A . indicates nesting. What exactly is the condition that you think should show a warning?

[Folcon]

Sorry, just that it's not necessarily obvious that . indicates nesting at all? I mean all this time I was under the impression that the signal field was a type of label, referencing the field in data sure. I suppose it's a question if that's obvious or not?

Hence suggesting that it might merit a warning? I mean I was faced with a blank plot after working with vega-lite for a while, meaning that I spent a while trying to workout what in my spec was broken and being really puzzled that I wasn't getting errors, then wondering if vega-lite was broken...

To be honest I don't have much of a stake in this, as I said, I doubt I'm going to trip over this in future, but it does feel like a rough edge that will trip up someone new to the lib, however it's wholly within your remit to decide it will just add noise =)...

[domoritz]

Thank you so much for raising the issue and describing an improvement. It's really helpful to hear this kind of feedback.

I don't think I want to add a default warning whenever a field name uses . but we should definitely make sure that the docs are clear. In the future, we should improve tracking of what fields are used, which would enable warnings for any kind of unrecognized field.

The tracking feature request is in https://github.com/vega/vega-lite/issues/2862. I am marking this as a documentation request. Sounds good?

[Folcon]

Sure, feel free to close this =)...

[domoritz]

I'll close it when I think the docs are good enough.