[DOCUMENTATION] event descriptor documentation about external field
Opened this issue · 1 comments
Two pieces of documentation in this report could be clearer.
https://github.com/bluesky/event-model/blob/master/docs/source/event-descriptors.rst
(optional) external --- a string specifying where external data, such as a large image array, is stored
It seems the right answer for many cases is the string
'external': 'FILESTORE:'
but I don't see this in the documentation. I would edit myself in a PR, but I don't know all the things that this was intended to take. The way I read datbroker.core._documents_to_xarray, it maybe doesn't matter what the value is, just that the field is there.
From https://blueskyproject.io/event-model/external.html
The presence of the key 'external' indicates that the Events’ 'image' contains a reference to an asset outside the documents. (The value of that key is not currently used by any part of the system; only its existence is checked for. The value may be used in the futue as a hook for integration with outside systems.)
The description in the schema should be updated to reflect this.