Add paragraph on store path links

1 files changed, 28 insertions, 0 deletions

diff --git a/doc/src/02000-store.md b/doc/src/02000-store.md
index 482facbb..8290f915 100644
--- a/doc/src/02000-store.md
+++ b/doc/src/02000-store.md
@@ -97,4 +97,32 @@ sub-folders like this:
 /module/some/sub/folder/example~0.1
 ```
 
+## Store path links {#sec:thestore:links}
+
+Linking entries MUST BE version independent.
+
+This means if an entry "a" from a module "A" gets written to the store, it may
+link to an entry "b" from a module "B", which is in version "0.1" at the moment.
+If the module "B" gets updated, it might update its entries in the store as
+well.
+The link from the "a" MUST NOT get invalid in this case.
+
+This is accomplished by linking without the version number: So a link for the
+entry
+
+```
+/module/some/sub/folder/example~0.1
+```
+
+is
+
+```
+imag://module/some/sub/folder/example
+```
+
+As shown in the example, a link to imag-internal entries, the link is prefixed
+with a "imag://" identifier.
+A link to external content MUST NEVER be prefixed this way.
+The path of the internal link MUST NEVER be relative, but always absolute from
+the root directory of the store.