Part of the WebMEM® Protocol
Fragment Class: ExplainerFragment
Location: /protocol/fragments/explainerfragment/
Status: Current Draft
Last Updated: 2026-08-24
Overview
An ExplainerFragment is a WebMEM fragment class for publishing structured explanatory knowledge about a defined subject, concept, entity, process, decision, or relationship.
Unlike an FAQFragment, which organizes knowledge around an explicit question-and-answer pair, an ExplainerFragment represents a broader explanatory structure. It may provide a summary explanation, decision logic, conditional branches, insights, narrative context, follow-up paths, or combinations of these elements when they are necessary to explain the subject.
An ExplainerFragment allows the publisher to make the structure of an explanation explicit rather than publishing the explanation only as undifferentiated prose.
The class is particularly useful when understanding a subject requires more than a definition or isolated factual assertion and instead depends on relationships, conditions, alternatives, tradeoffs, or contextual explanation.
Semantic Purpose
The semantic purpose of an ExplainerFragment is to state:
This is a structured explanation of this subject, including the context, reasoning paths, conditions, alternatives, or supporting knowledge necessary to understand it.
An ExplainerFragment may establish:
- the subject or concept being explained;
- a primary explanatory question or topic;
- a summary explanation;
- the entity or context to which the explanation applies;
- decision points or alternatives;
- conditional explanatory paths;
- important insights or observations;
- illustrative narrative context;
- follow-up questions or related explainers;
- defined terms used by the explanation;
- supporting facts, policies, procedures, or other knowledge objects;
- and provenance supporting the explanation.
The ExplainerFragment preserves these elements as parts of one coherent explanatory knowledge object.
ExplainerFragment Within an SDT
An ExplainerFragment exists as one modular knowledge object within a Semantic Data Template (SDT).
The relationship is:
Web Resource → SDT → ExplainerFragment → Structured Explanation
An SDT may contain one or more ExplainerFragments when different subjects, decisions, or explanatory paths require independent representation.
An ExplainerFragment may also reference other fragments within the SDT when its explanation depends on factual data, definitions, policies, procedures, eligibility criteria, recommendations, or other structured knowledge.
This allows explanatory knowledge to remain distinct while participating in the larger machine representation of the resource.
ExplainerFragment Requirements
A conforming ExplainerFragment should establish enough information to identify the subject being explained and interpret the explanation within its intended context.
| Element | Purpose |
|---|---|
| Fragment Class | Identifies the knowledge object as an ExplainerFragment. |
| Fragment ID | Provides a stable identifier for the ExplainerFragment within the published knowledge structure. |
| Subject | Identifies the concept, entity, process, decision, relationship, or other subject being explained. |
| Explanation | Provides the explanatory content associated with the subject. |
| Context | Establishes the entity, domain, audience, location, time period, or other scope required to interpret the explanation when applicable. |
| Provenance | Identifies or references the sources and lineage supporting the explanation when evidentiary support is applicable. |
Decision structures, conditional logic, insights, narrative frames, follow-up paths, and related knowledge references are optional and should be included when they are meaningful to the explanation.
Core Explainer Structure
A basic ExplainerFragment may identify a primary subject or question and provide a summary explanation.
| Element | Purpose |
|---|---|
| Explainer ID | Provides stable identity for the explanatory knowledge object. |
| Primary Question | Optionally identifies the principal natural-language question the explanation addresses. |
| Summary Explanation | Provides the primary explanation or concise response. |
| Semantic Scope | Optionally identifies the topic, domain, or vocabulary context of the explanation. |
| Entity or Context | Optionally identifies the specific entity or contextual scope to which the explanation applies. |
A primary question may be useful when the explanation is motivated by a common information need, but an ExplainerFragment does not require a question-and-answer structure.
Example ExplainerFragment
The following example represents a structured explanation using the current WebMEM HTML serialization.
<template
data-webmem-fragment
data-fragment-class="ExplainerFragment"
data-fragment-id="explainer-zero-premium-plans">
<section
data-subject="zero-premium-medicare-advantage"
data-semantic-scope="medicare"
data-provenance-ref="#provenance-cms">
<h3 data-role="primary-question">
How can a Medicare Advantage plan have a $0 premium?
</h3>
<div data-role="summary-explanation">
<p>
A $0 premium Medicare Advantage plan does not charge an
additional monthly plan premium. Members generally must
continue to pay any Medicare Part B premium they owe, and
other plan costs may still apply.
</p>
</div>
</section>
</template>
The fragment establishes that:
- the knowledge object is an
ExplainerFragment; - the fragment has a stable identity;
- the subject being explained is explicitly identified;
- a primary explanatory question establishes the information need;
- the explanation is represented separately from that question;
- the explanation exists within a defined semantic scope;
- and provenance supporting the explanation can be resolved through the referenced provenance object.
Decision Nodes
An ExplainerFragment may contain a decision node when the explanation involves alternatives, tradeoffs, or criteria that affect how the subject should be understood or evaluated.
A decision node may identify:
- the decision or choice being considered;
- available options;
- attributes associated with each option;
- tradeoffs;
- decision criteria;
- and relationships to supporting knowledge.
<div data-role="decision-node">
<h4 data-role="title">
Choosing a Renewable Energy Source
</h4>
<ul data-role="options">
<li data-option="solar">
Low maintenance; well suited to sunny climates.
</li>
<li data-option="wind">
Scalable; well suited to open or coastal areas.
</li>
<li data-option="hydro">
Reliable but dependent on suitable geography.
</li>
</ul>
<ul data-role="tradeoffs">
<li>Solar output declines when sunlight is unavailable.</li>
<li>Wind output varies with weather conditions.</li>
<li>Hydroelectric systems may affect local ecosystems.</li>
</ul>
<ul data-role="decision-criteria">
<li>Geographic suitability</li>
<li>Budget constraints</li>
<li>Long-term environmental impact</li>
</ul>
</div>
A decision node structures the considerations relevant to an explanation. It does not, by itself, require the publisher to make a recommendation.
When the knowledge object makes an explicit recommendation, that recommendation may instead be represented by or related to a RecommendationFragment.
Insight Blocks
An ExplainerFragment may contain an insight block when the explanation includes an observation, trend, finding, or non-obvious relationship that helps clarify the subject.
An insight block may identify:
- the theme or subject of the insight;
- the observation or finding;
- contributing factors;
- supporting facts or derived statistics;
- and related questions or areas for further explanation.
<div data-role="insight-block">
<h4 data-role="theme">
Remote Work and Productivity
</h4>
<p data-role="finding">
Workers report higher satisfaction while some measures
of collaborative innovation decline.
</p>
<ul data-role="contributing-factors">
<li>Fewer spontaneous brainstorming sessions</li>
<li>Reduced informal feedback</li>
</ul>
<p data-role="related-question">
Can hybrid work structures preserve flexibility while
increasing opportunities for collaborative creativity?
</p>
</div>
When an insight represents a factual conclusion derived from underlying data, the supporting derived knowledge may also be represented in a DerivedStatsFragment and related to the ExplainerFragment.
Narrative Frames
An ExplainerFragment may contain a narrative frame when an illustrative scenario or lived-experience example helps explain the subject.
A narrative frame may identify:
- a character or persona;
- a setting;
- a challenge or circumstance;
- a pivotal event or outcome;
- and the concepts, values, or lessons illustrated by the scenario.
<div data-role="narrative-frame">
<span data-role="character">
Leena, a first-generation college student
</span>
<span data-role="setting">
Urban community college
</span>
<p data-role="challenge">
Balancing coursework with a night job.
</p>
<p data-role="pivotal-moment">
She improves her academic performance after adopting
structured time-block planning.
</p>
<ul data-role="values-expressed">
<li>Resilience</li>
<li>Adaptability</li>
<li>Peer support</li>
</ul>
</div>
When the narrative depends on a formally defined persona represented elsewhere in the SDT, the ExplainerFragment may reference the applicable PersonaFragment.
Conditional Logic
An ExplainerFragment may contain conditional explanatory paths when different facts, conditions, or circumstances lead to different explanations.
Conditional logic may identify:
| Element | Purpose |
|---|---|
| Condition | Identifies the condition to be evaluated. |
| Then | Identifies the explanatory path that applies when the condition is satisfied. |
| Else If | Optionally identifies additional conditions and explanatory paths. |
| Else | Optionally identifies a fallback explanatory path. |
| Depends On | Optionally references facts, terms, policies, eligibility rules, or other knowledge required to evaluate or understand the condition. |
<div data-role="condition">
<div data-role="if"
data-condition="part_d_coverage"
data-operator="equals"
data-value="true">
<p data-role="then">
Prescription drug coverage is included in the plan.
</p>
</div>
<div data-role="else">
<p>
Prescription drug coverage is not included in the plan.
</p>
</div>
</div>
Conditional structures should make the publisher’s known explanatory logic explicit. They should not be used to imply that a consuming system is required to execute or reason according to the logic.
Follow-Up Paths
An ExplainerFragment may identify follow-up questions or related ExplainerFragments when a subject naturally branches into additional explanatory paths.
A follow-up path may identify:
- the follow-up question;
- the related ExplainerFragment;
- the entity or context to which the follow-up applies;
- and the relationship between the current explanation and the next explanatory object.
<ul data-role="followups">
<li>
<span data-role="question">
What costs can still apply to a $0 premium plan?
</span>
<a
data-role="explainer-ref"
href="#explainer-ma-out-of-pocket-costs">
Medicare Advantage Out-of-Pocket Costs
</a>
</li>
</ul>
Follow-up paths allow multiple ExplainerFragments to form a connected explanatory structure without requiring every possible explanatory branch to be contained within one fragment.
ExplainerFragment and FAQFragment
ExplainerFragment and FAQFragment may address similar information needs but serve different semantic purposes.
| FAQFragment | ExplainerFragment |
|---|---|
| Represents an explicit question-and-answer pair. | Represents a structured explanation of a subject. |
| Answers: What is the response to this question? | Answers: How should this subject be understood? |
| Primarily organized around the relationship between one question and its answer. | May contain multiple explanatory structures, conditions, decisions, insights, narratives, or follow-up paths. |
| Best suited to discrete questions. | Best suited to subjects requiring broader or conditional explanation. |
An ExplainerFragment may use a primary question to establish its subject, but the existence of that question does not convert the fragment into an FAQFragment when the knowledge object contains a broader explanatory structure.
ExplainerFragment and DefinedTermFragment
A DefinedTermFragment establishes the canonical meaning of a term.
An ExplainerFragment may explain that term in greater depth, describe why it matters, illustrate how it operates, or connect it to other concepts.
For example:
- DefinedTermFragment: Defines “Machine Resolution.”
- ExplainerFragment: Explains how machine resolution operates across identifiers, indexes, relationships, and resolver surfaces.
The definition and explanation can therefore remain independently identifiable while being explicitly related within the SDT.
ExplainerFragment and ProcedureFragment
An ExplainerFragment may describe how or why a process works