From ffb3ab62f2f721b0867e9aff0bbb72fce24b8b70 Mon Sep 17 00:00:00 2001 From: rly <310197+rly@users.noreply.github.com> Date: Fri, 24 Apr 2026 16:48:46 -0700 Subject: [PATCH 1/4] Clarify best practice #5 on adding fields to included types Distinguish extension (data_type_def + data_type_inc) from inclusion (data_type_inc only), and add a VectorData/resolution example. Co-Authored-By: Claude Opus 4.7 (1M context) --- source/best_practices.rst | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/source/best_practices.rst b/source/best_practices.rst index 19f10fa..c1115e9 100644 --- a/source/best_practices.rst +++ b/source/best_practices.rst @@ -15,10 +15,14 @@ and confusing. unless you really want to require that all instances of the data type have that name. Mismatch between the name defined on the data type definition and where it is included can lead to unexpected behavior in the APIs. -5. Create a new data type when adding attributes/datasets/groups/links to an existing data type. See -`hdmf-schema-language#13`_ for details. Adding attributes/datasets/groups/links to an existing data type using -``data_type_inc`` is partially supported by the APIs (for example, the validator may not check these added fields), -so this is discouraged until full, tested support is added. +5. When adding attributes, datasets, groups, or links to an existing data type, create a new data type that extends +it (using both ``data_type_def`` and ``data_type_inc``) rather than adding those fields to an included instance of +the type (i.e., a group/dataset that uses only ``data_type_inc: X`` without a ``data_type_def``). For example, if a +group includes a named dataset with ``data_type_inc: VectorData`` and adds a ``resolution`` attribute to that +dataset, the added attribute is tied to that specific included location rather than to a reusable data type, and is +only partially supported by the APIs (for example, the validator may not check these added fields). Instead, define +a new type that extends ``VectorData`` with the ``resolution`` attribute, and include that type. See +`hdmf-schema-language#13`_ for details. 6. Modifying the dtype, shape, or quantity of a data type when using ``data_type_inc`` should only restrict the values from their original definitions. This ensures that the data types follow the object-oriented programming principle of From 47fe446ca25178f5d5172d1608768f3ce1860ecf Mon Sep 17 00:00:00 2001 From: rly <310197+rly@users.noreply.github.com> Date: Fri, 24 Apr 2026 17:02:22 -0700 Subject: [PATCH 2/4] Add top-level heading so the page renders in the toctree The file had no section title, which prevented Sphinx from showing it in the index toctree. Co-Authored-By: Claude Opus 4.7 (1M context) --- source/best_practices.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/source/best_practices.rst b/source/best_practices.rst index c1115e9..57ba2a3 100644 --- a/source/best_practices.rst +++ b/source/best_practices.rst @@ -1,3 +1,6 @@ +Best Practices +============== + When writing schema using the HDMF Schema Language, including extensions, the HDMF development team provides a few best practices to ensure correct behavior from the HDMF reference API and other APIs that we are aware of (e.g., MatNWB). From b27daf1c5bd2de575d0318eec0a8db1936822d69 Mon Sep 17 00:00:00 2001 From: rly <310197+rly@users.noreply.github.com> Date: Fri, 24 Apr 2026 17:03:59 -0700 Subject: [PATCH 3/4] Indent enumerated list continuation lines RST requires continuation lines of an enumerated list item to align with the text after the marker; without indentation, list items 2-8 broke out of the list and rendered inconsistently. Co-Authored-By: Claude Opus 4.7 (1M context) --- source/best_practices.rst | 50 +++++++++++++++++++-------------------- 1 file changed, 25 insertions(+), 25 deletions(-) diff --git a/source/best_practices.rst b/source/best_practices.rst index 57ba2a3..941d553 100644 --- a/source/best_practices.rst +++ b/source/best_practices.rst @@ -7,41 +7,41 @@ practices to ensure correct behavior from the HDMF reference API and other APIs 1. Do not create schema that the HDMF reference API does not yet support. See `hdmf_support`_ for details. 2. Define new data types (``data_type_def``) at the root of the schema rather than nested within another data type -definition. Nested type definitions may in some cases lead to errors in HDMF. See `hdmf#511`_ and `hdmf#73`_. + definition. Nested type definitions may in some cases lead to errors in HDMF. See `hdmf#511`_ and `hdmf#73`_. 3. Use the ``quantity`` key not in the data type definition but in the group/dataset spec where the type is included. -When the data type is included within another data type via ``data_type_inc``, if the ``quantity`` key is omitted, the -default value of 1 would be used. This makes the ``quantity`` defined in the data type definition meaningless -and confusing. + When the data type is included within another data type via ``data_type_inc``, if the ``quantity`` key is omitted, + the default value of 1 would be used. This makes the ``quantity`` defined in the data type definition meaningless + and confusing. 4. Use the ``name`` key not in the data type definition but in the group/dataset spec where the type is included, -unless you really want to require that all instances of the data type have that name. Mismatch between the name -defined on the data type definition and where it is included can lead to unexpected behavior in the APIs. + unless you really want to require that all instances of the data type have that name. Mismatch between the name + defined on the data type definition and where it is included can lead to unexpected behavior in the APIs. 5. When adding attributes, datasets, groups, or links to an existing data type, create a new data type that extends -it (using both ``data_type_def`` and ``data_type_inc``) rather than adding those fields to an included instance of -the type (i.e., a group/dataset that uses only ``data_type_inc: X`` without a ``data_type_def``). For example, if a -group includes a named dataset with ``data_type_inc: VectorData`` and adds a ``resolution`` attribute to that -dataset, the added attribute is tied to that specific included location rather than to a reusable data type, and is -only partially supported by the APIs (for example, the validator may not check these added fields). Instead, define -a new type that extends ``VectorData`` with the ``resolution`` attribute, and include that type. See -`hdmf-schema-language#13`_ for details. - -6. Modifying the dtype, shape, or quantity of a data type when using ``data_type_inc`` should only restrict the values -from their original definitions. This ensures that the data types follow the object-oriented programming principle of -inheritance. For example, if type A has ``dtype: text`` and type B extends type A -(``data_type_def: B, data_type_inc: A``), then type B should not redefine ``dtype`` to be ``int`` -which is incompatible with the ``dtype`` of type A. The same idea holds if type A is included in another type -and a new type is not defined (just ``data_type_inc: A``). -In other words, all children types should be valid against the parent type. See `hdmf#321`_. + it (using both ``data_type_def`` and ``data_type_inc``) rather than adding those fields to an included instance of + the type (i.e., a group/dataset that uses only ``data_type_inc: X`` without a ``data_type_def``). For example, if + a group includes a named dataset with ``data_type_inc: VectorData`` and adds a ``resolution`` attribute to that + dataset, the added attribute is tied to that specific included location rather than to a reusable data type, and + is only partially supported by the APIs (for example, the validator may not check these added fields). Instead, + define a new type that extends ``VectorData`` with the ``resolution`` attribute, and include that type. See + `hdmf-schema-language#13`_ for details. + +6. Modifying the dtype, shape, or quantity of a data type when using ``data_type_inc`` should only restrict the + values from their original definitions. This ensures that the data types follow the object-oriented programming + principle of inheritance. For example, if type A has ``dtype: text`` and type B extends type A + (``data_type_def: B, data_type_inc: A``), then type B should not redefine ``dtype`` to be ``int`` + which is incompatible with the ``dtype`` of type A. The same idea holds if type A is included in another type + and a new type is not defined (just ``data_type_inc: A``). + In other words, all children types should be valid against the parent type. See `hdmf#321`_. 7. The use of list values for the ``value`` and ``default_value`` keys, e.g., ``value: [0, 1, 2]`` is not fully -supported in the official APIs, so this is discouraged until full, tested support is added. + supported in the official APIs, so this is discouraged until full, tested support is added. 8. The names of data types or objects should use only characters in the sets ``a-z``, ``A-Z``, ``0-9``, ``-``, ``_``, -``.``. This helps ensure consistent behavior in the APIs across different storage backends and operating systems. -For example, writing a group that contains ":" to a Zarr backend on a Windows machine is not allowed by Windows. -See `pynwb#1421`_ and `hdmf-zarr#219`_ for examples. + ``.``. This helps ensure consistent behavior in the APIs across different storage backends and operating systems. + For example, writing a group that contains ":" to a Zarr backend on a Windows machine is not allowed by Windows. + See `pynwb#1421`_ and `hdmf-zarr#219`_ for examples. .. _hdmf#511: https://github.com/hdmf-dev/hdmf/issues/511 From b4f2800a52ca9f45b15dfd9079a0788ca9f3fe91 Mon Sep 17 00:00:00 2001 From: rly <310197+rly@users.noreply.github.com> Date: Fri, 24 Apr 2026 17:06:24 -0700 Subject: [PATCH 4/4] Add spacing between numbered list items Adds a 1em bottom margin to arabic ordered-list items so the Best Practices page reads less like a wall of text. Co-Authored-By: Claude Opus 4.7 (1M context) --- source/_static/theme_overrides.css | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/source/_static/theme_overrides.css b/source/_static/theme_overrides.css index 63ee6cc..bc624b1 100644 --- a/source/_static/theme_overrides.css +++ b/source/_static/theme_overrides.css @@ -11,3 +11,8 @@ overflow: visible !important; } } + +/* add breathing room between numbered list items */ +.rst-content ol.arabic > li { + margin-bottom: 1em; +}