Value

// A Single View or a Layer Specification
{
  ...,
  "mark/layer": ...,
  "encoding": {     // Encoding
    ...: {
      "datum": ..., // Value
    },
    ...
  },
  ...
}

You can use a datum definition to map a constant data value to an encoding channel via an underlying scale by setting the datum property.

Examples

Highlight a Specific Data Value

datum is particularly useful for annotating a certain data value.

For example, you can use it with a rule mark to highlight a certain threshold value (e.g., 200 dollars stock price).

{
  "layer": [
    {
      "data": {"url": "data/stocks.csv"},
      "mark": "line",
      "encoding": {
        "x": {"field": "date", "type": "temporal"},
        "y": {"field": "price", "type": "quantitative"},
        "color": {"field": "symbol", "type": "nominal"}
      }
    },
    {
      "data": {"values": [{}]},
      "mark": {"type": "rule", "strokeDash": [2, 2], "size": 2},
      "encoding": {
        "y": {"datum": 300}
      }
    }
  ]
}

You can also use datum with a date time definition, for example, to highlight a certain year:

{
  "layer": [
    {
      "data": {"url": "data/stocks.csv"},
      "mark": "line",
      "encoding": {
        "x": {"field": "date", "type": "temporal"},
        "y": {"field": "price", "type": "quantitative"},
        "color": {"field": "symbol", "type": "nominal"}
      }
    },
    {
      "data": {"values": [{}]},
      "mark": {"type": "rule", "strokeDash": [2, 2], "size": 2},
      "encoding": {
        "x": {"datum": {"year": 2006}}
      }
    }
  ]
}

Using Datum to Color Multi-series Chart

Another application of datum is to color a multi-series line chart created with repeat.

{
  "data": {
    "url": "data/movies.json"
  },
  "repeat": {
    "layer": ["US Gross", "Worldwide Gross"]
  },
  "spec": {
    "mark": "line",
    "encoding": {
      "x": {
        "bin": true,
        "field": "IMDB Rating",
        "type": "quantitative"
      },
      "y": {
        "aggregate": "mean",
        "field": {"repeat": "layer"},
        "type": "quantitative",
        "title": "Mean of US and Worldwide Gross"
      },
      "color": {
        "datum": {"repeat": "layer"},
        "type": "nominal"
      }
    }
  }
}