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.       

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..1 ValueSet.expansion.contains.concept.designation.designationUseContext.code     Coding (this will be the language reference set SCTID)

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

Extension Output parameters - for CodeSystem $lookup

0..* Parameters.designation.designationUseContext    Element

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

1..1 Parameters.designation.designationUseContext.reason   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)

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

Extension: DesignationUseContextExtension 
Id: designation-use-context
Title: "Designation Use Context Extension"
Description: "Extension to allow specific contexts of use (eg SNOMED Language Reference Sets) to be specified when working with designations"
* ^context[0].type = element
* ^context[0].expression = "ValueSet.expansion.concept.designation"
* ^context[1].type = element
* ^context[1].expression = "Parameters.parameter"
* extension contains
    code 1..1 and
    reason 1..1 // inline definition of sub-extensions
* extension[code] ^short = "Language Reference Set"
* extension[code].value[x] only code
* extension[code].valueCode from <URI for a ValueSet eg < 900000000000506000 |Language type reference set (foundation metadata concept)| > (example)
* extension[reason] ^short = "Acceptability"
* extension[reason].value[x] only code
* extension[reason].valueCode from <URI for a ValueSet eg < 900000000000511003 |Acceptability (foundation metadata concept)| > (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.

  • No labels

1 Comment

  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!