search

bluesky / event-model

data model for event-based data collection and analysis
https://blueskyproject.io/event-model
BSD 3-Clause "New" or "Revised" License
15 stars 31 forks source link

[DOCUMENTATION] event descriptor documentation about external field #191

Open dylanmcreynolds opened 4 years ago

dylanmcreynolds commented 4 years ago

Two pieces of documentation in this report could be clearer.

https://github.com/bluesky/event-model/blob/14b082682a428d54e92676368777285b17815183/event_model/schemas/event_descriptor.json#L21

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.

danielballan commented 4 years ago

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.