GH-22342: [Format][Documentation] Clarify Union type ids

[erichanwang]

Rationale for this change

The Union layout documentation does not explain that the type IDs stored in the types buffer can differ from the child array indices, or how the optional typeIds metadata maps children to physical type IDs.

What changes are included in this PR?

• Document the relationship between Union child array indices, physical type IDs, and the optional typeIds metadata.
• Clarify that the types buffer stores the type ID for each slot.

Fixes #22342.

Are these changes tested?

git diff --check passes and the RST change was reviewed against Schema.fbs and the existing Union layout documentation. A local Sphinx/RST checker is not installed in this environment.

Are there any user-facing changes?

No.

• GitHub Issue: [Format][Documentation] add discussion of Union.typeIds to Layout.rst  #22342

[github-actions]

⚠️ GitHub issue #22342 has been automatically assigned in GitHub to PR creator.

[erichanwang]

Formatting follow-up:

• Wrapped the new Union type-id paragraph to match the surrounding Arrow RST line-wrapping style.
• git diff --check passes; no semantic content changed.

[uros-b]

Nice focused improvement, LGTM!

[github-actions]

⚠️ GitHub issue #22342 has been automatically assigned in GitHub to PR creator.

[pitrou]

@paleolimbot @tustvold @alamb What do you think about these clarifications in the format spec?

[tustvold]

I think the change makes sense, an example might clear up any remaining ambiguity

[tustvold]

It isn't clear from this how they actually do this, I think an example would make it clear.

[paleolimbot]

Also possibly calling it just typeIds metadata (the term "array" here I believe is talking about a different kind of array than it is later in the paragraph)

[paleolimbot]

Definite improvement! I found this confusing when I implemented it. I don't believe that creating these types of unions is common (and agreed that an example would help).

For what it's worth, GeoArrow does use these and does use meaningful type IDs (although they aren't widely used compared to the other types in the spec). https://geoarrow.org/format.html#geometrycollection

[paleolimbot]

Also possibly calling it just typeIds metadata (the term "array" here I believe is talking about a different kind of array than it is later in the paragraph)

[alamb]

Thanks @pitrou -- this seems like an improvement to me

I think @tustvold and @paleolimbot 's suggestions are good ones too, but I also think this could be merged as is as it is an improvement over the current version in my mind

[pitrou]

I've applied some minor modifications to address some of the comments, in the interest of moving this forward.

I think adding an example can be done in a followup task if someone is motivated to do so.

[pitrou]

I'll wait for CI and then merge.