Summary
As discussed with @oruebel, MeaningsTable.target is currently defined as a link to a VectorData. It should likely be an object-reference attribute instead, matching VectorIndex.target and DynamicTableRegion.table.
# current
links:
- name: target
target_type: VectorData
doc: Link to the VectorData object for which this table provides meanings.
# proposed
attributes:
- name: target
dtype:
target_type: VectorData
reftype: object
doc: Reference to the VectorData object for which this table provides meanings.
Rationale
NWB/HDMF has used a pretty consistent heuristic for the two mechanisms:
- Link — points to a shared, standalone object owned elsewhere in the file (and possibly in another file, since links can be external). Examples:
Device, ImagingPlane, source TimeSeries.
- Object-reference attribute/dtype — points to a co-located dataset from within table/column machinery. Examples:
VectorIndex.target, DynamicTableRegion.table, ElectrodesTable.group (dataset of references), ImageReferences (dataset of references).
MeaningsTable.target is the second case: it points to a VectorData column of the same DynamicTable that owns the meanings group. The target must be a column of that table, so the target is inherently co-located and the link's only unique advantage (cross-file reach) does not apply. VectorIndex.target is the exact precedent: same target type, same name, same "annotate a column of this table" role, defined as an object reference.
Cost / consideration
This is technically a breaking schema change: files already written with a target link (schema 1.9.0+) would not match the new definition. But hdmf-common-schema 1.9.0 was not being used until nwb-schema 2.10.0 and PyNWB 4.0.0 were released last/this week, so I believe we can make a quick fix to the type, with compatibility support for files already written with a target link, before widespread usage.
Summary
As discussed with @oruebel,
MeaningsTable.targetis currently defined as a link to aVectorData. It should likely be an object-reference attribute instead, matchingVectorIndex.targetandDynamicTableRegion.table.Rationale
NWB/HDMF has used a pretty consistent heuristic for the two mechanisms:
Device,ImagingPlane, sourceTimeSeries.VectorIndex.target,DynamicTableRegion.table,ElectrodesTable.group(dataset of references),ImageReferences(dataset of references).MeaningsTable.targetis the second case: it points to aVectorDatacolumn of the sameDynamicTablethat owns themeaningsgroup. The target must be a column of that table, so the target is inherently co-located and the link's only unique advantage (cross-file reach) does not apply.VectorIndex.targetis the exact precedent: same target type, same name, same "annotate a column of this table" role, defined as an object reference.Cost / consideration
This is technically a breaking schema change: files already written with a
targetlink (schema 1.9.0+) would not match the new definition. But hdmf-common-schema 1.9.0 was not being used until nwb-schema 2.10.0 and PyNWB 4.0.0 were released last/this week, so I believe we can make a quick fix to the type, with compatibility support for files already written with atargetlink, before widespread usage.