Lack of examples for iterable fields

[victoriaosunablanco]

When creating a phenopacket, some fields must be provided as lists (for example, interpretations or biosamples), whereas others do not require this, such as individual. Without a complete example of how to create a phenopacket in Python, this behavior is difficult to infer, which complicates the initial implementation steps. Including clear, working examples would be extremely helpful.

[julesjacobsen]

@victoriaosunablanco is this a problem with the Python library or the documentation?

[ielis]

Hello @victoriaosunablanco
this is to some extent addressed in the Working with Phenopackets in Python page.

The Create building blocks programmatically shows how to import all v2 schema elements and then how to combine them to build a larger structure, such as phenopacket. The docs show how to assign a value to a singular (non-message) field, to a non-singular field (using CopyFrom), and to a repeated field (iterable in your message).

In my opinion, the examples show the complete picture. However, I admit that the docs are somewhat terse, and more examples could be helpful.

I could draft a PR, @julesjacobsen let me know if you think it is a good idea.

[victoriaosunablanco]

This is primarily a documentation issue rather than a problem with the Python library itself. The library appears to function as intended once the correct structure is understood, but the documentation does not clearly explain which fields must be provided as lists and which can be provided as single objects when constructing a phenopacket. Having an example that more clearly illustrates how to act in this situation, ideally a small, complete Python example showing both list-based fields (such as interpretations or biosamples) and singular fields (such as individual), would be greatly appreciated and very helpful for new users during the initial implementation.

…

On Tue, Jan 20, 2026 at 6:49 PM Jules Jacobsen ***@***.***> wrote: *julesjacobsen* left a comment (ga4gh/phenopacket-schema#416) <#416 (comment)> @victoriaosunablanco <https://github.com/victoriaosunablanco> is this a problem with the Python library or the documentation? — Reply to this email directly, view it on GitHub <#416 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/BZQ3OLROCR5M6LN4MBQT7G34HZTCZAVCNFSM6AAAAACOPAKKIOVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTONZUGE4DEMRXGM> . You are receiving this because you were mentioned.Message ID: ***@***.***>