API Reference¶

class BaseEntity(BaseModel):
    """
    Base class used to define `ObjectType` and `VocabularyType` classes. It extends the `BaseModel`
    adding new methods that are useful for interfacing with openBIS.
    """

    code: str | None = Field(
        default=None,
        description="""
        Code of the entity to assign as permanent identifier in openBIS.
        """,
    )

    def __init__(self, **kwargs):
        super().__init__()

        # We store the `_property_metadata` during instantiation of the class
        self._property_metadata = self.get_property_metadata()

        for key, value in kwargs.items():
            setattr(self, key, value)

    def __setattr__(self, key, value):
        # Allow initialization before metadata exists
        if not hasattr(self, "_property_metadata"):
            return object.__setattr__(self, key, value)

        if key == "_property_metadata":
            super().__setattr__(key, value)
            return

        if key in self._property_metadata:
            # TODO add CONTROLLEDVOCABULARY and OBJECT cases
            expected_type = self._property_metadata[key].data_type.pytype
            if expected_type and not isinstance(value, expected_type):
                raise TypeError(
                    f"Invalid type for '{key}': Expected {expected_type.__name__}, got {type(value).__name__}"
                )

        # TODO add check if someone tries to set up a definition instead of an assigned property

        object.__setattr__(self, key, value)

    def __repr__(self):
        # Filter for attributes that are `PropertyTypeAssignment` and set to a finite value
        class_prop_name = None
        fields = []
        for key, metadata in self._property_metadata.items():
            if isinstance(metadata, PropertyTypeAssignment):
                value = getattr(self, key, None)
                # Only include set attributes
                if value is not None and not isinstance(value, PropertyTypeAssignment):
                    if key == "name":
                        class_prop_name = value
                    fields.append(f"{key}={repr(value)}")

        # Format the output
        class_name = self.cls_name
        if class_prop_name:  # adding `name` if available
            class_name = f"{class_prop_name}:{class_name}"
        return f"{class_name}({', '.join(fields)})"

    # Overwriting the __str__ method to use the same representation as __repr__
    __str__ = __repr__

    @property
    def cls_name(self) -> str:
        """
        Returns the entity name of the class as a string to speed up checks. This is a property
        to be overwritten by each of the abstract entity types.
        """
        return self.__class__.__name__

    @property
    def _base_attrs(self) -> list:
        """
        List of base properties or terms assigned to an entity type. This are the direct properties or terms
        assigned when defining a new entity type.
        """
        cls_attrs = self.__class__.__dict__
        base_attrs = [
            attr_name
            for attr_name in cls_attrs
            if not (
                attr_name.startswith("_")
                or callable(cls_attrs[attr_name])
                or attr_name
                in ["defs", "model_config", "model_fields", "model_computed_fields"]
            )
        ]
        return [getattr(self, attr_name) for attr_name in base_attrs]

    @deprecated(
        "This method is deprecated and will be removed in a future major release. The creation of Object Types, "
        "Property Types, and Vocabularies is done now in the corresponding ObjectType and VocabularyType classes."
    )
    def _to_openbis(
        self,
        logger: "BoundLoggerLazyProxy",
        openbis: "Openbis",
        type: str,
        *,
        type_map: dict,
        get_type: Callable[..., Any],
        create_type: Callable[..., Any],
    ) -> None:
        """
        Simplified function to add or update the entity type in openBIS.
        """
        # Get all existing entities from openBIS
        openbis_entities = getattr(
            OpenbisEntities(url=openbis.url), f"get_{type}_dict"
        )()
        defs = getattr(self, "defs")

        is_vocab = isinstance(self, VocabularyType)

        # Check if the entity already exists
        if defs.code in openbis_entities:
            logger.info(f"Entity '{defs.code}' already exists in openBIS.")
            # Retrieve the existing entity
            entity = get_type(openbis, defs.code)
            # entity = openbis_entities[defs.code]

            # Get properties from self and openBIS
            self_properties = getattr(self, "terms" if is_vocab else "properties", [])
            obis_properties = (
                entity.get_terms().df.code
                if is_vocab
                else entity.get_property_assignments()
            )
            obis_property_codes = [
                prop.code if not is_vocab else prop for prop in obis_properties
            ]

            # Check for properties in self that are not in openBIS
            new_properties_added = False
            for prop in self_properties:
                if prop.code not in obis_property_codes:
                    logger.info(
                        f"Adding new '{'term' if is_vocab else 'property'}' {prop.code}' to entity '{defs.code}'."
                    )
                    new_properties_added = True

                    # Handle special case for OBJECT or SAMPLE data types
                    if not is_vocab and (
                        prop.data_type == "OBJECT" or prop.data_type == "SAMPLE"
                    ):
                        prop.data_type = "SAMPLE"

                    # Assign the term or property to the entity
                    if is_vocab:
                        term = openbis.new_term(
                            code=prop.code,
                            vocabularyCode=defs.code,
                            label=prop.label,
                            description=prop.description,
                        )
                        if prop.official:
                            term.official = prop.official
                        term.save()
                    else:
                        if prop.vocabulary_code:
                            entity.assign_property(
                                prop=prop.code,
                                section=prop.section,
                                mandatory=prop.mandatory,
                                showInEditView=prop.show_in_edit_views,
                                vocabulary=prop.vocabulary_code,
                                ordinal=prop.ordinal,
                            )
                        else:
                            entity.assign_property(
                                prop=prop.code,
                                section=prop.section,
                                mandatory=prop.mandatory,
                                showInEditView=prop.show_in_edit_views,
                                ordinal=prop.ordinal,
                            )

            if not new_properties_added:
                logger.info(
                    f"No new '{'terms' if is_vocab else 'properties'}' added to entity '{defs.code}'."
                )

            # Save the entity after adding new properties
            if not is_vocab:
                entity.save()
            return entity

        # If the entity is new, create it
        logger.info(f"Creating new entity '{defs.code}' in openBIS.")
        if not is_vocab:
            entity = create_type(openbis, defs)
            entity.save()

            # Assign properties to the new entity
            properties = getattr(self, "properties", [])
            for prop in properties:
                logger.info(f"Adding new property '{prop.code}' to '{defs.code}'.")
                # Handle special case for OBJECT or SAMPLE data types
                if prop.data_type == "OBJECT" or prop.data_type == "SAMPLE":
                    prop.data_type = "SAMPLE"

                # Assign the property to the entity
                entity.assign_property(
                    prop=prop.code,
                    section=prop.section,
                    mandatory=prop.mandatory,
                    showInEditView=prop.show_in_edit_views,
                    ordinal=prop.ordinal,
                )
        else:
            # Transform the list of VocabularyTerm objects into the desired format
            terms = [
                {
                    "code": term.code,
                    "label": term.label,
                    "description": term.description,
                }
                for term in getattr(self, "terms", [])
            ]
            term_codes = ", ".join([term.code for term in getattr(self, "terms", [])])
            logger.info(f"Adding new terms {term_codes} to '{defs.code}'.")
            entity = create_type(openbis, defs, terms)
            entity.save()

        # Save the entity after assigning properties
        if not is_vocab:
            entity.save()
        return entity

    def get_property_metadata(self) -> dict:
        """
        Dictionary containing the metadata of the properties assigned to the entity type.

        Returns:
            dict: A dictionary containing the keys of the `PropertyTypeAssignment` attribute names and the
            values of the definitions of `PropertyTypeAssignment`. Example:
            {
                "name": PropertyTypeAssignment(
                    code="$NAME",
                    data_type=VARCHAR,
                    mandatory=True,
                    property_label="Name"
                ),
                "age": PropertyTypeAssignment(
                    code="AGE",
                    data_type=INTEGER,
                    mandatory=False,
                    property_label="Age"
                ),
            }
        """
        cls_attrs = self.__class__.__dict__

        # Store property metadata at class level
        prop_meta_dict: dict = {}
        for base in type(self).__mro__:
            cls_attrs = getattr(base, "__dict__", {})
            for attr_name, attr_value in cls_attrs.items():
                if isinstance(attr_value, PropertyTypeAssignment):
                    prop_meta_dict[attr_name] = attr_value
        return prop_meta_dict

    def to_json(self, indent: int | None = None) -> str:
        """
        Returns the entity as a string in JSON format storing the value of the properties
        assigned to the entity.

        Args:
            indent (Optional[int], optional): The indent to print in JSON. Defaults to None.

        Returns:
            str: The JSON representation of the entity.
        """
        data: dict = {}
        for key in self._property_metadata.keys():
            try:
                value = getattr(self, key)
            except AttributeError:
                continue
            if isinstance(value, PropertyTypeAssignment):
                continue
            data[key] = value
        return json.dumps(data, indent=indent, sort_keys=True)

    def to_dict(self) -> dict:
        """
        Returns the entity as a dictionary storing the value of the properties assigned to the entity.

        Returns:
            dict: The dictionary representation of the entity.
        """
        dump_json = self.to_json()
        return json.loads(dump_json)

    def to_hdf5(self, hdf_file: h5py.File, group_name: str = "") -> h5py.File:
        """
        Serialize the entity to a HDF5 file under the group specified in the input.

        Args:
            hdf_file (h5py.File): The HDF5 file to store the entity.
            group_name (str, optional): The group name to serialize the data.
        """
        if not group_name:
            group_name = self.cls_name
        group = hdf_file.create_group(group_name)

        for key in self._property_metadata.keys():
            try:
                value = getattr(self, key)
                if not value:
                    continue
                if isinstance(value, str | int | float | bool | list | tuple):
                    group.create_dataset(key, data=value)
                else:
                    raise TypeError(
                        f"Unsupported type {type(value)} for key {key} for HDF5 serialization."
                    )
            except AttributeError:
                continue

    def model_to_dict(self) -> dict:
        """
        Returns the model as a dictionary storing the data `defs` and the property or vocabulary term
        assignments.

        Returns:
            dict: The dictionary representation of the model.
        """
        data = self.model_dump()

        attr_value = getattr(self, "defs")
        if isinstance(attr_value, BaseModel):
            data["defs"] = attr_value.model_dump()
        else:
            data["defs"] = attr_value
        return data

    def model_to_json(self, indent: int | None = None) -> str:
        """
        Returns the model as a string in JSON format storing the data `defs` and the property or
        vocabulary term assignments.

        Args:
            indent (Optional[int], optional): The indent to print in JSON. Defaults to None.

        Returns:
            str: The JSON representation of the model.
        """
        # * `model_dump_json()` from pydantic does not store the `defs` section of each entity.
        data = self.model_to_dict()
        return json.dumps(data, indent=indent)

    def _add_properties_rdf(
        self,
        namespace: "Namespace",
        graph: "Graph",
        prop: "PropertyTypeAssignment",
        logger: "BoundLoggerLazyProxy",
    ) -> "URIRef":
        """
        Add the properties assigned to the entity to the RDF graph extracting the information from
        OpenBIS for the `object_code` or `vocabulary_code`.

        Args:
            namespace (Namespace): The namespace to use for the RDF graph.
            graph (Graph): The RDF graph to which the properties are added.
            prop (PropertyTypeAssignment): The property assigned to the entity.
            logger (BoundLoggerLazyProxy): The logger to log messages.

        Returns:
            URIRef: The URI reference of the property added to the RDF graph.
        """
        prop_uri = namespace[prop.id]

        # Define the property as an OWL class inheriting from PropertyType
        graph.add((prop_uri, RDF.type, OWL.Thing))
        graph.add((prop_uri, RDFS.subClassOf, namespace.PropertyType))

        # Add attributes like id, code, description in English and Deutsch, property_label, data_type
        graph.add((prop_uri, RDFS.label, Literal(prop.id, lang="en")))
        graph.add((prop_uri, DC.identifier, Literal(prop.code)))
        descriptions = prop.description.split("//")
        if len(descriptions) > 1:
            graph.add((prop_uri, RDFS.comment, Literal(descriptions[0], lang="en")))
            graph.add((prop_uri, RDFS.comment, Literal(descriptions[1], lang="de")))
        else:
            graph.add((prop_uri, RDFS.comment, Literal(prop.description, lang="en")))
        graph.add(
            (prop_uri, namespace.propertyLabel, Literal(prop.property_label, lang="en"))
        )
        graph.add((prop_uri, namespace.dataType, Literal(prop.data_type.value)))
        if prop.data_type.value == "OBJECT":
            # entity_ref_uri = BAM[code_to_class_name(obj.object_code)]
            # graph.add((prop_uri, BAM.referenceTo, entity_ref_uri))
            object_code = code_to_class_name(prop.object_code, logger)
            if not object_code:
                logger.error(
                    f"Failed to identify the `object_code` for the property {prop.id}"
                )
                return prop_uri
            entity_ref_uri = namespace[object_code]

            # Create a restriction with referenceTo
            restriction = BNode()
            graph.add((restriction, RDF.type, OWL.Restriction))
            graph.add((restriction, OWL.onProperty, namespace["referenceTo"]))
            graph.add((restriction, OWL.someValuesFrom, entity_ref_uri))

            # Add the restriction as a subclass of the property
            graph.add((prop_uri, RDFS.subClassOf, restriction))
        return prop_uri

    # skos:prefLabel used for class names
    # skos:definition used for `description` (en, de)
    # dc:identifier used for `code`  # ! only defined for internal codes with $ symbol
    # parents defined from `code`
    # assigned properties can be Mandatory or Optional, can be PropertyType or ObjectType
    # ? For OBJECT TYPES
    # ? `generated_code_prefix`, `auto_generate_codes`?
    @no_type_check
    def model_to_rdf(
        self, namespace: "Namespace", graph: "Graph", logger: "BoundLoggerLazyProxy"
    ) -> None:
        """
        Convert the entity to RDF triples and add them to the graph. The function uses the
        `_add_properties_rdf` method to convert the properties assigned to the entity to RDF triples.

        Args:
            namespace (Namespace): The namespace to use for the RDF graph.
            graph (Graph): The RDF graph to which the entity is added.
            logger (BoundLoggerLazyProxy): The logger to log messages.
        """
        entity_uri = namespace[self.defs.id]

        # Define the entity as an OWL class inheriting from the specific namespace type
        graph.add((entity_uri, RDF.type, OWL.Thing))
        parent_classes = self.__class__.__bases__
        for parent_class in parent_classes:
            if issubclass(parent_class, BaseEntity) and parent_class != BaseEntity:
                # if parent_class.__name__ in [
                #     "ObjectType",
                #     "CollectionType",
                #     "DatasetType",
                # ]:
                #     # ! add here logic of subClassOf connecting with PROV-O or BFO
                #     # ! maybe via classes instead of ObjectType/CollectionType/DatasetType?
                #     # ! Example:
                #     # !     graph.add((entity_uri, RDFS.subClassOf, "http://www.w3.org/ns/prov#Entity"))
                #     continue
                parent_uri = namespace[parent_class.__name__]
                graph.add((entity_uri, RDFS.subClassOf, parent_uri))

        # Add attributes like id, code, description in English and Deutsch, property_label, data_type
        graph.add((entity_uri, RDFS.label, Literal(self.defs.id, lang="en")))
        graph.add((entity_uri, DC.identifier, Literal(self.defs.code)))
        descriptions = self.defs.description.split("//")
        if len(descriptions) > 1:
            graph.add((entity_uri, RDFS.comment, Literal(descriptions[0], lang="en")))
            graph.add((entity_uri, RDFS.comment, Literal(descriptions[1], lang="de")))
        else:
            graph.add(
                (entity_uri, RDFS.comment, Literal(self.defs.description, lang="en"))
            )
        # Adding properties relationships to the entities
        for assigned_prop in self._base_attrs:
            prop_uri = self._add_properties_rdf(namespace, graph, assigned_prop, logger)
            restriction = BNode()
            graph.add((restriction, RDF.type, OWL.Restriction))
            if assigned_prop.mandatory:
                graph.add(
                    (restriction, OWL.onProperty, namespace["hasMandatoryProperty"])
                )
            else:
                graph.add(
                    (restriction, OWL.onProperty, namespace["hasOptionalProperty"])
                )
            graph.add((restriction, OWL.someValuesFrom, prop_uri))

            # Add the restriction as a subclass of the entity
            graph.add((entity_uri, RDFS.subClassOf, restriction))

class ObjectType(BaseEntity):
    """
    Base class used to define object types. All object types must inherit from this class. The
    object types are defined in the module `bam_masterdata/object_types.py`.

    The `ObjectType` class contains a list of all `properties` defined for a `ObjectType`, for
    internally represent the model in other formats (e.g., JSON or Excel).

    Note this is also used for `CollectionType` and `DatasetType`, as they also contain a list of
    properties.
    """

    model_config = ConfigDict(
        ignored_types=(
            ObjectTypeDef,
            CollectionTypeDef,
            DatasetTypeDef,
            PropertyTypeAssignment,
        )
    )

    properties: list[PropertyTypeAssignment] = Field(
        default_factory=list,
        description="""
        List of properties assigned to an object type. This is useful for internal representation of the model.
        """,
    )

    datasets: list[str] = Field(
        default_factory=list,
        exclude=True,
        description="""
        List of file paths attached to this object as datasets. Useful for attaching data or plots directly to objects.
        """,
    )

    def __init__(self, **kwargs):
        super().__init__(**kwargs)

        # Initialize the properties list to store PropertyTypeAssignment instances
        self._properties = {}
        for key, prop in self._property_metadata.items():
            self._properties[key] = prop.data_type

    def _set_object_value(self, key, value):
        """
        Sets the value when the data type is OBJECT.
        """
        if isinstance(value, str):
            # Validate the path format: /{space}/{project}/{collection}/{object} or /{space}/{project}/{object}
            # If path is valid, store it as-is
            if not value.startswith("/"):
                raise ValueError(
                    f"Invalid OBJECT path format for '{key}': Path must start with '/', got '{value}'"
                )
            path_parts = value.strip("/").split("/")
            if len(path_parts) not in [3, 4]:
                raise ValueError(
                    f"Invalid OBJECT path format for '{key}': Expected '/<space>/<project>/<collection>/<object>' "
                    f"or '/<space>/<project>/<object>', got '{value}'"
                )
            # * We don't validate if the object exists here as it requires pybis connection
            # * That validation should be done when saving to openBIS
        elif isinstance(value, ObjectType):
            # Check if the object instance has a code
            if not hasattr(value, "code") or value.code is None:
                raise ValueError(
                    f"Object instance for '{key}' must have a 'code' attribute set to be used as a reference"
                )
        else:
            raise TypeError(
                f"Invalid type for OBJECT property '{key}': Expected str (path) or ObjectType instance, "
                f"got {type(value).__name__}"
            )
        return value

    def _validate_controlled_vocabulary(self, meta, key, value) -> None:
        """
        Validates the value of a CONTROLLEDVOCABULARY.
        """
        vocabulary_code = meta[key].vocabulary_code

        # Patch to handle institutional vocabularies
        if vocabulary_code in [
            "BAM_FLOOR",
            "BAM_HOUSE",
            "BAM_LOCATION",
            "BAM_LOCATION_COMPLETE",
            "BAM_OE",
            "BAM_ROOM",
            "PERSON_STATUS",
        ]:
            warnings.warn(
                f"The attribute '{key}' uses the institutional vocabulary '{vocabulary_code}'. "
                "This value will not be validated against internal vocabulary definitions.",
                UserWarning,
                stacklevel=3,
            )
            return None

        if not vocabulary_code:
            raise ValueError(
                f"Property '{key}' of type CONTROLLEDVOCABULARY must have a vocabulary_code defined."
            )
        vocab_paths = []
        for file in listdir_py_modules(DATAMODEL_DIR):
            if "vocabulary_types.py" in file or "vocabularies.py" in file:
                vocab_paths.append(file)
        if not vocab_paths:
            raise FileNotFoundError(
                f"No file 'vocabularies.py' was not found in the directory and sub-directories specified by {DATAMODEL_DIR}."
            )

        # Scan all vocabularies.py files
        vocabulary_class = None
        for vocab_path in vocab_paths:
            vocabulary_class = self.get_vocabulary_class(vocabulary_code, vocab_path)
            if vocabulary_class is not None:
                break
        if vocabulary_class is None:
            raise ValueError(
                f"No matching vocabulary class found for vocabulary_code '{vocabulary_code}'."
            )
        codes = [term.code for term in vocabulary_class.terms]
        if value not in codes:
            raise ValueError(
                f"{value} for {key} is not in the list of allowed terms for vocabulary."
            )

    def __setattr__(self, key, value):
        if not hasattr(self, "_property_metadata"):
            return object.__setattr__(self, key, value)

        if key in [
            "_property_metadata",
            "_properties",
            "code",
            "properties",
            "datasets",
        ]:
            super().__setattr__(key, value)
            return

        # key search in every nested class
        for base in type(self).__mro__:
            prop_meta = getattr(base, "get_property_metadata", None)
            if callable(prop_meta):
                meta = (
                    prop_meta(self)
                    if base is not type(self)
                    else self._property_metadata
                )
                if key in meta:
                    # Type check
                    expected_type = meta[key].data_type.pytype
                    if expected_type is datetime.datetime:
                        if isinstance(value, datetime.datetime):
                            try:
                                value = value.strftime(
                                    "%Y-%m-%d %H:%M:%S"
                                )  # create string
                                expected_type = str
                            except ValueError:
                                raise ValueError(
                                    f"Invalid datetime format for '{key}': Expected ISO format string, got '{value}'"
                                )
                        elif isinstance(value, str):
                            try:
                                datetime.datetime.fromisoformat(value)
                                expected_type = str
                            except ValueError:
                                raise ValueError(
                                    f"Invalid datetime format for '{key}': Expected ISO format string, got '{value}'"
                                )
                        else:
                            raise TypeError(
                                f"Invalid type for '{key}': Expected datetime or ISO format string, got {type(value).__name__}"
                            )
                    if expected_type and not isinstance(value, expected_type):
                        raise TypeError(
                            f"Invalid type for '{key}': Expected {expected_type.__name__}, got {type(value).__name__}"
                        )

                    # Get data type for additional checks
                    data_type = meta[key].data_type
                    # OBJECT check and attr assignment
                    if data_type == "OBJECT":
                        return object.__setattr__(
                            self, key, self._set_object_value(key, value)
                        )
                    # CONTROLLEDVOCABULARY check
                    if data_type == "CONTROLLEDVOCABULARY":
                        self._validate_controlled_vocabulary(meta, key, value)

                    # Setting attribute value after all checks
                    return object.__setattr__(self, key, value)

        raise KeyError(
            f"Key '{key}' not found in any property_metadata of {type(self).__name__} or its bases."
        )

    def get_vocabulary_class(
        self, vocabulary_code: str, vocab_path: str
    ) -> VocabularyType | None:
        """
        Get the class instance of the vocabulary type defined by `vocabulary_code` in the Python module
        specified by `vocab_path`.

        Args:
            vocabulary_code (str): Code of the vocabulary type to get.
            vocab_path (str): Path to the module containing the vocabulary type definitions.

        Returns:
            VocabularyType | None: The class of the vocabulary type if found, otherwise None.
        """
        module = import_module(vocab_path)
        vocabulary_class = None
        for _, obj in inspect.getmembers(module, inspect.isclass):
            if obj.__module__ != module.__name__:
                continue

            if obj.defs.code == vocabulary_code:
                vocabulary_class = obj()
                break

        return vocabulary_class

    @property
    def base_name(self) -> str:
        """
        Returns the entity name of the class as a string.
        """
        return "ObjectType"

    @model_validator(mode="after")
    @classmethod
    def model_validator_after_init(cls, data: Any) -> Any:
        """
        Validate the model after instantiation of the class.

        Args:
            data (Any): The data containing the fields values to validate.

        Returns:
            Any: The data with the validated fields.
        """
        # ordered parent -> child properties
        collected_properties = []
        for base in reversed(cls.__mro__):
            for _, attr_val in base.__dict__.items():
                if isinstance(attr_val, PropertyTypeAssignment):
                    collected_properties.append(attr_val)

        # Group by section preserving first appearance order
        grouped_sections = OrderedDict()
        for prop in collected_properties:
            section = prop.section or ""
            grouped_sections.setdefault(section, [])
            grouped_sections[section].append(prop)

        # Flatten grouped properties
        ordered_properties = []
        for props in grouped_sections.values():
            ordered_properties.extend(props)
        data.properties = ordered_properties

        return data

    @deprecated(
        "This method will soon be deprecated and will be removed in a future major release. "
        "The push to openbis and synchronization happens in `to_openbis_sync()` instead."
    )
    def to_openbis(self, logger: "BoundLoggerLazyProxy", openbis: "Openbis") -> None:
        def _assign_property(prop, entity, openbis) -> None:
            """
            Assign the property to the entity, adding the `vocabulary` parameter if the `vocabulary_code`
            is defined for the property. If the property does not exist in openBIS, create it before assigning to the entity.

            Args:
                prop (PropertyTypeAssignment): The property to assign.
                entity (Entity): The entity to assign the property to.
                openbis (Openbis): The openBIS instance.
            """
            # Handle special case for OBJECT data type to map into the legacy name
            if prop.data_type == "OBJECT":
                prop.data_type = DataType.SAMPLE

            # If property does not exist in openBIS, create it before assigning to the entity
            if not openbis.get_property_types(prop.code):
                # For CONTROLLEDVOCABULARY properties with a defined vocabulary_code, we need to create the property with the vocabulary assigned
                if prop.data_type == "CONTROLLEDVOCABULARY" and prop.vocabulary_code:
                    openbis.new_property_type(
                        code=prop.code,
                        label=prop.property_label,
                        description=prop.description,
                        dataType=prop.data_type.value,
                        vocabulary=prop.vocabulary_code,
                    ).save()
                else:
                    openbis.new_property_type(
                        code=prop.code,
                        label=prop.property_label,
                        description=prop.description,
                        dataType=prop.data_type.value,
                    ).save()

            # Assign the property to the entity, adding the `vocabulary` parameter if the `vocabulary_code` is defined for the property
            # TODO check what happens when dataType="SAMPLE" and how to use pyBIS for this
            if prop.vocabulary_code:
                entity.assign_property(
                    prop=prop.code,
                    section=prop.section,
                    mandatory=prop.mandatory,
                    showInEditView=prop.show_in_edit_views,
                    ordinal=prop.ordinal,
                )
            else:
                entity.assign_property(
                    prop=prop.code,
                    section=prop.section,
                    mandatory=prop.mandatory,
                    showInEditView=prop.show_in_edit_views,
                    ordinal=prop.ordinal,
                )

        # Get all existing entities from openBIS
        openbis_entities = OpenbisEntities(url=openbis.url).get_object_dict()

        if self.defs.code in openbis_entities:
            logger.info(f"Object type '{self.defs.code}' already exists in openBIS.")
            entity = openbis.get_object_type(self.defs.code)

            # Get properties from openBIS
            obis_properties = entity.get_property_assignments()
            obis_property_codes = [prop.code for prop in obis_properties]

            # Check for properties in self that are not in openBIS
            new_properties_added = False
            for prop in self.properties:
                if prop.code not in obis_property_codes:
                    logger.info(
                        f"Adding new property '{prop.code}' to object type '{self.defs.code}'."
                    )
                    new_properties_added = True
                    _assign_property(prop, entity, openbis)

            if not new_properties_added:
                logger.info(
                    f"No new properties added to object type '{self.defs.code}'."
                )

        else:
            logger.info(f"Creating new object type '{self.defs.code}' in openBIS.")
            entity = openbis.new_object_type(
                code=self.defs.code,
                description=self.defs.description,
                validationPlugin=self.defs.validation_script,
                generatedCodePrefix=self.defs.generated_code_prefix,
                autoGeneratedCode=self.defs.auto_generate_codes,
            )
            entity.save()  # we need to save this before assigning properties

            # Assign properties to the new entity
            for prop in self.properties:
                logger.info(
                    f"Adding new property '{prop.code}' to object type '{self.defs.code}'."
                )
                _assign_property(prop, entity, openbis)

        entity.save()
        return entity

    def dataset(self):
        # nur lesbar von außen
        return self.datasets

    def add_dataset(self, file):
        self.datasets.append(file)

    def _openbis_data_type(self, prop: PropertyTypeAssignment) -> str:
        """Translates bam-masterdata data types to their openBIS representation.

        Args:
            prop (PropertyTypeAssignment): The property to translate its data type.

        Returns:
            str: The value string as defined in `DataType`.
        """
        if prop.data_type in (DataType.OBJECT, DataType.SAMPLE):
            return DataType.SAMPLE.value
        return prop.data_type.value

    def _create_object_type(self, openbis: "Openbis", result: SyncResult) -> None:
        """
        Creates a new object type using the `new_object_type()` method from pyBIS.

        Args:
            openbis (Openbis): The openBIS instance to create the object type.
            result (SyncResult): The result metadata of the synchronization process.
        """
        obj_type = openbis.new_object_type(
            code=self.defs.code,
            description=self.defs.description,
            validationPlugin=self.defs.validation_script,
            generatedCodePrefix=self.defs.generated_code_prefix,
            autoGeneratedCode=self.defs.auto_generate_codes,
        )
        obj_type.save()

        result.created(
            target=SyncTarget.OBJECT_TYPE,
            code=self.defs.code,
        )

        # Synchronizing properties
        self._sync_property_assignments(
            obj_type=obj_type, openbis=openbis, result=result
        )

    def _sync_object_type_definition(
        self,
        obj_type: "SampleType",
        result: SyncResult,
    ) -> None:
        """
        Synchronizes an object type definition in the openBIS instance.

        Args:
            obj_type (SampleType): The object type to be synchronized.
            result (SyncResult): The result metadata of the synchronization process.
        """
        if obj_type.description != self.defs.description:
            old_value = obj_type.description
            obj_type.description = self.defs.description

            result.modified(
                target=SyncTarget.OBJECT_TYPE,
                code=self.defs.code,
                field="description",
                old_value=old_value,
                new_value=self.defs.description,
            )

        if obj_type.generatedCodePrefix != self.defs.generated_code_prefix:
            result.rejected(
                target=SyncTarget.OBJECT_TYPE,
                code=self.defs.code,
                field="generated_code_prefix",
                old_value=obj_type.generatedCodePrefix,
                new_value=self.defs.generated_code_prefix,
            )

    def _update_existing_property(
        self,
        prop: PropertyTypeAssignment,
        obj_type: "SampleType",
        openbis: "Openbis",
        result: SyncResult,
    ) -> None:
        """
        Updates an existing property type and its assignment metadata.

        Args:
            prop (PropertyTypeAssignment): The property type to be updated.
            obj_type (SampleType): The object type where the property is assigned to.
            openbis (Openbis): The openBIS instance where entities exists.
            result (SyncResult): The result metadata of the synchronization process.
        """
        if prop.code.startswith("$"):
            result.add(
                action=SyncAction.UNCHANGED,
                target=SyncTarget.PROPERTY_ASSIGNMENT,
                code=prop.code,
                parent_code=self.defs.code,
                field="type_and_assignment",
                old_value=None,
                new_value=None,
                message="Internal property types and assignments cannot be modified by the current user.",
            )
            return None

        # --- PropertyType fields ---
        property_type = openbis.get_property_type(prop.code)
        expected_data_type = self._openbis_data_type(prop)
        # Unsupported: data type changes
        if property_type.dataType != expected_data_type:
            result.rejected(
                target=SyncTarget.PROPERTY_TYPE,
                code=prop.code,
                field="data_type",
                old_value=property_type.dataType,
                new_value=expected_data_type,
            )
            return None

        # Unsupported: vocabulary changes
        if prop.data_type == DataType.CONTROLLEDVOCABULARY:
            current_vocabulary = getattr(property_type, "vocabulary", None)

            if current_vocabulary != prop.vocabulary_code:
                result.rejected(
                    target=SyncTarget.PROPERTY_TYPE,
                    code=prop.code,
                    field="vocabulary_code",
                    old_value=current_vocabulary,
                    new_value=prop.vocabulary_code,
                )
                return None

        property_type_modified = False

        # Supported: label
        if property_type.label != prop.property_label:
            old_value = property_type.label
            property_type.label = prop.property_label
            property_type_modified = True

            result.modified(
                target=SyncTarget.PROPERTY_TYPE,
                code=prop.code,
                field="property_label",
                old_value=old_value,
                new_value=prop.property_label,
            )

        # Supported: description
        if property_type.description != prop.description:
            old_value = property_type.description
            property_type.description = prop.description
            property_type_modified = True

            result.modified(
                target=SyncTarget.PROPERTY_TYPE,
                code=prop.code,
                field="description",
                old_value=old_value,
                new_value=prop.description,
            )

        if property_type_modified:
            property_type.save()

        # --- PropertyAssignment fields ---

        assignments = obj_type.get_property_assignments()
        assignment = next(
            assignment for assignment in assignments if assignment.code == prop.code
        )

        assignment_modified = False

        if assignment.section != prop.section:
            result.modified(
                target=SyncTarget.PROPERTY_ASSIGNMENT,
                code=prop.code,
                parent_code=self.defs.code,
                field="section",
                old_value=assignment.section,
                new_value=prop.section,
            )
            assignment_modified = True

        if assignment.mandatory != prop.mandatory:
            result.modified(
                target=SyncTarget.PROPERTY_ASSIGNMENT,
                code=prop.code,
                parent_code=self.defs.code,
                field="mandatory",
                old_value=assignment.mandatory,
                new_value=prop.mandatory,
            )
            assignment_modified = True

        if assignment.showInEditView != prop.show_in_edit_views:
            result.modified(
                target=SyncTarget.PROPERTY_ASSIGNMENT,
                code=prop.code,
                parent_code=self.defs.code,
                field="show_in_edit_views",
                old_value=assignment.showInEditView,
                new_value=prop.show_in_edit_views,
            )
            assignment_modified = True

        if assignment.ordinal != prop.ordinal:
            result.add(
                action=SyncAction.IGNORED,
                target=SyncTarget.PROPERTY_ASSIGNMENT,
                code=prop.code,
                parent_code=self.defs.code,
                message="Modification of the ordinal attribute in property assignments is not supported yet.",
            )

        if assignment_modified:
            obj_type.assign_property(
                prop=prop.code,
                section=prop.section,
                mandatory=prop.mandatory,
                showInEditView=prop.show_in_edit_views,
                ordinal=prop.ordinal,
            )

    def _create_property_assignment(
        self,
        prop: PropertyTypeAssignment,
        obj_type: "SampleType",
        openbis: "Openbis",
        result: SyncResult,
    ) -> None:
        """
        Creates (optionally, if property type does not exist already in openBIS) and assigns
        the property `prop` to the object type `obj_type`.

        Args:
            prop (PropertyTypeAssignment): The property type to be (optionally) created and assigned.
            obj_type (SampleType): The object type where the property is assigned to.
            openbis (Openbis): The openBIS instance where the entity definitions exists.
            result (SyncResult): The result metadata of the synchronization process.
        """
        try:
            _ = openbis.get_property_type(prop.code)
        except ValueError:
            kwargs = {
                "code": prop.code,
                "label": prop.property_label,
                "description": prop.description,
                "dataType": self._openbis_data_type(prop),
            }
            # For CONTROLLEDVOCABULARY properties with a defined vocabulary_code, we need to create the property with the vocabulary assigned
            if prop.data_type == DataType.CONTROLLEDVOCABULARY and prop.vocabulary_code:
                kwargs["vocabulary"] = prop.vocabulary_code

            openbis.new_property_type(**kwargs).save()
            result.created(
                target=SyncTarget.PROPERTY_TYPE,
                code=prop.code,
            )

        obj_type.assign_property(
            prop=prop.code,
            section=prop.section,
            mandatory=prop.mandatory,
            showInEditView=prop.show_in_edit_views,
            ordinal=prop.ordinal,
        )

        result.created(
            target=SyncTarget.PROPERTY_ASSIGNMENT,
            code=prop.code,
            parent_code=self.defs.code,
        )

    def _sync_property_assignments(
        self,
        obj_type: "SampleType",
        openbis: "Openbis",
        result: SyncResult,
    ) -> None:
        """
        Synchronizes the property assignemtns to the object type specified in `obj_type`.

        Args:
            obj_type (SampleType): The object type where properties are assigned and synchronized.
            openbis (Openbis): The openBIS instance where the defintions (both of object type and property type) exists.
            result (SyncResult): The result metadata of the synchronization process.
        """
        # openBIS property assigned codes
        openbis_assignments = obj_type.get_property_assignments()
        openbis_codes = set(openbis_assignments.df["code"])
        # BAM Masterdata property assigned codes
        model_props = {prop.code: prop for prop in self.properties}
        model_codes = set(model_props)

        # Comparison
        # Preserve the order defined in self.properties
        new_codes = [
            prop.code for prop in self.properties if prop.code not in openbis_codes
        ]

        existing_codes = [
            prop.code for prop in self.properties if prop.code in openbis_codes
        ]
        # Order here is less important because these are only reported as missing.
        missing_codes = openbis_codes - model_codes

        # Creating and assigning properties
        for code in new_codes:
            self._create_property_assignment(
                prop=model_props[code],
                obj_type=obj_type,
                openbis=openbis,
                result=result,
            )

        # Modifying existing assigned properties
        for code in existing_codes:
            self._update_existing_property(
                prop=model_props[code],
                obj_type=obj_type,
                openbis=openbis,
                result=result,
            )

        # Ignoring deletion of assigned properties
        for code in missing_codes:
            result.add(
                action=SyncAction.IGNORED,
                target=SyncTarget.PROPERTY_ASSIGNMENT,
                code=code,
                parent_code=self.defs.code,
                message="Deletion of property assignments is not implemented yet.",
            )

    def to_openbis_sync(self, openbis: "Openbis") -> SyncResult:
        """
        Synchronizes this ObjectType definition and its PropertyTypeAssignment with the `openbis` instance.

        Supported operations:
        - create new object types
        - add new assigned properties to existing object types
        - modify specific fields in object types or assigned properties

        Not supported operations:
        - deletion of object types
        - deletion of previously assigned properties
        - assigned properties code changes
        - assigned properties unit changes
        - assigned properties data type changes

        Args:
            logger (BoundLoggerLazyProxy): The logger to log messages.
            openbis (Openbis): The openBIS instance to synchronize this object type to.

        Returns:
            (SyncResult): The result of the synchronization process. Useful for structuring logging.
        """
        result = SyncResult()

        # Get all existing object types from openBIS
        openbis_object_types = OpenbisEntities(url=openbis).get_object_dict()

        # Create object type if missing in openBIS
        if self.defs.code not in openbis_object_types:
            self._create_object_type(openbis=openbis, result=result)
            return result

        obj_type = openbis.get_object_type(self.defs.code)

        # Otherwise, synchronize definition
        self._sync_object_type_definition(obj_type=obj_type, result=result)
        # Then synchronize properties
        self._sync_property_assignments(
            obj_type=obj_type, openbis=openbis, result=result
        )

        obj_type.save()

        return result