DOC: Clarify documentation of the extern keyword

src/doc/yaml_interface.rst

-
 ===============================
  YAML data model specification
 ===============================
@@ -20,10 +19,10 @@ in the library sources.
     Person:
        recommended_properties:
           firstName:
-             datatype: TEXT 
+             datatype: TEXT
              description: 'first name'
           lastName:
-             datatype: TEXT 
+             datatype: TEXT
              description: 'last name'
     LabbookEntry:
        recommended_properties:
@@ -53,7 +52,7 @@ This example defines 3 ``RecordTypes``:
 - A ``Project`` with one obligatory property ``datatype``
 - A Person with a ``firstName`` and a ``lastName`` (as recommended properties)
 - A ``LabbookEntry`` with multiple recommended properties of different data types
-- It is assumed that the server knows a RecordType or Property with the name 
+- It is assumed that the server knows a RecordType or Property with the name
   ``Textfile``.
 
 
@@ -70,9 +69,22 @@ Note the difference between the three property declarations of ``LabbookEntry``:
 - ``responsible``: This defines and adds a property with name "responsible" to ``LabbookEntry`, which has a datatype ``Person``. ``Person`` is defined above.
 - ``firstName``: This defines and adds a property with the standard data type ``TEXT`` to record type ``Person``.
 
-If the data model depends on record types or properties which already exist in CaosDB, those can be
-added using the ``extern`` keyword: ``extern`` takes a list of previously defined names.
+If the data model depends on record types or properties which already exist in
+LinkAhead, those can be added using the ``extern`` keyword: ``extern`` takes a
+list of previously defined names of Properties and/or RecordTypes. Note that if you happen to use an already existing ``REFERENCE`` property that has an already existing RecordType as datatype, you also need to add that RecordType's name to the ``extern`` list, e.g.,
+
+.. code-block:: yaml
+
+   extern:
+     # Let's assume the following is a reference property with datatype Person
+     - Author
+     # We need Person (since it's the datatype of Author) even though we might
+     # not use it explicitly
+     - Person
 
+   Dataset:
+     recommended_properties:
+       Author:
 
 
 Datatypes
@@ -117,7 +129,7 @@ You can use the yaml parser directly in python as follows:
 
 
 .. code-block:: python
-   
+
   from caosadvancedtools.models import parser as parser
   model = parser.parse_model_from_yaml("model.yml")
 
@@ -135,7 +147,7 @@ You can now use the functions from ``DataModel`` to synchronize
 the model with a CaosDB instance, e.g.:
 
 .. code-block:: python
-   
+
   model.sync_data_model()
 
 ..  LocalWords:  yml projectId UID firstName lastName LabbookEntry entryId textElement labbook