dsp-tools 9.1.0.post11__py3-none-any.whl → 18.3.0.post13__py3-none-any.whl

dsp_tools/xmllib/models/dsp_base_resources.py

@@ -1,250 +1,518 @@
 from __future__ import annotations
 
-import warnings
+from collections.abc import Collection
 from dataclasses import dataclass
-from dataclasses import field
 from typing import Any
 
-from lxml import etree
-
-from dsp_tools.models.custom_warnings import DspToolsUserWarning
-from dsp_tools.models.exceptions import InputError
-from dsp_tools.xmllib.models.migration_metadata import MigrationMetadata
-from dsp_tools.xmllib.models.values import ColorValue
-from dsp_tools.xmllib.models.values import LinkValue
-from dsp_tools.xmllib.models.values import Richtext
-from dsp_tools.xmllib.value_checkers import find_geometry_problem
-from dsp_tools.xmllib.value_checkers import is_color
+from dsp_tools.error.xmllib_warnings import MessageInfo
+from dsp_tools.error.xmllib_warnings_util import emit_xmllib_input_warning
+from dsp_tools.xmllib.internal.input_converters import check_and_fix_collection_input
+from dsp_tools.xmllib.internal.input_converters import check_and_fix_is_non_empty_string
+from dsp_tools.xmllib.models.config_options import NewlineReplacement
+from dsp_tools.xmllib.models.internal.geometry import Circle
+from dsp_tools.xmllib.models.internal.geometry import GeometryPoint
+from dsp_tools.xmllib.models.internal.geometry import GeometryShape
+from dsp_tools.xmllib.models.internal.geometry import Polygon
+from dsp_tools.xmllib.models.internal.geometry import Rectangle
+from dsp_tools.xmllib.models.internal.geometry import Vector
+from dsp_tools.xmllib.models.internal.migration_metadata import MigrationMetadata
+from dsp_tools.xmllib.models.internal.values import LinkValue
+from dsp_tools.xmllib.models.internal.values import Richtext
+from dsp_tools.xmllib.models.internal.values import SimpleText
+from dsp_tools.xmllib.models.internal.values import Value
+from dsp_tools.xmllib.models.permissions import Permissions
 from dsp_tools.xmllib.value_checkers import is_decimal
-from dsp_tools.xmllib.value_checkers import is_string_like
-
-XML_NAMESPACE_MAP = {None: "https://dasch.swiss/schema", "xsi": "http://www.w3.org/2001/XMLSchema-instance"}
-DASCH_SCHEMA = "{https://dasch.swiss/schema}"
+from dsp_tools.xmllib.value_checkers import is_nonempty_value
 
 LIST_SEPARATOR = "\n    - "
 
 
 @dataclass
-class AnnotationResource:
+class RegionResource:
     res_id: str
     label: str
-    annotation_of: str
-    comments: list[str]
-    permissions: str = "res-default"
+    values: list[Value]
+    geometry: GeometryShape | None
+    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS
     migration_metadata: MigrationMetadata | None = None
 
-    def __post_init__(self) -> None:
-        _check_strings(string_to_check=self.res_id, res_id=self.res_id, field_name="Resource ID")
-        _check_strings(string_to_check=self.label, res_id=self.res_id, field_name="Label")
-
-    def new(
-        self, res_id: str, label: str, annotation_of: str, comments: list[str], permissions: str = "res-default"
-    ) -> AnnotationResource:
-        return AnnotationResource(
+    @staticmethod
+    def create_new(
+        res_id: str,
+        label: str,
+        region_of: str,
+        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
+    ) -> RegionResource:
+        """
+        Creates a new region resource.
+        A region is a region of interest (ROI) in a StillImageRepresentation.
+
+        Exactly one geometry shape has to be added to the resource with one of the following methods:
+        `add_rectangle`, `add_polygon`, `add_circle` (see documentation below for more information).
+
+        [See XML documentation for details](https://docs.dasch.swiss/latest/DSP-TOOLS/file-formats/xml-data-file/#region)
+
+        Args:
+            res_id: ID of this region resource
+            label: label of this region resource
+            region_of: ID of the image resource that this region refers to (cardinality 1)
+            permissions: permissions of this region resource
+
+        Returns:
+            A region resource
+
+        Examples:
+            ```python
+            region = xmllib.RegionResource.create_new(
+                res_id="ID",
+                label="label",
+                region_of="image_id",
+            )
+            ```
+        """
+        _check_strings(string_to_check=res_id, res_id=res_id, field_name="Resource ID")
+        res_id = str(res_id)
+        lbl = check_and_fix_is_non_empty_string(value=label, res_id=res_id, value_field="label")
+        return RegionResource(
             res_id=res_id,
-            label=label,
-            annotation_of=annotation_of,
-            comments=comments,
+            label=lbl,
+            values=[
+                LinkValue.new(
+                    value=region_of, prop_name="isRegionOf", resource_id=res_id, comment=None, permissions=permissions
+                )
+            ],
+            geometry=None,
             permissions=permissions,
         )
 
-    def add_comment(self, comment: str) -> AnnotationResource:
-        self.comments.append(comment)
-        return self
-
-    def add_comments(self, comments: list[str]) -> AnnotationResource:
-        self.comments.extend(comments)
-        return self
-
-    def add_migration_metadata(
-        self, creation_date: str | None, iri: str | None = None, ark: str | None = None
-    ) -> AnnotationResource:
-        if self.migration_metadata:
-            raise InputError(
-                f"The resource with the ID '{self.res_id}' already contains migration metadata, "
-                f"no new data can be added."
+    def add_rectangle(
+        self,
+        point1: tuple[float, float],
+        point2: tuple[float, float],
+        line_width: float = 2,
+        color: str = "#5b24bf",
+        active: bool = True,
+    ) -> RegionResource:
+        """
+        Add a rectangle shape to the region.
+
+        [For a visual example see the XML documentation](https://docs.dasch.swiss/latest/DSP-TOOLS/file-formats/xml-data-file/#geometry)
+
+        Args:
+            point1: first point of the rectangle represented as two numbers between 0 and 1 in the format (x, y)
+            point2: second point of the rectangle represented as two numbers between 0 and 1 in the format (x, y)
+            line_width: A number in pixels between 1 - 5
+            color: A hexadecimal color value which starts with a `#` followed by 3 or 6 numerals.
+                The default value was chosen as it is distinguishable for most color-blind people.
+            active: If set to `False`, the region is marked as 'deleted'
+
+        Returns:
+            Region with added rectangle
+
+        Examples:
+            ```python
+            region = region.add_rectangle(
+                point1=(0.1, 0.1),
+                point2=(0.2, 0.2),
+            )
+            ```
+
+            ```python
+            # with custom display values
+            region = region.add_rectangle(
+                point1=(0.1, 0.1),
+                point2=(0.2, 0.2),
+                line_width=3,
+                color="#32a873",
             )
-        self.migration_metadata = MigrationMetadata(creation_date=creation_date, iri=iri, ark=ark, res_id=self.res_id)
+            ```
+        """
+        self.geometry = Rectangle(
+            point1=GeometryPoint(point1[0], point1[1], self.res_id),
+            point2=GeometryPoint(point2[0], point2[1], self.res_id),
+            line_width=line_width,
+            color=color,
+            active=active,
+            resource_id=self.res_id,
+        )
         return self
 
-    def serialise(self) -> etree._Element:
-        self.comments = _transform_unexpected_input(self.comments, "comments", self.res_id)
-        res_ele = self._serialise_resource_element()
-        res_ele.append(self._serialise_annotation_of())
-        res_ele.append(_serialise_has_comment(self.comments, self.res_id))
-        return res_ele
+    def add_polygon(
+        self,
+        points: list[tuple[float, float]],
+        line_width: float = 2,
+        color: str = "#5b24bf",
+        active: bool = True,
+    ) -> RegionResource:
+        """
+        Add a polygon shape to the region.
+        A polygon should have at least three points.
+        If you wish to create a rectangle, please use the designated `add_rectangle` method.
 
-    def _serialise_resource_element(self) -> etree._Element:
-        attribs = {"label": self.label, "id": self.res_id}
-        if self.permissions:
-            attribs["permissions"] = self.permissions
-        return etree.Element(f"{DASCH_SCHEMA}annotation", attrib=attribs, nsmap=XML_NAMESPACE_MAP)
+        [For a visual example see the XML documentation](https://docs.dasch.swiss/latest/DSP-TOOLS/file-formats/xml-data-file/#geometry)
 
-    def _serialise_annotation_of(self) -> etree._Element:
-        return LinkValue(value=self.annotation_of, prop_name="isAnnotationOf", resource_id=self.res_id).serialise()
+        **Please note that this cannot currently be displayed in the dsp-app.**
 
+        Args:
+            points: list of tuples containing two numbers between 0 and 1 in the format (x, y)
+            line_width: A number in pixels between 1 - 5
+            color: A hexadecimal color value which starts with a `#` followed by 3 or 6 numerals.
+                The default value was chosen as it is distinguishable for most color-blind people.
+            active: If set to `False` the region is marked as 'deleted'
 
-@dataclass
-class RegionResource:
-    res_id: str
-    label: str
-    color: str
-    region_of: str
-    geometry: dict[str, Any]
-    comments: list[str]
-    permissions: str = "res-default"
-    migration_metadata: MigrationMetadata | None = None
+        Returns:
+            Region with added polygon
 
-    def __post_init__(self) -> None:
-        _check_strings(string_to_check=self.res_id, res_id=self.res_id, field_name="Resource ID")
-        _check_strings(string_to_check=self.label, res_id=self.res_id, field_name="Label")
-        if not is_color(self.color):
-            msg = (
-                f"The color value '{self.color}' for the resource with the ID: '{self.res_id}' failed validation. "
-                f"Please consult the documentation for details."
+        Examples:
+            ```python
+            region = region.add_polygon(
+                points=[(0.1, 0.1), (0.2, 0.2), (0.3, 0.3)],
+            )
+            ```
+
+            ```python
+            # with custom display values
+            region = region.add_polygon(
+                points=[(0.1, 0.1), (0.2, 0.2), (0.3, 0.3)],
+                line_width=3,
+                color="#32a873",
             )
-            warnings.warn(DspToolsUserWarning(msg))
-        if fail_msg := find_geometry_problem(self.geometry):
-            msg = f"The geometry of the resource with the ID '{self.res_id}' failed validation.\n" + fail_msg
-            warnings.warn(DspToolsUserWarning(msg))
+            ```
+        """
+        geom_points = [GeometryPoint(val[0], val[1], self.res_id) for val in points]
+        self.geometry = Polygon(
+            points=geom_points, line_width=line_width, color=color, active=active, resource_id=self.res_id
+        )
+        return self
 
-    def new(
+    def add_circle(
         self,
-        res_id: str,
-        label: str,
-        color: str,
-        region_of: str,
-        geometry: dict[str, Any],
-        comments: list[str],
-        permissions: str = "res-default",
+        center: tuple[float, float],
+        radius: tuple[float, float],
+        line_width: float = 2,
+        color: str = "#5b24bf",
+        active: bool = True,
     ) -> RegionResource:
-        return RegionResource(
-            res_id=res_id,
-            label=label,
+        """
+        Add a circle shape to the region.
+
+        [For a visual example see the XML documentation](https://docs.dasch.swiss/latest/DSP-TOOLS/file-formats/xml-data-file/#geometry)
+
+        **Please note that this cannot currently be displayed in the dsp-app.**
+
+        Args:
+            center: center of the circle, represented as two numbers between 0 and 1 in the format (x, y)
+            radius: radius of the circle, represented as a 2-dimensional vector,
+                i.e. two numbers between 0 and 1 in the format (x, y)
+            line_width: A number in pixels between 1 - 5
+            color: A hexadecimal color value which starts with a `#` followed by 3 or 6 numerals.
+                The default value was chosen as it is distinguishable for most color-blind people.
+            active: If set to `False` the region is marked as 'deleted'
+
+        Returns:
+            Region with added circle
+
+        Examples:
+            ```python
+            region = region.add_circle(
+                center=(0.1, 0.1),
+                radius=(0.2, 0.2),
+            )
+            ```
+
+            ```python
+            # with custom display values
+            region = region.add_circle(
+                center=(0.1, 0.1),
+                radius=(0.2, 0.2),
+                line_width=3,
+                color="#32a873",
+            )
+            ```
+        """
+        self.geometry = Circle(
+            center=GeometryPoint(center[0], center[1], self.res_id),
+            radius=Vector(radius[0], radius[1], self.res_id),
+            line_width=line_width,
             color=color,
-            region_of=region_of,
-            geometry=geometry,
-            comments=comments,
-            permissions=permissions,
+            active=active,
+            resource_id=self.res_id,
         )
-
-    def add_comment(self, comment: str) -> RegionResource:
-        self.comments.append(comment)
         return self
 
-    def add_comments(self, comments: list[str]) -> RegionResource:
-        self.comments.extend(comments)
+    def add_comment(
+        self,
+        text: str,
+        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
+        comment: str | None = None,
+        newline_replacement: NewlineReplacement = NewlineReplacement.LINEBREAK,
+    ) -> RegionResource:
+        """
+        Add a comment to the region
+
+        Args:
+            text: text of the comment
+            permissions: optional permissions of this value
+            comment: optional comment about this comment
+            newline_replacement: options how to deal with `\\n` inside the text value. Default: replace with `<br/>`
+
+        Returns:
+            The original region, with the added comment
+
+        Examples:
+            ```python
+            region = region.add_comment("comment text")
+            ```
+
+            ```python
+            region = region.add_comment(text="comment text", comment="Comment about the comment.")
+            ```
+        """
+        self.values.append(
+            Richtext.new(
+                value=text,
+                prop_name="hasComment",
+                permissions=permissions,
+                comment=comment,
+                resource_id=self.res_id,
+                newline_replacement=newline_replacement,
+            )
+        )
         return self
 
-    def add_migration_metadata(
-        self, creation_date: str | None, iri: str | None = None, ark: str | None = None
+    def add_comment_multiple(
+        self,
+        texts: Collection[str],
+        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
+        comment: str | None = None,
+        newline_replacement: NewlineReplacement = NewlineReplacement.LINEBREAK,
     ) -> RegionResource:
-        if self.migration_metadata:
-            raise InputError(
-                f"The resource with the ID '{self.res_id}' already contains migration metadata, "
-                f"no new data can be added."
+        """
+        Add several comments to the region
+
+        Args:
+            texts: list of texts
+            permissions: optional permissions of these values
+            comment: optional comment about these comments
+            newline_replacement: options how to deal with `\\n` inside the text value. Default: replace with `<br/>`
+
+        Returns:
+            The original region, with the added comments
+
+        Examples:
+            ```python
+            region = region.add_comment_multiple(["comment 1", "comment 2"])
+            ```
+        """
+        vals = check_and_fix_collection_input(texts, "hasComment", self.res_id)
+        comnts = [
+            Richtext.new(
+                value=x,
+                prop_name="hasComment",
+                permissions=permissions,
+                comment=comment,
+                resource_id=self.res_id,
+                newline_replacement=newline_replacement,
             )
-        self.migration_metadata = MigrationMetadata(creation_date=creation_date, iri=iri, ark=ark, res_id=self.res_id)
-        return self
-
-    def serialise(self) -> etree._Element:
-        self.comments = _transform_unexpected_input(self.comments, "comments", self.res_id)
-        res_ele = self._serialise_resource_element()
-        res_ele.append(self._serialise_geometry())
-        res_ele.extend(self._serialise_values())
-        if self.comments:
-            res_ele.append(_serialise_has_comment(self.comments, self.res_id))
-        return res_ele
-
-    def _serialise_resource_element(self) -> etree._Element:
-        attribs = {"label": self.label, "id": self.res_id}
-        if self.permissions:
-            attribs["permissions"] = self.permissions
-        return etree.Element(f"{DASCH_SCHEMA}region", attrib=attribs, nsmap=XML_NAMESPACE_MAP)
-
-    def _serialise_values(self) -> list[etree._Element]:
-        return [
-            ColorValue(value=self.color, prop_name="hasColor", resource_id=self.res_id).serialise(),
-            LinkValue(value=self.region_of, prop_name="isRegionOf", resource_id=self.res_id).serialise(),
+            for x in vals
         ]
+        self.values.extend(comnts)
+        return self
 
-    def _serialise_geometry(self) -> etree._Element:
-        geo_prop = etree.Element(f"{DASCH_SCHEMA}geometry-prop", name="hasGeometry", nsmap=XML_NAMESPACE_MAP)
-        ele = etree.Element(f"{DASCH_SCHEMA}geometry", nsmap=XML_NAMESPACE_MAP)
-        ele.text = str(self.geometry)
-        geo_prop.append(ele)
-        return geo_prop
+    def add_comment_optional(
+        self,
+        text: Any,
+        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
+        comment: str | None = None,
+        newline_replacement: NewlineReplacement = NewlineReplacement.LINEBREAK,
+    ) -> RegionResource:
+        """
+        If the value is not empty, add it as comment, otherwise return the region unchanged.
+
+        Args:
+            text: text of the comment (or empty value)
+            permissions: optional permissions of this value
+            comment: optional comment about this comment
+            newline_replacement: options how to deal with `\\n` inside the text value. Default: replace with `<br/>`
+
+        Returns:
+            The original region, with the added comment
+
+        Examples:
+            ```python
+            region = region.add_comment_optional("comment text")
+            ```
+
+            ```python
+            region = region.add_comment_optional(None)
+            ```
+        """
+        if is_nonempty_value(text):
+            return self.add_comment(text, permissions, comment, newline_replacement)
+        return self
 
 
 @dataclass
 class LinkResource:
     res_id: str
     label: str
-    link_to: list[str]
-    comments: list[str]
-    permissions: str = "res-default"
+    values: list[Value]
+    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS
     migration_metadata: MigrationMetadata | None = None
 
-    def new(
-        self, res_id: str, label: str, link_to: list[str], comments: list[str], permissions: str = "res-default"
+    @staticmethod
+    def create_new(
+        res_id: str,
+        label: str,
+        link_to: Collection[str],
+        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
     ) -> LinkResource:
+        """
+        Creates a new link resource.
+        A link resource is like a container that groups together several other resources of different classes.
+
+        [See XML documentation for details](https://docs.dasch.swiss/latest/DSP-TOOLS/file-formats/xml-data-file/#link)
+
+        Args:
+            res_id: ID of this link resource
+            label: label of this link resource
+            link_to: IDs of the resources that should be linked together (cardinality 1-n)
+            permissions: permissions of this link resource
+
+        Returns:
+            A link resource
+
+        Examples:
+            ```python
+            link_resource = xmllib.LinkResource.create_new(
+                res_id="ID",
+                label="label",
+                link_to=["target_resource_id_1", "target_resource_id_2"],
+            )
+            ```
+        """
+        _check_strings(string_to_check=res_id, res_id=res_id, field_name="Resource ID")
+        res_id = str(res_id)
+        lbl = check_and_fix_is_non_empty_string(value=label, res_id=res_id, value_field="label")
+        links_to = check_and_fix_collection_input(link_to, "hasLinkTo", res_id)
+        link_vals: list[Value] = [
+            LinkValue.new(value=x, prop_name="hasLinkTo", resource_id=res_id, comment=None, permissions=permissions)
+            for x in links_to
+        ]
         return LinkResource(
             res_id=res_id,
-            label=label,
-            link_to=link_to,
-            comments=comments,
+            label=lbl,
+            values=link_vals,
             permissions=permissions,
         )
 
-    def add_comment(self, comment: str) -> LinkResource:
-        self.comments.append(comment)
+    def add_comment(
+        self,
+        text: str,
+        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
+        comment: str | None = None,
+        newline_replacement: NewlineReplacement = NewlineReplacement.LINEBREAK,
+    ) -> LinkResource:
+        """
+        Add a comment to the resource
+
+        Args:
+            text: text of the comment
+            permissions: optional permissions of this value
+            comment: optional comment about this comment
+            newline_replacement: options how to deal with `\\n` inside the text value. Default: replace with `<br/>`
+
+        Returns:
+            The original resource, with the added comment
+
+        Examples:
+            ```python
+            link_resource = link_resource.add_comment("comment text")
+            ```
+
+            ```python
+            link_resource = link_resource.add_comment(text="comment text", comment="Comment about the comment.")
+            ```
+        """
+        self.values.append(
+            Richtext.new(
+                value=text,
+                prop_name="hasComment",
+                permissions=permissions,
+                comment=comment,
+                resource_id=self.res_id,
+                newline_replacement=newline_replacement,
+            )
+        )
         return self
 
-    def add_comments(self, comments: list[str]) -> LinkResource:
-        self.comments.extend(comments)
+    def add_comment_multiple(
+        self,
+        texts: Collection[str],
+        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
+        comment: str | None = None,
+        newline_replacement: NewlineReplacement = NewlineReplacement.LINEBREAK,
+    ) -> LinkResource:
+        """
+        Add several comments to the resource
+
+        Args:
+            texts: list of texts
+            permissions: optional permissions of these values
+            comment: optional comment about this comment
+            newline_replacement: options how to deal with `\\n` inside the text value. Default: replace with `<br/>`
+
+        Returns:
+            The original resource, with the added comments
+
+        Examples:
+            ```python
+            link_resource = link_resource.add_comment_multiple(["comment 1", "comment 2"])
+            ```
+        """
+        vals = check_and_fix_collection_input(texts, "hasComment", self.res_id)
+        for v in vals:
+            self.add_comment(v, permissions, comment, newline_replacement)
         return self
 
-    def add_migration_metadata(
-        self, creation_date: str | None, iri: str | None = None, ark: str | None = None
+    def add_comment_optional(
+        self,
+        text: Any,
+        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
+        comment: str | None = None,
+        newline_replacement: NewlineReplacement = NewlineReplacement.LINEBREAK,
     ) -> LinkResource:
-        if self.migration_metadata:
-            raise InputError(
-                f"The resource with the ID '{self.res_id}' already contains migration metadata, "
-                f"no new data can be added."
-            )
-        self.migration_metadata = MigrationMetadata(creation_date=creation_date, iri=iri, ark=ark, res_id=self.res_id)
+        """
+        If the value is not empty, add it as comment, otherwise return the resource unchanged.
+
+        Args:
+            text: text of the comment (or empty value)
+            permissions: optional permissions of this value
+            comment: optional comment about this comment
+            newline_replacement: options how to deal with `\\n` inside the text value. Default: replace with `<br/>`
+
+        Returns:
+            The original resource, with the added comment
+
+        Examples:
+            ```python
+            link_resource = link_resource.add_comment_optional("comment text")
+            ```
+
+            ```python
+            link_resource = link_resource.add_comment_optional(None)
+            ```
+        """
+        if is_nonempty_value(text):
+            return self.add_comment(text, permissions, comment, newline_replacement)
         return self
 
-    def serialise(self) -> etree._Element:
-        self._check_for_and_convert_unexpected_input()
-        res_ele = self._serialise_resource_element()
-        res_ele.append(_serialise_has_comment(self.comments, self.res_id))
-        res_ele.append(self._serialise_links())
-        return res_ele
-
-    def _check_for_and_convert_unexpected_input(self) -> None:
-        _check_strings(string_to_check=self.res_id, res_id=self.res_id, field_name="Resource ID")
-        _check_strings(string_to_check=self.label, res_id=self.res_id, field_name="Label")
-        self.comments = _transform_unexpected_input(self.comments, "comments", self.res_id)
-        self.link_to = _transform_unexpected_input(self.link_to, "link_to", self.res_id)
-
-    def _serialise_resource_element(self) -> etree._Element:
-        attribs = {"label": self.label, "id": self.res_id}
-        if self.permissions:
-            attribs["permissions"] = self.permissions
-        return etree.Element(f"{DASCH_SCHEMA}link", attrib=attribs, nsmap=XML_NAMESPACE_MAP)
-
-    def _serialise_links(self) -> etree._Element:
-        prop_ele = etree.Element(f"{DASCH_SCHEMA}resptr-prop", name="hasLinkTo", nsmap=XML_NAMESPACE_MAP)
-        vals = [LinkValue(value=x, prop_name="hasLinkTo", resource_id=self.res_id) for x in self.link_to]
-        prop_ele.extend([v.make_element() for v in vals])
-        return prop_ele
-
 
 @dataclass
 class SegmentBounds:
     segment_start: float | int | str
     segment_end: float | int | str
+    permissions: Permissions
     res_id: str
 
     def __post_init__(self) -> None:
@@ -254,309 +522,1021 @@ class SegmentBounds:
         if not is_decimal(self.segment_end):
             msg.append(f"Segment End Value: {self.segment_end} | Type: {type(self.segment_start)}")
         if msg:
-            title = (
-                f"The resource with the ID: '{self.res_id}' expects a float or integer for segment bounds. "
-                f"The following places have an unexpected type:"
+            wrng = f"{LIST_SEPARATOR}{LIST_SEPARATOR.join(msg)}"
+            msg_info = MessageInfo(
+                f"Segment bounds must be a float or integer. The following places have an unexpected type: {wrng}",
+                self.res_id,
             )
-            wrng = f"{title}{LIST_SEPARATOR}{LIST_SEPARATOR.join(msg)}"
-            warnings.warn(DspToolsUserWarning(wrng))
+            emit_xmllib_input_warning(msg_info)
+        self.segment_start = str(self.segment_start)
+        self.segment_end = str(self.segment_end)
 
 
 @dataclass
 class VideoSegmentResource:
     res_id: str
     label: str
-    segment_of: str
     segment_bounds: SegmentBounds
-    title: str | None = None
-    comments: list[str] = field(default_factory=list)
-    descriptions: list[str] = field(default_factory=list)
-    keywords: list[str] = field(default_factory=list)
-    relates_to: list[str] = field(default_factory=list)
-    permissions: str = "res-default"
+    values: list[Value]
+    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS
     migration_metadata: MigrationMetadata | None = None
 
-    def new(
-        self,
+    @staticmethod
+    def create_new(
         res_id: str,
         label: str,
         segment_of: str,
-        segment_start: float,
-        segment_end: float,
-        title: str | None = None,
-        permissions: str = "res-default",
+        segment_start: float | int | str,
+        segment_end: float | int | str,
+        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
     ) -> VideoSegmentResource:
+        """
+        Creates a new video segment resource, i.e. a time span of a MovingImageRepresentation.
+
+        [See XML documentation for details](https://docs.dasch.swiss/latest/DSP-TOOLS/file-formats/xml-data-file/#video-segment-and-audio-segment)
+
+        Args:
+            res_id: ID of this video segment resource
+            label: label of this video segment resource
+            segment_of: ID of the video resource that this segment refers to (cardinality 1)
+            segment_start: start of the segment in seconds (cardinality 1)
+            segment_end: end of the segment in seconds (cardinality 1)
+            permissions: permissions of this resource
+
+        Returns:
+            A video segment resource
+
+        Examples:
+            ```python
+            video_segment = xmllib.VideoSegmentResource.create_new(
+                res_id="ID",
+                label="label",
+                segment_of="video_resource_id",
+                segment_start=1.2,
+                segment_end=3.4,
+            )
+            ```
+        """
+        _check_strings(string_to_check=res_id, res_id=res_id, field_name="Resource ID")
+        res_id = str(res_id)
+        lbl = check_and_fix_is_non_empty_string(value=label, res_id=res_id, value_field="label")
+        segment_of_val = LinkValue.new(
+            value=segment_of, prop_name="isSegmentOf", permissions=permissions, comment=None, resource_id=res_id
+        )
         return VideoSegmentResource(
             res_id=res_id,
-            label=label,
-            segment_of=segment_of,
-            segment_bounds=SegmentBounds(segment_start, segment_end, res_id),
-            title=title,
+            label=lbl,
+            values=[segment_of_val],
+            segment_bounds=SegmentBounds(segment_start, segment_end, permissions, res_id),
             permissions=permissions,
         )
 
-    def add_title(self, title: str) -> VideoSegmentResource:
-        if self.title:
-            _warn_value_exists(self.title, title, "title", self.res_id)
-        self.title = title
+    def add_title(
+        self,
+        title: str,
+        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
+        comment: str | None = None,
+    ) -> VideoSegmentResource:
+        """
+        Add a title to the resource.
+
+        Args:
+            title: text
+            permissions: permissions of the value
+            comment: comments on the value
+
+        Returns:
+            The original resource, with the added title
+
+        Examples:
+            ```python
+            video_segment = video_segment.add_title("segment title")
+            ```
+        """
+        existing_titles = [x for x in self.values if x.prop_name == "hasTitle"]
+        if any(existing_titles):
+            _warn_value_exists(
+                old_value=existing_titles.pop(0).value, new_value=title, value_field="title", res_id=self.res_id
+            )
+        self.values.append(
+            SimpleText.new(
+                value=title,
+                prop_name="hasTitle",
+                permissions=permissions,
+                comment=comment,
+                resource_id=self.res_id,
+            )
+        )
         return self
 
-    def add_comment(self, comment: str) -> VideoSegmentResource:
-        self.comments.append(comment)
+    def add_title_optional(
+        self,
+        title: Any,
+        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
+        comment: str | None = None,
+    ) -> VideoSegmentResource:
+        """
+        If the value is not empty, add it as title, otherwise return the resource unchanged.
+
+        Args:
+            title: text or empty value
+            permissions: permissions of the value
+            comment: comments on the value
+
+        Returns:
+            The original resource, with the added title
+
+        Examples:
+            ```python
+            video_segment = video_segment.add_title("segment title")
+            ```
+
+            ```python
+            video_segment = video_segment.add_title(None)
+            ```
+        """
+        if is_nonempty_value(title):
+            self.add_title(title, permissions, comment)
         return self
 
-    def add_comments(self, comments: list[str]) -> VideoSegmentResource:
-        self.comments.extend(comments)
+    def add_comment(
+        self,
+        text: str,
+        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
+        comment: str | None = None,
+        newline_replacement: NewlineReplacement = NewlineReplacement.LINEBREAK,
+    ) -> VideoSegmentResource:
+        """
+        Add a comment to the resource
+
+        Args:
+            text: text
+            permissions: optional permissions of this value
+            comment: optional comment about this comment
+            newline_replacement: options how to deal with `\\n` inside the text value. Default: replace with `<br/>`
+
+        Returns:
+            The original resource, with the added comment
+
+        Examples:
+            ```python
+            video_segment = video_segment.add_comment("comment text")
+            ```
+        """
+        self.values.append(
+            Richtext.new(
+                value=text,
+                prop_name="hasComment",
+                permissions=permissions,
+                comment=comment,
+                resource_id=self.res_id,
+                newline_replacement=newline_replacement,
+            )
+        )
         return self
 
-    def add_description(self, description: str) -> VideoSegmentResource:
-        self.descriptions.append(description)
+    def add_comment_multiple(
+        self,
+        texts: Collection[str],
+        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
+        comment: str | None = None,
+        newline_replacement: NewlineReplacement = NewlineReplacement.LINEBREAK,
+    ) -> VideoSegmentResource:
+        """
+        Add several comments to the resource
+
+        Args:
+            texts: list of texts
+            permissions: optional permissions of these values
+            comment: optional comment about these comments
+            newline_replacement: options how to deal with `\\n` inside the text value. Default: replace with `<br/>`
+
+        Returns:
+            The original resource, with the added comments
+
+        Examples:
+            ```python
+            video_segment = video_segment.add_comment_multiple(["comment 1", "comment 2"])
+            ```
+        """
+        vals = check_and_fix_collection_input(texts, "hasComment", self.res_id)
+        for v in vals:
+            self.add_comment(v, permissions, comment, newline_replacement)
         return self
 
-    def add_descriptions(self, descriptions: list[str]) -> VideoSegmentResource:
-        self.descriptions.extend(descriptions)
+    def add_comment_optional(
+        self,
+        text: Any,
+        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
+        comment: str | None = None,
+        newline_replacement: NewlineReplacement = NewlineReplacement.LINEBREAK,
+    ) -> VideoSegmentResource:
+        """
+        If the value is not empty, add it as comment, otherwise return the resource unchanged.
+
+        Args:
+            text: text of the comment (or empty value)
+            permissions: optional permissions of this value
+            comment: optional comment about this comment
+            newline_replacement: options how to deal with `\\n` inside the text value. Default: replace with `<br/>`
+
+        Returns:
+            The original resource, with the added comment
+
+        Examples:
+            ```python
+            video_segment = video_segment.add_comment_optional("comment text")
+            ```
+
+            ```python
+            video_segment = video_segment.add_comment_optional(None)
+            ```
+        """
+        if is_nonempty_value(text):
+            self.add_comment(text, permissions, comment, newline_replacement)
         return self
 
-    def add_keyword(self, keywords: str) -> VideoSegmentResource:
-        self.keywords.append(keywords)
+    def add_description(
+        self,
+        description: str,
+        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
+        comment: str | None = None,
+        newline_replacement: NewlineReplacement = NewlineReplacement.LINEBREAK,
+    ) -> VideoSegmentResource:
+        """
+        Add a description to the resource
+
+        Args:
+            description: text
+            permissions: optional permissions of this value
+            comment: optional comment
+            newline_replacement: options how to deal with `\\n` inside the text value. Default: replace with `<br/>`
+
+        Returns:
+            The original resource, with the added description
+
+        Examples:
+            ```python
+            video_segment = video_segment.add_description("description text")
+            ```
+        """
+        self.values.append(
+            Richtext.new(
+                value=description,
+                prop_name="hasDescription",
+                permissions=permissions,
+                comment=comment,
+                resource_id=self.res_id,
+                newline_replacement=newline_replacement,
+            )
+        )
         return self
 
-    def add_keywords(self, keywords: list[str]) -> VideoSegmentResource:
-        self.keywords.extend(keywords)
+    def add_description_multiple(
+        self,
+        descriptions: Collection[str],
+        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
+        comment: str | None = None,
+        newline_replacement: NewlineReplacement = NewlineReplacement.LINEBREAK,
+    ) -> VideoSegmentResource:
+        """
+        Add several descriptions to the resource
+
+        Args:
+            descriptions: list of texts
+            permissions: optional permissions of these value
+            comment: optional comment
+            newline_replacement: options how to deal with `\\n` inside the text value. Default: replace with `<br/>`
+
+        Returns:
+            The original resource, with the added descriptions
+
+        Examples:
+            ```python
+            video_segment = video_segment.add_description_multiple(["description 1", "description 2"])
+            ```
+        """
+        vals = check_and_fix_collection_input(descriptions, "description", self.res_id)
+        for v in vals:
+            self.add_description(v, permissions, comment, newline_replacement)
         return self
 
-    def add_relates_to(self, relates_to: str) -> VideoSegmentResource:
-        self.relates_to.append(relates_to)
+    def add_description_optional(
+        self,
+        description: Any,
+        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
+        comment: str | None = None,
+        newline_replacement: NewlineReplacement = NewlineReplacement.LINEBREAK,
+    ) -> VideoSegmentResource:
+        """
+        If the value is not empty, add it as description, otherwise return the resource unchanged.
+
+        Args:
+            description: text or empty value
+            permissions: optional permissions of this value
+            comment: optional comment
+            newline_replacement: options how to deal with `\\n` inside the text value. Default: replace with `<br/>`
+
+        Returns:
+            The original resource, with the added description
+
+        Examples:
+            ```python
+            video_segment = video_segment.add_description_optional("description text")
+            ```
+
+            ```python
+            video_segment = video_segment.add_description_optional(None)
+            ```
+        """
+        if is_nonempty_value(description):
+            self.add_description(description, permissions, comment, newline_replacement)
         return self
 
-    def add_relates_to_multiple(self, relates_to: list[str]) -> VideoSegmentResource:
-        self.relates_to.extend(relates_to)
+    def add_keyword(
+        self,
+        keyword: str,
+        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
+        comment: str | None = None,
+    ) -> VideoSegmentResource:
+        """
+        Add a keyword to the resource
+
+        Args:
+            keyword: text
+            permissions: optional permissions of this value
+            comment: optional comment
+
+        Returns:
+            The original resource, with the added keyword
+
+        Examples:
+            ```python
+            video_segment = video_segment.add_keyword("keyword")
+            ```
+        """
+        self.values.append(
+            SimpleText.new(
+                value=keyword,
+                prop_name="hasKeyword",
+                permissions=permissions,
+                comment=comment,
+                resource_id=self.res_id,
+            )
+        )
         return self
 
-    def add_migration_metadata(
-        self, creation_date: str | None, iri: str | None = None, ark: str | None = None
+    def add_keyword_multiple(
+        self,
+        keywords: Collection[str],
+        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
+        comment: str | None = None,
     ) -> VideoSegmentResource:
-        if self.migration_metadata:
-            raise InputError(
-                f"The resource with the ID '{self.res_id}' already contains migration metadata, "
-                f"no new data can be added."
-            )
-        self.migration_metadata = MigrationMetadata(creation_date=creation_date, iri=iri, ark=ark, res_id=self.res_id)
+        """
+        Add several keywords to the resource
+
+        Args:
+            keywords: list of texts
+            permissions: optional permissions of these values
+            comment: optional comment
+
+        Returns:
+            The original resource, with the added keywords
+
+        Examples:
+            ```python
+            video_segment = video_segment.add_keyword_multiple(["keyword 1", "keyword 2"])
+            ```
+        """
+        vals = check_and_fix_collection_input(keywords, "keywords", self.res_id)
+        for v in vals:
+            self.add_keyword(v, permissions, comment)
         return self
 
-    def serialise(self) -> etree._Element:
-        self._check_for_and_convert_unexpected_input()
-        res_ele = self._serialise_resource_element()
-        res_ele.extend(_serialise_segment_children(self))
-        return res_ele
+    def add_keyword_optional(
+        self,
+        keyword: Any,
+        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
+        comment: str | None = None,
+    ) -> VideoSegmentResource:
+        """
+        If the value is not empty, add it as keyword, otherwise return the resource unchanged.
+
+        Args:
+            keyword: text or empty value
+            permissions: optional permissions of this value
+            comment: optional comment
+
+        Returns:
+            The original resource, with the added keyword
+
+        Examples:
+            ```python
+            video_segment = video_segment.add_keyword_optional("keyword")
+            ```
+
+            ```python
+            video_segment = video_segment.add_keyword_optional(None)
+            ```
+        """
+        if is_nonempty_value(keyword):
+            self.add_keyword(keyword, permissions, comment)
+        return self
 
-    def _check_for_and_convert_unexpected_input(self) -> None:
-        self.comments = _transform_unexpected_input(self.comments, "comments", self.res_id)
-        self.descriptions = _transform_unexpected_input(self.descriptions, "descriptions", self.res_id)
-        self.keywords = _transform_unexpected_input(self.keywords, "keywords", self.res_id)
-        self.relates_to = _transform_unexpected_input(self.relates_to, "relates_to", self.res_id)
-        _validate_segment(self)
+    def add_relates_to(
+        self,
+        relates_to: str,
+        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
+        comment: str | None = None,
+    ) -> VideoSegmentResource:
+        """
+        Add a link to a related resource
+
+        Args:
+            relates_to: ID of the related resource
+            permissions: optional permissions of this value
+            comment: optional comment
+
+        Returns:
+            The original resource, with the added related resource
+
+        Examples:
+            ```python
+            video_segment = video_segment.add_relates_to("target_resource_id")
+            ```
+        """
+        self.values.append(
+            LinkValue.new(
+                value=relates_to,
+                prop_name="relatesTo",
+                permissions=permissions,
+                comment=comment,
+                resource_id=self.res_id,
+            )
+        )
+        return self
+
+    def add_relates_to_multiple(
+        self,
+        relates_to: Collection[str],
+        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
+        comment: str | None = None,
+    ) -> VideoSegmentResource:
+        """
+        Add several links to related resources
+
+        Args:
+            relates_to: list of IDs of the related resources
+            permissions: optional permissions of these values
+            comment: optional comment
+
+        Returns:
+            The original resource, with the added related resources
+
+        Examples:
+            ```python
+            video_segment = video_segment.add_relates_to_multiple(["target_resource_id_1", "target_resource_id_2"])
+            ```
+        """
+        vals = check_and_fix_collection_input(relates_to, "relatesTo", self.res_id)
+        for v in vals:
+            self.add_relates_to(v, permissions, comment)
+        return self
 
-    def _serialise_resource_element(self) -> etree._Element:
-        attribs = {"label": self.label, "id": self.res_id}
-        if self.permissions:
-            attribs["permissions"] = self.permissions
-        return etree.Element(f"{DASCH_SCHEMA}video-segment", attrib=attribs, nsmap=XML_NAMESPACE_MAP)
+    def add_relates_to_optional(
+        self,
+        relates_to: Any,
+        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
+        comment: str | None = None,
+    ) -> VideoSegmentResource:
+        """
+        If the value is not empty, add it as related resource, otherwise return the resource unchanged.
+
+        Args:
+            relates_to: ID or the related resource or empty value
+            permissions: optional permissions of this value
+            comment: optional comment
+
+        Returns:
+            The original resource, with the added related resources
+
+        Examples:
+            ```python
+            video_segment = video_segment.add_relates_to_optional("target_resource_id")
+            ```
+
+            ```python
+            video_segment = video_segment.add_relates_to_optional(None)
+            ```
+        """
+        if is_nonempty_value(relates_to):
+            self.add_relates_to(relates_to, permissions, comment)
+        return self
 
 
 @dataclass
 class AudioSegmentResource:
     res_id: str
     label: str
-    segment_of: str
     segment_bounds: SegmentBounds
-    title: str | None = None
-    comments: list[str] = field(default_factory=list)
-    descriptions: list[str] = field(default_factory=list)
-    keywords: list[str] = field(default_factory=list)
-    relates_to: list[str] = field(default_factory=list)
-    permissions: str = "res-default"
+    values: list[Value]
+    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS
     migration_metadata: MigrationMetadata | None = None
 
-    def new(
-        self,
+    @staticmethod
+    def create_new(
         res_id: str,
         label: str,
         segment_of: str,
-        segment_start: float,
-        segment_end: float,
-        title: str | None = None,
-        permissions: str = "res-default",
+        segment_start: float | int | str,
+        segment_end: float | int | str,
+        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
     ) -> AudioSegmentResource:
+        """
+        Creates a new audio segment resource, i.e. a time span of an AudioRepresentation.
+
+        [See XML documentation for details](https://docs.dasch.swiss/latest/DSP-TOOLS/file-formats/xml-data-file/#video-segment-and-audio-segment)
+
+        Args:
+            res_id: ID of this audio segment resource
+            label: label of this audio segment resource
+            segment_of: ID of the audio resource that this segment refers to (cardinality 1)
+            segment_start: start of the segment in seconds (cardinality 1)
+            segment_end: end of the segment in seconds (cardinality 1)
+            permissions: permissions of this resource
+
+        Returns:
+            An audio segment resource
+        """
+        _check_strings(string_to_check=res_id, res_id=res_id, field_name="Resource ID")
+        res_id = str(res_id)
+        lbl = check_and_fix_is_non_empty_string(value=label, res_id=res_id, value_field="label")
+        segment_of_val = LinkValue.new(
+            value=segment_of, prop_name="isSegmentOf", permissions=permissions, comment=None, resource_id=res_id
+        )
         return AudioSegmentResource(
             res_id=res_id,
-            label=label,
-            segment_of=segment_of,
-            segment_bounds=SegmentBounds(segment_start, segment_end, res_id),
-            title=title,
+            label=lbl,
+            segment_bounds=SegmentBounds(segment_start, segment_end, permissions, res_id),
+            values=[segment_of_val],
             permissions=permissions,
         )
 
-    def add_title(self, title: str) -> AudioSegmentResource:
-        if self.title:
-            _warn_value_exists(self.title, title, "title", self.res_id)
-        self.title = title
+    def add_title(
+        self,
+        title: str,
+        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
+        comment: str | None = None,
+    ) -> AudioSegmentResource:
+        """
+        Add a title to the resource.
+
+        Args:
+            title: text
+            permissions: permissions of the value
+            comment: comments on the value
+
+        Returns:
+            The original resource, with the added title
+
+        Examples:
+            ```python
+            audio_segment = audio_segment.add_title("segment title")
+            ```
+        """
+        existing_title = [x for x in self.values if x.prop_name == "hasTitle"]
+        if any(existing_title):
+            _warn_value_exists(
+                old_value=existing_title.pop(0).value, new_value=title, value_field="title", res_id=self.res_id
+            )
+        self.values.append(
+            SimpleText.new(
+                value=title,
+                prop_name="hasTitle",
+                permissions=permissions,
+                comment=comment,
+                resource_id=self.res_id,
+            )
+        )
+        return self
+
+    def add_title_optional(
+        self,
+        title: Any,
+        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
+        comment: str | None = None,
+    ) -> AudioSegmentResource:
+        """
+        If the value is not empty, add it as title, otherwise return the resource unchanged.
+
+        Args:
+            title: text or empty value
+            permissions: permissions of the value
+            comment: comments on the value
+
+        Returns:
+            The original resource, with the added title
+
+        Examples:
+            ```python
+            audio_segment = audio_segment.add_title("segment title")
+            ```
+
+            ```python
+            audio_segment = audio_segment.add_title(None)
+            ```
+        """
+        if is_nonempty_value(title):
+            self.add_title(title, permissions, comment)
+        return self
+
+    def add_comment(
+        self,
+        text: str,
+        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
+        comment: str | None = None,
+        newline_replacement: NewlineReplacement = NewlineReplacement.LINEBREAK,
+    ) -> AudioSegmentResource:
+        """
+        Add a comment to the resource
+
+        Args:
+            text: text of the comment
+            permissions: optional permissions of this value
+            comment: optional comment about this comment
+            newline_replacement: options how to deal with `\\n` inside the text value. Default: replace with `<br/>`
+
+        Returns:
+            The original resource, with the added comment
+
+        Examples:
+            ```python
+            audio_segment = audio_segment.add_comment("comment text")
+            ```
+        """
+        self.values.append(
+            Richtext.new(
+                value=text,
+                prop_name="hasComment",
+                permissions=permissions,
+                comment=comment,
+                resource_id=self.res_id,
+                newline_replacement=newline_replacement,
+            )
+        )
         return self
 
-    def add_comment(self, comment: str) -> AudioSegmentResource:
-        self.comments.append(comment)
+    def add_comment_multiple(
+        self,
+        texts: Collection[str],
+        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
+        comment: str | None = None,
+        newline_replacement: NewlineReplacement = NewlineReplacement.LINEBREAK,
+    ) -> AudioSegmentResource:
+        """
+        Add several comments to the resource
+
+        Args:
+            texts: list of texts
+            permissions: optional permissions of these values
+            comment: optional comment about these comments
+            newline_replacement: options how to deal with `\\n` inside the text value. Default: replace with `<br/>`
+
+        Returns:
+            The original resource, with the added comments
+
+        Examples:
+            ```python
+            audio_segment = audio_segment.add_comment_multiple(["comment 1", "comment 2"])
+            ```
+        """
+        vals = check_and_fix_collection_input(texts, "hasComment", self.res_id)
+        for v in vals:
+            self.add_comment(v, permissions, comment, newline_replacement)
         return self
 
-    def add_comments(self, comments: list[str]) -> AudioSegmentResource:
-        self.comments.extend(comments)
+    def add_comment_optional(
+        self,
+        text: Any,
+        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
+        comment: str | None = None,
+        newline_replacement: NewlineReplacement = NewlineReplacement.LINEBREAK,
+    ) -> AudioSegmentResource:
+        """
+        If the value is not empty, add it as comment, otherwise return the resource unchanged.
+
+        Args:
+            text: text of the comment (or empty value)
+            permissions: optional permissions of this value
+            comment: optional comment about this comment
+            newline_replacement: options how to deal with `\\n` inside the text value. Default: replace with `<br/>`
+
+        Returns:
+            The original resource, with the added comment
+
+        Examples:
+            ```python
+            audio_segment = audio_segment.add_comment_optional("comment text")
+            ```
+
+            ```python
+            audio_segment = audio_segment.add_comment_optional(None)
+            ```
+        """
+        if is_nonempty_value(text):
+            self.add_comment(text, permissions, comment, newline_replacement)
         return self
 
-    def add_description(self, description: str) -> AudioSegmentResource:
-        self.descriptions.append(description)
+    def add_description(
+        self,
+        description: str,
+        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
+        comment: str | None = None,
+        newline_replacement: NewlineReplacement = NewlineReplacement.LINEBREAK,
+    ) -> AudioSegmentResource:
+        """
+        Add a description to the resource
+
+        Args:
+            description: text
+            permissions: optional permissions of this value
+            comment: optional comment
+            newline_replacement: options how to deal with `\\n` inside the text value. Default: replace with `<br/>`
+
+        Returns:
+            The original resource, with the added description
+
+        Examples:
+            ```python
+            audio_segment = audio_segment.add_description("description text")
+            ```
+        """
+        self.values.append(
+            Richtext.new(
+                value=description,
+                prop_name="hasDescription",
+                permissions=permissions,
+                comment=comment,
+                resource_id=self.res_id,
+                newline_replacement=newline_replacement,
+            )
+        )
         return self
 
-    def add_descriptions(self, descriptions: list[str]) -> AudioSegmentResource:
-        self.descriptions.extend(descriptions)
+    def add_description_multiple(
+        self,
+        descriptions: Collection[str],
+        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
+        comment: str | None = None,
+        newline_replacement: NewlineReplacement = NewlineReplacement.LINEBREAK,
+    ) -> AudioSegmentResource:
+        """
+        Add several descriptions to the resource
+
+        Args:
+            descriptions: list of texts
+            permissions: optional permissions of these values
+            comment: optional comment
+            newline_replacement: options how to deal with `\\n` inside the text value. Default: replace with `<br/>`
+
+        Returns:
+            The original resource, with the added descriptions
+
+        Examples:
+            ```python
+            audio_segment = audio_segment.add_description_multiple(["description 1", "description 2"])
+            ```
+        """
+        vals = check_and_fix_collection_input(descriptions, "description", self.res_id)
+        for v in vals:
+            self.add_description(v, permissions, comment, newline_replacement)
         return self
 
-    def add_keyword(self, keywords: str) -> AudioSegmentResource:
-        self.keywords.append(keywords)
+    def add_description_optional(
+        self,
+        description: Any,
+        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
+        comment: str | None = None,
+        newline_replacement: NewlineReplacement = NewlineReplacement.LINEBREAK,
+    ) -> AudioSegmentResource:
+        """
+        If the value is not empty, add it as description, otherwise return the resource unchanged.
+
+        Args:
+            description: text or empty value
+            permissions: optional permissions of this value
+            comment: optional comment
+            newline_replacement: options how to deal with `\\n` inside the text value. Default: replace with `<br/>`
+
+        Returns:
+            The original resource, with the added description
+
+        Examples:
+            ```python
+            audio_segment = audio_segment.add_description_optional("description text")
+            ```
+
+            ```python
+            audio_segment = audio_segment.add_description_optional(None)
+            ```
+        """
+        if is_nonempty_value(description):
+            self.add_description(description, permissions, comment, newline_replacement)
         return self
 
-    def add_keywords(self, keywords: list[str]) -> AudioSegmentResource:
-        self.keywords.extend(keywords)
+    def add_keyword(
+        self,
+        keyword: str,
+        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
+        comment: str | None = None,
+    ) -> AudioSegmentResource:
+        """
+        Add a keyword to the resource
+
+        Args:
+            keyword: text
+            permissions: optional permissions of this value
+            comment: optional comment
+
+        Returns:
+            The original resource, with the added keyword
+
+        Examples:
+            ```python
+            audio_segment = audio_segment.add_keyword("keyword")
+            ```
+        """
+        self.values.append(
+            SimpleText.new(
+                value=keyword,
+                prop_name="hasKeyword",
+                permissions=permissions,
+                comment=comment,
+                resource_id=self.res_id,
+            )
+        )
         return self
 
-    def add_relates_to(self, relates_to: str) -> AudioSegmentResource:
-        self.relates_to.append(relates_to)
+    def add_keyword_multiple(
+        self,
+        keywords: Collection[str],
+        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
+        comment: str | None = None,
+    ) -> AudioSegmentResource:
+        """
+        Add several keywords to the resource
+
+        Args:
+            keywords: list of texts
+            permissions: optional permissions of these values
+            comment: optional comment
+
+        Returns:
+            The original resource, with the added keywords
+
+        Examples:
+            ```python
+            audio_segment = audio_segment.add_keyword_multiple(["keyword 1", "keyword 2"])
+            ```
+        """
+        vals = check_and_fix_collection_input(keywords, "keywords", self.res_id)
+        for v in vals:
+            self.add_keyword(v, permissions, comment)
         return self
 
-    def add_relates_to_multiple(self, relates_to: list[str]) -> AudioSegmentResource:
-        self.relates_to.extend(relates_to)
+    def add_keyword_optional(
+        self,
+        keyword: Any,
+        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
+        comment: str | None = None,
+    ) -> AudioSegmentResource:
+        """
+        If the value is not empty, add it as keyword, otherwise return the resource unchanged.
+
+        Args:
+            keyword: text or empty value
+            permissions: optional permissions of this value
+            comment: optional comment
+
+        Returns:
+            The original resource, with the added keyword
+
+        Examples:
+            ```python
+            audio_segment = audio_segment.add_keyword_optional("keyword")
+            ```
+
+            ```python
+            audio_segment = audio_segment.add_keyword_optional(None)
+            ```
+        """
+        if is_nonempty_value(keyword):
+            self.add_keyword(keyword, permissions, comment)
         return self
 
-    def add_migration_metadata(
-        self, creation_date: str | None, iri: str | None = None, ark: str | None = None
+    def add_relates_to(
+        self,
+        relates_to: str,
+        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
+        comment: str | None = None,
     ) -> AudioSegmentResource:
-        if self.migration_metadata:
-            raise InputError(
-                f"The resource with the ID '{self.res_id}' already contains migration metadata, "
-                f"no new data can be added."
+        """
+        Add a link to a related resource
+
+        Args:
+            relates_to: ID of the related resource
+            permissions: optional permissions of this value
+            comment: optional comment
+
+        Returns:
+            The original resource, with the added related resource
+
+        Examples:
+            ```python
+            audio_segment = audio_segment.add_relates_to("target_resource_id")
+            ```
+        """
+        self.values.append(
+            LinkValue.new(
+                value=relates_to,
+                prop_name="relatesTo",
+                permissions=permissions,
+                comment=comment,
+                resource_id=self.res_id,
             )
-        self.migration_metadata = MigrationMetadata(creation_date=creation_date, iri=iri, ark=ark, res_id=self.res_id)
-        return self
-
-    def serialise(self) -> etree._Element:
-        self._check_for_and_convert_unexpected_input()
-        res_ele = self._serialise_resource_element()
-        res_ele.extend(_serialise_segment_children(self))
-        return res_ele
-
-    def _check_for_and_convert_unexpected_input(self) -> None:
-        self.comments = _transform_unexpected_input(self.comments, "comments", self.res_id)
-        self.descriptions = _transform_unexpected_input(self.descriptions, "descriptions", self.res_id)
-        self.keywords = _transform_unexpected_input(self.keywords, "keywords", self.res_id)
-        self.relates_to = _transform_unexpected_input(self.relates_to, "relates_to", self.res_id)
-        _validate_segment(self)
-
-    def _serialise_resource_element(self) -> etree._Element:
-        attribs = {"label": self.label, "id": self.res_id}
-        if self.permissions:
-            attribs["permissions"] = self.permissions
-        return etree.Element(f"{DASCH_SCHEMA}audio-segment", attrib=attribs, nsmap=XML_NAMESPACE_MAP)
-
-
-def _check_strings(string_to_check: str, res_id: str, field_name: str) -> None:
-    if not is_string_like(string_to_check):
-        msg = (
-            f"The resource with the ID '{res_id}' has an invalid string at the following location:\n"
-            f"Field: {field_name} | Value: {string_to_check}"
         )
-        warnings.warn(DspToolsUserWarning(msg))
-
-
-def _serialise_has_comment(comments: list[str], res_id: str) -> etree._Element:
-    cmts = [Richtext(value=x, prop_name="hasComment", resource_id=res_id) for x in comments]
-    cmt_prop = cmts[0].make_prop()
-    cmt_prop.extend([cmt.make_element() for cmt in cmts])
-    return cmt_prop
-
-
-def _validate_segment(segment: AudioSegmentResource | VideoSegmentResource) -> None:
-    problems = []
-    if not is_string_like(segment.res_id):
-        problems.append(f"Field: Resource ID | Value: {segment.res_id}")
-    if not is_string_like(segment.label):
-        problems.append(f"Field: label | Value: {segment.label}")
-    if not is_string_like(segment.segment_of):
-        problems.append(f"Field: segment_of | Value: {segment.segment_of}")
-    if segment.title and not is_string_like(segment.title):
-        problems.append(f"Field: title | Value: {segment.title}")
-    if fails := [x for x in segment.comments if not is_string_like(x)]:
-        problems.extend([f"Field: comment | Value: {x}" for x in fails])
-    if fails := [x for x in segment.descriptions if not is_string_like(x)]:
-        problems.extend([f"Field: description | Value: {x}" for x in fails])
-    if fails := [x for x in segment.keywords if not is_string_like(x)]:
-        problems.extend([f"Field: keywords | Value: {x}" for x in fails])
-    if fails := [x for x in segment.relates_to if not is_string_like(x)]:
-        problems.extend([f"Field: relates_to | Value: {x}" for x in fails])
-    if problems:
-        msg = f"The resource with the ID '{segment.res_id}' has the following problem(s):{'\n- '.join(problems)}"
-        warnings.warn(DspToolsUserWarning(msg))
-
-
-def _serialise_segment_children(segment: AudioSegmentResource | VideoSegmentResource) -> list[etree._Element]:
-    segment_elements = []
-    segment_of = etree.Element(f"{DASCH_SCHEMA}isSegmentOf", nsmap=XML_NAMESPACE_MAP)
-    segment_of.text = segment.segment_of
-    segment_elements.append(segment_of)
-    segment_elements.append(
-        etree.Element(
-            f"{DASCH_SCHEMA}hasSegmentBounds",
-            attrib={"start": str(segment.segment_bounds.segment_start), "end": str(segment.segment_bounds.segment_end)},
-            nsmap=XML_NAMESPACE_MAP,
-        )
-    )
-    if segment.title:
-        segment_elements.append(_make_element_with_text("hasTitle", segment.title))
-    segment_elements.extend([_make_element_with_text("hasComment", x) for x in segment.comments])
-    segment_elements.extend([_make_element_with_text("hasDescription", x) for x in segment.descriptions])
-    segment_elements.extend([_make_element_with_text("hasKeyword", x) for x in segment.keywords])
-    segment_elements.extend([_make_element_with_text("relatesTo", x) for x in segment.relates_to])
-    return segment_elements
-
-
-def _make_element_with_text(tag_name: str, text_content: str) -> etree._Element:
-    ele = etree.Element(f"{DASCH_SCHEMA}{tag_name}", nsmap=XML_NAMESPACE_MAP)
-    ele.text = text_content
-    return ele
-
-
-def _transform_unexpected_input(value: Any, prop_name: str, res_id: str) -> list[str]:
-    match value:
-        case list():
-            return value
-        case set() | tuple():
-            return list(value)
-        case str():
-            return [value]
-        case _:
-            _warn_unexpected_value(value, prop_name, res_id)
-            return [str(value)]
-
-
-def _warn_unexpected_value(value: Any, prop_name: str, res_id: str | None) -> None:
-    msg = (
-        f"The resource: {res_id} should have a list of strings for the field '{prop_name}'. "
-        f"Your input: '{value}' is of type {type(value)}."
-    )
-    warnings.warn(DspToolsUserWarning(msg))
+        return self
+
+    def add_relates_to_multiple(
+        self,
+        relates_to: Collection[str],
+        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
+        comment: str | None = None,
+    ) -> AudioSegmentResource:
+        """
+        Add several links to related resources
+
+        Args:
+            relates_to: list of IDs of the related resources
+            permissions: optional permissions of these values
+            comment: optional comment
+
+        Returns:
+            The original resource, with the added related resources
+
+        Examples:
+            ```python
+            audio_segment = audio_segment.add_relates_to_multiple(["target_resource_id_1", "target_resource_id_2"])
+            ```
+        """
+        vals = check_and_fix_collection_input(relates_to, "relatesTo", self.res_id)
+        for v in vals:
+            self.add_relates_to(v, permissions, comment)
+        return self
+
+    def add_relates_to_optional(
+        self,
+        relates_to: Any,
+        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
+        comment: str | None = None,
+    ) -> AudioSegmentResource:
+        """
+        If the value is not empty, add it as related resource, otherwise return the resource unchanged.
+
+        Args:
+            relates_to: ID of the related resource or empty value
+            permissions: optional permissions of this value
+            comment: optional comment
+
+        Returns:
+            The original resource, with the added related resources
+
+        Examples:
+            ```python
+            audio_segment = audio_segment.add_relates_to_optional("target_resource_id")
+            ```
+
+            ```python
+            audio_segment = audio_segment.add_relates_to_optional(None)
+            ```
+        """
+        if is_nonempty_value(relates_to):
+            self.add_relates_to(relates_to, permissions, comment)
+        return self
+
+
+def _check_strings(
+    *, string_to_check: str, res_id: str, prop_name: str | None = None, field_name: str | None = None
+) -> None:
+    if not is_nonempty_value(string_to_check):
+        msg_info = MessageInfo("The entered string is not valid.", res_id, prop_name, field_name)
+        emit_xmllib_input_warning(msg_info)
 
 
-def _warn_value_exists(old_value: Any, new_value: Any, value_field: str, res_id: str | None) -> None:
-    """Emits a warning if a values is not in the expected format."""
+def _warn_value_exists(*, old_value: Any, new_value: Any, res_id: str | None, value_field: str | None = None) -> None:
     msg = (
-        f"The resource with the ID '{res_id}' already has a value in the field '{value_field}'. "
+        f"This resource already has a value in this location. "
         f"The old value '{old_value}' is being replace with '{new_value}'."
     )
-    warnings.warn(DspToolsUserWarning(msg))
+    msg_info = MessageInfo(msg, res_id, field=value_field)
+    emit_xmllib_input_warning(msg_info)