⚠️ This is a developmental version of the guide and is under active development. Content may change at any time without notice. No official release has been made. The final base canonical URL and hosting location have not yet been determined. This guide should not be used for production implementations.

2.3. CDS Hooks Card Guidance for USCDI+ CTM

This section provides guidance for how USCDI+ CTM implementations should use CDS Hooks cards in the Provider-initiated Scenario. This guidance does not redefine the CDS Hooks card structure, required fields, rendering model, or response semantics. Those are defined by the CDS Hooks specification. Instead, this section defines CTM-specific semantic conventions and recommended usage patterns so that CTM-related CDS Hooks responses are more understandable and more consistent across implementations.

2.3.1. Relationship to CDS Hooks

CDS Hooks defines the core card model, including:

• The cards array in a successful response
• Required card fields such as:
  • summary
  • indicator
  • source
• Optional card content such as:
  • detail
  • links
  • suggestions
  • selectionBehavior
  • overrideReasons

This IG uses the CDS Hooks structures as defined in the CDS Hooks specification and adds guidance regarding:

• Recommended semantic card categories
• Intended meaning of those categories
• When each category should be used
• Recommended content conventions for CTM workflows

These categories are semantic conventions only. They are not new CDS Hooks card types. This IG does not currently standardize:

• Exact card wording
• The number of cards returned for a given situation
• Trial ranking or scoring language
• Specific trial metadata displayed in cards
• UI rendering behavior
• Workflow implementation details

Those behaviors remain implementation-specific and subject to the CDS Hooks specification and local workflow requirements.

2.3.2. CTM Card Categories

Implementations should retain flexibility to tailor wording, links, workflow actions, and presentation to local workflow needs. However, implementations should use a shared set of semantic card categories so that users and implementers can consistently interpret CTM card meaning across deployments. The following semantic card categories are recommended for USCDI+ CTM the Provider-initiated Scenario:

• Match / Multiple Matches Found
• Missing Information
• No Match

These categories describe the intended meaning of the card content. They do not modify the CDS Hooks card schema.

2.3.3. Card Usage by Category

The following table summarizes when to use each semantic card category and the recommended behavior. These categories describe intended meaning only; they do not modify the CDS Hooks card schema.

Category	When to Use	Typical User Meaning	Recommended indicator	Recommended Card Behavior	Semantic Expectation
Match / Multiple Matches Found	The service identifies one or more candidate clinical trials using the CTM-relevant data provided.	One or more potential candidate trials were identified; the clinician should review details, links, or follow-up actions.	info	SHOULD indicate in summary that matches were found SHOULD explain in detail why the patient may qualify SHOULD use links for trial details, referral, or review apps MAY use suggestions for workflow actions MAY return one summary card for multiple matches, or multiple cards	A candidate match only — not a definitive eligibility determination.
Missing Information	The service cannot perform a meaningful evaluation because required or important CTM-relevant data is missing, incomplete, unavailable, or potentially outdated.	Matching could not be completed reliably; additional information may be required.	warning	SHOULD indicate in summary that data is missing or insufficient SHOULD identify missing data categories in detail MAY use suggestions to guide follow-up actions MAY use links for workflow support or documentation	Evaluation could not be completed with sufficient confidence. Not to be confused with No Match: this category means matching was not possible due to missing data, not that matching completed and found nothing.
No Match	The service completes evaluation using the available CTM data and finds no candidate clinical trial matches.	Matching was attempted and completed; no matches at this time.	info	SHOULD state in summary that no matches were found MAY explain in detail that the result reflects currently available data MAY provide links to broader search or review resources	Evaluation completed successfully with no matches found. Not to be confused with Missing Information: do not use this category when evaluation was limited by missing or incomplete data.

For the Match category, a single card MAY represent one candidate trial or summarize multiple candidate trials, and implementations MAY return either one summary card for multiple matches or multiple cards, depending on workflow needs.

2.3.4. Card Content Conventions

Across all CTM card categories, implementations SHOULD apply the following field conventions.

Field	Convention
summary	SHOULD be concise, clinically understandable, action-oriented when appropriate, and readable in compact UI contexts.
detail	SHOULD provide additional context when appropriate, avoid overstating clinical certainty, use language appropriate for clinical workflow, and clearly distinguish among candidate-match results, missing-data conditions, and completed no-match evaluations.
source.label	SHOULD clearly identify the CTM service or program generating the card, using stable and recognizable labels so users can distinguish CTM cards from other CDS services.
indicator	info — generally appropriate for match and no-match cards. warning — generally appropriate for missing-information cards and often for workflow advisories. critical — SHOULD be used sparingly and reserved for situations requiring immediate attention. Definitions and rendering remain governed by the CDS Hooks specification.
links	Recommended when users may need access to trial details, CTM review workflows, referral workflows, supporting documentation, or CTM applications / SMART app launches.
suggestions	Optional; SHOULD only be used when the implementation supports a clear workflow action.

2.3.5. Example CTM CDS Hooks Cards

Representative examples of CTM CDS Hooks cards for the Provider-initiated Scenario are maintained on a dedicated page to keep this specification focused on conformance guidance. These examples illustrate recommended semantic usage patterns for the CTM card categories. They are not intended to define the only acceptable representations.

The table below summarizes the available examples and the card category, typical indicator, and CDS Hooks features each one demonstrates. See the full, copyable JSON for every example on the example CTM CDS Hooks Cards page.

Card Category	Typical indicator	Demonstrates	Reference
Match / Multiple Matches Found	info	summary, detail, source, links	Example 1
Missing Information	warning	Distinguishing missing data from a no-match result; links to data requirements	Example 2
No Match	info	A completed evaluation with no candidate matches	Example 3