refactor: make embedded-spec read/write backend-agnostic

io.spec.writeEmbeddedSpecifications, io.spec.validateEmbeddedSpecifications,
and io.spec.readEmbeddedSpecifications were hardcoded to raw HDF5 file IDs
(H5G.open, H5L.delete, h5info, H5F.open, H5D.open/read), even though
export/read already go through the io.backend.base.Writer/Reader
abstraction everywhere else. This blocked any non-HDF5 storage backend
(e.g. a Zarr v3 writer) from ever completing nwbExport/nwbRead, since
NwbFile.embedSpecifications passed a raw H5-typed writer.FileId into
these functions regardless of the actual backend.

Adds three methods to the abstract io.backend.base.Writer interface,
implemented for HDF5Writer by delegating to the existing HDF5 utility
functions it already wraps:
  - getEmbeddedSpecLocation() (mirrors the existing Reader-side method)
  - listChildGroupNames(groupPath)
  - deleteNode(nodePath)

writeEmbeddedSpecifications/validateEmbeddedSpecifications now take the
writer object itself and only call through this interface.
readEmbeddedSpecifications now takes the reader object and is
reimplemented using the already-abstract reader.readNodeInfo/
readDatasetValue (no new Reader methods needed). NwbFile.embedSpecifications
and nwbRead's generateEmbeddedSpec are updated accordingly.

Verified against the full existing HDF5 test suite (517/521 passing; the
4 failures are pre-existing HDF5 dynamic-filter-availability issues on
this machine, unrelated to this change) plus manual round-trip checks:
fresh export, edit-mode re-export (exercises the namespace-version
overwrite path), missing-namespace warning, and unused-namespace deletion.

Note: this does not itself add a Zarr v3 writer/reader -- it only removes
the H5-specific blocker so a future non-HDF5 backend can implement
getEmbeddedSpecLocation/listChildGroupNames/deleteNode on the Writer side
(the Reader side already only needs readNodeInfo/readDatasetValue, which
every existing Reader implementation already provides) and get full
nwbExport/nwbRead support for free.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: ehennestad

+io/+backend/+base/Writer.m

@@ -33,6 +33,27 @@ function writeAttribute(obj, attributePath, value, varargin) %#ok<INUSD>
             io.backend.base.Writer.throwNotImplemented("writeAttribute")
         end
 
+        function specLocation = getEmbeddedSpecLocation(obj) %#ok<MANU>
+            % getEmbeddedSpecLocation - Return the location of embedded schema
+            % specifications, or '' if none are embedded yet. Mirrors
+            % io.backend.base.Reader.getEmbeddedSpecLocation for the write
+            % side (needed when editing a file that may already embed specs).
+            specLocation = '';
+            io.backend.base.Writer.throwNotImplemented("getEmbeddedSpecLocation")
+        end
+
+        function groupNames = listChildGroupNames(obj, groupPath) %#ok<INUSD>
+            % listChildGroupNames - Return the names of immediate child
+            % groups (not datasets) under groupPath.
+            groupNames = {};
+            io.backend.base.Writer.throwNotImplemented("listChildGroupNames")
+        end
+
+        function deleteNode(obj, nodePath) %#ok<INUSD>
+            % deleteNode - Delete the group or dataset at nodePath.
+            io.backend.base.Writer.throwNotImplemented("deleteNode")
+        end
+
         function close(obj) %#ok<MANU>
             % Default no-op. Concrete backends can override when they own
             % resources that should be released explicitly.

+io/+backend/+hdf5/HDF5Writer.m

@@ -82,6 +82,18 @@ function writeValue(obj, datasetPath, value, varargin)
         function writeAttribute(obj, attributePath, value, varargin)
             io.writeAttribute(obj.H5FileId, attributePath, value, varargin{:});
         end
+
+        function specLocation = getEmbeddedSpecLocation(obj)
+            specLocation = io.spec.internal.readEmbeddedSpecLocation(obj.H5FileId);
+        end
+
+        function groupNames = listChildGroupNames(obj, groupPath)
+            groupNames = io.internal.h5.listGroupNames(obj.H5FileId, groupPath);
+        end
+
+        function deleteNode(obj, nodePath)
+            io.internal.h5.deleteGroup(obj.H5FileId, nodePath);
+        end
     end
 
     methods (Access = protected)

+io/+spec/readEmbeddedSpecifications.m

@@ -1,12 +1,15 @@
-function specs = readEmbeddedSpecifications(filename, specLocation)
+function specs = readEmbeddedSpecifications(reader, specLocation)
 % readEmbeddedSpecifications - Read embedded specs from an NWB file
 %
-%   specs = io.spec.readEmbeddedSpecifications(filename, specLocation) read 
-%       embedded specs from the specLocation in an NWB file
+%   specs = io.spec.readEmbeddedSpecifications(reader, specLocation) reads
+%       embedded specs from the specLocation in an NWB file, using reader
+%       (an io.backend.base.Reader) to access the file. Backend-agnostic:
+%       only uses the io.backend.base.Reader interface, so this works for
+%       any registered storage backend, not just HDF5.
 %
 %   Inputs:
-%       filename (string) : Absolute path of an nwb file
-%       specLocation (string) : h5 path for the location of specs inside the NWB file
+%       reader (io.backend.base.Reader) : Reader for the NWB file
+%       specLocation (string) : Path for the location of specs inside the NWB file
 %
 %   Outputs
 %       specs cell: A cell array of structs with one element for each embedded
@@ -17,40 +20,38 @@
 %       - schemaMap (containers.Map): A set of schema specifications for the namespace
 
     arguments
-        filename (1,1) string {matnwb.common.mustBeNwbFile}
+        reader (1,1) io.backend.base.Reader
         specLocation (1,1) string
     end
 
-    specInfo = h5info(filename, specLocation);
+    specInfo = reader.readNodeInfo(specLocation);
     specs = deal( cell(size(specInfo.Groups)) );
-    
-    fid = H5F.open(filename);
-    fileCleanup = onCleanup(@(id) H5F.close(fid) );
 
     for iGroup = 1:length(specInfo.Groups)
-        location = specInfo.Groups(iGroup).Groups(1);
+        namespaceGroupInfo = specInfo.Groups(iGroup);
+        location = namespaceGroupInfo.Groups(1);
 
-        namespaceName = split(specInfo.Groups(iGroup).Name, '/');
+        namespaceName = split(namespaceGroupInfo.Name, '/');
         namespaceName = namespaceName{end};
 
-        filenames = {location.Datasets.Name};
-        if ~any(strcmp('namespace', filenames))
+        datasetNames = {location.Datasets.Name};
+        if ~any(strcmp('namespace', datasetNames))
             warning('NWB:Read:GenerateSpec:CacheInvalid',...
                 'Couldn''t find a `namespace` in namespace `%s`.  Skipping cache generation.',...
                 namespaceName);
             return;
         end
-        sourceNames = {location.Datasets.Name};
-        fileLocation = strcat(location.Name, '/', sourceNames);
+
         schemaMap = containers.Map;
-        for iFileLocation = 1:length(fileLocation)
-            did = H5D.open(fid, fileLocation{iFileLocation});
-            if strcmp('namespace', sourceNames{iFileLocation})
-                namespaceText = H5D.read(did);
+        for iDataset = 1:length(datasetNames)
+            datasetName = datasetNames{iDataset};
+            datasetPath = strcat(location.Name, '/', datasetName);
+            datasetValue = reader.readDatasetValue(location.Datasets(iDataset), datasetPath);
+            if strcmp('namespace', datasetName)
+                namespaceText = datasetValue;
             else
-                schemaMap(sourceNames{iFileLocation}) = H5D.read(did);
+                schemaMap(datasetName) = datasetValue;
             end
-            H5D.close(did);
         end
 
         specs{iGroup}.namespaceName = namespaceName;

+io/+spec/validateEmbeddedSpecifications.m

@@ -1,27 +1,33 @@
-function validateEmbeddedSpecifications(h5_file_id, expectedNamespaceNames)
+function validateEmbeddedSpecifications(writer, expectedNamespaceNames)
 % validateEmbeddedSpecifications - Validate the embedded specifications
 %
 % This function does two things:
 %   1) Displays a warning if specifications of expected namespaces
-%      are not embedded in the file. 
+%      are not embedded in the file.
 %        E.g if cached namespaces were cleared prior to export.
-%   
-%   2) Deletes specifications for unused namespaces that are embedded. 
+%
+%   2) Deletes specifications for unused namespaces that are embedded.
 %      - E.g. If neurodata type from an embedded namespace was removed and the
 %        file was re-exported
+%
+% Backend-agnostic: only uses the io.backend.base.Writer interface, so
+% this works for any registered storage backend, not just HDF5.
 
-% NB: Input h5_file_id must point to a file opened with write access
+    arguments
+        writer (1,1) io.backend.base.Writer
+        expectedNamespaceNames
+    end
 
-    specLocation = io.spec.internal.readEmbeddedSpecLocation(h5_file_id);
-    embeddedNamespaceNames = io.internal.h5.listGroupNames(h5_file_id, specLocation);
+    specLocation = writer.getEmbeddedSpecLocation();
+    embeddedNamespaceNames = writer.listChildGroupNames(specLocation);
 
     checkMissingNamespaces(expectedNamespaceNames, embeddedNamespaceNames)
 
     unusedNamespaces = checkUnusedNamespaces(...
         expectedNamespaceNames, embeddedNamespaceNames);
 
     if ~isempty(unusedNamespaces)
-        deleteUnusedNamespaces(h5_file_id, unusedNamespaces, specLocation)
+        deleteUnusedNamespaces(writer, unusedNamespaces, specLocation)
     end
 end
 
@@ -45,10 +51,10 @@ function checkMissingNamespaces(expectedNamespaceNames, embeddedNamespaceNames)
     unusedNamespaces = setdiff(embeddedNamespaceNames, expectedNamespaceNames);
 end
 
-function deleteUnusedNamespaces(fileId, unusedNamespaces, specRootLocation)
+function deleteUnusedNamespaces(writer, unusedNamespaces, specRootLocation)
     for i = 1:numel(unusedNamespaces)
         thisName = unusedNamespaces{i};
         namespaceSpecLocation = strjoin( {specRootLocation, thisName}, '/');
-        io.internal.h5.deleteGroup(fileId, namespaceSpecLocation)
+        writer.deleteNode(namespaceSpecLocation)
     end
 end

+io/+spec/writeEmbeddedSpecifications.m

@@ -1,12 +1,15 @@
 function writeEmbeddedSpecifications(writer, jsonSpecs)
 % writeEmbeddedSpecifications - Write schema specifications to an NWB file
+%
+%   Backend-agnostic: only uses the io.backend.base.Writer interface, so
+%   this works for any registered storage backend, not just HDF5.
 
     arguments
         writer (1,1) io.backend.base.Writer
         jsonSpecs   % String representation of schema specifications in json format
     end
 
-    specLocation = io.spec.internal.readEmbeddedSpecLocation(writer.FileId);
+    specLocation = writer.getEmbeddedSpecLocation();
 
     if isempty(specLocation)
         specLocation = '/specifications';
@@ -20,12 +23,9 @@ function writeEmbeddedSpecifications(writer, jsonSpecs)
         schemaNamespaceLocation = strjoin({specLocation, JsonDatum.name}, '/');
         namespaceExists = writer.writeGroup(schemaNamespaceLocation);
         if namespaceExists
-            namespaceGroupId = H5G.open(writer.FileId, schemaNamespaceLocation);
-            names = getVersionNames(namespaceGroupId);
-            H5G.close(namespaceGroupId);
+            names = writer.listChildGroupNames(schemaNamespaceLocation);
             for iNames = 1:length(names)
-                H5L.delete(writer.FileId, [schemaNamespaceLocation '/' names{iNames}],...
-                    'H5P_DEFAULT');
+                writer.deleteNode([schemaNamespaceLocation '/' names{iNames}]);
             end
         end
         schemaLocation = ...
@@ -40,13 +40,3 @@ function writeEmbeddedSpecifications(writer, jsonSpecs)
         end
     end
 end
-
-function versionNames = getVersionNames(namespaceGroupId)
-    [~, ~, versionNames] = H5L.iterate(namespaceGroupId,...
-        'H5_INDEX_NAME', 'H5_ITER_NATIVE',...
-        0, @appendName, {});
-    function [status, versionNames] = appendName(~, name, versionNames)
-        versionNames{end+1} = name;
-        status = 0;
-    end
-end

+tests/+unit/+io/+backend/+base/BaseWriterTest.m

@@ -8,6 +8,9 @@
             "writeGroup", ...
             "writeValue", ...
             "writeAttribute", ...
+            "getEmbeddedSpecLocation", ...
+            "listChildGroupNames", ...
+            "deleteNode", ...
             "abort", ...
             "close", ...
             "ensure" ...

NwbFile.m

@@ -392,7 +392,7 @@ function embedSpecifications(obj, writer)
                 jsonSpecs);
 
             io.spec.validateEmbeddedSpecifications(...
-                writer.FileId, ...
+                writer, ...
                 strrep(namespaceNames, '_', '-'))
         end
 

nwbRead.m

@@ -87,7 +87,7 @@
                 end
             end
         else
-            generateEmbeddedSpec(filename, specLocation, 'savedir', options.savedir);
+            generateEmbeddedSpec(reader, specLocation, 'savedir', options.savedir);
         end
     else
         warnIfSchemaVersionsMismatch(schemaVersionOfFile, schemaVersionActive)
@@ -119,15 +119,15 @@
     nwb.resolveSoftLinks()
 end
 
-function generateEmbeddedSpec(filename, specLocation, options)
+function generateEmbeddedSpec(reader, specLocation, options)
 % generateEmbeddedSpec - Generate embedded specifications / namespaces
     arguments
-        filename (1,1) string {matnwb.common.compatibility.mustBeFile}
+        reader (1,1) io.backend.base.Reader
         specLocation (1,1) string
         options.savedir (1,1) string = misc.getMatnwbDir(); % {matnwb.common.compatibility.mustBeFolder} ?
     end
 
-    specs = io.spec.readEmbeddedSpecifications(filename, specLocation);
+    specs = io.spec.readEmbeddedSpecifications(reader, specLocation);
     specNames = cell(size(specs));
 
     for iSpec = 1:numel(specs)