Tagged model serialization: let a document say which class it holds

[d-chambers]

DASCore's models do not say what they are when serialized, so a document can only be read back by something which already knows what it holds. Position supplies that knowledge inside a nested document, and nothing supplies it anywhere else. Three things want that fixed, one of them already broken today.

Writing this up as a direction rather than a plan; the parts marked open at the bottom are genuinely open.

1. A custom PatchAttrs subclass does not survive a round trip

There are 17 PatchAttrs subclasses under dascore/io/, one per format that carries fields the base class does not model. None of them come back:

import dascore as dc
from dascore.io.ai4eps.core import AI4EPSPatchAttrs

patch = dc.get_example_patch()
attrs = AI4EPSPatchAttrs(**dict(patch.attrs), event_id="ev1")
patch = patch.update(attrs=attrs)
patch.io.write(path, "dasdae")

type(dc.read(path)[0].attrs)   # PatchAttrs, not AI4EPSPatchAttrs

Through DASDAE the values survive, because HDF5 keeps the numpy types, so today the loss is isinstance and the subclass's own validation. Through a text format the coercion goes as well: a DateTime64 field arrives as a string and nothing re-coerces it, because the class that declared it is not the class being built.

2. Some of those subclasses cannot round trip through a text format at all

Independent of the above, and a prerequisite for it. AI4EPSPatchAttrs cannot be reconstructed from its own model_dump_json():

pydantic_core._pydantic_core.ValidationError: 4 validation errors for Patch Summary
magnitude
  Input should be a valid number [type=float_type, input_value=None, input_type=NoneType]

magnitude: float = np.nan serializes to null, and a float field then refuses None. The pattern appears in roughly ten IO modules (odh4, ai4eps, ap_sensing, optodas, febus, sr4731, sintela, prodml, xml_binary). The inventory models avoided it by spelling an optional number FiniteFloat | None, which serializes to null and reconstructs; migrating to that is the fix, and it is a behavior change for anyone reading such a field expecting NaN.

Naming the class is worth nothing until this is fixed: dispatch would find the right class, which would then refuse to build.

3. What is coming

• Standalone serialization. Any object should be writable to YAML and readable back on its own. There is no enclosing document then, so nothing but the document itself can say what it is.
• Regions of interest. Squares, polygons and similar annotations are not inventory, but should share this machinery rather than grow their own.
• An open set of types. Once plugins can contribute shapes, a closed Literal discriminator cannot enumerate what it does not know.

Proposed direction

A tag naming the class, resolved through a registry.

A registered name, never an import path. dascore.core.inventory.Cable welds stored documents to today's module layout — moving a class between modules would break every file on disk — and resolving a dotted path out of user data is an arbitrary-import surface in a format meant to be read from someone else's archive. A registry lookup costs the same to write and has neither property. FiberIO is the in-house precedent.

Namespaced value, bare name means dascore. type: Cable keeps working and stays hand-authorable, which matters because the inventory authoring format has a type column in its union CSVs that a field crew fills in per row. A plugin registers under its own prefix, myplugin:Square.

A plain type key, not a YAML tag. YAML's native tag syntax (!core/ndarray-1.0.0) has no JSON equivalent, and .json and .yaml are interchangeable spellings of one data model. A plain key survives both.

A serializer concern on DascoreBaseModel, not a field on every model. A model_serializer plus a before-validator can inject and check the tag universally, so it round trips everywhere without landing in model_fields, get_summary_df, or the generated reference tables. The two genuinely discriminated unions (_Resource, OpticalComponent) keep their Literal field, which pydantic needs to pick a class before an object exists; the base-class check passes over them. This generalizes what already exists rather than replacing it.

Version in the tag, if ever. No separate version field: it would land in every nested object's dump, join __eq__/__hash__ (which hash field values, per #878), and be per-class rather than per-instance if it means a schema version. Room for dascore:Cable-0.0.1 later, with an absent version meaning the earliest — which needs nothing today and never requires assigning one retroactively.

Where it lives. dascore/utils/models.py, on DascoreBaseModel, since the first three customers are PatchAttrs, the inventory models, and ROIs. It is DASCore's tagged-model serialization, not an inventory feature borrowed later.

Relationship to the inventory authoring format

Independent, and deliberately so. The authoring-format loader already requires type in every object file and reads it as a property of the format, popping it for the models where it is not a discriminating field. Its entire coupling to this question is two lines and one test pinning which models carry the field. When universal tags land, the pop disappears and the pin inverts.

Open questions

• Does PatchAttrs get a tag? It is the first customer and the reason this is worth doing, but it is also on the hot path and feeds the index, so the blast radius is larger than for the inventory models.
• Do nested objects carry a tag, or only ones which can stand alone? Universal is simpler to explain; selective is quieter in the document.
• Whether the ~10 nan-defaulted float fields in §2 should be their own issue and fix, landing first.