From 8825fc46355fba84da5866447eeabde107403ca8 Mon Sep 17 00:00:00 2001
From: "confidence-agent[bot]"
 <253939730+confidence-agent[bot]@users.noreply.github.com>
Date: Mon, 2 Nov 2026 11:08:08 +0000
Subject: [PATCH] docs: deprecate list/array flag values

Documents list/array flag values as deprecated without changing runtime behavior.

- README: new "Deprecated: list/array flag values" section with a compatibility statement (lists still parsed and returned; lists in context/events unaffected).
- Docstring deprecation notes on resolve_object_details / resolve_object_details_async (Confidence) and resolve_object_details (OpenFeature provider), the only surfaces that return list flag values.

Surfaces/gaps: there is no list-specific flag API; lists flow through the object getters and the shared FieldType alias, which also covers context/event values. Per scope, no runtime warnings, no deprecation of object getters or FieldType, no removal date or version bump. No new test added since behavior is unchanged; existing tests cover list parsing.

Validation: pytest (69 passed).
---
 README.md                          |  8 ++++++++
 confidence/confidence.py           | 10 ++++++++++
 confidence/openfeature_provider.py |  5 +++++
 3 files changed, 23 insertions(+)

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)