Add special value for scalar shape, change default shape meaning (#37)

source/description.rst

@@ -768,14 +768,30 @@ may have multiple valid shape options, e.g.:
     - - null
       - 5
 
+To represent that an attribute/dataset can be a scalar,
+use the special value "scalar":
+
+.. code-block:: yaml
+
+    ...
+    shape: scalar
+
+Specifying that an attribute/dataset can be either a scalar or a non-scalar shape is
+currently not supported.
+
 The default behavior for shape is:
 
 .. code-block:: yaml
 
     ...
     shape: null
 
-indicating that the attribute/dataset is a scalar.
+indicating that the attribute/dataset is any shape.
+
+.. note::
+
+    Prior to version 3.0, the default behavior for shape, ``shape: null``, meant that the
+    attribute/dataset is a scalar.
 
 .. _sec-value:
 

source/hdmf.schema.json

@@ -141,6 +141,9 @@
         {
           "type": "array",
           "items": {"$ref": "#/definitions/shape_spec"}
+        },
+        {
+          "const": "scalar"
         }
       ]
     },

source/release_notes.rst

@@ -7,11 +7,13 @@ Version 3.0.0 (Upcoming)
 * Deprecated the ``default_value`` key for datasets. This key is still supported for attributes.
 * Deprecated ``linkable`` key for groups and datasets.
 * First release as hdmf-schema-language.
-* Remove legacy description of the `specs` or `spec` key.
-* Add specification for the specification language used by each file.
-* Add dtypes that are already supported in ``hdmf.spec``: short, uint64, bytes, and datetime.
-* Clarify that if `name` is defined on a group/dataset/link specification, `quantity` may not be >1.
-* Update ``datetime`` specification to allow a date with no time or timezone.
+* Removed legacy description of the ``specs`` or ``spec`` key.
+* Added specification for the specification language used by each file.
+* Added dtypes that are already supported in ``hdmf.spec``: short, uint64, bytes, and datetime.
+* Clarified that if ``name`` is defined on a group/dataset/link specification, ``quantity`` may not be greater than 1.
+* Updated ``datetime`` specification to allow a date with no time or timezone.
+* Changed the meaning of the default shape ``shape: null`` from representing a scalar to representing any shape.
+* Added special value for ``shape: scalar`` that represents a scalar.
 
 Version 2.0.2 (March, 2020)
 ---------------------------------