ValueSet - compose versus expansion

I’m defining some ValueSets for use with an application and am looking for some guidance on when to use the compose property versus the expansion property to specify the values.

For a simple ValueSet that returns all contents of a code-system, definition is simple via compose.include. However, I noticed that when I retrieve this ValueSet via the $expand operation, it returns the values in the expansion property. Why is that?

For a ValueSet that represents a subset of a code-system - e.g. a set of ICD-10 codes - it seems that using the compose.include property is the way to go, explicitly specifying the codes I want included.

When would I define a ValueSet using the expansion property? Or, is this property only intended to be populated by a server in the response to an $expand API call?

Many thanks!

Our recommendation is that you do not define a value set by means of expansion, and that expansion is only intended to be populated by a terminology server in response to the $expand call. It’s a matter of the difference between ‘here’s the rules’ and ‘here’s what the applying the rules ends up meaning’ - storing and using the second is fragile over time, as the context in which the rules exists changes. But many terminology frameworks - some in wide use - only store and distribute the expansions. And there are cases where pre-computing and storing the expansions is useful even where you have terminology servers that can compute the $expand operation ubiquitiously available.

For these reasons, we allow the expansion - and sometimes only the expansion - to be stored and exchanged, even though our recommendation is that you always use $compose except in the response to $expand

Thank you Graham. Exactly what I was looking for. Cheers!