DOC: Document limitations

CHANGELOG.md

@@ -11,8 +11,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - CFood that creates a Record for each line in a csv file
 - `generic_analysis.py` allows to easily call scripts to perform analyses in
   server side scripting [EXPERIMENTAL]
-- Models parser can import from Json Schema files now:
-  `models.parser.parse_model_from_json_schema(...)`
+- **EXPERIMENTAL:** Models parser can import from Json Schema files now:
+  `models.parser.parse_model_from_json_schema(...)`. See the documentation of
+  `models.parser.JsonSchemaParser` for the limitations of the current
+  implementation.
 - New keyword "role" in yaml data model that allows creation of Records and Files.
 - It is now possible to set values of properties and default values of properties
   directly in the yaml model.
@@ -37,7 +39,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added ###
 - `check_reference_field` function to check whether entities with provided ids
   exits (for example when importing data from a table)
-- added the `datatypes` argument to `TableImporter` for columns that do not 
+- added the `datatypes` argument to `TableImporter` for columns that do not
   need a special conversion function
 
 ## [0.3.0] - 2021-11-02 ##
@@ -51,14 +53,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - New class to collect possible problems with the data model
 - New class for checking and importing tables
 - Function to get a file path to a shared resource directory
-- Function to setup logging appropriate for server side scripts with webui 
+- Function to setup logging appropriate for server side scripts with webui
   output
 - New class for collecting information for exporting tables, e.g., to
   metadata repositories
 - new name parsing
 - new test for software folder structure
 - new assure_name_is function
-- two utility functions when working with files: NameCollector and 
+- two utility functions when working with files: NameCollector and
   get_file_via_download
 - Automated documentation builds: `make doc`
 - Crawler documentation
@@ -71,8 +73,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed ###
 
-- identifiables of single CFoods are now treated one after the other. This 
-  allows them to have dependencies among each other if they are ordered 
+- identifiables of single CFoods are now treated one after the other. This
+  allows them to have dependencies among each other if they are ordered
   correctly
 - identifiables must have at least one property or a name
 - `caosadvancedtools.serverside.helper.init_data_model` also checks the role
@@ -100,9 +102,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   cause an `sqlite3.IntegrityError` if more than one change was cached
   for the same entity.
 - #40 Insertion of identifiables with missing obligatory properties
-- Before, a Property with the datatype "LIST(TEXT)" would lead to the creation 
+- Before, a Property with the datatype "LIST(TEXT)" would lead to the creation
   of a RecordType. This is fixed now.
-- #52 `XLSimporter.read_xls` throwed a wrong error when reading from a file with a wrong ending. 
+- #52 `XLSimporter.read_xls` throwed a wrong error when reading from a file with a wrong ending.
   Now, a `DataInconsistencyError` is raised instead of a ValueError.
 - List properties are no longer updated unnecessarily by the crawler.
 

src/caosadvancedtools/models/parser.py

@@ -151,7 +151,25 @@ def parse_model_from_string(string):
 
 
 def parse_model_from_json_schema(filename: str):
-    """Return a datamodel parsed from a json schema definition."""
+    """Return a datamodel parsed from a json schema definition.
+
+    Parameters
+    ----------
+    filename : str
+        The path of the json schema file that is to be parsed
+
+    Returns
+    -------
+    out : Datamodel
+        The datamodel generated from the input schema which then can be used for
+        synchronizing with CaosDB.
+    
+    Note
+    ----
+    This is an experimental feature, see ``JsonSchemaParser`` for information
+    about the limitations of the current implementation.
+
+    """
     # @author Florian Spreckelsen
     # @date 2022-02-17
     # @review Daniel Hornung 2022-02-18
@@ -566,7 +584,27 @@ class Parser(object):
 
 
 class JsonSchemaParser(Parser):
-    """Extends the yaml parser to read in datamodels defined in a json schema."""
+    """Extends the yaml parser to read in datamodels defined in a json schema.
+
+    **EXPERIMENTAL:** While this calss can already be used to create data models
+    from basic json schemas, there are the following limitations and missing
+    features:
+
+    * Due to limitations of json-schema itself, we currently do not support
+      inheritance in the imported data models
+    * The same goes for suggested properties of RecordTypes
+    * Currently, ``$defs`` and ``$ref`` in the input schema are not resolved.
+    * Already defined RecordTypes and (scalar) Properties can't be re-used as
+      list properties
+    * Reference properties that are different from the referenced RT. (Although
+      this is possible for list of references)
+    * Values
+    * Roles
+    * The extern keyword from the yaml parser
+    * Currently, a json-schema cannot be transformed into a data model if its
+      root element isn't a RecordType (or Property) with ``title`` and ``type``.
+
+    """
     # @author Florian Spreckelsen
     # @date 2022-02-17
     # @review Timm Fitschen 2022-02-30