null values

README.md

@@ -18,6 +18,7 @@ See also the [Heta video tutorial](https://hetalang.github.io/#/resources/?id=le
 - [Modules](https://hetalang.github.io/#/specifications/modules)
 - [Namespaces](https://hetalang.github.io/#/specifications/namespaces)
 - [Math expressions](https://hetalang.github.io/#/specifications/math)
+- [Null values](https://hetalang.github.io/#/specifications/null)
 - [Units](https://hetalang.github.io/#/specifications/units)
 - [Tabular format](https://hetalang.github.io/#/specifications/tabular-format)
 - [Cases](https://hetalang.github.io/#/specifications/cases)

null.md

@@ -0,0 +1,83 @@
+# Null values
+
+Null values are special property values that represent the absence of a value. They are used to indicate that a property is intentionally empty or missing.
+
+null values cannot be used as a ID of components because it is reserved word. 
+
+Setting a property to `null` works differently for different statements.
+
+## null in #insert and #update
+
+When we set a property to `null` in the `#insert` or `#forceInsert` statements, it means that the property is intentionally empty,missing, or has the default value. It is the same as we do not declare the property at all.
+
+```heta
+k1 @Const {units: null} = 1; // implicit #insert
+```
+
+works the same as
+
+```heta
+k1 @Const = 1;
+```
+
+When we set a property to `null` in the `#update` statement, it means that the property is intentionally removed.
+
+```heta
+k1 @Const {units: mM};
+k1 {units: null} = 1; // implicit #update
+```
+
+which is equivalent to
+
+```heta
+k1 @Const = 1;
+```
+
+## wrong usage of null
+
+Null properties are allowed only in properties but not in sub-properties like in examples below.
+
+```heta
+x1 @Record {
+    aux: {a: 1, b: null} // throw syntax error
+}; 
+```
+
+```heta
+x1 @Record {
+    aux: null // correct
+}; 
+```
+
+```heta
+x1 @Record {
+    tags: [a, b, null] // throw syntax error
+}; 
+```
+
+```heta
+x1 @Record {
+    tags: null // correct
+}; 
+```
+
+Null properties values must be used only for components, but not for `#defineFunction` or `#defineUnit`.
+
+```heta
+#defineFunction f1 {
+    arguments: [x,y,z],
+    math: null          // throw syntax error
+};
+```
+
+```heta
+#defineUnit u1 {
+    units: null          // throw syntax error
+};
+```
+
+Null value cannot be used as a ID of components.
+
+```heta
+null @Const = 1; // throw syntax error
+```

syntax.md

@@ -24,14 +24,14 @@ The Heta code represents a sequence of statements that create and modify element
     - Assignments (with several subtypes)
 
 ## Plain Format of Action Statement
-1. The plain format is the most flexible way to describe action properties. It begins with the `{` symbol and ends with the `}` symbol, and it can contain a set of key-value pairs divided by commas (`,`), similar to a dictionary in JSON or YAML format.
+1. The plain format is the most straightforward way to describe action properties. It begins with the `{` symbol and ends with the `}` symbol, and it can contain a set of key-value pairs divided by commas (`,`), similar to a dictionary in JSON or YAML format.
 
     Example:
     ```heta
     { prop1: value 1, prop2: value 2, ...};
     ```
 
-    The **property** is always a string without spaces. Properties must be unique within a dictionary. The **value** can be one of five types: \<String\>, \<Number\>, \<Boolean\>, \<Dictionary\>, or \<Array\>. \<Dictionary\> and \<Array\> values might include other types.
+    The **property** name is always a string without spaces, it must be unique within a dictionary. The **value** can be one of five types: \<String\>, \<Number\>, \<Boolean\>, \<Dictionary\>, \<Array\> or \<Null\>. \<Dictionary\> and \<Array\> values might include other types.
 
 
     Example:
@@ -41,7 +41,8 @@ The Heta code represents a sequence of statements that create and modify element
         numberProp: 1.2e-3,
         booleanProp: true,
         dictionaryProp: { nestedProp: true },
-        arrayProp: [1, 2, 3]
+        arrayProp: [1, 2, 3],
+        someProp: null
     };
     ```
 
@@ -112,6 +113,8 @@ The Heta code represents a sequence of statements that create and modify element
     };
     ```
 
+7. The \<Null\> value is used to describe the value which must be empty. See more detailes in [Null values](./null)
+
 ## Shortened Format of Action Statement
 
 1. To simplify code reading and writing, there are several types of statement parts that describe commonly used properties in a compact form. See the [Classes](./classes) description for details.