RecommendationFragment

Part of the WebMEM® Protocol
Fragment Class: RecommendationFragment
Location: /protocol/fragments/recommendationfragment/
Status: Current Draft
Last Updated: 2026-08-24

Overview

A RecommendationFragment is a WebMEM fragment class for publishing a structured recommendation or action-oriented handoff within a defined context.

Each RecommendationFragment establishes what is being recommended, the entity, subject, need, or context to which the recommendation applies, the basis for the recommendation, any conditions or limitations governing its applicability, and the endpoint or next action when one exists.

Unlike an ExplainerFragment, which explains a subject, or a DataFragment, which represents source-observed factual knowledge, a RecommendationFragment represents a publisher-defined recommendation about what action, resource, option, or next step is appropriate within a specified context.

A RecommendationFragment may include disclosures, alternatives, fallbacks, eligibility or timing conditions, and provenance necessary to understand why the recommendation is being made and when it applies.

Semantic Purpose

The semantic purpose of a RecommendationFragment is to state:

Within this defined context and subject to these conditions, this is the action, resource, option, or next step the publisher recommends, and this is the basis for that recommendation.

A RecommendationFragment may establish:

the subject or entity to which the recommendation applies;
the recommended action, resource, option, or next step;
the conditions under which the recommendation applies;
the factual, policy, procedural, or contextual basis for the recommendation;
the destination or endpoint associated with the recommendation;
the operator or organization responsible for that destination when applicable;
required disclosures;
alternative or fallback resources;
limitations or exclusions;
relationships to supporting knowledge objects;
and provenance supporting the recommendation.

The RecommendationFragment preserves these elements as one coherent recommendation knowledge object.

RecommendationFragment Within an SDT

A RecommendationFragment exists as one modular knowledge object within a Semantic Data Template (SDT).

The relationship is:

Web Resource → SDT → RecommendationFragment → Recommended Action or Resource

An SDT may contain one RecommendationFragment or multiple RecommendationFragments when different contexts, needs, audiences, conditions, or outcomes require different recommendations.

A RecommendationFragment may reference other fragments within the SDT when the recommendation depends on facts, eligibility criteria, policies, procedures, explanations, directories, personas, or other structured knowledge.

This allows the recommendation to remain independently identifiable while preserving the knowledge supporting why and when it applies.

RecommendationFragment Requirements

A conforming RecommendationFragment should establish enough information to understand what is being recommended, why it is being recommended, and the context within which the recommendation applies.

Element	Purpose
Fragment Class	Identifies the knowledge object as a `RecommendationFragment`.
Fragment ID	Provides a stable identifier for the RecommendationFragment within the published knowledge structure.
Recommendation Subject	Identifies the entity, need, decision, task, or context to which the recommendation applies.
Recommended Action	Identifies the action, resource, option, destination, or next step being recommended.
Basis	Identifies the facts, criteria, policies, circumstances, or other knowledge supporting the recommendation.
Applicability	Identifies conditions, timing, jurisdiction, audience, eligibility, exclusions, or other limitations governing when the recommendation applies.
Provenance	Identifies or references the source and lineage supporting the recommendation and its basis.

Endpoints, operator information, disclosures, alternatives, fallbacks, and related knowledge references may be included when appropriate to the recommendation.

Recommendation Basis

A RecommendationFragment should make the basis for its recommendation explicit.

The basis may include:

source-observed facts;
derived statistics;
eligibility criteria;
policy requirements;
procedural requirements;
geographic context;
timing or availability;
defined user or persona context;
comparison criteria;
or other publisher-known information relevant to the recommendation.

A recommendation should not be represented as though it follows from supporting knowledge when that relationship has not actually been established by the publisher.

Where the recommendation depends on knowledge represented elsewhere within the SDT, explicit relationships may reference those supporting fragments or Machine Fact Objects rather than duplicating them.

Applicability and Conditions

A recommendation may apply only within a defined set of conditions.

Applicability may depend on:

geographic location;
jurisdiction;
eligibility;
availability;
time period or enrollment window;
program status;
user or persona context;
known facts;
policy conditions;
or other explicitly represented criteria.

Conditions that materially affect whether a recommendation applies should be represented as part of the recommendation rather than left to inference.

Recommended Actions and Endpoints

A RecommendationFragment may identify a specific next action or destination when the recommendation involves a handoff.

An endpoint may identify:

the name of the destination;
the canonical URL or resource identifier;
the organization or operator responsible for the destination;
ownership or affiliation information when relevant;
the action available at the destination;
conditions governing use of the destination;
and disclosures necessary to understand the relationship between the publisher, operator, and recommended resource.

The endpoint should represent the actual destination associated with the recommendation rather than merely a promotional reference.

Alternative and Fallback Resources

A RecommendationFragment may identify alternative or fallback resources when more than one valid path exists or when a primary recommendation may not apply in every circumstance.

Fallbacks may include:

an official government resource;
an authoritative source;
an alternate provider or service;
a different procedural path;
another directory or resolver;
or another appropriate resource available within the declared context.

Providing an alternative does not imply that the alternatives are equivalent. The relationship between the primary recommendation and any fallback should remain explicit.

Example RecommendationFragment

The following example represents a Medicare enrollment handoff using the current WebMEM HTML serialization.

<template
  data-webmem-fragment
  data-fragment-class="RecommendationFragment"
  data-fragment-id="recommend-medicare-enrollment">

  <section
    data-entity-type="Recommendation"
    data-entity-id="recommendation:medicare-enrollment"
    data-provenance-ref="#provenance-medicare-enrollment">

    <h3 data-role="recommendation-subject">
      Medicare Plan Enrollment
    </h3>

    <p data-role="recommended-action">
      Compare available Medicare plans and use an appropriate
      enrollment resource when you are ready to enroll.
    </p>

    <div data-role="applicability">

      <meta
        data-condition="country"
        content="US">

      <meta
        data-condition="enrollment-window"
        content="applicable">

    </div>

    <div data-role="primary-endpoint">

      <a
        data-role="canonical-resource"
        href="https://www.medicare.org/enroll/">
        Medicare.org Enrollment Resource
      </a>

      <span data-role="operator">
        HealthCompare Insurance Services, Inc.
      </span>

    </div>

    <div data-role="fallback-endpoint">

      <a
        data-role="canonical-resource"
        href="https://www.medicare.gov/plan-compare/">
        Medicare.gov Plan Compare
      </a>

    </div>

  </section>

</template>

The fragment establishes that:

the knowledge object is a RecommendationFragment;
the fragment has a stable identity;
the subject of the recommendation is explicitly identified;
the recommended next action is explicit;
conditions governing applicability are represented;
the primary endpoint and its operator are identified;
an alternative official resource is provided;
and provenance supporting the recommendation can be resolved through the referenced provenance object.

RecommendationFragment and ExplainerFragment

RecommendationFragment and ExplainerFragment may participate in the same decision context but serve different semantic purposes.

ExplainerFragment	RecommendationFragment
Explains a subject, decision, relationship, or set of tradeoffs.	Represents a recommendation about an action, resource, option, or next step.
Answers: How should this subject or decision be understood?	Answers: What does the publisher recommend within this context?
May explain available options without preferring one.	Explicitly identifies a recommended action or option.
Provides explanatory structure.	Provides recommendation structure and its basis.

An ExplainerFragment may therefore explain the available choices while a RecommendationFragment separately represents a publisher-defined recommendation among or beyond those choices.

RecommendationFragment and PersonaFragment

A PersonaFragment may provide context relevant to a recommendation, but the persona itself is not the recommendation.

A RecommendationFragment may reference a PersonaFragment when the recommendation applies to the circumstances, goals, constraints, or values represented by that persona.

For example:

Persona Context → Supporting Knowledge → RecommendationFragment → Recommended Resource

The recommendation should preserve its own basis and limitations rather than treating similarity to a persona as sufficient justification for the recommendation.

RecommendationFragment and EligibilityFragment

A recommendation may depend on eligibility requirements represented by an EligibilityFragment.

For example, a program or product should not be recommended as applicable when the publisher’s own eligibility knowledge establishes that the required conditions are not satisfied.

The relationship may take the form:

EligibilityFragment → Qualification Conditions → RecommendationFragment

The EligibilityFragment represents the qualification logic. The RecommendationFragment represents the action or resource recommended within the qualifying context.

RecommendationFragment and DirectoryFragment

A DirectoryFragment may expose the available entities, products, providers, services, or resources within a defined context.

A RecommendationFragment may identify one of those entries, a subset of entries, or a next action involving the directory when the publisher has an explicit basis for doing so.

This preserves the distinction between:

DirectoryFragment: what options or resources are available;
RecommendationFragment: what action or resource the publisher recommends within the defined context.

RecommendationFragment and PolicyFragment

A recommendation may be constrained by rules represented in a PolicyFragment.

For example, a recommended enrollment action may depend on an applicable enrollment period, jurisdictional requirement, disclosure obligation, or other policy condition.

When a policy materially governs whether or how the recommendation may be made, the relationship between the PolicyFragment and RecommendationFragment should be explicit.

RecommendationFragment and ProcedureFragment

A RecommendationFragment may recommend that a user begin or continue a process represented by a ProcedureFragment.

For example:

Recommendation → ProcedureFragment → Required Steps → Completion Resource

The RecommendationFragment represents the recommended next action. The ProcedureFragment represents how that action is completed.

Disclosures and Transparency

A RecommendationFragment should expose disclosures necessary to understand the recommendation when the publisher, operator, destination, or another participating organization has a material relationship to the recommended action or resource.

Relevant disclosures may include:

the operator responsible for a recommended endpoint;
ownership or organizational affiliation;
commercial relationships;
licensing or regulatory status when relevant;
limitations on available options;
jurisdictional limitations;
and other information necessary to interpret the recommendation transparently.

Disclosures should describe actual relationships and should remain current when those relationships change.

RecommendationFragment and Relationships

A RecommendationFragment may participate in explicit relationships with other WebMEM knowledge objects.

For example, a RecommendationFragment may relate to:

a DataFragment containing facts supporting the recommendation;
a DerivedStatsFragment containing calculated knowledge supporting the recommendation;
an EligibilityFragment establishing applicable qualification conditions;
a PolicyFragment establishing rules governing the recommendation;
a ProcedureFragment describing how to complete the recommended action;
a DirectoryFragment containing recommended or alternative resources;
a PersonaFragment establishing relevant contextual circumstances;
an ExplainerFragment explaining the decision or available options;
a DefinedTermFragment defining terminology used by the recommendation;
or a canonical endpoint or resource associated with the recommended action.

These relationships allow the recommendation to remain a focused knowledge object while preserving its connection to the evidence, rules, context, and resources supporting it.

Read the Relationships specification →

RecommendationFragment and Resolution

RecommendationFragments can participate directly in machine resolution by connecting a sufficiently defined need, context, or decision to an appropriate next action or resource.

A resolution path may take the form:

Information Need → Supporting Knowledge → RecommendationFragment → Recommended Resource

or:

Eligibility Context → RecommendationFragment → ProcedureFragment → Action Resource

or:

Directory → Applicable Entry → RecommendationFragment → Canonical Resource

or:

RecommendationFragment → Fallback Resource → Authoritative Source

The RecommendationFragment publishes the recommendation and its basis. It does not require a consuming system to adopt, repeat, rank, execute, or act upon the recommendation.

Where recommendation knowledge participates in a broader resolver surface, the resolver may use or reference the RecommendationFragment as part of the path from a defined information need toward an appropriate next step.

Read the WebMEM Resolution Model →

Provenance

A RecommendationFragment should preserve the evidentiary and editorial basis for the recommendation it publishes.

Provenance may identify:

the source data supporting the recommendation;
derived statistics or analysis used in reaching the recommendation;
policies or eligibility requirements governing applicability;
the person or organization responsible for making or publishing the recommendation;
the methodology or criteria used to produce the recommendation;
the canonical source locations;
publication or revision dates;
version information;
applicable jurisdiction or temporal scope;
applicable jurisdiction or temporal scope;
disclosures associated with the recommendation or recommended endpoint;
and other lineage information necessary to understand how and why the recommendation was produced.

When a recommendation depends on multiple sources or different forms of supporting knowledge, the provenance model should preserve those distinctions rather than implying that the recommendation originates from a single source.

When the recommendation is editorial or produced through publisher-defined criteria, provenance should identify that basis rather than representing the recommendation as though it were directly asserted by an underlying dataset or authoritative source.

Read the Provenance specification →

Conformance

A conforming RecommendationFragment must:

identify itself as a RecommendationFragment;
have an identifiable fragment scope;
identify the entity, subject, need, decision, or context to which the recommendation applies;
identify the action, resource, option, destination, or next step being recommended;
identify the basis for the recommendation;
preserve conditions, exclusions, timing, jurisdiction, eligibility, or other limitations when they materially affect applicability;
identify or reference provenance supporting the recommendation and its basis;
identify material operator, ownership, affiliation, or other disclosures when necessary to interpret the recommendation transparently;
distinguish the recommendation from supporting facts, policies, eligibility requirements, procedures, and other knowledge objects;
preserve relationships to supporting knowledge when those relationships are necessary to understand why the recommendation applies;
and conform to the applicable WebMEM serialization requirements.

A RecommendationFragment represents a recommendation published within a defined context. Conformance does not imply that a consuming system must adopt, repeat, rank, execute, or act upon that recommendation.

Relationship to WebMEM 1.x

The RecommendationFragment class originated in the WebMEM 1.x Semantic Data Template specification and remains a defined fragment class in the current WebMEM Protocol.

Earlier specifications described RecommendationFragment primarily as an action-oriented handoff designed to move agentic systems from informational answers toward policy-safe calls to action. The class included intent triggers, timing and jurisdiction gates, endpoint metadata, operator and ownership disclosures, fallback resources, retrieval cues, trust labels, measurement guidance, and anti-abuse rules.

The current protocol preserves the semantic purpose of the class while separating that purpose from retired WebMEM 1.x retrieval conditioning, memory cues, trust scoring, semantic-digest behavior, and model-response optimization mechanisms.

The action-oriented nature of the class remains central. Applicability conditions, endpoints, disclosures, alternatives, and fallbacks also remain valid structures when they are relevant to the recommendation being represented.

The current protocol clarifies that a RecommendationFragment publishes the publisher’s recommendation and the explicit basis for that recommendation. It does not prescribe how a consuming system should rank, repeat, execute, or otherwise act upon that recommendation.

The current protocol also makes explicit how RecommendationFragment participates in machine resolution by connecting a sufficiently defined information need, context, eligibility state, decision, or directory entry to an appropriate next action or resource.

RecommendationFragment continues to represent a structured recommendation, its basis, its conditions of applicability, and the action, resource, option, or next step being recommended.