Add optional num_samples dataset to ImageSeries for external file timing

core/nwb.image.yaml

@@ -102,6 +102,14 @@ groups:
         attribute will have values [0, 5, 15]. If there is a single external file that
         holds all of the frames of the ImageSeries (and so there is a single element in
         the 'external_file' dataset), then this attribute should have value [0].
+  - name: num_samples
+    dtype: uint32
+    doc: Total number of frames across all external files. This is required when
+      format='external' and timing is described using starting_time and rate, since
+      data is empty and its first dimension cannot be used to determine the number
+      of frames. When timestamps is provided, len(timestamps) already serves this
+      purpose.
+    quantity: '?'
   - name: format
     dtype: text
     default_value: raw

docs/format/source/format_release_notes.rst

@@ -12,11 +12,15 @@ Major changes
 
 Minor changes
 ^^^^^^^^^^^^^
+- Added optional ``num_samples`` dataset (``uint32``) to ``ImageSeries`` to store the total number of frames
+  across all external files. This is needed when ``format='external'`` and timing is described using
+  ``starting_time`` and ``rate``, since ``data`` is empty and its first dimension cannot be used to determine
+  the number of frames. (#561, #543, #677, #678)
 - Improved documentation of ``ElectrodeGroup`` to clarify its purpose as a physical grouping of electrodes
   that are typically used together for analysis, such as spike sorting. (#659)
 - Specified that units for ``ElectrodesTable`` coordinate fields (``x``, ``y``, ``z``, ``rel_x``, ``rel_y``, ``rel_z``)
   should be in microns. (#658)
-- Expanded documentation for the ``Subject`` 'age' dataset, including details on ISO 8601 Duration format and 
+- Expanded documentation for the ``Subject`` 'age' dataset, including details on ISO 8601 Duration format and
   age range representation.
 
 2.9.0 (June 26, 2025)