Page tree
Skip to end of metadata
Go to start of metadata

Currently designation.use allows to specify that the designation is a synonym or a fully specified name. It is proposed that "Consumer-friendly term" is to be added to the value set.

By SNOMED standards, there are three distinct aspects that should be managed by designation.*:

  • the description type (Synonym or Fully specified name (or Definition), <900000000000446008 |Description type (core metadata concept)|)
  • the language reference set (e.g. 900000000000508004 | Great Britain English language reference set (foundation metadata concept) |, 281000210109 | NZ patient-friendly language reference set (foundation metadata concept) |, 500191000057100 | Laboratory medicine context language type reference set (foundation metadata concept) |. <900000000000506000 | Language type reference set (foundation metadata concept) |)
  • the acceptability of the description in that language reference set (<900000000000511003 | Acceptability (foundation metadata concept) |)

Specification of these aspects would be required for both querying (term filtering with $expand, I cannot see that the specification allows this!) and for results ($lookup and $expand). $expand has distinct IN parameters whereas $lookup relies on properties. The language for X.display is specified by displayLanguage parameter for $lookup and $expand.

Proposal to create an extension to designation to allow unambiguous specification of the three aspects above, including a specification on how designation.use shall be used with SNOMED CT.

Behaviour when parameters are not specified (defaults) and/or when there are no descriptions meeting criteria (fall back) should be specified.


  1. For the $expand operation we need to be able to specify one or more "Context of Use" which would allow us to specify such, and in a SNOMED CT context this would be a language reference set.   Are we adjusting the display element in these cases?     This will be irrespective of language ie include that designation regardless of the language specific or featured in that description.
  2. In the designation as part of the response, we want to specify an array of "contexts of use" for each term, which specifies if the term is acceptable, preferred or ?unacceptable for that context.   ML:  We would only return designation that match the given language reference sets and allow the client to decide the order of preference.
  3. Do we want to specify Preferred or Acceptable in the request?  Or can we assume Preferred.   ML Suggested that we'd return all and let the client decide which it wants.

Further questions - when filtering do we need to indicate the language used in the search criteria such that only terms in that language should be matched against it?

Defaults and fallbacks - if there are no terms found matching the specified context of use then we have the option of returning some (server decides) fallback term and indicating "unacceptable"

Note that we can already return designations in languages that differ from that of the ValueSet itself using ValueSet.compose.include.concept.designation.language

Update 25 Feb 2020:  Group expressed concern about "Patient Friendly Terms" 

What are we going to call the extension - not SNOMED.  In general we're looking to return additional information about designations and specify.      

Update 3 Nov 2020:  DL Suggests we change cardinality to stop reason from being mandatory.   ML suggests we improve on "code" as an element name since it offers no indication of usage.   See also ticket on lack of CodeSystem for these element value:   TODO Provide example bindings for <URI for a ValueSet eg < 900000000000511003 |Acceptability| > (example) both SNOMED and other.

Question: would should be assumed if the use role is not supplied?  We avoid this question by making the "role" mandatory - but what would the valueset be for non-SNOMED use cases?

Next Steps: Vocab call next week Rob Hausamwhat is this group's position?  DL "We have an extension that clarifies some aspects of designation.use and we're happy to discuss further"   The SNOMED description type appearing in ValueSet.compose.include.concept.designation.use is not terribly useful and our proposal for designation.context.use would improve the semantics.   RH "Will be good to get comments here and probably also a topic on the Zulip terminology stream, before having discussion and/or vote on the Vocab call"

There is a designation use context branch of the snomed-ig here:

These can be used with both CodeSystem $lookup and ValueSet $expand

Extension Input parameters

Token 0..* designationUseContext  (this will be the language reference set SCTID, potentially a number of them)

Example:   designationUseContext=|32570271000036106&designationUseContext=|123456

Note group discussed also passing through the reason, but a) there's no way to pair it with a particular code and b) this is only about reducing the amount of data going over the wire.   The client will be able to sort out if it just wants the preferred term.

Question:  Is the list of refsets a prioritised list (ie return the first one), or is this "OR".  ANSWER: It is OR, no priority indicated (this is true in general of REST parameters).   Note that the client, again, could sort out if it wanted one or all.  Answer:   It is the designation that states which ones you want to see.  If you've asked only for one then we'd return the first acceptable language reference set.   If more are wanted, then more languages can be specified for designations.   Doesn't help with language reference sets in the same language.

10 March: Further discussion of whether we could set the display field to be a preferred synonym.   ML makes point that implementations may not have access to the original URL to determine the order of language reference sets.

Question: How will this interact with the display value?  "Display is set by the code System"

Note: using this parameter implies that includeDesignations=true

Extension Output parameters - for ValueSet $expand

0..* ValueSet.expansion.concept.designation.designationUseContext    Element

1..* ValueSet.expansion.contains.concept.designation.designationUseContext.code     Coding (this will be the language reference set SCTID)

0..1 ValueSet.expansion.contains.concept.designation.designationUseContext.role Coding   (this will be our <! 900000000000511003 |Acceptability (foundation metadata concept)|

Extension Output parameters - for CodeSystem $lookup

0..* Parameters.designation.designationUseContext    Element

1..* Parameters.designation.designationUseContext.code     Coding (this will be the language reference set SCTID)

0..1 Parameters.designation.designationUseContext.role   Coding   (this will be the SNOMED acceptability <! 900000000000511003 |Acceptability (foundation metadata concept)| )

Note that a designation could appear in multiple language referencesets, so a given term may have a number of designationUseContext elements (hence 0..* cardinality).    Option instead to have multiple instances of the extension.

  • Peter G. WilliamsUpdate examples for both CodeSystem and ValueSet expansions input and output

Designation Extension Example

Tooling and Expertise

URI for extension 

Choice of : XML, FHIR Shorthand with Sushi command line processor (see documentation here), Fhirly (licencing issue?)

Note edition URIs:  4.4.2 Edition URI Examples

Update 10 March: 

Structure Definition in FSH


See also

Extension: DesignationUseContextExtension
Id: designation-use-context
Title: "Designation Use Context Extension"
Description: """
Extension to allow specific contexts of use (eg SNOMED Language Reference Sets,
LOINC short name, long common name, consumer name, as well as ICD-10 rubrics)
to be specified when working with designations
* ^context[0].type = #fhirpath
* ^context[0].expression = "(CodeSystem|ValueSet).descendants().select(designation)"
* ^context[1].type = #element
* ^context[1].expression = "Parameters.parameter"
* extension contains
context 0..1 and
role 0..1 and
type 0..1
* extension[context] ^short = "Designation use context"
* extension[context].value[x] only Coding
* extension[context].valueCoding from (example)
* extension[role] ^short = "Role of designation in context"
* extension[role].value[x] only Coding
* extension[role].valueCoding from (example)
* extension[type] ^short = "Type of designation in context"
* extension[type].value[x] only Coding
* extension[type].valueCoding from (example)


  • For extension[code] there must be a fixed system, otherwise we need to use a Coding. If we want to generalise beyond SNOMED Language Refsets, eg to LOINC, then I think this must change.
  • 'code' is probably not a useful field name – this  actually identifies the context, so I would call it 'context' or 'useContext'
  • Again, if binding is other than 'required' and thus the code system can vary, this should be a Coding.
  • For SNOMED understanding, when we say Designation Use Context we're thinking of Language Reference Sets.

  • No labels


  1. As I read the FHIR R4 specification, the (token) designation input parameter to the $expansion operation is not constrained to a particular Code System and/or Concept.

    Therefore, IMHO, where SNOMED CT is the Code System, the code does NOT have to come from the Designation Use Value Set documented at  It's only what is returned in the contains → designation→ use elements of the ValueSet expansion that is currently constrained to that (extensible) Value Set.

    Hence, I still believe that it is acceptable to pass a Language Reference Set Identifier in the Request token and, as the cardinality of that parameter is 0..*, it satisfies the 'multiple contexts of use' requirement.

    The remaining question is how to specify the context of use in the response!

  2. I think the proposed extension only make sense for SNOMED CT since it is addressing semantics quite specific to Language Reference Sets (which actually are only about specifying Acceptability).  See for the relevant structure.