highlevel: describe metadata and specification
@@ -56,6 +56,20 @@ You can find a complete example at the end of this document and [here](../../../
## Core Concepts
+### Metadata and Specification
+
+In Elektra keys may have [attached meta data](/doc/help/elektra-metadata.md) describing additional properties of the key. By using [Elektra's
+namespaces](/doc/tutorials/namespaces.md) and [cascading keys](/doc/tutorials/cascading.md) it is also possible to have a full specification
+of your applications configuration.
+
+This specification should be placed into the `spec` namespace. From there the high-level API and Elektra's plugins will access it. A
+specification for use with the high-level API has to define at least the `default` and the `type` meta data for each key the application
+is going to use. The `default` meta key simple defines which value will be returned, if the user didn't set a value. `type` defines the data
+type of key. For more information on data types [see below](#data-types).
+
+The API also supports passing a `KeySet` to `elektraOpen` that contains the specification. This is, however, not recommended for general use
+and is mainly useful for debugging and testing purposes.
+
### Struct `Elektra`
`Elektra` is the handle you use to access the underlying KDB (hierarchical key database) that stores the configuration key-value pairs.
