Part of the WebMEM® Protocol
Fragment Class: DirectoryFragment
Location: /protocol/fragments/directoryfragment/
Status: Current Draft
Last Updated: 2026-08-24
Overview
A DirectoryFragment is a WebMEM fragment class for publishing a structured directory of entities, products, providers, services, resources, or other identifiable entries within a defined context.
Each DirectoryFragment establishes the directory itself, the scope within which it applies, and the structured entries that belong to it. Individual entries may include identity, type, location, availability, eligibility, coverage, attributes, canonical resources, and other information necessary to understand or navigate the directory.
Unlike an IndexFragment, which primarily establishes membership and navigability within a collection, a DirectoryFragment provides a richer structured representation of the entries within a directory.
The class is useful when the publisher knows not only which entities belong to a collection, but also enough structured information about those entities to expose a meaningful directory.
Semantic Purpose
The semantic purpose of a DirectoryFragment is to state:
Within this defined context, these are the available or relevant entities, products, providers, services, or resources, together with the structured information needed to identify, distinguish, understand, filter, or resolve them.
A DirectoryFragment may establish:
- the identity of the directory;
- the entity or context defining its scope;
- the entries belonging to the directory;
- the identity and type of each entry;
- geographic or service-area information;
- availability or eligibility information;
- coverage, services, benefits, or other entry attributes;
- relationships between entries and other knowledge objects;
- canonical resources associated with directory entries;
- and provenance supporting the directory and its contents.
This allows a directory to be represented as a coherent machine-readable knowledge object rather than requiring machines to reconstruct directory structure from visible listings, tables, filters, or navigation.
DirectoryFragment Within an SDT
A DirectoryFragment exists as one modular knowledge object within a Semantic Data Template (SDT).
The relationship is:
Web Resource → SDT → DirectoryFragment → Directory Entries
An SDT may contain one DirectoryFragment or multiple DirectoryFragments when the resource exposes different directories, entity types, or scopes.
For example, a healthcare resource might contain:
- a directory of available health plans;
- a directory of participating providers;
- a directory of pharmacies;
- or another collection of structured healthcare entities.
Each directory remains an independently identifiable knowledge object while participating in the broader machine representation of the resource.
DirectoryFragment Requirements
A conforming DirectoryFragment should establish enough information to identify the directory, understand its scope, and distinguish the entries it contains.
| Element | Purpose |
|---|---|
| Fragment Class | Identifies the knowledge object as a DirectoryFragment. |
| Fragment ID | Provides a stable identifier for the DirectoryFragment within the published knowledge structure. |
| Directory Scope | Identifies the entity, geography, organization, service area, category, or other context defining the directory. |
| Directory Entries | Contains one or more identifiable entities, products, providers, services, resources, or other directory members. |
| Entry Identity | Provides sufficient identity information to distinguish individual directory entries. |
| Entry Type | Identifies the type or class of object represented by a directory entry when necessary for interpretation. |
| Provenance | Identifies or references the source and lineage supporting directory membership and entry information when applicable. |
Additional entry attributes may be included according to the domain, directory purpose, entity model, relationship model, or applicable conformance profile.
Directory Entries
A directory entry represents an identifiable member of the directory.
Depending on the application, a directory entry may represent:
- a health plan;
- a healthcare provider;
- a pharmacy;
- a business or organization;
- a public service;
- a government program;
- a facility;
- a product;
- a resource;
- or another identifiable object appropriate to the directory.
An entry may contain only the information necessary to identify and resolve the entity, or it may contain additional structured attributes needed to support the purpose of the directory.
Directory Entry Fields
Directory entry fields depend on the domain and the type of entity represented.
Common entry information may include:
| Element | Purpose |
|---|---|
| Entry ID | Provides a stable identifier for the directory entry. |
| Entity Name | Provides the human-readable name of the entity, product, provider, service, or resource. |
| Entity Type | Identifies the type of object represented by the entry. |
| Location | Identifies geographic scope, physical location, service area, or other applicable geographic information. |
| Eligibility | Identifies or references conditions governing access or eligibility when applicable. |
| Coverage or Services | Identifies what the entity provides, covers, offers, or supports when applicable. |
| Canonical Resource | Identifies the canonical web resource or other resolvable object associated with the entry when available. |
| Related Terms | Identifies defined terms associated with the entry when explicit semantic alignment is useful. |
DirectoryFragment does not require every directory to use the same entry fields. The structure should reflect the actual knowledge associated with the directory and the entities it contains.
Example DirectoryFragment
The following example represents a directory of Medicare Advantage plans within a defined county context using the current WebMEM HTML serialization.
<template
data-webmem-fragment
data-fragment-class="DirectoryFragment"
data-fragment-id="county-ma-plan-directory">
<section
data-directory-type="MedicareAdvantagePlan"
data-entity-type="County"
data-entity-id="04015"
data-plan-year="2026"
data-provenance-ref="#provenance-cms-landscape">
<ol data-role="directory">
<li
data-role="directory-entry"
data-entity-type="MedicarePlan"
data-entity-id="H5521-290-0">
<span data-role="entity-name">
Example Medicare Advantage PPO
</span>
<data
data-field="plan_type"
value="PPO">PPO</data>
<data
data-field="monthly_premium"
value="0"
data-type="number"
data-unit="USD">$0</data>
<a
data-role="canonical-resource"
href="/medicare-advantage/plans/H5521-290-0/">
H5521-290-0
</a>
</li>
<li
data-role="directory-entry"
data-entity-type="MedicarePlan"
data-entity-id="H2406-129-0">
<span data-role="entity-name">
Example Medicare Advantage HMO
</span>
<data
data-field="plan_type"
value="HMO">HMO</data>
<data
data-field="monthly_premium"
value="24.50"
data-type="number"
data-unit="USD">$24.50</data>
<a
data-role="canonical-resource"
href="/medicare-advantage/plans/H2406-129-0/">
H2406-129-0
</a>
</li>
</ol>
</section>
</template>
The fragment establishes that:
- the knowledge object is a
DirectoryFragment; - the directory has a stable identity;
- the directory is scoped to a defined county and plan year;
- each directory entry represents an identifiable Medicare plan;
- structured attributes distinguish and describe the entries;
- canonical resources are provided for the individual plans;
- and provenance supporting the directory can be resolved through the referenced provenance object.
DirectoryFragment and IndexFragment
DirectoryFragment and IndexFragment both represent collections of identifiable objects, but they serve different semantic purposes.
| IndexFragment | DirectoryFragment |
|---|---|
| Primarily represents membership in a defined collection. | Represents a structured directory of entities together with information describing those entries. |
| Answers: What identifiable objects belong here? | Answers: What entities are available here, and what structured information is published about each entry? |
| May require only stable member identifiers. | Typically contains richer entry-level attributes. |
| Optimized for identifying and resolving members of a collection. | Optimized for representing and navigating a directory of structured entries. |
A publisher may use an IndexFragment when collection membership is the primary knowledge being represented and a DirectoryFragment when the entries themselves require richer structured representation.
The two classes may also coexist when a resource benefits from both a compact index and a richer directory representation.
DirectoryFragment and DataFragment
A DirectoryFragment may contain factual attributes describing its entries, but its semantic purpose remains the representation of the directory.
A DataFragment represents source-observed factual knowledge about an entity or context.
For example:
- DirectoryFragment: identifies a plan as an entry in a county plan directory and exposes selected attributes useful within that directory.
- DataFragment: publishes a structured set of source-observed facts about that individual plan.
Directory entry attributes should therefore support the purpose of the directory rather than attempt to reproduce every fact known about each entity.
Eligibility and Filtering
A DirectoryFragment may contain or reference information used to determine whether particular entries apply within a specified context.
Examples may include:
- geographic availability;
- service-area membership;
- age requirements;
- program qualification;
- condition-specific eligibility;
- provider-network participation;
- or other criteria relevant to the directory.
When eligibility rules themselves form a distinct knowledge object, those rules may be represented by an EligibilityFragment and related to the applicable directory entries.
This allows the DirectoryFragment to identify the available entities while the EligibilityFragment preserves the semantic structure of the eligibility rules.
Conditional Logic
A DirectoryFragment may reference conditional logic when directory membership, availability, filtering, or applicability depends on known conditions.
For example:
<div data-role="condition">
<div
data-role="if"
data-condition="service_area"
data-operator="contains"
data-value="86401">
<span data-role="result">
Available in this service area
</span>
</div>
</div>
Conditional structures should express known publisher logic. They should not imply that a consuming system is required to execute that logic.
Where the conditional rules constitute substantive eligibility knowledge, a related EligibilityFragment should be used rather than embedding the entire eligibility model within the directory.
Decision Structures
A directory may expose information useful in comparing or evaluating entries, but the DirectoryFragment itself does not inherently make a recommendation.
Structured comparison criteria may include:
- location;
- cost;
- coverage;
- network participation;
- availability;
- eligibility;
- or other attributes appropriate to the directory.
If the publisher creates an explicit recommendation based on those attributes, that recommendation may be represented by a RecommendationFragment.
If the publisher explains the tradeoffs among different options, the explanatory structure may be represented by an ExplainerFragment.
DirectoryFragment and Relationships
A DirectoryFragment may participate in relationships with other WebMEM knowledge objects.
For example, a directory entry may relate to:
- a DataFragment containing additional facts about the entity;
- an IdentityFragment establishing canonical identity;
- an EligibilityFragment defining access or qualification criteria;
- a PolicyFragment governing the entity or service;
- an ExplainerFragment describing how an option works;
- a RecommendationFragment evaluating or recommending an option;
- a DefinedTermFragment defining terminology used by the entry;
- or another canonical resource associated with the entity.
These relationships allow the directory to remain focused on its entries while connecting those entries to deeper knowledge elsewhere in the SDT or broader WebMEM information architecture.
Read the Relationships specification →
DirectoryFragment and Resolution
DirectoryFragments can play an important role in machine resolution because they connect a broad context to a structured set of more specific entities.
A resolution path may take the form:
Location → DirectoryFragment → Directory Entry → Canonical Entity Resource
or:
Service Need → DirectoryFragment → Matching Service → Canonical Resource
or:
Organization → DirectoryFragment → Provider → Provider Resource
Where canonical resources are known, directory entries may expose those paths directly.
Where additional resolver logic is required, the DirectoryFragment may participate in or reference the appropriate WebMEM resolver structure.
The class therefore preserves its original purpose as a structured directory while participating naturally in the broader WebMEM Resolution Model.
Read the WebMEM Resolution Model →
DirectoryFragment and Resolvers
A DirectoryFragment and a resolver are related but distinct.
The DirectoryFragment answers:
What structured entries are available within this directory?
A resolver answers:
How can a machine move from the current context toward the appropriate information object?
A resolver may use a DirectoryFragment as part of its resolution surface, particularly when resolving a location, category, organization, or service need to a set of available entities.
The DirectoryFragment publishes the directory knowledge. The resolver defines or exposes the path through that knowledge.
Read the Resolvers specification →
Provenance
A DirectoryFragment should preserve the evidentiary basis for directory membership and entry attributes when those assertions depend on external source information.
Provenance may identify:
- the dataset or datasets supporting directory membership;
- the source responsible for entry attributes;
- the source creator or publisher;
- the canonical source location;
- an archive or source-file location;
- publication or effective dates;
- retrieval or import dates;
- source version information;
- source format;
- checksum or integrity information;
- and other lineage information necessary to establish the evidentiary basis of the directory.
When all directory entries share the same source basis, provenance may be established at the fragment level.
When different entries or attributes originate from different sources, more specific provenance relationships may be used so the source of each assertion remains identifiable.
This is particularly important when a directory combines information from multiple datasets or publishing authorities.
Read the Provenance specification →
Conformance
A conforming DirectoryFragment must:
- identify itself as a
DirectoryFragment; - have an identifiable fragment scope;
- identify the directory, entity, or context defining its scope;
- contain one or more identifiable directory entries;
- provide sufficient identity information to distinguish individual entries;
- identify entry type when required to interpret the directory;
- preserve applicable geographic, eligibility, coverage, service, or other contextual information necessary to interpret the entries;
- identify or reference provenance when directory membership or entry attributes depend on external source information;
- preserve relationships to canonical resources when those relationships are published as part of the directory;
- and conform to the applicable WebMEM serialization requirements.
Additional requirements may apply under domain-specific profiles or future protocol extensions.
Relationship to WebMEM 1.x
The DirectoryFragment 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 DirectoryFragment as a machine-ingestible directory structure optimized for agentic querying, filtering, explainability, trust-scored reasoning, memory cues, and semantic-digest behavior.
The current protocol preserves the semantic purpose of the class while separating that purpose from retired WebMEM 1.x serialization, memory, scoring, digest, and retrieval mechanisms.
The original support for structured directory entries, eligibility information, conditional logic, decision structures, follow-up paths, and provenance remains part of the class where those structures are appropriate to the directory being represented.
The current protocol also makes explicit the relationship between DirectoryFragment and machine resolution: a structured directory can connect a broad context to identifiable entries and, where available, to their canonical resources.
DirectoryFragment continues to represent a structured directory of identifiable entities and the information necessary to understand, distinguish, navigate, or resolve those entries.