feat: add SdJwtVcData.findByPath for nested and array claim lookup

Author: marinaioannou

README.md

@@ -542,67 +542,52 @@ val givenNameDisplay = givenNameClaim.issuerMetadata?.display
 Notes:
  - `dataElementName` is the ISO mdoc data-element identifier within a namespace.
  - `claimName` returns the top-level object key for SD-JWT VC claims; it is `null`
-   for array indices and the wildcard. When you need to handle those, switch on
-   `pathElement` directly (`ClaimPathElement.Claim` / `ArrayElement` /
-   `AllArrayElements`).
- - Nested SD-JWT VC claims (e.g. `place_of_birth.country`) are reachable via
-   `SdJwtVcClaim.children`.
+   for array indices and the wildcard. Use `pathElement` directly when you need to
+   handle those (`ClaimPathElement.Claim` / `ArrayElement` / `AllArrayElements`).
 
-##### Nested SD-JWT VC claims
+#### Resolving SD-JWT VC claim paths
 
-A nested object such as `place_of_birth = { country, locality, region }` is stored
-as one `SdJwtVcClaim` whose `children` list holds the inner claims:
+`SdJwtVcData.findByPath` looks up a claim by its full path — useful when the
+claim you want is inside a nested object (e.g. `place_of_birth.country`), at a
+specific array index (e.g. `nationalities[0]`), or across every element of an
+array.
 
-```kotlin
-val birthCountry: String? = (pidDocument.data as? SdJwtVcData)?.claims
-    .orEmpty()
-    .find { it.claimName == "place_of_birth" }
-    ?.children
-    ?.find { it.claimName == "country" }
-    ?.value as? String
-```
-
-The same shape extends to deeper nesting — keep chaining `.children` and matching
-by `claimName`.
+A path is built from three kinds of elements:
 
-##### SD-JWT VC array elements
+ - `ClaimPathElement.Claim(name)` — an object key.
+ - `ClaimPathElement.ArrayElement(i)` — a specific array index.
+ - `ClaimPathElement.AllArrayElements` — every element of an array (the
+   `null` wildcard in OpenID4VP claim paths).
 
-An array such as `nationalities = ["GR", "SE"]` is stored as one parent
-`SdJwtVcClaim` whose `children` are per-index entries. The convenience property
-`arrayIndex` returns the integer when `pathElement` is a
-`ClaimPathElement.ArrayElement`:
+The function returns one `SdJwtVcClaim` per match, or an empty list if no claim
+exists at that path. Paths with a wildcard return one claim per array entry.
 
 ```kotlin
-// First nationality.
-val primaryNationality: String? = (pidDocument.data as? SdJwtVcData)?.claims
-    .orEmpty()
-    .find { it.claimName == "nationalities" }
-    ?.children
-    ?.find { it.arrayIndex == 0 }
-    ?.value as? String
-
-// All nationalities.
-val nationalities: List<String> = (pidDocument.data as? SdJwtVcData)?.claims
-    .orEmpty()
-    .find { it.claimName == "nationalities" }
-    ?.children
-    ?.mapNotNull { it.value as? String }
-    .orEmpty()
+val sdJwtData = (pidDocument.data as? SdJwtVcData) ?: return
+
+// Nested object: place_of_birth.country  →  "Greece"
+val birthCountry = sdJwtData
+    .findByPath(ClaimPath(Claim("place_of_birth"), Claim("country")))
+    .firstOrNull()?.value as? String
+
+// Indexed array: nationalities[0]  →  "GR"
+val primaryNationality = sdJwtData
+    .findByPath(ClaimPath(Claim("nationalities"), ArrayElement(0)))
+    .firstOrNull()?.value as? String
+
+// Trailing wildcard: every nationality  →  ["GR", "SE"]
+val nationalities = sdJwtData
+    .findByPath(ClaimPath(Claim("nationalities"), AllArrayElements))
+    .mapNotNull { it.value as? String }
+
+// Non-trailing wildcard: city of every address  →  ["Athens", "Berlin"]
+val addressCities = sdJwtData
+    .findByPath(ClaimPath(Claim("addresses"), AllArrayElements, Claim("city")))
+    .mapNotNull { it.value as? String }
 ```
 
-For arrays of objects (e.g. `addresses[0].city`), combine the two: descend into
-the indexed child, then into its named grand-child:
-
-```kotlin
-val firstAddressCity: String? = (pidDocument.data as? SdJwtVcData)?.claims
-    .orEmpty()
-    .find { it.claimName == "addresses" }
-    ?.children
-    ?.find { it.arrayIndex == 0 }
-    ?.children
-    ?.find { it.claimName == "city" }
-    ?.value as? String
-```
+Each returned node is a full `SdJwtVcClaim` — value, `issuerMetadata`, `children`,
+and `selectivelyDisclosable` are all available for rendering.
 
 ### Other features
 

document-manager/src/main/java/eu/europa/ec/eudi/wallet/document/format/DocumentData.kt

@@ -18,6 +18,7 @@ package eu.europa.ec.eudi.wallet.document.format
 
 import eu.europa.ec.eudi.sdjwt.DefaultSdJwtOps
 import eu.europa.ec.eudi.sdjwt.DefaultSdJwtOps.recreateClaimsAndDisclosuresPerClaim
+import eu.europa.ec.eudi.sdjwt.vc.ClaimPath
 import eu.europa.ec.eudi.sdjwt.vc.ClaimPathElement
 import eu.europa.ec.eudi.sdjwt.vc.SelectPath.Default.query
 import eu.europa.ec.eudi.wallet.document.NameSpace
@@ -248,6 +249,32 @@ data class SdJwtVcData(
         }.map { it.toSdJwtVcClaim() }
     }
 
+    /**
+     * Resolve a [ClaimPath] against the stored claim tree.
+     *
+     * Path elements are matched against [SdJwtVcClaim.pathElement] at each level:
+     *  - [ClaimPathElement.Claim] matches the same object key by name.
+     *  - [ClaimPathElement.ArrayElement] matches the same array index.
+     *  - [ClaimPathElement.AllArrayElements] expands to every array-element child
+     *    at that level (one match per index).
+     *
+     * Examples — for a credential carrying
+     * `nationalities = ["GR", "SE"]` and
+     * `addresses = [{ city = "Athens" }, { city = "Berlin" }]`:
+     *
+     *  - `ClaimPath(Claim("given_name"))` → 1 leaf claim with the user's first name.
+     *  - `ClaimPath(Claim("nationalities"), ArrayElement(0))` → 1 leaf (`"GR"`).
+     *  - `ClaimPath(Claim("nationalities"), AllArrayElements)` → 2 leaves (`"GR"`, `"SE"`).
+     *  - `ClaimPath(Claim("addresses"), AllArrayElements, Claim("city"))` → 2 leaves
+     *    (`"Athens"`, `"Berlin"`).
+     *
+     * Returns an empty list when no path element matches. The returned nodes carry
+     * the full [SdJwtVcClaim] (value, issuer metadata, children, selectively-
+     * disclosable flag) so the caller can render them directly.
+     */
+    fun findByPath(path: ClaimPath): List<SdJwtVcClaim> =
+        findInTree(claims, path.value)
+
     companion object {
         internal val ExcludedIdentifiers = arrayOf(
             "cnf",
@@ -260,6 +287,28 @@ data class SdJwtVcData(
     }
 }
 
+/**
+ * Walks [remaining] path elements over [nodes], descending into children as needed.
+ * When `remaining` is empty, returns the current matched [nodes].
+ */
+private fun findInTree(
+    nodes: List<SdJwtVcClaim>,
+    remaining: List<ClaimPathElement>,
+): List<SdJwtVcClaim> {
+    if (remaining.isEmpty()) return nodes
+    val head = remaining.first()
+    val tail = remaining.drop(1)
+    val matched = nodes.filter { it.matches(head) }
+    return if (tail.isEmpty()) matched
+    else matched.flatMap { findInTree(it.children, tail) }
+}
+
+private fun SdJwtVcClaim.matches(element: ClaimPathElement): Boolean = when (element) {
+    is ClaimPathElement.Claim -> claimName == element.name
+    is ClaimPathElement.ArrayElement -> arrayIndex == element.index
+    ClaimPathElement.AllArrayElements -> pathElement is ClaimPathElement.ArrayElement
+}
+
 /**
  * Represents a claim of a document in the SdJwtVc format.
  *

document-manager/src/test/java/eu/europa/ec/eudi/wallet/document/format/SdJwtVcDataTest.kt

@@ -19,12 +19,15 @@ package eu.europa.ec.eudi.wallet.document.format
 import eu.europa.ec.eudi.sdjwt.DefaultSdJwtOps
 import eu.europa.ec.eudi.sdjwt.DefaultSdJwtOps.recreateClaimsAndDisclosuresPerClaim
 import eu.europa.ec.eudi.sdjwt.SdJwt
+import eu.europa.ec.eudi.sdjwt.vc.ClaimPath
+import eu.europa.ec.eudi.sdjwt.vc.ClaimPathElement
 import eu.europa.ec.eudi.wallet.document.getResourceAsText
 import eu.europa.ec.eudi.wallet.document.metadata.IssuerMetadata
 import kotlinx.serialization.json.JsonObject
 import kotlin.test.BeforeTest
 import kotlin.test.Test
 import kotlin.test.assertEquals
+import kotlin.test.assertTrue
 
 class SdJwtVcDataTest {
 
@@ -72,6 +75,127 @@ class SdJwtVcDataTest {
         )
     }
 
+    /**
+     * Top-level claim by name returns exactly one entry whose value matches the
+     * issuer-provided disclosure.
+     */
+    @Test
+    fun `findByPath returns the single top-level claim by name`() {
+        val data = sdJwtVcData()
+
+        val result = data.findByPath(
+            ClaimPath(ClaimPathElement.Claim("given_name"))
+        )
+
+        assertEquals(1, result.size, "expected exactly one match for given_name")
+        assertEquals("Tyler", result.first().value)
+    }
+
+    /**
+     * A nested object path (`place_of_birth.country`) descends through `children`
+     * and returns the leaf claim with the inner value.
+     */
+    @Test
+    fun `findByPath descends into nested object members`() {
+        val data = sdJwtVcData()
+
+        val result = data.findByPath(
+            ClaimPath(
+                ClaimPathElement.Claim("place_of_birth"),
+                ClaimPathElement.Claim("country"),
+            )
+        )
+
+        assertEquals(1, result.size, "expected one nested leaf for place_of_birth.country")
+        assertEquals("AT", result.first().value)
+    }
+
+    /**
+     * Indexed array access (`nationalities[0]`) resolves through the parent's
+     * `ArrayElement(0)` child.
+     */
+    @Test
+    fun `findByPath resolves an array element by index`() {
+        val data = sdJwtVcData()
+
+        val result = data.findByPath(
+            ClaimPath(
+                ClaimPathElement.Claim("nationalities"),
+                ClaimPathElement.ArrayElement(0),
+            )
+        )
+
+        assertEquals(1, result.size, "expected one match for nationalities[0]")
+        assertEquals("AT", result.first().value)
+    }
+
+    /**
+     * The trailing `AllArrayElements` wildcard fans out across every array-element
+     * child. The fixture's `nationalities` array has one entry, so we expect one
+     * match — and the matched node is the array-element wrapper, not the parent.
+     */
+    @Test
+    fun `findByPath expands the trailing wildcard to every array element`() {
+        val data = sdJwtVcData()
+
+        val result = data.findByPath(
+            ClaimPath(
+                ClaimPathElement.Claim("nationalities"),
+                ClaimPathElement.AllArrayElements,
+            )
+        )
+
+        assertEquals(1, result.size, "fixture has 1 nationality entry, got ${result.size}")
+        assertTrue(
+            result.all { it.pathElement is ClaimPathElement.ArrayElement },
+            "expected ArrayElement wrappers, got ${result.map { it.pathElement }}",
+        )
+    }
+
+    /**
+     * A path that does not exist anywhere in the credential resolves to the empty
+     * list — never an exception.
+     */
+    @Test
+    fun `findByPath returns empty list when nothing matches`() {
+        val data = sdJwtVcData()
+
+        val result = data.findByPath(
+            ClaimPath(ClaimPathElement.Claim("does_not_exist"))
+        )
+
+        assertTrue(result.isEmpty(), "expected no matches, got $result")
+    }
+
+    /**
+     * Two-level descent into a different nested object (`address.region`) — sanity
+     * that the recursive descent works for any object key, not just one fixture
+     * field.
+     */
+    @Test
+    fun `findByPath handles deeper nested objects`() {
+        val data = sdJwtVcData()
+
+        val result = data.findByPath(
+            ClaimPath(
+                ClaimPathElement.Claim("address"),
+                ClaimPathElement.Claim("region"),
+            )
+        )
+
+        assertEquals(1, result.size, "expected one match for address.region")
+        assertEquals("Lower Austria", result.first().value)
+    }
+
+    /**
+     * Wrap the same `SdJwtVcData` construction every `findByPath` test uses.
+     */
+    private fun sdJwtVcData() = SdJwtVcData(
+        format = SdJwtVcFormat(vct = "urn:eu.europa.ec.eudi:pid:1"),
+        issuerMetadata = metadata,
+        sdJwtVc = sdJwtVcString,
+    )
+
     private fun printSdJwtVcClaims(sdJwtVcClaims: List<SdJwtVcClaim>, indent: String = "") {
         for (sdJwtVcClaim in sdJwtVcClaims) {
             println("$indent- PathElement: ${sdJwtVcClaim.pathElement}")