I've noticed that when the RESTful call https://api.firecloud.org/#!/Entities/getEntity is issued on a sample_set entity the payload returned contains an attributes sub-object, one of the members of which is "samples".
This gave me pause and does not strike me as ideal, because it conflates containment (or membership) with annotation. That is, attributes are metadata attached to an entity, which serve to annotate it in flexible and essentially boundless ways; but samples are the constituent elements contained by that entity.
These are fundamentally different, so I would argue that the "samples" field be removed from the "attributes" sub-object, and instead promoted to being its own field "members," living at the same level as "attributes" in the returned object:
IE, for container entities (like sample_set etc) the top-level of the payload returned by getEntity changes from
[u'attributes', u'entityType', u'name']
to
['u''members', u'attributes', u'entityType', u'name']
Think of a suitcase model of how data flows through the system: ATTRIBUTES are metadata like the weight & height of the suitcase, the shipping label and all of its passport stamps (e.g. as the data flow through various algorithms and are successively annotated with the outputs of each); while members are the actual contents INSIDE the suitcase.
More support for this viewpoint (e.g. that samples are "members" rather than "attributes" of a sample_set) is given in the difference between so-called "MEMBERSHIP" and "UPDATE" load files as described in the docs, e.g. the DataModel section of the FireCloud Basics content: