diff --git a/README.md b/README.md
index 7d6e51b..1c3e880 100644
--- a/README.md
+++ b/README.md
@@ -67,6 +67,14 @@ flag_value = client.get_string_value("flag-name.property-name", "my-default-valu
 print(f"Flag value: {flag_value}")
 ```
 
+### Deprecated: list/array flag values
+
+Using lists (arrays) as flag schema types or flag values is deprecated in this SDK. Prefer
+modeling such data as a struct/object flag property. Existing behavior is unchanged: list
+values are still parsed and returned by `resolve_object_details` (and the OpenFeature
+provider's object resolution), so current integrations keep working. This deprecation applies
+only to flag values; lists remain supported in evaluation context and event data.
+
 ### Configuration options
 
 The SDK can be configured with several options:
diff --git a/confidence/confidence.py b/confidence/confidence.py
index 4f2a9ac..1225e7b 100644
--- a/confidence/confidence.py
+++ b/confidence/confidence.py
@@ -171,11 +171,21 @@ async def resolve_string_details_async(
     def resolve_object_details(
         self, flag_key: str, default_value: Union[Object, List[Primitive]]
     ) -> FlagResolutionDetails[Union[Object, List[Primitive]]]:
+        """Resolve an object flag.
+
+        Note: list/array flag values are deprecated (flag values only; lists in
+        context and events are unaffected). They are still parsed and returned.
+        """
         return self._evaluate(flag_key, Object, default_value, self.context)
 
     async def resolve_object_details_async(
         self, flag_key: str, default_value: Union[Object, List[Primitive]]
     ) -> FlagResolutionDetails[Union[Object, List[Primitive]]]:
+        """Resolve an object flag.
+
+        Note: list/array flag values are deprecated (flag values only; lists in
+        context and events are unaffected). They are still parsed and returned.
+        """
         return await self._evaluate_async(flag_key, Object, default_value, self.context)
 
     #
diff --git a/confidence/openfeature_provider.py b/confidence/openfeature_provider.py
index 2f7daae..ca68616 100644
--- a/confidence/openfeature_provider.py
+++ b/confidence/openfeature_provider.py
@@ -183,6 +183,11 @@ def resolve_object_details(
         default_value: Union[Object, List[Primitive]],
         evaluation_context: Optional[EvaluationContext] = None,
     ) -> FlagResolutionDetails[Union[Object, List[Primitive]]]:
+        """Resolve an object flag.
+
+        Note: list/array flag values are deprecated (flag values only; lists in
+        context and events are unaffected). They are still parsed and returned.
+        """
         details = self._confidence_with_context(
             evaluation_context
         ).resolve_object_details(flag_key, default_value)