Data masks

Note

When using the TrackedState and/or TrackedModel classes, data masks are created for you, so you don’t have to deal with these yourself and it will just work.

A data mask is a model’s description of what data it produces (pub), and what data it is interested in (sub). The mask specifies datasets, entity groups and attributes in the following way:

{
  "pub": {
    "some_dataset": {
      "foo_entities": ["attribute.a", "attribute.b"]
    }
  },
  "sub": {
    "some_other_dataset": {
      "bar_entities": ["attributes.c"]
    }
  }
}

The above data mask indicates that a model publishes data on foo_entities inside some_dataset and that it only ever publishes attribute.a and attribute.b. It subscribes to bar_entities in some_other_dataset, and is only interested in attribute.c

Note

A model does not need to publish every attribute that is in their pub mask at every update the pub mask only indicates that it could publish these attributes. However, if it publishes attributes that are not announced in its pub mask, these data may not be sent to all models that are interested in these data.

A data mask can contain multiple datasets and entity groups. There may be null values inside a data mask. A null value means “match everything at this level”. The following example shows valid locations for null:

{
  "pub": {
    "some_dataset": {
      "foo_entities": null
    },
    "some_other_dataset": null
  },
  "sub": null
}

The pub mask means the model could publish anything in some_dataset.foo_entities and anything in some_other_dataset. It is not obliged to do so. Meanwhile it subscribes to everything in the world state.

Empty containers ({} or []) are not allowed in a data mask, except directly after pub or sub. The following data masks shows some invalid occurences of empty containers. In these cases the entry should just be omitted from the data mask.

{
  "pub": {
    "some_dataset": {
      "foo_entities": []
    },

  },
  "sub": {
    "some_other_dataset": {}
  }
}

The exception is that the pub and sub key may contain an empty dictionary:

{
  "pub": {},
  "sub": {}
}

This means that nothing is matched, so this datamask means that the model would publish nothing, and would subscribe to nothing. (Which makes it a pretty useless model; normally a maximum of one of pub and sub would be an empty dictionary.)

Usage by the Orchestrator

The Orchestrator uses the Data Mask of every model to construct a dependency graph