Vignette: Nested Entities

[jonthegeek]

Decide whether this is the right approach for point 5 from api2r/rapid#92, and then implement it if so:

5. Nested Entities: Unpacking vs. Path-Vector Keys

Tibblify offers two approaches for nested data:

1. Path-vector keys: Flatten at parse time using c("owner", "name")
2. Nested tib_row()/tib_df(): Parse as nested tibbles, optionally unpack() later

Each has tradeoffs that aren't well documented:

# approach 1: flatten with path vectors (loses structure)
tspec_df(
  id = tib_int("id"),
  owner_name = tib_chr(c("owner", "name")),      # flattened key
  owner_email = tib_chr(c("owner", "email")),    # must prefix to avoid collisions
  address_city = tib_chr(c("address", "city"))
)

# approach 2: preserve nesting with tib_row (keeps structure)
tspec_df(
  id = tib_int("id"),
  owner = tib_row(
    "owner",
    name = tib_chr("name"),
    email = tib_chr("email")
  ),
  address = tib_row(
    "address",
    city = tib_chr("city"),
    state = tib_chr("state")
  )
)
# then optionally: tidyr::unpack(result, c(owner, address))

Path vectors are simpler but:

• Lose the original nesting structure
• Require manual prefixing to avoid column name collisions
• Make it harder to extract related fields as a unit
• Don't map cleanly back to the source schema for round-tripping

Nested tib_row/tib_df preserves structure but:

• Creates tibble columns that some downstream code doesn't expect
• Requires explicit unpack() calls if you want flat output
• The relationship between unpack options and tib_row() isn't clear

For database normalization workflows, I need to extract nested entities into separate tables with proper foreign keys. Nested tib_df() is ideal for this—but the documentation doesn't cover these patterns.

Suggestion: A vignette on when to use path-vector keys vs. nested specs, the unpack workflow, and extracting nested tibbles for relational database use cases.