Enrich Specs

[danielballan]

Specs are currently given as a list of strings, like

["XDI", "HasBatteryChargeData"]

I propose to promote them to a list of objects with one required field (the name, as now) and some optional ones. A minimal spec might look like

[{"spec": "XDI"}, {"spec": "HasBatteryChargeData"}]

Below are some additional optional fields we may want.

Version

This would refer to the version of the standard or schema. Validators would have access to the version and be able to switch their behavior on it.

{"spec": "XDI", "version": 1}

Alternatively, we could do this in-band, as in XDI_1 or some such thing, but doing it out-of-band has advantages:

• straightforward version comparisons (e.g. version > N)
• simple dispatch to validators and custom clients based on the just the spec, leaving version concerns as an internal detail

@maffettone has emphasizes that versioning schemas is an important lesson learned. I'm 50/50 on whether we should require version but I think we should at least support it.

Location

In BMM's Bluesky metadata, XDI is stored under a subkey (I think it's just "XDI"). I could imagine various data providers placing the same standard metadata in various subsidiary keys. It may be useful to indicate where the specified metadata "starts".

{"spec": "XDI", "loc": "start.XDI"}

where the value of "loc" could be standardized to be a JMESPath, which we already use for optionally filtering metadata in Tiled.

Others?

Of course, once we take the leap from string to object, it's easy to add other fields in the future.

Downsides

This makes specs more complex and verbose. In the Python API we can ameliorate this by using a dataclass Spec with optional arguments:

Adapter(
    ...,
    specs=[Spec("BlueskyRun"), Spec("XDI", version=1, loc="start.XDI")],
)

[danielballan]

Thoughts, @dylanmcreynolds @jmaruland @kleinhenz @x94carbone?

[danielballan]

Sorry @maffettone I "assigned" you but what I meant to you was tag you to solicit your thoughts/feedback.

[maffettone]

The dataclass definitely seems like a meaningful way to interface it.

The curiosity I have is, where are valid (or tiled seal of approval) specs kept? Or do we give people space in their config to hold "valid specs"?

And how to best version the specs? Tough to use versioneer or an automated tool, but the danger of it being a string field is that it never gets updated. Still all is better than than the EPICS way of having AD_V33, AD_V34, AD_V35...

[matthewcarbone]

@danielballan This is a good idea.

My first very realistic use case for this is as follows. Perhaps we have a spec for XAS and someone at some beam line proposes adding new information (a new column, or new metadata). The spec should be versioned the same way a software package might. Given that adding a new column or metadata will be de-facto backwards compatible (all methods defined on v1.0 should work on v1.1), the version can reflect that. I.e.,

v1.0  # First version
v1.1  # Second version

That way we don't run into situations where specs are like XAS, XAS-v2, XAS-v-Eli, and whatnot. We can simply use accepted semantics for versioning.

Backwards incompatible changes could possibly occur during development but also if the community decides at some point that certain metadata requires significant changes. Those could be indexed the same way major changes are to a version:

v1.0
v2.0  # Not compatible with any postprocessing <v2.0

The same logic could be applied to this as are to real software.

@maffettone dunamai is my choice for this. Much cleaner than using versioneer 😊

[danielballan]

Yes, the valid specs are defined in config, associated with validators, as in:

https://github.com/AI-multimodal/aimmdb/blob/8851d5335206bf926b03179d4a697dacd86697bb/deploy/spin/config/config.yml#L97

I think we can leave it the validators to enforce internally any bounds on supported versions of the spec that they validate.

Specs mean different things: some will be invented for a given purpose and never have any broader use or definition outside of a particular project. Other like XDI are an external standard with a versioned scheme. I think the question of how spec versions are bumped will vary case to case, and it is outside of Tiled’s scope.

I suppose versions have to be strings, yeah, not integers as I gave in my basic example.

[jmaruland]

I like this approach. It feels that it lands somewhere in the middle between the current implementation and the other model that we discussed before about having a tree of specs where children can inherit the features of the parent but not share between them. What I like about this new approach is that it considers that a spec is not necessarily static during the lifecycle of a project, for example Data models can change/updated and this approach helps to keep track of the validators once we start adding more in a server.

[maffettone]

Re-reading all this after the sick week.

Support the ideas presented, and yes, allowing the version to be any hashable would be good (i.e. could be a commit, and AWS hashkey, or just a number for sanity). I can imagine deploying a version of tiled and a version of a spec to a web service that houses a processing pipeline, and wanting an easy way to test on new commits of the spec.