lamindb 1.0.4__py3-none-any.whl → 1.1.0__py3-none-any.whl

lamindb/models.py

@@ -65,6 +65,7 @@ if TYPE_CHECKING:
     from pyarrow.dataset import Dataset as PyArrowDataset
     from tiledbsoma import Collection as SOMACollection
     from tiledbsoma import Experiment as SOMAExperiment
+    from tiledbsoma import Measurement as SOMAMeasurement
     from upath import UPath
 
     from lamindb.core import LabelManager, MappedCollection, QuerySet, RecordList
@@ -152,9 +153,13 @@ def current_run() -> Run | None:
     if not _TRACKING_READY:
         _TRACKING_READY = _check_instance_setup()
     if _TRACKING_READY:
-        import lamindb.core
+        import lamindb
 
-        return lamindb.context.run
+        # also see get_run() in core._data
+        run = lamindb._tracked.get_current_tracked_run()
+        if run is None:
+            run = lamindb.context.run
+        return run
     else:
         return None
 
@@ -239,6 +244,7 @@ class CanCurate:
         mute: bool = False,
         organism: str | Record | None = None,
         source: Record | None = None,
+        strict_source: bool = False,
     ) -> InspectResult:
         """Inspect if values are mappable to a field.
 
@@ -252,6 +258,10 @@ class CanCurate:
             mute: Whether to mute logging.
             organism: An Organism name or record.
             source: A `bionty.Source` record that specifies the version to inspect against.
+            strict_source: Determines the validation behavior against records in the registry.
+                - If `False`, validation will include all records in the registry, ignoring the specified source.
+                - If `True`, validation will only include records in the registry  that are linked to the specified source.
+                Note: this parameter won't affect validation against bionty/public sources.
 
         See Also:
             :meth:`~lamindb.core.CanCurate.validate`
@@ -278,10 +288,11 @@ class CanCurate:
         mute: bool = False,
         organism: str | Record | None = None,
         source: Record | None = None,
+        strict_source: bool = False,
     ) -> np.ndarray:
         """Validate values against existing values of a string field.
 
-        Note this is strict validation, only asserts exact matches.
+        Note this is strict_source validation, only asserts exact matches.
 
         Args:
             values: Values that will be validated against the field.
@@ -291,6 +302,10 @@ class CanCurate:
             mute: Whether to mute logging.
             organism: An Organism name or record.
             source: A `bionty.Source` record that specifies the version to validate against.
+            strict_source: Determines the validation behavior against records in the registry.
+                - If `False`, validation will include all records in the registry, ignoring the specified source.
+                - If `True`, validation will only include records in the registry  that are linked to the specified source.
+                Note: this parameter won't affect validation against bionty/public sources.
 
         Returns:
             A vector of booleans indicating if an element is validated.
@@ -370,6 +385,7 @@ class CanCurate:
         synonyms_field: str = "synonyms",
         organism: str | Record | None = None,
         source: Record | None = None,
+        strict_source: bool = False,
     ) -> list[str] | dict[str, str]:
         """Maps input synonyms to standardized names.
 
@@ -392,6 +408,10 @@ class CanCurate:
             synonyms_field: A field containing the concatenated synonyms.
             organism: An Organism name or record.
             source: A `bionty.Source` record that specifies the version to validate against.
+            strict_source: Determines the validation behavior against records in the registry.
+                - If `False`, validation will include all records in the registry, ignoring the specified source.
+                - If `True`, validation will only include records in the registry  that are linked to the specified source.
+                Note: this parameter won't affect validation against bionty/public sources.
 
         Returns:
             If `return_mapper` is `False`: a list of standardized names. Otherwise,
@@ -1187,7 +1207,7 @@ class Transform(Record, IsVersioned):
 
         Create a transform for a pipeline:
 
-        >>> transform = ln.Transform(name="Cell Ranger", version="7.2.0", type="pipeline").save()
+        >>> transform = ln.Transform(key="Cell Ranger", version="7.2.0", type="pipeline").save()
 
         Create a transform from a notebook:
 
@@ -1230,7 +1250,11 @@ class Transform(Record, IsVersioned):
     .. versionchanged:: 0.75
        The `source_code` field is no longer an artifact, but a text field.
     """
-    hash: str | None = CharField(max_length=HASH_LENGTH, db_index=True, null=True)
+    # we have a unique constraint here but not on artifact because on artifact, we haven't yet
+    # settled how we model the same artifact in different storage locations
+    hash: str | None = CharField(
+        max_length=HASH_LENGTH, db_index=True, null=True, unique=True
+    )
     """Hash of the source code."""
     reference: str | None = CharField(max_length=255, db_index=True, null=True)
     """Reference for the transform, e.g., a URL."""
@@ -1340,7 +1364,7 @@ class Param(Record, CanCurate, TracksRun, TracksUpdates):
     _name_field: str = "name"
 
     name: str = CharField(max_length=100, db_index=True)
-    dtype: str = CharField(max_length=64, db_index=True)
+    dtype: str | None = CharField(db_index=True, null=True)
     """Data type ("num", "cat", "int", "float", "bool", "datetime").
 
     For categorical types, can define from which registry values are
@@ -1353,7 +1377,7 @@ class Param(Record, CanCurate, TracksRun, TracksUpdates):
     """
     records: Param
     """Records of this type."""
-    is_type: bool = BooleanField(default=None, db_index=True, null=True)
+    is_type: bool = BooleanField(default=False, db_index=True, null=True)
     """Distinguish types from instances of the type."""
     _expect_many: bool = models.BooleanField(default=False, db_default=False)
     """Indicates whether values for this param are expected to occur a single or multiple times for an artifact/run (default `False`).
@@ -1369,6 +1393,28 @@ class Param(Record, CanCurate, TracksRun, TracksUpdates):
     values: ParamValue
     """Values for this parameter."""
 
+    def __init__(self, *args, **kwargs):
+        from ._feature import process_init_feature_param
+        from .errors import ValidationError
+
+        if len(args) == len(self._meta.concrete_fields):
+            super().__init__(*args, **kwargs)
+            return None
+
+        dtype = kwargs.get("dtype", None)
+        kwargs = process_init_feature_param(args, kwargs, is_param=True)
+        super().__init__(*args, **kwargs)
+        dtype_str = kwargs.pop("dtype", None)
+        if not self._state.adding:
+            if not (
+                self.dtype.startswith("cat")
+                if dtype == "cat"
+                else self.dtype == dtype_str
+            ):
+                raise ValidationError(
+                    f"Feature {self.name} already exists with dtype {self.dtype}, you passed {dtype_str}"
+                )
+
 
 # FeatureValue behaves in many ways like a link in a LinkORM
 # in particular, we don't want a _public field on it
@@ -1460,8 +1506,8 @@ class Run(Record):
 
         Create a run record:
 
-        >>> ln.Transform(name="Cell Ranger", version="7.2.0", type="pipeline").save()
-        >>> transform = ln.Transform.get(name="Cell Ranger", version="7.2.0")
+        >>> ln.Transform(key="Cell Ranger", version="7.2.0", type="pipeline").save()
+        >>> transform = ln.Transform.get(key="Cell Ranger", version="7.2.0")
         >>> run = ln.Run(transform)
 
         Create a global run context for a custom transform:
@@ -1679,7 +1725,7 @@ class ULabel(Record, HasParents, CanCurate, TracksRun, TracksUpdates):
     )
     """A universal random id, valid across DB instances."""
     name: str = CharField(max_length=150, db_index=True)
-    """Name or title of ulabel (`unique=True`)."""
+    """Name or title of ulabel."""
     type: ULabel | None = ForeignKey("self", PROTECT, null=True, related_name="records")
     """Type of ulabel, e.g., `"donor"`, `"split"`, etc.
 
@@ -1687,7 +1733,7 @@ class ULabel(Record, HasParents, CanCurate, TracksRun, TracksUpdates):
     """
     records: ULabel
     """Records of this type."""
-    is_type: bool = BooleanField(default=None, db_index=True, null=True)
+    is_type: bool = BooleanField(default=False, db_index=True, null=True)
     """Distinguish types from instances of the type.
 
     For example, a ulabel "Project" would be a type, and the actual projects "Project 1", "Project 2", would be records of that `type`.
@@ -1727,6 +1773,8 @@ class ULabel(Record, HasParents, CanCurate, TracksRun, TracksUpdates):
     def __init__(
         self,
         name: str,
+        type: ULabel | None = None,
+        is_type: bool = False,
         description: str | None = None,
         reference: str | None = None,
         reference_type: str | None = None,
@@ -1765,12 +1813,15 @@ class Feature(Record, CanCurate, TracksRun, TracksUpdates):
 
     Args:
         name: `str` Name of the feature, typically.  column name.
-        dtype: `FeatureDtype | Registry | list[Registry]` See :class:`~lamindb.base.types.FeatureDtype`.
+        dtype: `FeatureDtype | Registry | list[Registry] | FieldAttr` See :class:`~lamindb.base.types.FeatureDtype`.
             For categorical types, can define from which registry values are
             sampled, e.g., `ULabel` or `[ULabel, bionty.CellType]`.
         unit: `str | None = None` Unit of measure, ideally SI (`"m"`, `"s"`, `"kg"`, etc.) or `"normalized"` etc.
         description: `str | None = None` A description.
         synonyms: `str | None = None` Bar-separated synonyms.
+        nullable: `bool = True` Whether the feature can have null-like values (`None`, `pd.NA`, `NaN`, etc.), see :attr:`~lamindb.Feature.nullable`.
+        default_value: `Any | None = None` Default value for the feature.
+        cat_filters: `dict[str, str] | None = None` Subset a registry by additional filters to define valid categories.
 
     Note:
 
@@ -1835,6 +1886,10 @@ class Feature(Record, CanCurate, TracksRun, TracksUpdates):
         abstract = False
 
     _name_field: str = "name"
+    _aux_fields: dict[str, tuple[str, type]] = {
+        "0": ("default_value", bool),
+        "1": ("nullable", bool),
+    }
 
     id: int = models.AutoField(primary_key=True)
     """Internal id, valid only in one DB instance."""
@@ -1843,8 +1898,8 @@ class Feature(Record, CanCurate, TracksRun, TracksUpdates):
     )
     """Universal id, valid across DB instances."""
     name: str = CharField(max_length=150, db_index=True, unique=True)
-    """Name of feature (`unique=True`)."""
-    dtype: FeatureDtype = CharField(db_index=True)
+    """Name of feature (hard unique constraint `unique=True`)."""
+    dtype: FeatureDtype | None = CharField(db_index=True, null=True)
     """Data type (:class:`~lamindb.base.types.FeatureDtype`).
 
     For categorical types, can define from which registry values are
@@ -1860,7 +1915,7 @@ class Feature(Record, CanCurate, TracksRun, TracksUpdates):
     """
     records: Feature
     """Records of this type."""
-    is_type: bool = BooleanField(default=None, db_index=True, null=True)
+    is_type: bool = BooleanField(default=False, db_index=True, null=True)
     """Distinguish types from instances of the type."""
     unit: str | None = CharField(max_length=30, db_index=True, null=True)
     """Unit of measure, ideally SI (`m`, `s`, `kg`, etc.) or 'normalized' etc. (optional)."""
@@ -1922,10 +1977,15 @@ class Feature(Record, CanCurate, TracksRun, TracksUpdates):
     def __init__(
         self,
         name: str,
-        dtype: FeatureDtype | Registry | list[Registry],
-        unit: str | None,
-        description: str | None,
-        synonyms: str | None,
+        dtype: FeatureDtype | Registry | list[Registry] | FieldAttr,
+        type: Feature | None = None,
+        is_type: bool = False,
+        unit: str | None = None,
+        description: str | None = None,
+        synonyms: str | None = None,
+        nullable: bool = True,
+        default_value: str | None = None,
+        cat_filters: dict[str, str] | None = None,
     ): ...
 
     @overload
@@ -1950,6 +2010,58 @@ class Feature(Record, CanCurate, TracksRun, TracksUpdates):
         """Save."""
         pass
 
+    @property
+    def default_value(self) -> Any:
+        """A default value that overwrites missing values (default `None`).
+
+        This takes effect when you call `Curator.standardize()`.
+        """
+        if self._aux is not None and "af" in self._aux and "0" in self._aux["af"]:
+            return self._aux["af"]["0"]
+        else:
+            return None
+
+    @default_value.setter
+    def default_value(self, value: bool) -> None:
+        if self._aux is None:
+            self._aux = {}
+        if "af" not in self._aux:
+            self._aux["af"] = {}
+        self._aux["af"]["0"] = value
+
+    @property
+    def nullable(self) -> bool:
+        """Indicates whether the feature can have nullable values (default `True`).
+
+        Example::
+
+            import lamindb as ln
+            import pandas as pd
+
+            disease = ln.Feature(name="disease", dtype=ln.ULabel, nullable=False).save()
+            schema = ln.Schema(features=[disease]).save()
+            dataset = {"disease": pd.Categorical([pd.NA, "asthma"])}
+            df = pd.DataFrame(dataset)
+            curator = ln.curators.DataFrameCurator(df, schema)
+            try:
+                curator.validate()
+            except ln.errors.ValidationError as e:
+                assert str(e).startswith("non-nullable series 'disease' contains null values")
+
+        """
+        if self._aux is not None and "af" in self._aux and "1" in self._aux["af"]:
+            return self._aux["af"]["1"]
+        else:
+            return True
+
+    @nullable.setter
+    def nullable(self, value: bool) -> None:
+        if self._aux is None:
+            self._aux = {}
+        if "af" not in self._aux:
+            self._aux["af"] = {}
+        self._aux["af"]["1"] = value
+
 
 class FeatureValue(Record, TracksRun):
     """Non-categorical features values.
@@ -2000,9 +2112,10 @@ class FeatureValue(Record, TracksRun):
         # Simple types: int, float, str, bool
         if isinstance(value, (int, float, str, bool)):
             try:
-                return cls.objects.create(
-                    feature=feature, value=value, hash=None
-                ), False
+                return (
+                    cls.objects.create(feature=feature, value=value, hash=None),
+                    False,
+                )
             except IntegrityError:
                 return cls.objects.get(feature=feature, value=value), True
 
@@ -2010,15 +2123,16 @@ class FeatureValue(Record, TracksRun):
         else:
             hash = hash_dict(value)
             try:
-                return cls.objects.create(
-                    feature=feature, value=value, hash=hash
-                ), False
+                return (
+                    cls.objects.create(feature=feature, value=value, hash=hash),
+                    False,
+                )
             except IntegrityError:
                 return cls.objects.get(feature=feature, hash=hash), True
 
 
 class Schema(Record, CanCurate, TracksRun):
-    """Feature sets (dataset schemas).
+    """Schemas / feature sets.
 
     Stores references to dataset schemas: these are the sets of columns in a dataset
     that correspond to :class:`~lamindb.Feature`, :class:`~bionty.Gene`, :class:`~bionty.Protein` or other
@@ -2036,23 +2150,37 @@ class Schema(Record, CanCurate, TracksRun):
         These reasons do not hold for label sets. Hence, LaminDB does not model label sets.
 
     Args:
-        features: `Iterable[Record]` An iterable of :class:`~lamindb.Feature`
+        features: `Iterable[Record] | None = None` An iterable of :class:`~lamindb.Feature`
             records to hash, e.g., `[Feature(...), Feature(...)]`. Is turned into
             a set upon instantiation. If you'd like to pass values, use
             :meth:`~lamindb.Schema.from_values` or
             :meth:`~lamindb.Schema.from_df`.
+        components: `dict[str, Schema] | None = None` A dictionary mapping component names to
+            their corresponding :class:`~lamindb.Schema` objects for composite schemas.
+        name: `str | None = None` A name.
+        description: `str | None = None` A description.
         dtype: `str | None = None` The simple type. Defaults to
             `None` for sets of :class:`~lamindb.Feature` records.
             Otherwise defaults to `"num"` (e.g., for sets of :class:`~bionty.Gene`).
-        name: `str | None = None` A name.
+        itype: `str | None = None` The schema identifier type (e.g. :class:`~lamindb.Feature`, :class:`~bionty.Gene`, ...).
+        type: `Schema | None = None` A type.
+        is_type: `bool = False` Distinguish types from instances of the type.
+        otype: `str | None = None` An object type to define the structure of a composite schema.
+        minimal_set: `bool = True` Whether the schema contains a minimal set of linked features.
+        ordered_set: `bool = False` Whether features are required to be ordered.
+        maximal_set: `bool = False` If `True`, no additional features are allowed.
+        slot: `str | None = None` The slot name when this schema is used as a component in a
+            composite schema.
+        coerce_dtype: `bool = False` When True, attempts to coerce values to the specified dtype
+            during validation, see :attr:`~lamindb.Schema.coerce_dtype`.
 
     Note:
 
-        A feature set can be identified by the `hash` its feature uids.
+        A feature set can be identified by the `hash` of its feature uids.
         It's stored in the `.hash` field.
 
-        A `slot` provides a string key to access feature sets.
-        It's typically the accessor within the registered data object, here `pd.DataFrame.columns`.
+        A `slot` provides a string key to access feature sets. For instance, for the schema of an
+        `AnnData` object, it would be `'obs'` for `adata.obs`.
 
     See Also:
         :meth:`~lamindb.Schema.from_values`
@@ -2062,24 +2190,20 @@ class Schema(Record, CanCurate, TracksRun):
 
     Examples:
 
-        Create a feature set / schema from df with types:
+        Create a schema (feature set) from df with types:
 
         >>> df = pd.DataFrame({"feat1": [1, 2], "feat2": [3.1, 4.2], "feat3": ["cond1", "cond2"]})
-        >>> feature_set = ln.FeatureSet.from_df(df)
+        >>> schema = ln.Schema.from_df(df)
 
-        Create a feature set / schema from features:
+        Create a schema (feature set) from features:
 
         >>> features = [ln.Feature(name=feat, dtype="float").save() for feat in ["feat1", "feat2"]]
-        >>> feature_set = ln.FeatureSet(features)
+        >>> schema = ln.Schema(features)
 
-        Create a feature set / schema from feature values:
+        Create a schema (feature set) from identifier values:
 
         >>> import bionty as bt
-        >>> feature_set = ln.FeatureSet.from_values(adata.var["ensemble_id"], Gene.ensembl_gene_id, organism="mouse").save()
-
-        Link a feature set to an artifact:
-
-        >>> artifact.features.add_feature_set(feature_set, slot="var")
+        >>> schema = ln.Schema.from_values(adata.var["ensemble_id"], Gene.ensembl_gene_id, organism="mouse").save()
 
     """
 
@@ -2087,6 +2211,7 @@ class Schema(Record, CanCurate, TracksRun):
         abstract = False
 
     _name_field: str = "name"
+    _aux_fields: dict[str, tuple[str, type]] = {"0": ("coerce_dtype", bool)}
 
     id: int = models.AutoField(primary_key=True)
     """Internal id, valid only in one DB instance."""
@@ -2098,89 +2223,116 @@ class Schema(Record, CanCurate, TracksRun):
     """A description."""
     n = IntegerField()
     """Number of features in the set."""
-    dtype: str | None = CharField(max_length=64, null=True)
+    dtype: str | None = CharField(max_length=64, null=True, editable=False)
     """Data type, e.g., "num", "float", "int". Is `None` for :class:`~lamindb.Feature`.
 
     For :class:`~lamindb.Feature`, types are expected to be heterogeneous and defined on a per-feature level.
     """
-    # _itype: ContentType = models.ForeignKey(ContentType, on_delete=models.CASCADE)
-    # ""Index of the registry that stores the feature identifiers, e.g., `Feature` or `Gene`."""
-    itype: str | None = CharField(max_length=120, db_index=True, null=True)
+    itype: str | None = CharField(
+        max_length=120, db_index=True, null=True, editable=False
+    )
     """A registry that stores feature identifiers used in this schema, e.g., `'Feature'` or `'bionty.Gene'`.
 
     Depending on the registry, `.members` stores, e.g., `Feature` or `bionty.Gene` records.
 
     .. versionchanged:: 1.0.0
-        Was called `itype` before.
+        Was called `registry` before.
     """
-    type: Feature | None = ForeignKey(
-        "self", PROTECT, null=True, related_name="records"
-    )
-    """Type of feature set (e.g., 'ExpressionPanel', 'ProteinPanel', 'Multimodal', 'Metadata', 'Embedding').
+    type: Schema | None = ForeignKey("self", PROTECT, null=True, related_name="records")
+    """Type of schema.
+
+    Allows to group schemas by type, e.g., all meassurements evaluating gene expression vs. protein expression vs. multi modal.
 
-    Allows to group feature sets by type, e.g., all meassurements evaluating gene expression vs. protein expression vs. multi modal.
+    You can define types via `ln.Schema(name="ProteinPanel", is_type=True)`.
+
+    Here are a few more examples for type names: `'ExpressionPanel'`, `'ProteinPanel'`, `'Multimodal'`, `'Metadata'`, `'Embedding'`.
     """
-    records: Feature
+    records: Schema
     """Records of this type."""
-    is_type: bool = BooleanField(default=None, db_index=True, null=True)
+    is_type: bool = BooleanField(default=False, db_index=True, null=True)
     """Distinguish types from instances of the type."""
     otype: str | None = CharField(max_length=64, db_index=True, null=True)
     """Default Python object type, e.g., DataFrame, AnnData."""
-    hash: str | None = CharField(max_length=HASH_LENGTH, db_index=True, null=True)
+    hash: str | None = CharField(
+        max_length=HASH_LENGTH, db_index=True, null=True, editable=False
+    )
     """A hash of the set of feature identifiers.
 
     For a composite schema, the hash of hashes.
     """
-    minimal_set: bool = BooleanField(default=True, db_index=True)
+    minimal_set: bool = BooleanField(default=True, db_index=True, editable=False)
     """Whether the schema contains a minimal set of linked features (default `True`).
 
     If `False`, no features are linked to this schema.
 
     If `True`, features are linked and considered as a minimally required set in validation.
     """
-    ordered_set: bool = BooleanField(default=False, db_index=True)
-    """Whether the linked features are ordered (default `False`)."""
-    maximal_set: bool = BooleanField(default=False, db_index=True)
+    ordered_set: bool = BooleanField(default=False, db_index=True, editable=False)
+    """Whether features are required to be ordered (default `False`)."""
+    maximal_set: bool = BooleanField(default=False, db_index=True, editable=False)
     """If `False`, additional features are allowed (default `False`).
 
     If `True`, the the minimal set is a maximal set and no additional features are allowed.
     """
-    composite: Schema | None = ForeignKey(
-        "self", PROTECT, related_name="components", default=None, null=True
-    )
-    """The composite schema that contains this schema as a component.
-
-    The composite schema composes multiple simpler schemas into one object.
-
-    For example, an AnnData composes multiple schemas: `var[DataFrameT]`, `obs[DataFrame]`, `obsm[Array]`, `uns[dict]`, etc.
-    """
-    slot: str | None = CharField(max_length=100, db_index=True, null=True)
-    """The slot in which the schema is stored in the composite schema."""
-    validated_by: Schema | None = ForeignKey(
-        "self", PROTECT, related_name="validated_schemas", default=None, null=True
+    components: Schema = ManyToManyField(
+        "self", through="SchemaComponent", symmetrical=False, related_name="composites"
     )
-    """The schema that validated this schema during curation.
+    """Components of this schema."""
+    composites: Schema
+    """The composite schemas that contains this schema as a component.
 
-    When performing validation, the schema that enforced validation is often less concrete than what is validated.
-
-    For instance, the set of measured features might be a superset of the minimally required set of features.
-
-    Often, the curating schema does not specficy any concrete features at all
+    For example, an `AnnData` composes multiple schemas: `var[DataFrameT]`, `obs[DataFrame]`, `obsm[Array]`, `uns[dict]`, etc.
     """
     features: Feature
     """The features contained in the schema."""
     params: Param
     """The params contained in the schema."""
     artifacts: Artifact
-    """The artifacts that observe this schema."""
+    """The artifacts that measure a feature set that matches this schema."""
+    validated_artifacts: Artifact
+    """The artifacts that were validated against this schema with a :class:`~lamindb.curators.Curator`."""
+    projects: Project
+    """Associated projects."""
     _curation: dict[str, Any] = JSONField(default=None, db_default=None, null=True)
+    # lamindb v2
+    # _itype: ContentType = models.ForeignKey(ContentType, on_delete=models.CASCADE)
+    # ""Index of the registry that stores the feature identifiers, e.g., `Feature` or `Gene`."""
+    # -- the following two fields are dynamically removed from the API for now
+    validated_by: Schema | None = ForeignKey(
+        "self", PROTECT, related_name="validated_schemas", default=None, null=True
+    )
+    # """The schema that validated this schema during curation.
+
+    # When performing validation, the schema that enforced validation is often less concrete than what is validated.
+
+    # For instance, the set of measured features might be a superset of the minimally required set of features.
+    # """
+    # validated_schemas: Schema
+    # """The schemas that were validated against this schema with a :class:`~lamindb.curators.Curator`."""
+    composite: Schema | None = ForeignKey(
+        "self", PROTECT, related_name="+", default=None, null=True
+    )
+    # The legacy foreign key
+    slot: str | None = CharField(max_length=100, db_index=True, null=True)
+    # The legacy slot
 
     @overload
     def __init__(
         self,
-        features: Iterable[Record],
-        dtype: str | None = None,
+        features: Iterable[Record] | None = None,
+        components: dict[str, Schema] | None = None,
         name: str | None = None,
+        description: str | None = None,
+        dtype: str | None = None,
+        itype: str | Registry | FieldAttr | None = None,
+        type: Schema | None = None,
+        is_type: bool = False,
+        otype: str | None = None,
+        minimal_set: bool = True,
+        ordered_set: bool = False,
+        maximal_set: bool = False,
+        slot: str | None = None,
+        coerce_dtype: bool = False,
     ): ...
 
     @overload
@@ -2256,6 +2408,25 @@ class Schema(Record, CanCurate, TracksRun):
         """A queryset for the individual records of the set."""
         pass
 
+    @property
+    def coerce_dtype(self) -> bool:
+        """Whether dtypes should be coerced during validation.
+
+        For example, a `objects`-dtyped pandas column can be coerced to `categorical` and would pass validation if this is true.
+        """
+        if self._aux is not None and "af" in self._aux and "0" in self._aux["af"]:
+            return self._aux["af"]["0"]
+        else:
+            return False
+
+    @coerce_dtype.setter
+    def coerce_dtype(self, value: bool) -> None:
+        if self._aux is None:
+            self._aux = {}
+        if "af" not in self._aux:
+            self._aux["af"] = {}
+        self._aux["af"]["0"] = value
+
     @property
     @deprecated("itype")
     def registry(self) -> str:
@@ -2265,8 +2436,23 @@ class Schema(Record, CanCurate, TracksRun):
     def registry(self, value) -> None:
         self.itype = value
 
+    def describe(self, return_str=False) -> None | str:
+        """Describe schema."""
+        message = str(self) + "\ncomponents:"
+        for component in self.components.all():
+            message += "\n    " + str(component)
+        if return_str:
+            return message
+        else:
+            print(message)
+            return None
+
+    def _get_component(self, slot: str) -> Schema:
+        return self.components.get(links_component__slot=slot)
+
 
 class Artifact(Record, IsVersioned, TracksRun, TracksUpdates):
+    # Note that this docstring has to be consistent with Curator.save_artifact()
     """Datasets & models stored as files, folders, or arrays.
 
     Artifacts manage data in local or remote storage.
@@ -2276,10 +2462,10 @@ class Artifact(Record, IsVersioned, TracksRun, TracksUpdates):
 
     Args:
         data: `UPathStr` A path to a local or remote folder or file.
-        type: `Literal["dataset", "model"] | None = None` The artifact type.
-        key: `str | None = None` A path-like key to reference artifact in default storage, e.g., `"myfolder/myfile.fcs"`. Artifacts with the same key form a revision family.
+        kind: `Literal["dataset", "model"] | None = None` Distinguish models from datasets from other files & folders.
+        key: `str | None = None` A path-like key to reference artifact in default storage, e.g., `"myfolder/myfile.fcs"`. Artifacts with the same key form a version family.
         description: `str | None = None` A description.
-        revises: `Artifact | None = None` Previous version of the artifact. Triggers a revision.
+        revises: `Artifact | None = None` Previous version of the artifact. Is an alternative way to passing `key` to trigger a new version.
         run: `Run | None = None` The run that creates the artifact.
 
     .. dropdown:: Typical storage formats & their API accessors
@@ -2313,26 +2499,28 @@ class Artifact(Record, IsVersioned, TracksRun, TracksUpdates):
 
     Examples:
 
-        Create an artifact from a file path and pass `description`:
+        Create an artifact by passing `key`:
+
+        >>> artifact = ln.Artifact("./my_file.parquet", key="example_datasets/my_file.parquet").save()
+        >>> artifact = ln.Artifact("./my_folder", key="project1/my_folder").save()
 
-        >>> artifact = ln.Artifact("s3://my_bucket/my_folder/my_file.csv", description="My file")
-        >>> artifact = ln.Artifact("./my_local_file.jpg", description="My image")
+        Calling `.save()` uploads the file to the default storage location of your lamindb instance.
+        (If it's a local instance, the "upload" is a mere copy operation.)
 
-        You can also pass `key` to create a virtual filepath hierarchy:
+        If your artifact is already in the cloud, lamindb auto-populates the `key` field based on the S3 key and there is no upload:
 
-        >>> artifact = ln.Artifact("./my_local_file.jpg", key="example_datasets/dataset1.jpg")
+        >>> artifact = ln.Artifact("s3://my_bucket/my_folder/my_file.csv").save()
 
-        What works for files also works for folders:
+        You can make a new version of the artifact with `key = "example_datasets/my_file.parquet"`
 
-        >>> artifact = ln.Artifact("s3://my_bucket/my_folder", description="My folder")
-        >>> artifact = ln.Artifact("./my_local_folder", description="My local folder")
-        >>> artifact = ln.Artifact("./my_local_folder", key="project1/my_target_folder")
+        >>> artifact_v2 = ln.Artifact("./my_file.parquet", key="example_datasets/my_file.parquet").save()
+        >>> artifact_v2.versions.df()  # see all versions
 
         .. dropdown:: Why does the API look this way?
 
             It's inspired by APIs building on AWS S3.
 
-            Both boto3 and quilt select a bucket (akin to default storage in LaminDB) and define a target path through a `key` argument.
+            Both boto3 and quilt select a bucket (a storage location in LaminDB) and define a target path through a `key` argument.
 
             In `boto3 <https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/s3/bucket/upload_file.html>`__::
 
@@ -2349,16 +2537,18 @@ class Artifact(Record, IsVersioned, TracksRun, TracksUpdates):
                 bucket = quilt3.Bucket('mybucket')
                 bucket.put_file('hello.txt', '/tmp/hello.txt')
 
+        Sometimes you want to avoid mapping the artifact into a file hierarchy, and you can then _just_ populate `description` instead:
 
-        Make a new version of an artifact:
+        >>> artifact = ln.Artifact("s3://my_bucket/my_folder", description="My folder").save()
+        >>> artifact = ln.Artifact("./my_local_folder", description="My local folder").save()
 
-        >>> artifact = ln.Artifact.from_df(df, key="example_datasets/dataset1.parquet").save()
-        >>> artifact_v2 = ln.Artifact(df_updated, key="example_datasets/dataset1.parquet").save()
+        Because you can then not use `key`-based versioning you have to pass `revises` to make a new artifact version:
 
-        Alternatively, if you don't want to provide a value for `key`, you can use `revises`:
+        >>> artifact_v2 = ln.Artifact("./my_file.parquet", revises=old_artifact).save()
 
-        >>> artifact = ln.Artifact.from_df(df, description="My dataframe").save()
-        >>> artifact_v2 = ln.Artifact(df_updated, revises=artifact).save()
+        If an artifact with the exact same hash already exists, `Artifact()` returns the existing artifact. In concurrent workloads where
+        the same artifact is created multiple times, `Artifact()` doesn't yet return the existing artifact but creates a new one; `.save()` however
+        detects the duplication and will return the existing artifact.
 
     """
 
@@ -2455,9 +2645,11 @@ class Artifact(Record, IsVersioned, TracksRun, TracksUpdates):
     """
     description: str | None = CharField(db_index=True, null=True)
     """A description."""
-    storage: Storage = ForeignKey(Storage, PROTECT, related_name="artifacts")
+    storage: Storage = ForeignKey(
+        Storage, PROTECT, related_name="artifacts", editable=False
+    )
     """Storage location, e.g. an S3 or GCP bucket or a local directory."""
-    suffix: str = CharField(max_length=30, db_index=True)
+    suffix: str = CharField(max_length=30, db_index=True, editable=False)
     # Initially, we thought about having this be nullable to indicate folders
     # But, for instance, .zarr is stored in a folder that ends with a .zarr suffix
     """Path suffix or empty string if no canonical suffix exists.
@@ -2470,19 +2662,27 @@ class Artifact(Record, IsVersioned, TracksRun, TracksUpdates):
         null=True,
     )
     """:class:`~lamindb.base.types.ArtifactKind` (default `None`)."""
-    otype: str | None = CharField(max_length=64, db_index=True, null=True)
+    otype: str | None = CharField(
+        max_length=64, db_index=True, null=True, editable=False
+    )
     """Default Python object type, e.g., DataFrame, AnnData."""
-    size: int | None = BigIntegerField(null=True, db_index=True, default=None)
+    size: int | None = BigIntegerField(
+        null=True, db_index=True, default=None, editable=False
+    )
     """Size in bytes.
 
     Examples: 1KB is 1e3 bytes, 1MB is 1e6, 1GB is 1e9, 1TB is 1e12 etc.
     """
-    hash: str | None = CharField(max_length=HASH_LENGTH, db_index=True, null=True)
+    hash: str | None = CharField(
+        max_length=HASH_LENGTH, db_index=True, null=True, unique=True, editable=False
+    )
     """Hash or pseudo-hash of artifact content.
 
     Useful to ascertain integrity and avoid duplication.
     """
-    n_files: int | None = BigIntegerField(null=True, db_index=True, default=None)
+    n_files: int | None = BigIntegerField(
+        null=True, db_index=True, default=None, editable=False
+    )
     """Number of files for folder-like artifacts, `None` for file-like artifacts.
 
     Note that some arrays are also stored as folders, e.g., `.zarr` or `.tiledbsoma`.
@@ -2490,19 +2690,28 @@ class Artifact(Record, IsVersioned, TracksRun, TracksUpdates):
     .. versionchanged:: 1.0
         Renamed from `n_objects` to `n_files`.
     """
-    n_observations: int | None = BigIntegerField(null=True, db_index=True, default=None)
+    n_observations: int | None = BigIntegerField(
+        null=True, db_index=True, default=None, editable=False
+    )
     """Number of observations.
 
     Typically, this denotes the first array dimension.
     """
-    _hash_type: str | None = CharField(max_length=30, db_index=True, null=True)
+    _hash_type: str | None = CharField(
+        max_length=30, db_index=True, null=True, editable=False
+    )
     """Type of hash."""
     ulabels: ULabel = models.ManyToManyField(
         ULabel, through="ArtifactULabel", related_name="artifacts"
     )
     """The ulabels measured in the artifact (:class:`~lamindb.ULabel`)."""
     run: Run | None = ForeignKey(
-        Run, PROTECT, related_name="output_artifacts", null=True, default=None
+        Run,
+        PROTECT,
+        related_name="output_artifacts",
+        null=True,
+        default=None,
+        editable=False,
     )
     """Run that created the artifact."""
     input_of_runs: Run = models.ManyToManyField(Run, related_name="input_artifacts")
@@ -2516,13 +2725,17 @@ class Artifact(Record, IsVersioned, TracksRun, TracksUpdates):
     collections: Collection
     """The collections that this artifact is part of."""
     schema: Schema | None = ForeignKey(
-        Schema, PROTECT, null=True, default=None, related_name="artifacts"
+        Schema,
+        PROTECT,
+        null=True,
+        default=None,
+        related_name="validated_artifacts",
     )
-    """The schema of the artifact (to be populated in lamindb 1.1)."""
-    _schemas_m2m: Schema = models.ManyToManyField(
-        Schema, related_name="_artifacts_m2m", through="ArtifactSchema"
+    """The schema that validated this artifact in a :class:`~lamindb.curators.Curator`."""
+    feature_sets: Schema = models.ManyToManyField(
+        Schema, related_name="artifacts", through="ArtifactSchema"
     )
-    """[For backward compatibility] The feature sets measured in the artifact."""
+    """The feature sets measured by the artifact."""
     _feature_values: FeatureValue = models.ManyToManyField(
         FeatureValue, through="ArtifactFeatureValue", related_name="artifacts"
     )
@@ -2543,6 +2756,7 @@ class Artifact(Record, IsVersioned, TracksRun, TracksUpdates):
         PROTECT,
         default=current_user_id,
         related_name="created_artifacts",
+        editable=False,
     )
     """Creator of record."""
     _overwrite_versions: bool = BooleanField(default=None)
@@ -2566,7 +2780,7 @@ class Artifact(Record, IsVersioned, TracksRun, TracksUpdates):
         # here; and we might refactor this but we might also keep that internal
         # usage
         data: UPathStr,
-        type: ArtifactKind | None = None,
+        kind: ArtifactKind | None = None,
         key: str | None = None,
         description: str | None = None,
         revises: Artifact | None = None,
@@ -2606,11 +2820,6 @@ class Artifact(Record, IsVersioned, TracksRun, TracksUpdates):
     def n_objects(self) -> int:
         return self.n_files
 
-    @property
-    def feature_sets(self) -> QuerySet[Schema]:
-        """Feature sets linked to this artifact."""
-        return self._schemas_m2m
-
     # add the below because this is what people will have in their code
     # if they implement the recommended migration strategy
     # - FeatureSet -> Schema
@@ -2620,14 +2829,14 @@ class Artifact(Record, IsVersioned, TracksRun, TracksUpdates):
     # def schemas(self) -> QuerySet[Schema]:
     #     """Schemas linked to artifact via many-to-many relationship.
 
-    #     Is now mediating the private `._schemas_m2m` relationship during
+    #     Is now mediating the private `.feature_sets` relationship during
     #     a transition period to better schema management.
 
     #     .. versionchanged: 1.0
     #        Was previously called `.feature_sets`.
 
     #     """
-    #     return self._schemas_m2m
+    #     return self.feature_sets
 
     @property
     def path(self) -> Path:
@@ -2637,7 +2846,7 @@ class Artifact(Record, IsVersioned, TracksRun, TracksUpdates):
 
         >>> artifact = ln.Artifact("s3://my-bucket/my-file.csv").save()
         >>> artifact.path
-        S3Path('s3://my-bucket/my-file.csv')
+        S3QueryPath('s3://my-bucket/my-file.csv')
 
         File in local storage:
 
@@ -2652,6 +2861,7 @@ class Artifact(Record, IsVersioned, TracksRun, TracksUpdates):
     def from_df(
         cls,
         df: pd.DataFrame,
+        *,
         key: str | None = None,
         description: str | None = None,
         run: Run | None = None,
@@ -2692,6 +2902,7 @@ class Artifact(Record, IsVersioned, TracksRun, TracksUpdates):
     def from_anndata(
         cls,
         adata: AnnData | UPathStr,
+        *,
         key: str | None = None,
         description: str | None = None,
         run: Run | None = None,
@@ -2728,6 +2939,7 @@ class Artifact(Record, IsVersioned, TracksRun, TracksUpdates):
     def from_mudata(
         cls,
         mdata: MuData,
+        *,
         key: str | None = None,
         description: str | None = None,
         run: Run | None = None,
@@ -2760,11 +2972,38 @@ class Artifact(Record, IsVersioned, TracksRun, TracksUpdates):
         pass
 
     @classmethod
-    def from_dir(
+    def from_tiledbsoma(
         cls,
         path: UPathStr,
+        *,
         key: str | None = None,
+        description: str | None = None,
+        run: Run | None = None,
+        revises: Artifact | None = None,
+        **kwargs,
+    ) -> Artifact:
+        """Create from a tiledbsoma store.
+
+        Args:
+            path: A tiledbsoma store with .tiledbsoma suffix.
+            key: A relative path within default storage,
+                e.g., `"myfolder/mystore.tiledbsoma"`.
+            description: A description.
+            revises: An old version of the artifact.
+            run: The run that creates the artifact.
+
+        Examples:
+            >>> artifact = ln.Artifact.from_tiledbsoma("s3://mybucket/store.tiledbsoma", description="a tiledbsoma store")
+            >>> artifact.save()
+        """
+        pass
+
+    @classmethod
+    def from_dir(
+        cls,
+        path: UPathStr,
         *,
+        key: str | None = None,
         run: Run | None = None,
     ) -> list[Artifact]:
         """Create a list of artifact objects from a directory.
@@ -2791,7 +3030,7 @@ class Artifact(Record, IsVersioned, TracksRun, TracksUpdates):
 
     def replace(
         self,
-        data: UPathStr,
+        data: UPathStr | pd.DataFrame | AnnData | MuData,
         run: Run | None = None,
         format: str | None = None,
     ) -> None:
@@ -2824,6 +3063,7 @@ class Artifact(Record, IsVersioned, TracksRun, TracksUpdates):
         | BackedAccessor
         | SOMACollection
         | SOMAExperiment
+        | SOMAMeasurement
         | PyArrowDataset
     ):
         """Return a cloud-backed data object.
@@ -2966,13 +3206,13 @@ class Collection(Record, IsVersioned, TracksRun, TracksUpdates):
 
     Args:
         artifacts: `list[Artifact]` A list of artifacts.
-        name: `str` A name.
+        key: `str` A file-path like key, analogous to the `key` parameter of `Artifact` and `Transform`.
         description: `str | None = None` A description.
         revises: `Collection | None = None` An old version of the collection.
         run: `Run | None = None` The run that creates the collection.
         meta: `Artifact | None = None` An artifact that defines metadata for the collection.
-        reference: `str | None = None` For instance, an external ID or a URL.
-        reference_type: `str | None = None` For instance, `"url"`.
+        reference: `str | None = None` A simple reference, e.g. an external ID or a URL.
+        reference_type: `str | None = None` A way to indicate to indicate the type of the simple reference `"url"`.
 
     See Also:
         :class:`~lamindb.Artifact`
@@ -2981,11 +3221,11 @@ class Collection(Record, IsVersioned, TracksRun, TracksUpdates):
 
         Create a collection from a list of :class:`~lamindb.Artifact` objects:
 
-        >>> collection = ln.Collection([artifact1, artifact2], name="My collection")
+        >>> collection = ln.Collection([artifact1, artifact2], key="my_project/my_collection")
 
         Create a collection that groups a data & a metadata artifact (e.g., here :doc:`docs:rxrx`):
 
-        >>> collection = ln.Collection(data_artifact, name="My collection", meta=metadata_artifact)
+        >>> collection = ln.Collection(data_artifact, key="my_project/my_collection", meta=metadata_artifact)
 
     """
 
@@ -3008,13 +3248,15 @@ class Collection(Record, IsVersioned, TracksRun, TracksUpdates):
     """Universal id, valid across DB instances."""
     key: str = CharField(db_index=True)
     """Name or path-like key."""
-    # these here is the only case in which we use a TextField
+    # below is the only case in which we use a TextField
     # for description; we do so because users had descriptions exceeding 255 chars
     # in their instances
     description: str | None = TextField(null=True, db_index=True)
     """A description or title."""
-    hash: str | None = CharField(max_length=HASH_LENGTH, db_index=True, null=True)
-    """Hash of collection content. 86 base64 chars allow to store 64 bytes, 512 bits."""
+    hash: str | None = CharField(
+        max_length=HASH_LENGTH, db_index=True, null=True, unique=True
+    )
+    """Hash of collection content."""
     reference: str | None = CharField(max_length=255, db_index=True, null=True)
     """A reference like URL or external ID."""
     # also for reference_type here, we allow an extra long max_length
@@ -3058,7 +3300,7 @@ class Collection(Record, IsVersioned, TracksRun, TracksUpdates):
     def __init__(
         self,
         artifacts: list[Artifact],
-        name: str,
+        key: str,
         description: str | None = None,
         meta: Any | None = None,
         reference: str | None = None,
@@ -3084,21 +3326,39 @@ class Collection(Record, IsVersioned, TracksRun, TracksUpdates):
         """Add an artifact to the collection.
 
         Creates a new version of the collection.
+        This does not modify the original collection in-place, but returns a new version
+        of the original collection with the added artifact.
 
         Args:
             artifact: An artifact to add to the collection.
             run: The run that creates the new version of the collection.
 
+        Examples:
+            >>> collection = ln.Collection(artifact, key="new collection")
+            >>> collecton.save()
+            >>> collection = collection.append(another_artifact) # returns a new version
+            >>> collection.save() # save the new version
+
         .. versionadded:: 0.76.14
         """
         pass
 
+    def open(self, is_run_input: bool | None = None) -> PyArrowDataset:
+        """Return a cloud-backed pyarrow Dataset.
+
+        Works for `pyarrow` compatible formats.
+
+        Notes:
+            For more info, see tutorial: :doc:`/arrays`.
+        """
+        pass
+
     def mapped(
         self,
         layers_keys: str | list[str] | None = None,
         obs_keys: str | list[str] | None = None,
         obsm_keys: str | list[str] | None = None,
-        obs_filter: dict[str, str | tuple[str, ...]] | None = None,
+        obs_filter: dict[str, str | list[str]] | None = None,
         join: Literal["inner", "outer"] | None = "inner",
         encode_labels: bool | list[str] = True,
         unknown_label: str | dict[str, str] | None = None,
@@ -3136,7 +3396,7 @@ class Collection(Record, IsVersioned, TracksRun, TracksUpdates):
             obsm_keys: Keys from the ``.obsm`` slots.
             obs_filter: Select only observations with these values for the given obs columns.
                 Should be a dictionary with obs column names as keys
-                and filtering values (a string or a tuple of strings) as values.
+                and filtering values (a string or a list of strings) as values.
             join: `"inner"` or `"outer"` virtual joins. If ``None`` is passed,
                 does not join.
             encode_labels: Encode labels into integers.
@@ -3330,7 +3590,7 @@ class Project(Record, CanCurate, TracksRun, TracksUpdates, ValidateFields):
     """Type of project (e.g., 'Program', 'Project', 'GithubIssue', 'Task')."""
     records: Project
     """Records of this type."""
-    is_type: bool = BooleanField(default=None, db_index=True, null=True)
+    is_type: bool = BooleanField(default=False, db_index=True, null=True)
     """Distinguish types from instances of the type."""
     abbr: str | None = CharField(max_length=32, db_index=True, null=True)
     """An abbreviation."""
@@ -3434,7 +3694,7 @@ class Reference(Record, CanCurate, TracksRun, TracksUpdates, ValidateFields):
     """
     records: Reference
     """Records of this type."""
-    is_type: bool = BooleanField(default=None, db_index=True, null=True)
+    is_type: bool = BooleanField(default=False, db_index=True, null=True)
     """Distinguish types from instances of the type."""
     url: str | None = URLField(null=True)
     """URL linking to the reference."""
@@ -3476,7 +3736,7 @@ class Reference(Record, CanCurate, TracksRun, TracksUpdates, ValidateFields):
 # -------------------------------------------------------------------------------------
 # Data models
 
-from django.contrib.postgres.fields import JSONField
+from django.contrib.postgres.fields import JSONField  # type: ignore
 from django.core.exceptions import ValidationError
 from django.db import models
 
@@ -3543,7 +3803,7 @@ class RunData(BasicRecord, DataMixin):
     class Meta:
         constraints = [
             models.CheckConstraint(
-                check=(
+                condition=(
                     models.Q(feature__isnull=False, param__isnull=True)
                     | models.Q(feature__isnull=True, param__isnull=False)
                 ),
@@ -3574,7 +3834,7 @@ class FlexTable(Record, TracksRun, TracksUpdates):
     """Type of tidy table, e.g., `Cell`, `SampleSheet`, etc."""
     records: ULabel
     """Records of this type."""
-    is_type: bool = BooleanField(default=None, db_index=True, null=True)
+    is_type: bool = BooleanField(default=False, db_index=True, null=True)
     """Distinguish types from instances of the type."""
     description: str = CharField(null=True, db_index=True)
     """A description."""
@@ -3593,7 +3853,7 @@ class FlexTableData(BasicRecord, DataMixin):
     class Meta:
         constraints = [
             models.CheckConstraint(
-                check=(
+                condition=(
                     models.Q(feature__isnull=False, param__isnull=True)
                     | models.Q(feature__isnull=True, param__isnull=False)
                 ),
@@ -3621,8 +3881,8 @@ class LinkORM:
 
 class SchemaFeature(BasicRecord, LinkORM):
     id: int = models.BigAutoField(primary_key=True)
-    schema: Schema = ForeignKey(Schema, CASCADE, related_name="+")
-    feature: Feature = ForeignKey(Feature, PROTECT, related_name="+")
+    schema: Schema = ForeignKey(Schema, CASCADE, related_name="links_feature")
+    feature: Feature = ForeignKey(Feature, PROTECT, related_name="links_schema")
 
     class Meta:
         unique_together = ("schema", "feature")
@@ -3640,15 +3900,22 @@ class SchemaParam(BasicRecord, LinkORM):
 class ArtifactSchema(BasicRecord, LinkORM, TracksRun):
     id: int = models.BigAutoField(primary_key=True)
     artifact: Artifact = ForeignKey(Artifact, CASCADE, related_name="_links_schema")
-    # we follow the lower() case convention rather than snake case for link models
     schema: Schema = ForeignKey(Schema, PROTECT, related_name="_links_artifact")
-    slot: str | None = CharField(max_length=40, null=True)
-    feature_ref_is_semantic: bool | None = BooleanField(
-        null=True
-    )  # like Feature name or Gene symbol or CellMarker name
+    slot: str | None = CharField(null=True)
+    feature_ref_is_semantic: bool | None = BooleanField(null=True)
 
     class Meta:
-        unique_together = ("artifact", "schema")
+        unique_together = (("artifact", "schema"), ("artifact", "slot"))
+
+
+class SchemaComponent(BasicRecord, LinkORM, TracksRun):
+    id: int = models.BigAutoField(primary_key=True)
+    composite: Schema = ForeignKey(Schema, CASCADE, related_name="links_composite")
+    component: Schema = ForeignKey(Schema, PROTECT, related_name="links_component")
+    slot: str | None = CharField(null=True)
+
+    class Meta:
+        unique_together = (("composite", "component"), ("composite", "slot"))
 
 
 class CollectionArtifact(BasicRecord, LinkORM, TracksRun):
@@ -3883,14 +4150,14 @@ class CollectionReference(BasicRecord, LinkORM, TracksRun):
         unique_together = ("collection", "reference")
 
 
-# class Migration(Record):
-#     app = CharField(max_length=255)
-#     name = CharField(max_length=255)
-#     applied: datetime = DateTimeField()
+class Migration(BasicRecord):
+    app = CharField(max_length=255)
+    name = CharField(max_length=255)
+    applied: datetime = DateTimeField()
 
-#     class Meta:
-#         db_table = "django_migrations"
-#         managed = False
+    class Meta:
+        db_table = "django_migrations"
+        managed = False
 
 
 # -------------------------------------------------------------------------------------