mmif-python 1.5.2__tar.gz → 1.5.4__tar.gz

{mmif_python-1.5.2 → mmif_python-1.5.4}/CHANGELOG.md

@@ -1,4 +1,22 @@
 
+## releasing 1.5.3 (2026-07-08)
+### Overview
+This patch includes improvements in automatic conversion between contains-metadata properties and annotation properties (#396) 
+
+### Additions
+* automatic "factoring" of value-shared properties from annotation-level to contains-level at serialization time works much more generally now (formerly only worked for `Annotation` type and `document` prop) 
+
+### Changes
+* fixed a bug in reading old MMIF files with non-canonical prop names (contains-level prop value was not properly propagated at deserialization for those non-canonical named props)
+
+
+
+## releasing 1.5.2 (2026-07-07)
+### Overview
+This is a quick patch on the bug that when MMIF is deserialized, the annotation ID counts in the views weren't properly initialized. This should not be a real bug since new annotations should always written to new views (of current processing app) but not to existing views (where annotation count > 0), however, bugs in app code can trigger this condition, and this patch preventively fixes such cases.
+
+
+
 ## releasing 1.5.1 (2026-06-19)
 ### Overview
 This patch contains a bug fix in VDH that couldn't handle some mkv-contained video files (https://github.com/clamsproject/mmif-python/issues/390) , and some other minor documentation generation bugs.

{mmif_python-1.5.2 → mmif_python-1.5.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mmif-python
-Version: 1.5.2
+Version: 1.5.4
 Summary: Python implementation of MultiMedia Interchange Format specification. (https://mmif.clams.ai)
 License-Expression: Apache-2.0
 Project-URL: homepage, https://mmif.clams.ai
@@ -21,7 +21,7 @@ Requires-Dist: pillow; extra == "cv"
 Requires-Dist: opencv-python; extra == "cv"
 Requires-Dist: ffmpeg-python; extra == "cv"
 Requires-Dist: wurlitzer; extra == "cv"
-Requires-Dist: av; extra == "cv"
+Requires-Dist: av>=15; extra == "cv"
 Provides-Extra: seq
 Requires-Dist: numpy; extra == "seq"
 Provides-Extra: docs

{mmif_python-1.5.2 → mmif_python-1.5.4}/documentation/target-versions.csv

@@ -1,4 +1,6 @@
 "``mmif-python`` version","Target MMIF Specification"
+`1.5.4 <https://pypi.org/project/mmif-python/1.5.4/>`__,`1.2.0 <https://mmif.clams.ai/1.2.0/>`__
+`1.5.3 <https://pypi.org/project/mmif-python/1.5.3/>`__,`1.2.0 <https://mmif.clams.ai/1.2.0/>`__
 `1.5.2 <https://pypi.org/project/mmif-python/1.5.2/>`__,`1.2.0 <https://mmif.clams.ai/1.2.0/>`__
 `1.5.1 <https://pypi.org/project/mmif-python/1.5.1/>`__,`1.2.0 <https://mmif.clams.ai/1.2.0/>`__
 `1.5.0 <https://pypi.org/project/mmif-python/1.5.0/>`__,`1.2.0 <https://mmif.clams.ai/1.2.0/>`__

{mmif_python-1.5.2 → mmif_python-1.5.4}/mmif/serialize/annotation.py

@@ -6,6 +6,7 @@ In MMIF, annotations are created by apps in a workflow as a part
 of a view. For documentation on how views are represented, see
 :mod:`mmif.serialize.view`.
 """
+import functools
 import importlib
 import itertools
 import os
@@ -22,7 +23,7 @@ from .model import MmifObject, PRMTV_TYPES
 from .. import DocumentTypes, AnnotationTypes
 import mmif_docloc_http
 
-__all__ = ['Annotation', 'AnnotationProperties', 'Document', 'DocumentProperties', 'Text']
+__all__ = ['Annotation', 'AnnotationProperties', 'Document', 'DocumentProperties', 'Text', 'canonicalize_prop_name']
 
 T = TypeVar('T')
 LIST_PRMTV = typing.List[PRMTV_TYPES]  # list of values (most cases for annotation props)
@@ -41,6 +42,40 @@ discovered_docloc_plugins.update({
 })
 
 
+@functools.lru_cache(maxsize=None)
+def _prop_alias_map(shortname: str) -> Dict[str, str]:
+    """
+    Maps every spelling of an aliased property of a type to the canonical
+    name. The table is read from the latest version of the type in the
+    vocabulary (``AnnotationTypes.<shortname>``), which is the single source
+    of truth for property aliases.
+
+    :param shortname: shortname of the annotation type (e.g. ``TimeFrame``)
+    :return: ``{spelling: canonical_name}``, empty for types without aliases
+    """
+    latest = getattr(AnnotationTypes, shortname, None)
+    groups = getattr(latest, '_property_aliases', None) or {}
+    return {alias: canonical for canonical, group in groups.items() for alias in group}
+
+
+def canonicalize_prop_name(at_type: ThingTypesBase, prop_name: str) -> str:
+    """
+    Resolves a property name to its canonical spelling for the given type.
+    Property aliases were introduced in MMIF 1.0.2, when the general
+    ``label`` property replaced ``frameType`` (``TimeFrame``) and ``boxType``
+    (``BoundingBox``). Names that are not aliases, and types without an alias
+    table, are returned unchanged.
+
+    :param at_type: the ``@type`` of the annotation
+    :param prop_name: a property name, canonical or deprecated
+    :return: the canonical property name
+    """
+    shortname = getattr(at_type, 'shortname', None)
+    if not shortname:
+        return prop_name
+    return _prop_alias_map(shortname).get(prop_name, prop_name)
+
+
 class Annotation(MmifObject):
     """
     MmifObject that represents an annotation in a MMIF view.
@@ -49,11 +84,11 @@ class Annotation(MmifObject):
     def __init__(self, anno_obj: Optional[Union[bytes, str, dict]] = None, *_) -> None:
         self._type: ThingTypesBase = ThingTypesBase('')
         # to store the parent view ID
-        self._props_ephemeral: AnnotationProperties = AnnotationProperties()
+        self._props_ephemeral: AnnotationProperties = AnnotationProperties(None, self)
         self._alignments = {}  # to hold alignment information (Alignment anno long_id -> aligned anno long_id)
         self.reserved_names.update(('_props_ephemeral', '_alignments'))
         if not hasattr(self, 'properties'):  # don't overwrite DocumentProperties on super() call
-            self.properties: AnnotationProperties = AnnotationProperties()
+            self.properties: AnnotationProperties = AnnotationProperties(None, self)
             self._attribute_classes = {'properties': AnnotationProperties}
         self.disallow_additional_properties()
         self._required_attributes = ["_type", "properties"]
@@ -69,9 +104,7 @@ class Annotation(MmifObject):
         # here is the place to parse formatted IDs and store prefixes in the parent mmif object. 
         # (see https://github.com/clamsproject/mmif/issues/64#issuecomment-849241309 for discussion)
         super()._deserialize(input_dict)
-        for k, v in self.properties.items():
-            self._add_prop_aliases(k, v)
-                            
+
     def _cache_alignment(self, alignment_ann: 'Annotation', alignedto_ann: 'Annotation') -> None:
         """
         Cache alignment information. This cache will not be serialized.
@@ -107,29 +140,20 @@ class Annotation(MmifObject):
             yield aligned
         
         
-    def _add_prop_aliases(self, key_to_add, val_to_add):
-        """
-        Method to handle aliases of the same property.
-        Annotation property aliases were first introduced in MMIF 1.0.2, 
-        with addition of general `label` property to all `Annotation` 
-        subtypes, and effectively deprecated `frameType` and `boxType`
-        in `TimeFrame` and `BoundingBox` respectively.
-        """
-        prop_aliases = AnnotationTypes._prop_aliases.get(self._type.shortname, {})
-        for alias_rep, alias_group in prop_aliases.items():
-            if key_to_add in alias_group:
-                for alias in alias_group:
-                    if alias != key_to_add:
-                        self._props_ephemeral[alias] = val_to_add
-                        if alias in self.properties.keys():
-                            warning_msg = (f'Both "{key_to_add}" and "{alias}" are in the properties of "{self.id}", '
-                                           f'however ')
-                            if alias == alias_rep:
-                                warning_msg += f'"{key_to_add}" is an alias of "{alias_rep}".'
-                            else:
-                                warning_msg += f'"{key_to_add}" and "{alias}" are both aliases of "{alias_rep}".'
-                            warning_msg += f'Having two synonyms in the same annotation can cause unexpected behavior. '
-                            warnings.warn(warning_msg, UserWarning)
+    def _add_ephemeral_defaults(self, defaults: typing.Mapping[str, typing.Any]) -> None:
+        """
+        Distributes view-level defaults (from the ``contains`` metadata of the
+        parent view) to this annotation as ephemeral properties, under their
+        canonical names. An annotation-level value takes precedence over a
+        view-level default, so a default is skipped when the annotation
+        carries the property itself.
+
+        :param defaults: property defaults for this annotation's ``@type``
+        """
+        for name, value in defaults.items():
+            name = canonicalize_prop_name(self._type, name)
+            if name not in self.properties:
+                self._props_ephemeral[name] = value
 
     def is_type(self, at_type: Union[str, ThingTypesBase]) -> bool:
         """
@@ -239,7 +263,9 @@ class Annotation(MmifObject):
     def add_property(self, name: str,
                      value: Union[PRMTV_TYPES, LIST_PRMTV, LIST_LIST_PRMTV, DICT_PRMTV, DICT_LIST_PRMTV]) -> None:
         """
-        Adds a property to the annotation's properties.
+        Adds a property to the annotation's properties. A deprecated spelling
+        of an aliased property (e.g. ``frameType``) is stored under its
+        canonical name (``label``), with a :class:`DeprecationWarning`.
 
         :param name: the name of the property
         :param value: the property's desired value
@@ -252,14 +278,14 @@ class Annotation(MmifObject):
         #                      "either string, number, boolean, None, a JSON array of them, "
         #                      "or a JSON object of them keyed by strings."
         #                      f"(\"{name}\": \"{str(value)}\"")
-        self._add_prop_aliases(name, value)
 
     def __getitem__(self, prop_name: str):
         if prop_name in {'at_type', '@type'}:
             return str(self._type)
         elif prop_name == 'properties':
             return self.properties
-        elif prop_name in self.properties:
+        prop_name = canonicalize_prop_name(self._type, prop_name)
+        if prop_name in self.properties:
             return self.properties[prop_name]
         elif prop_name in self._props_ephemeral:
             return self._props_ephemeral[prop_name]
@@ -279,7 +305,9 @@ class Annotation(MmifObject):
         3. Special fields (``@type``, ``properties``)
 
         This allows convenient access to properties without explicitly
-        checking the ``properties`` object or view-level metadata.
+        checking the ``properties`` object or view-level metadata. A
+        deprecated spelling of an aliased property (e.g. ``frameType``)
+        resolves to the canonical property (``label``).
 
         :param prop_name: The name of the property to retrieve
         :param default: The value to return if the property is not found (default: None)
@@ -318,23 +346,6 @@ class Annotation(MmifObject):
         except KeyError:
             return False
     
-    def _get_label(self) -> str:
-        """
-        Another prototypical method to handle property aliases.
-        See :meth:`.Annotation._add_prop_aliases` for more details on 
-        what property aliases are.
-        Not recommended to use this method as `_add_prop_aliases` method 
-        is preferred. 
-        """
-        if 'label' in self:
-            return str(self.get('label'))
-        elif self._type.shortname == 'TimeFrame' and 'frameType' in self:
-            return str(self.get('frameType'))
-        elif self._type.shortname == 'BoundingBox' and 'boxType' in self:
-            return str(self.get('boxType'))
-        else:
-            raise KeyError("No label found in this annotation.")
-    
     def is_document(self):
         return isinstance(self._type, DocumentTypesBase)
 
@@ -356,8 +367,8 @@ class Document(Annotation):
         # see https://github.com/clamsproject/mmif-python/issues/226 for discussion
         # around the use of these three dictionaries
         # (names changed since, `existing` >> `ephemeral` and `temporary` >> `pending`)
-        self._props_original: DocumentProperties = DocumentProperties()
-        self._props_pending: AnnotationProperties = AnnotationProperties()
+        self._props_original: DocumentProperties = DocumentProperties(None, self)
+        self._props_pending: AnnotationProperties = AnnotationProperties(None, self)
         self.reserved_names.update(('_props_original', '_props_pending'))
         
         self._type: Union[ThingTypesBase, DocumentTypesBase] = ThingTypesBase('')
@@ -578,6 +589,7 @@ class AnnotationProperties(MmifObject, MutableMapping[str, T]):
     """
 
     def __delitem__(self, key: str) -> None:
+        key = self._canonical(key)
         frm = None
         for k in self.__iter__():
             if k == key:
@@ -593,36 +605,83 @@ class AnnotationProperties(MmifObject, MutableMapping[str, T]):
             del frm[key]
         else:
             raise KeyError(f'Key "{key}" not found.')
-                
+
     def __iter__(self) -> Iterator[str]:
         """
-        ``__iter__`` on Mapping should basically work as ``keys()`` method 
+        ``__iter__`` on Mapping should basically work as ``keys()`` method
         of vanilla dict.
         """
         for key in itertools.chain(self._named_attributes(), self._unnamed_attributes):
             yield key
-                
+
     def __getitem__(self, key):
         """
-        Parent MmifObject class has a __getitem__ method that checks if 
-        the value is empty when asked for an unnamed attribute. But for 
-        AnnotationProperties, any arbitrary property that's added 
-        explicitly by the user (developer) should not be ignored and 
-        returned even the value is empty. 
+        Parent MmifObject class has a __getitem__ method that checks if
+        the value is empty when asked for an unnamed attribute. But for
+        AnnotationProperties, any arbitrary property that's added
+        explicitly by the user (developer) should not be ignored and
+        returned even the value is empty.
         """
+        key = self._canonical(key)
         if key in self._named_attributes():
             return self.__dict__[key]
         else:
             return self._unnamed_attributes[key]
 
-    def __init__(self, mmif_obj: Optional[Union[bytes, str, dict]] = None, *_) -> None:
+    def __setitem__(self, key: str, value) -> None:
+        """
+        Sets a property. A deprecated spelling of an aliased property (e.g.
+        ``frameType``) is stored under its canonical name (``label``), with
+        a :class:`DeprecationWarning`.
+        """
+        canonical = self._canonical(key)
+        if canonical != key:
+            warnings.warn(f'"{key}" is a deprecated alias of "{canonical}", storing the value as "{canonical}".',
+                          DeprecationWarning)
+        super().__setitem__(canonical, value)
+
+    def __init__(self, mmif_obj: Optional[Union[bytes, str, dict]] = None,
+                 parent: Optional['Annotation'] = None, *_) -> None:
         self.id: str = ''
         # any individual at_type (subclassing this class) can have its own set of required attributes
         self._required_attributes = ["id"]
         # allowing additional attributes for arbitrary annotation properties
         self._unnamed_attributes = {}
+        # the Annotation these properties belong to; its `@type` decides which
+        # property names are aliases of each other (see `canonicalize_prop_name`)
+        self._parent_annotation = parent
+        self.reserved_names.add('_parent_annotation')
         super().__init__(mmif_obj)
 
+    def _canonical(self, key: str) -> str:
+        if self._parent_annotation is None:
+            return key
+        return canonicalize_prop_name(self._parent_annotation._type, key)
+
+    def _deserialize(self, input_dict: dict) -> None:
+        """
+        Deserializes the properties, rewriting deprecated spellings to their
+        canonical names so that there is one key per property. When two
+        spellings of the same property are present, the canonical one wins
+        (or the first one seen, when neither is canonical), with a warning.
+        """
+        canonical_dict = {}
+        # canonical name -> the deprecated spelling it was read from
+        from_alias = {}
+        for key, value in input_dict.items():
+            canonical = self._canonical(key)
+            if canonical in canonical_dict and (canonical != key or canonical in from_alias):
+                alias = key if canonical != key else from_alias[canonical]
+                warnings.warn(f'Both "{alias}" and "{canonical}" are in the properties of '
+                              f'"{input_dict.get("id", "")}", but "{alias}" is an alias of "{canonical}". '
+                              f'Keeping the value of "{canonical}".', UserWarning)
+                if canonical != key:
+                    continue
+            canonical_dict[canonical] = value
+            if canonical != key:
+                from_alias[canonical] = key
+        super()._deserialize(canonical_dict)
+
 
 class DocumentProperties(AnnotationProperties):
     """
@@ -632,7 +691,8 @@ class DocumentProperties(AnnotationProperties):
     :param mmif_obj: the JSON data that defines the properties
     """
 
-    def __init__(self, mmif_obj: Optional[Union[bytes, str, dict]] = None, *_) -> None:
+    def __init__(self, mmif_obj: Optional[Union[bytes, str, dict]] = None,
+                 parent: Optional['Annotation'] = None, *_) -> None:
         self.mime: str = ''
         # note the trailing underscore here. I wanted to use the name `location`
         # for @property in this class and `Document` class, so had to use a diff
@@ -643,9 +703,9 @@ class DocumentProperties(AnnotationProperties):
         self._attribute_classes = {'text': Text}
         # in theory, either `location` or `text` should appear in a `document`
         # but with current implementation, there's no easy way to set a condition 
-        # for `oneOf` requirement 
-        # see MmifObject::_required_attributes in model.py 
-        super().__init__(mmif_obj)
+        # for `oneOf` requirement
+        # see MmifObject::_required_attributes in model.py
+        super().__init__(mmif_obj, parent)
 
     def _deserialize(self, input_dict: dict) -> None:
         if "location" in input_dict:

{mmif_python-1.5.2 → mmif_python-1.5.4}/mmif/serialize/mmif.py

@@ -175,6 +175,14 @@ class Mmif(MmifObject):
        all_views = mmif.views[1:4]       # Slice of views
     """
 
+    #: Hardcoded list of property names that must stay at the individual
+    #: annotation level, and never "factored" into the view's ``contains``
+    #: metadata, even when redundant across annotations.
+    _NON_FACTORABLE_PROPS = frozenset({
+        'start', 'end', 'targets', 'source', 'target', 'representatives', 
+        'mime', 'location', 'location_', 'text',
+    })
+
     def __init__(self, mmif_obj: Optional[Union[bytes, str, dict]] = None, *, validate: bool = True) -> None:
         self.metadata: MmifMetadata = MmifMetadata()
         self.documents: DocumentsList = DocumentsList()
@@ -211,26 +219,42 @@ class Mmif(MmifObject):
             json_str = json.loads(json_str)
         jsonschema.validators.validate(json_str, schema)
 
-    def serialize(self, sanitize: bool = False, autogenerate_capital_annotations: bool = True, **kwargs) -> str:
+    def serialize(self,
+                  pretty: bool = False,
+                  include_context: bool = True,
+                  *,
+                  sanitize: bool = False,
+                  autogenerate_capital_annotations: bool = True,
+                  factor_out_shared_properties: bool = True) -> str:
         """
         Serializes the MMIF object to a JSON string.
 
+        :param pretty: If True, returns the string with indentation.
+        :param include_context: If False, excludes contextual attributes (e.g.
+            runtime timestamps) from serialization.
         :param sanitize: If True, performs some sanitization of before returning
             the JSON string. See :meth:`sanitize` for details.
         :param autogenerate_capital_annotations: If True, automatically convert
             any "pending" temporary properties from `Document` objects to
             `Annotation` objects. See :meth:`generate_capital_annotations` for
             details.
-        :param kwargs: Keyword arguments to pass to the parent's ``serialize``
-                       method (e.g., ``pretty=True``, ``include_context=False``).
+        :param factor_out_shared_properties: If True, lift properties shared
+            (same value) across all annotations of a type in a view into the
+            view's ``contains`` metadata. See
+            :meth:`factor_out_shared_properties` for details. Independent of
+            ``autogenerate_capital_annotations``, but runs after it (so
+            freshly-materialized pending properties are included) when both are
+            enabled.
         :return: JSON string of the MMIF object.
         """
         if autogenerate_capital_annotations:
             self.generate_capital_annotations()
+        if factor_out_shared_properties:
+            self.factor_out_shared_properties()
         # sanitization should be done after `Annotation` annotations are generated
         if sanitize:
             self.sanitize()
-        return super().serialize(**kwargs)
+        return super().serialize(pretty=pretty, include_context=include_context)
 
     def _deserialize(self, input_dict: dict) -> None:
         """
@@ -252,18 +276,11 @@ class Mmif(MmifObject):
         super()._deserialize(input_dict)
         for view in self.views:
             view._parent_mmif = self
-            # this dict will be populated with properties 
-            # that are not encoded in individual annotations objects themselves
-            extrinsic_props = defaultdict(dict)
-            for at_type, type_lv_props in view.metadata.contains.items():
-                for prop_key, prop_value in type_lv_props.items():
-                    extrinsic_props[at_type][prop_key] = prop_value
             for ann in view.get_annotations():
                 ## for "capital" Annotation properties
-                # first add all extrinsic properties to the Annotation objects
-                # as "ephemeral" properties
-                for prop_key, prop_value in extrinsic_props[ann.at_type].items():
-                    ann._props_ephemeral[prop_key] = prop_value
+                # first, distribute view-level defaults from `contains` metadata
+                # to the Annotation objects as "ephemeral" properties
+                ann._add_ephemeral_defaults(view.metadata.contains.get(ann.at_type, {}))
                 # then, do the same to associated Document objects. Note that, 
                 # in a view, it is guaranteed that all Annotation objects are not duplicates
                 if ann.at_type == AnnotationTypes.Annotation:
@@ -297,7 +314,7 @@ class Mmif(MmifObject):
                 f"Alignment {alignment_ann.id} has `source` and `target` properties that do not point to Annotation objects.",
                 RuntimeWarning)
         ## caching alignments
-        if all(map(lambda x: x in alignment_ann.properties, ('source', 'target'))):
+        if all(map(lambda x: x in alignment_ann, ('source', 'target'))):
             try:
                 source_ann = self.__getitem__(alignment_ann.get('source'))
                 target_ann = self.__getitem__(alignment_ann.get('target'))
@@ -383,15 +400,51 @@ class Mmif(MmifObject):
                     if view_to_write.metadata.app == current_app and doc_id in view_to_write.annotations:
                         view_to_write[doc_id].properties.update(props)
                     else:
-                        if len(anns_to_write) == 1:
-                            # if there's only one document, we can record the doc_id in the contains metadata
-                            view_to_write.metadata.new_contain(AnnotationTypes.Annotation, document=doc_id)
-                            props.pop('document', None)
-                        else:
-                            # otherwise, doc_id needs to be recorded in the annotation property
-                            props['document'] = doc_id
+                        props['document'] = doc_id
                         view_to_write.new_annotation(AnnotationTypes.Annotation, **props)
 
+
+    def factor_out_shared_properties(self):
+        """
+        Factor properties that are shared (identical value) across all
+        annotations of a type within a view up into that view's ``contains``
+        metadata, per the MMIF spec recommendation to prefer view-level
+        defaults for properties shared among annotations of a type.
+
+        A property is factored when it is present, with the same value, on
+        **every** annotation of a given ``@type`` in the view, there are at
+        least two such annotations (so the value is genuinely shared), and the
+        key is not in the :attr:`_NON_FACTORABLE_PROPS` protection list.
+        Factored values are mirrored into each annotation's ephemeral props at
+        deserialization time, so in-memory access is unchanged, while the 
+        serialized output carries the value once, in ``contains``.
+        """
+        for view in self.views:
+            by_type = defaultdict(list)
+            for ann in view.get_annotations():
+                by_type[ann.at_type].append(ann)
+            for at_type, anns in by_type.items():
+                if len(anns) < 2:
+                    continue
+                shared = {}
+                for key in list(anns[0].properties.keys()):
+                    if key in self._NON_FACTORABLE_PROPS:
+                        continue
+                    value = anns[0].properties[key]
+                    if all(key in a.properties and a.properties[key] == value
+                           for a in anns):
+                        shared[key] = value
+                if not shared:
+                    continue
+                if at_type not in view.metadata.contains:
+                    view.metadata.new_contain(at_type)
+                contain = view.metadata.contains[at_type]
+                for key, value in shared.items():
+                    contain[key] = value
+                    for a in anns:
+                        del a.properties[key]
+                        a._props_ephemeral[key] = value
+
     def sanitize(self):
         """
         Sanitizes a Mmif object by running some safeguards.

{mmif_python-1.5.2 → mmif_python-1.5.4}/mmif/serialize/view.py

@@ -17,7 +17,7 @@ from datetime import datetime
 from typing import Dict, Union, Optional, Generator, List, cast
 
 from mmif import DocumentTypes, AnnotationTypes, ThingTypesBase, ClamsTypesBase
-from mmif.serialize.annotation import Annotation, Document
+from mmif.serialize.annotation import Annotation, Document, canonicalize_prop_name
 from mmif.serialize.model import PRMTV_TYPES, MmifObject, DataList, DataDict
 from mmif.vocabulary.base_types import AnnotationTypesBase
 
@@ -197,8 +197,6 @@ class View(MmifObject):
         self._set_ann_id(new_annotation, aid)
         for propk, propv in properties.items():
             new_annotation.add_property(propk, propv)
-        for propk, propv in self.metadata.contains.get(at_type, {}).items():
-            new_annotation._props_ephemeral[propk] = propv
         return self.add_annotation(new_annotation, overwrite)
 
     def add_annotation(self, annotation: 'Annotation', overwrite=False) -> 'Annotation':
@@ -222,6 +220,7 @@ class View(MmifObject):
             annotation.id = f"{self.id}{self.id_delimiter}{annotation.id}"
         self.annotations.append(annotation, overwrite)
         self.new_contain(annotation.at_type)
+        annotation._add_ephemeral_defaults(self.metadata.contains.get(annotation.at_type, {}))
         if annotation.at_type == AnnotationTypes.Alignment:
             self._parent_mmif._cache_alignment(annotation)
         return annotation
@@ -280,13 +279,14 @@ class View(MmifObject):
         must match. Note that annotation type metadata are specified in the `contains` view metadata, not in individual \
         annotation objects.
         """
-        def prop_check(k, v, *props):
-            return any(k in prop and prop[k] == v for prop in props)
+        def prop_check(k, v, annotation, at_type_metadata):
+            k = canonicalize_prop_name(annotation.at_type, k)
+            return any(k in prop and prop[k] == v for prop in (annotation.properties, at_type_metadata))
 
         for annotation in self.annotations:
             at_type_metadata = self.metadata.contains.get(annotation.at_type, {})
             if not at_type or (at_type and annotation.at_type == at_type):
-                if all(map(lambda kv: prop_check(kv[0], kv[1], annotation.properties, at_type_metadata), 
+                if all(map(lambda kv: prop_check(kv[0], kv[1], annotation, at_type_metadata), 
                            properties.items())):
                     yield annotation
     
@@ -485,7 +485,7 @@ class ViewMetadata(MmifObject):
             at_type = ThingTypesBase.from_str(at_type)
             
         if at_type not in self.contains:
-            new_contain = Contain(contains_metadata)
+            new_contain = Contain._for_type(at_type, contains_metadata)
             self.add_contain(new_contain, at_type)
             return new_contain
     
@@ -563,6 +563,15 @@ class Contain(DataDict[str, str]):
     annotation type in the ``contains`` metadata of a MMIF view.
     """
 
+    @classmethod
+    def _for_type(cls, at_type: ThingTypesBase, contains_metadata: dict) -> 'Contain':
+        """
+        Builds a ``Contain`` for the given ``@type``, with property names
+        rewritten to their canonical spellings (see
+        :func:`mmif.serialize.annotation.canonicalize_prop_name`).
+        """
+        return cls({canonicalize_prop_name(at_type, k): v for k, v in contains_metadata.items()})
+
 
 class AnnotationsList(DataList[Union[Annotation, Document]]):
     """
@@ -608,7 +617,7 @@ class ContainsDict(DataDict[ThingTypesBase, Contain]):
         for key, value in input_dict.items():
             if isinstance(key, str):
                 key = ThingTypesBase.from_str(key)
-            self._items[key] = Contain(value)
+            self._items[key] = Contain._for_type(key, value)
 
     def update(self, other: Union[dict, 'ContainsDict'], overwrite=False):
         for k, v in other.items():