Knowledge-Node Object Architecture™ and Native HTML Serialization
Version: KNOL v1.0
Status: Working Specification
Revision: 2026-09-10
This document defines the current KNOL v1.0 Working Specification. Until KNOL v1.0 is designated final, normative requirements and vocabulary defined by this document MAY change between published revisions.
Implementations claiming conformance SHOULD identify the specific published revision of the KNOL v1.0 Working Specification against which conformance was evaluated.
1. Purpose
KNOL™ defines a model for publishing identifiable, addressable units of knowledge through ordinary web documents while preserving the native structural semantics of HTML.
A Knowledge-Node Object (KNOL) is an identifiable, addressable unit of knowledge concerning one or more entities, assertions, relationships, contexts, and provenance conditions.
A KNOL exists conceptually independently of any particular storage format, document format, serialization syntax, database schema, or publication manifestation.
This specification defines the initial KNOL architecture and the rules for Native KNOL HTML: a serialization in which knowledge semantics are bound directly to the human-facing HTML structures that manifest the knowledge.
The purpose of Native KNOL HTML is not to replace HTML semantics or create a parallel proprietary document model. It is to add knowledge identity, composition, addressability, canonical state, context, provenance, and semantic
relationships where native HTML does not already express those concepts unambiguously.
HTML determines document and structural semantics. KNOL determines
knowledge semantics.
2. Design Principle
KNOL is based on a simple rule:
KNOL attributes annotate knowledge already expressed by HTML; they
SHOULD NOT replace native HTML semantics.
An implementation SHOULD begin with the strongest native HTML structure that faithfully represents the human-facing content.
Accordingly:
<main>SHOULD be used for the primary document content.<section>SHOULD be used for thematic sections.<article>SHOULD be used for self-contained content where appropriate.<table>SHOULD be used for genuinely tabular relationships.<th>SHOULD express native row and column identity.<dl>,<dt>, and<dd>SHOULD express appropriate definition/value structures.<p>SHOULD remain prose.<span>MAY identify an addressable assertion or canonical value embedded within prose or presentation.<a href>SHOULD remain the native mechanism for navigation.<time datetime>SHOULD remain the native mechanism for canonical date and time representation.<ul>,<ol>, and<li>SHOULD retain their native collection and sequence semantics.
KNOL attributes SHOULD then add only the semantic state that those native structures do not already communicate unambiguously.
NATIVE HTML
|
| provides
v
DOCUMENT + STRUCTURAL SEMANTICS
|
| augmented by
v
KNOL
|
| provides
v
KNOWLEDGE IDENTITY
KNOWLEDGE COMPOSITION
ASSERTION ADDRESSABILITY
CANONICAL STATE
ENTITY CONTEXT
SCOPE
PROVENANCE
SEMANTIC RELATIONSHIPS
A conforming implementation SHOULD NOT duplicate native semantics merely because an equivalent KNOL annotation could be invented.
For example, a table already establishes relationships among captions, column headers, row headers, and cells. KNOL SHOULD identify the canonical assertions manifested by appropriate cells rather than recreating those row and column
relationships through proprietary attributes.
3. Normative Language
The key words MUST, MUST NOT,
REQUIRED, SHOULD,
SHOULD NOT, MAY, and
OPTIONAL in this specification indicate normative requirements or recommendations.
Where this specification describes an HTML element as the preferred native manifestation of a KNOL construct, that preference does not override the requirements of HTML itself. Authors MUST use HTML elements according to their
native meaning.
4. Architectural Model
KNOL separates the canonical knowledge object from the manifestation through which that knowledge is published.
CANONICAL KNOWLEDGE-NODE OBJECT
|
| serialization
v
MANIFESTATION
|
+----+----+
| |
v v
HUMAN STATE MACHINE-ADDRESSABLE
SEMANTIC STATE
A single KNOL MAY have multiple manifestations.
Examples include:
- Native HTML;
- encapsulated HTML;
- linked representations;
- JSON;
- JSON-LD;
- an API representation;
- a dedicated KNOL file representation; or
- other serialization formats.
The existence of one manifestation does not redefine the underlying KNOL.
Conceptually:
KNOL
|
+---------------+---------------+
| | |
v v v
NATIVE HTML ENCAPSULATED LINKED
MANIFESTATION MANIFESTATION MANIFESTATION
|
v
HUMAN DOCUMENT
+
MACHINE SEMANTICS
KNOL v1.0 primarily specifies the semantics and binding rules required for
Native KNOL HTML.
5. Relationship to WebMEM
WebMEM and KNOL describe different layers of the same publication architecture.
WebMEM describes how resolvable machine knowledge is composed and published on the web alongside human-readable publication.
KNOL identifies and addresses the knowledge object being published.
Native KNOL HTML defines how that knowledge object and its semantic composition can be manifested directly through native HTML.
WebMEM introduced two composition concepts that remain applicable to Native KNOL HTML:
- Semantic Data Template (SDT) — the page-level semantic composition associated with a publication surface; and
- Fragment — a coherent semantic unit within that composition.
Neither concept is inherently dependent upon the <template> element or any other particular serialization technology.
The term Semantic Data Template (SDT) identifies a logical semantic composition. It does not refer to, require, or derive its meaning from the HTML <template> element.
In earlier encapsulated WebMEM manifestations, a <template> could act as the container for the machine-facing
semantic composition.
In Native KNOL HTML, the semantic composition is bound to the native document itself.
ENCAPSULATED WEBMEM
HUMAN DOCUMENT
|
+----------------------+
|
v
<template>
|
| SDT
|
+----------+----------+
| | |
v v v
FRAGMENT FRAGMENT FRAGMENT
NATIVE KNOL HTML
<main>
|
| SDT / KNOL CONTEXT
|
+-----------+-----------+
| | |
v v v
<section> <section> <section>
| | |
FRAGMENT FRAGMENT FRAGMENT
The semantic composition therefore survives a change in manifestation.
The SDT is the semantic composition. The container through which that
composition is manifested may change.
6. Native KNOL HTML Composition Model
The ordinary Native KNOL HTML hierarchy is:
<main>
|
| SDT / PRIMARY KNOL CONTEXT
|
+-- <section>
| |
| | FRAGMENT
| |
| +-- native HTML structures
| |
| +-- assertions
| |
| +-- relationships
|
+-- <section>
| |
| | FRAGMENT
| |
| +-- native HTML structures
| +-- assertions
| +-- relationships
|
+-- <section>
|
| FRAGMENT
|
+-- native HTML structures
+-- assertions
+-- relationships
The principal semantic levels are:
SDT
|
+-- KNOL
|
+-- ENTITY
|
+-- SCOPE
|
+-- FRAGMENT
| |
| +-- ASSERTION
| +-- ASSERTION
| +-- RELATIONSHIP
|
+-- FRAGMENT
|
+-- ASSERTION
+-- RELATIONSHIP
These levels MUST NOT be treated as interchangeable.
A KNOL identifies a knowledge object.
An entity identifies the subject to which knowledge applies.
A Fragment identifies a coherent semantic unit within the applicable knowledge composition.
An assertion identifies an addressable semantic property or proposition.
A relationship identifies an intentional semantic edge between the applicable knowledge context and another identified entity, node, or resource.
7. Primary KNOL Context: <main>
For a page whose primary content manifests one principal knowledge-node context, the document’s <main> element SHOULD establish that context.
Example:
<main
data-knol="plan:H2406-129-0"
data-entity="plan:H2406-129-0"
data-scope="plan-year:2026">
...
</main>
In this example:
<main>
→ primary document content
data-knol
→ plan:H2406-129-0
data-entity
→ plan:H2406-129-0
data-scope
→ plan-year:2026
The <main> element provides the native document boundary. KNOL annotations establish the knowledge context manifested by that boundary.
Subordinate Fragments, assertions, and relationships MAY inherit applicable semantic context from this boundary.
An implementation SHOULD NOT repeat the primary
data-knol, data-entity, or
data-scope values on every descendant element when inheritance is unambiguous.
8. Semantic Fragments: <section>
A Fragment is a coherent semantic unit within an applicable KNOL or publication composition.
In Native KNOL HTML, a native <section> SHOULD ordinarily serve as the structural manifestation of a Fragment when the represented knowledge is also a legitimate thematic section of the human document.
The Fragment Class MUST be identified using data-fragment when a semantic Fragment is explicitly manifested
in Native KNOL HTML.
data-fragment is a core composition attribute. It identifies the semantic role of a coherent component within an applicable KNOL or SDT. It does not identify an assertion, canonical value, entity, or relationship target.
<section data-fragment="FAQFragment">
<h2>Frequently Asked Questions</h2>
...
</section>
The two semantic layers remain distinct:
<section>
→ This content forms a thematic section of the HTML document.
data-fragment="FAQFragment"
→ This section manifests an FAQ semantic Fragment.
The Fragment Class describes the semantic role of the composition. It does not necessarily identify:
- the source dataset;
- the ontology branch of every contained assertion;
- the entity owning every contained assertion;
- the visual presentation of the section; or
- the serialization technology used to publish the Fragment.
A Fragment MAY compose assertions from multiple knowledge domains when those assertions form a coherent semantic unit.
For example, an FAQFragment about a Medicare plan may contain questions concerning premium, maximum out-of-pocket cost, enrollment, drug deductible, and contract-level performance.
The Fragment remains an FAQFragment because its Fragment Class describes the semantic role of the section rather than the source taxonomy of each contained fact.
9. Fragment Context and Inheritance
A Fragment ordinarily inherits the KNOL, entity, and scope context established by its nearest applicable ancestor.
<main
data-knol="plan:H2406-129-0"
data-entity="plan:H2406-129-0"
data-scope="plan-year:2026">
<section data-fragment="FAQFragment">
...
</section>
</main>
The effective semantic context of the Fragment is:
KNOL
plan:H2406-129-0
ENTITY
plan:H2406-129-0
SCOPE
plan-year:2026
FRAGMENT
FAQFragment
The Fragment SHOULD NOT repeat inherited semantic state merely for verbosity.
A Fragment MAY refine inherited context when the knowledge manifested by the section applies to a more-specific or different entity or scope.
For example, a plan page may contain CMS Star Rating information whose performance entity is the CMS contract:
<main
data-knol="plan:H2406-129-0"
data-entity="plan:H2406-129-0"
data-scope="plan-year:2026">
<section
data-fragment="PerformanceFragment"
data-entity="contract:H2406">
<h2>CMS Star Ratings</h2>
...
</section>
</main>
The section remains a Fragment of the enclosing publication composition while refining the entity context for its contained assertions.
A subordinate element carrying a new data-knol value establishes a new knowledge-node boundary rather than merely refining the context of the existing Fragment.
<section
data-knol="analysis:2026-yuma-snp-landscape"
data-entity="county:arizona-yuma-04027"
data-scope="plan-year:2026">
...
</section>
Accordingly:
data-fragment
→ identifies a semantic composition within the current KNOL
data-entity / data-scope
→ may refine inherited context
data-knol
→ establishes a new knowledge-node boundary
10. Context Inheritance Rule
Native KNOL HTML uses hierarchical context inheritance.
Semantic state SHOULD be declared at the highest unambiguous scope and
inherited downward.
Unless explicitly overridden, a KNOL-aware consumer MUST determine effective context using the nearest applicable declaration in the HTML document tree.
For each inheritable KNOL attribute, the effective value for an element is resolved in the following order:
- If the element itself declares the attribute, that value is effective.
- Otherwise, the value declared by the nearest ancestor that supplies the
attribute is effective. - Otherwise, the value is unspecified.
This rule applies independently to each inheritable attribute. A descendant MAY therefore override one part of its inherited context while continuing to inherit the others.
The following attributes are inheritable context attributes in Native KNOL HTML:
data-knol;data-entity;data-scope; anddata-source.
The following attributes are local semantic attributes and MUST NOT be inherited from ancestor elements:
data-key;data-value;data-type;data-unit;data-derived;data-rel;data-ref; anddata-digest.
data-fragment establishes Fragment context rather than ordinary scalar inheritance. An element belongs to the nearest containing semantic Fragment established by an ancestor carrying data-fragment, unless the element itself establishes a new Fragment.
An assertion manifestation inherits the nearest applicable ancestor values unless the assertion itself or an intervening ancestor supplies a replacement value.
Omission means inheritance where inheritance is applicable.
An empty attribute value MUST NOT be used to negate inherited context.
<main
data-knol="plan:H2406-129-0"
data-entity="plan:H2406-129-0"
data-scope="plan-year:2026">
<section data-fragment="CostFragment">
<dl>
<dt>Monthly Premium</dt>
<dd
data-key="plan.landscape.monthly-premium"
data-value="295.00"
data-unit="USD">
$295.00
</dd>
</dl>
</section>
</main>
The effective assertion state is:
KNOL
plan:H2406-129-0
ENTITY
plan:H2406-129-0
SCOPE
plan-year:2026
FRAGMENT
CostFragment
ASSERTION
plan.landscape.monthly-premium
CANONICAL VALUE
295.00
UNIT
USD
None of the inherited context needs to be repeated on the <dd> because its applicable KNOL, entity, scope, and Fragment are already established by the document hierarchy.
11. KNOL HTML Attribute Vocabulary
KNOL v1.0 defines a compact HTML attribute vocabulary for adding knowledge semantics to native HTML.
The vocabulary is intentionally smaller than the complete KNOL object model. An implementation MAY internally maintain additional assertion records, provenance records, transformation state, validation state, serialization
manifests, invariant profiles, digests, or other knowledge structures without requiring an equivalent HTML attribute for every internal concept.
The object model may be rich. The HTML serialization vocabulary SHOULD
remain small.
11.1 Core Attributes
data-knol data-entity data-fragment data-key data-value data-rel data-ref
The seven core attributes answer seven different questions:
data-knol
→ What knowledge node am I in?
data-entity
→ What entity is this knowledge about?
data-fragment
→ What semantic Fragment does this structure manifest?
data-key
→ What assertion or semantic property is this?
data-value
→ What canonical machine value does this manifestation represent?
data-rel
→ What semantic relationship is being asserted?
data-ref
→ What entity, node, or resource does this relationship resolve to?
An attribute being part of the core vocabulary does not mean that the attribute is REQUIRED on every KNOL element.
Core status means that the attribute participates in the fundamental KNOL composition and addressing model.
11.2 Extended Attributes
data-type data-unit data-derived data-scope data-source data-digest
Extended attributes provide additional precision when the applicable semantic state is not already expressed sufficiently through native HTML or inherited KNOL context.
data-type
→ What datatype does the canonical value have?
data-unit
→ What measurement, currency, scale, or unit applies?
data-derived
→ Is the assertion source-reported or publisher-derived?
data-scope
→ Under what applicability or contextual boundary does the knowledge apply?
data-source
→ What provenance resource supports this knowledge?
data-digest
→ What version, snapshot, digest, or integrity state identifies the knowledge?
12. data-knol — Knowledge-Node Identity
data-knol identifies the boundary or root of a serialized Knowledge-Node Object.
An element carrying data-knol establishes a new KNOL context for that element and its applicable descendants.
A new data-knol declaration replaces any inherited data-knol value. It does not, by itself, clear or replace other
inheritable context attributes.
A new KNOL boundary SHOULD ordinarily declare data-entity when the knowledge object has an identifiable subject. A KNOL MAY omit data-entity when the knowledge object is intentionally entity-neutral or when no subject entity can be truthfully identified.
<main
data-knol="plan:H2406-129-0"
data-entity="plan:H2406-129-0"
data-scope="plan-year:2026">
...
</main>
The value SHOULD be stable within the applicable knowledge system and SHOULD be sufficiently specific to distinguish the node from other knowledge nodes.
KNOL identifiers SHOULD ordinarily be compact and typed.
plan:H2406-129-0 contract:H2406 county:arizona-yuma-04027 organization:unitedhealthcare analysis:2026-yuma-snp-landscape concept:query-fan-out
The type prefix identifies the class of object being addressed. The identifier following the prefix identifies the particular object within that class.
A KNOL identifier is a semantic identifier. It is not required to be a URL.
A URL MAY identify a manifestation of the KNOL without becoming the canonical KNOL identifier itself.
13. data-entity — Subject Identity
data-entity identifies the entity to which the applicable knowledge applies.
An element carrying data-entity establishes entity context for that element and its applicable descendants.
A local data-entity declaration replaces any inherited data-entity value. It does not, by itself, establish a new KNOL or alter inherited data-knol, data-scope, or data-source context.
KNOL identity and entity identity MUST NOT be assumed to be equivalent.
If no effective data-entity can be resolved for an assertion, the entity component of that assertion’s effective identity is unspecified. Consumers MUST NOT substitute the effective data-knol value as the entity merely because no data-entity is present.
A KNOL Profile MAY require entity identity for particular classes of knowledge. When such a requirement applies, an assertion for which no effective data-entity can be resolved is incomplete under that Profile.
data-knol
→ identifies the knowledge object
data-entity
→ identifies the subject of that knowledge object
They frequently MAY have identical values:
<main
data-knol="plan:H2406-129-0"
data-entity="plan:H2406-129-0">
But they are not required to.
<section
data-knol="analysis:2026-yuma-snp-landscape"
data-entity="county:arizona-yuma-04027">
In this example:
KNOL
analysis:2026-yuma-snp-landscape
ENTITY
county:arizona-yuma-04027
The KNOL is an analysis object. Yuma County is the entity the analysis concerns.
This distinction permits multiple independently identifiable knowledge objects to concern the same entity without collapsing those objects into a single entity record.
Entity identifiers SHOULD be stable, compact, and typed.
Within a knowledge system, data-entity functions as a semantic join key through which assertions, Fragments, relationships, and multiple manifestations concerning the same entity can be associated.
14. data-fragment — Semantic Fragment Class
data-fragment identifies the semantic role or class of a coherent
Fragment within the applicable KNOL composition.
An element carrying data-fragment establishes Fragment context for
that element and its applicable descendants.
A local data-fragment declaration replaces the Fragment context
established by any containing Fragment for that element and its applicable
descendants. It does not, by itself, establish a new KNOL or alter inherited
data-knol, data-entity,
data-scope, or data-source context.
Nested Fragments MAY be used when the nested native structure represents a
genuinely distinct semantic composition within the containing Fragment.
Implementations SHOULD NOT create nested Fragment boundaries merely to reflect
visual layout or ordinary HTML subdivision.
Fragment context describes the semantic composition in which an assertion or
relationship is manifested. Fragment context does not, by itself, alter the
identity of an assertion.
Accordingly, the same effective assertion MAY be manifested in multiple
Fragments without becoming multiple distinct assertions solely because its
Fragment context differs.
CostFragment
|
+-- plan.landscape.monthly-premium
FAQFragment
|
+-- plan.landscape.monthly-premium
ASSERTION IDENTITY
→ may remain the same
FRAGMENT CONTEXT
→ differs
In Native KNOL HTML, data-fragment SHOULD ordinarily be applied to
a native <section> when that section is the human-facing
structural manifestation of the Fragment.
<section data-fragment="FAQFragment">
...
</section>
The <section> creates the native thematic boundary.
data-fragment identifies the knowledge-composition role of that
boundary.
<section>
→ thematic HTML structure
data-fragment
→ semantic Fragment Class
Fragment Classes describe useful semantic units rather than serialization
technologies.
A Fragment Class MAY therefore have multiple manifestations. For example, a
DerivedStatsFragment could be represented through Native KNOL HTML,
encapsulated HTML, JSON, JSON-LD, an API, or another serialization while
remaining the same class of semantic composition.
A Fragment MAY contain:
- one or more assertions;
- one or more relationships;
- native structured data such as tables or definition lists;
- human explanatory prose;
- nested native structures;
- references to other entities or knowledge nodes; or
- any combination of these appropriate to the Fragment Class.
A Fragment Class SHOULD describe the semantic role of the composition rather
than merely its visual appearance.
For example:
FAQFragment
→ questions and answers concerning the applicable entity or knowledge context
DerivedStatsFragment
→ publisher-derived or calculated statistics concerning the applicable context
IndexFragment
→ membership or index information concerning identified objects
IdentityFragment
→ identity information concerning the applicable entity
ExplainerFragment
→ explanatory knowledge concerning the applicable subject
RelatedFragment
→ intentional semantic relationships to other identified knowledge resources
Fragment Classes MAY be domain-specific or general-purpose.
The Fragment Class does not determine the assertion namespace of every
assertion contained within it.
For example:
FAQFragment
|
+-- plan.landscape.monthly-premium
|
+-- plan.landscape.moop
|
+-- contract.performance.stars.value
|
+-- plan.enrollment.total
|
+-- plan.pbp.partd-deductible
These assertions may originate from different knowledge domains while still
forming a coherent FAQ semantic Fragment.
15. Initial Fragment Classes
KNOL v1.0 recognizes the WebMEM Fragment Class model as a reusable semantic
composition vocabulary.
The following initial Fragment Classes are defined or carried forward for use
with KNOL compositions:
DataFragment DerivedStatsFragment IndexFragment DefinedTermFragment FAQFragment MetaFragment ExplainerFragment DirectoryFragment EligibilityFragment ProcedureFragment GlossaryFragment PersonaFragment PolicyFragment RecommendationFragment IdentityFragment RelatedFragment
This list is extensible.
Implementations MAY define additional Fragment Classes when existing classes do
not accurately describe the semantic role of a composition.
Implementations SHOULD prefer a stable, reusable Fragment Class over creating
new classes for minor presentation differences.
15.1 DataFragment
A DataFragment groups source-reported or canonical data concerning
the applicable KNOL, entity, or scope.
Its native manifestation will frequently contain a
<table>, <dl>, list, or another structured
representation appropriate to the data.
15.2 DerivedStatsFragment
A DerivedStatsFragment groups statistics, aggregations,
calculations, classifications, or other knowledge derived from one or more
underlying assertions or datasets.
Assertions within a DerivedStatsFragment SHOULD use
data-derived="true" when derivation status is material.
The DerivedStatsFragment class describes the semantic role of the
Fragment but does not establish data-derived state for contained
assertions. Derivation state is assertion-specific and MUST be declared
explicitly on each assertion for which it applies.
An IndexFragment SHOULD use appropriate native HTML collection semantics,
including lists or tables, rather than inventing a parallel membership
structure.
15.4 DefinedTermFragment
A DefinedTermFragment identifies a semantic unit whose primary
purpose is to define a term, concept, identifier, or other addressable subject.
Where appropriate, native definition structures SHOULD be used.
15.5 FAQFragment
An FAQFragment groups questions and answers concerning the
applicable KNOL, entity, or scope.
The questions MAY concern multiple knowledge domains. The Fragment remains an
FAQFragment because its semantic role is question-and-answer composition.
An FAQFragment SHOULD preserve ordinary heading and prose semantics for its
human-facing questions and answers.
15.6 MetaFragment
A MetaFragment groups metadata concerning the applicable
publication, KNOL, entity, dataset, or manifestation.
Metadata that is already represented by stronger native HTML or another
standard mechanism SHOULD NOT be duplicated solely to populate a MetaFragment.
15.7 ExplainerFragment
An ExplainerFragment groups explanatory knowledge intended to
clarify the meaning, operation, interpretation, or significance of the
applicable subject.
An ExplainerFragment may be primarily prose and SHOULD retain native prose
semantics.
15.8 DirectoryFragment
A DirectoryFragment groups an organized collection of identifiable
entities or resources intended for discovery, navigation, or reference.
Native list, table, heading, and link structures SHOULD be used where
appropriate.
15.9 EligibilityFragment
An EligibilityFragment groups requirements, conditions,
qualifications, exclusions, or other knowledge used to determine whether an
entity or subject satisfies an applicable eligibility condition.
15.10 ProcedureFragment
A ProcedureFragment groups ordered or otherwise structured actions,
steps, requirements, or operations used to perform a procedure.
Where sequence is meaningful, native ordered-list semantics SHOULD be preferred.
15.11 GlossaryFragment
A GlossaryFragment groups multiple terms and their corresponding
definitions.
Native <dl>, <dt>, and
<dd> semantics SHOULD ordinarily be used where the content
is naturally represented as a definition list.
15.12 PersonaFragment
A PersonaFragment groups knowledge associated with an audience,
user type, role, use case, or other defined perspective relevant to the
applicable publication context.
15.13 PolicyFragment
A PolicyFragment groups rules, requirements, constraints,
permissions, prohibitions, or other policy knowledge associated with the
applicable subject.
15.14 RecommendationFragment
A RecommendationFragment groups recommendations, suggested actions,
preferred options, or other advisory knowledge.
Where recommendations are derived by the publisher rather than directly
reported by a source, derivation and provenance SHOULD be represented when
material.
15.15 IdentityFragment
An IdentityFragment groups knowledge used to identify or
disambiguate the applicable entity or knowledge object.
Identity knowledge MAY include names, identifiers, classifications, aliases,
parent relationships, geographic identity, or other distinguishing properties.
15.16 RelatedFragment
A RelatedFragment groups intentional semantic relationships from
the applicable KNOL or entity context to other identified entities, knowledge
nodes, or resources.
A RelatedFragment is not merely a collection of navigational links.
Each semantic edge SHOULD be expressed independently using
data-rel and data-ref where an appropriate native
manifestation exists.
<section data-fragment="RelatedFragment">
<h2>Related Medicare Information</h2>
<ul>
<li>
<a
href="/cms-contracts/H2406/"
data-rel="contract"
data-ref="contract:H2406">
CMS Contract H2406
</a>
</li>
<li>
<a
href="/organizations/unitedhealthcare/"
data-rel="offered-by"
data-ref="organization:unitedhealthcare">
UnitedHealthcare
</a>
</li>
</ul>
</section>
The Fragment identifies the semantic role of the collection. Each anchor
identifies an individual semantic relationship.
16. data-key — Assertion Address
data-key provides a stable semantic address for an assertion or
property manifested by an HTML element.
An assertion addressed by data-key MAY be scalar, temporal,
qualitative, composite, or propositional. data-key identifies the
semantic assertion or property being manifested; it does not require every
assertion to reduce to a single scalar value.
The HTML element carrying data-key SHOULD be the narrowest
appropriate native manifestation of that assertion. When a more precise native
or inline manifestation exists, it SHOULD be preferred over applying
data-key to a broader container.
An assertion is addressable when its data-key and applicable
semantic context can be resolved. The presence of data-value is
not required for assertion identity.
An assertion MAY be complete without data-value when its canonical
state is faithfully and unambiguously represented by native HTML or when the
assertion is not naturally modeled as a single scalar value.
An addressable assertion is not merely text near other text. It has a
semantic address.
The value of data-key SHOULD identify the canonical assertion
rather than merely reproduce a human-facing label.
Dotted namespaces SHOULD be used where they provide useful organization and
stability.
In the base KNOL v1.0 vocabulary, a data-key value MUST be a
non-empty semantic address and MUST NOT contain ASCII whitespace.
When dotted namespaces are used, each namespace segment MUST be non-empty.
Segments SHOULD use lowercase ASCII letters and MAY additionally contain ASCII
digits and hyphens.
assertion-address = segment *( "." segment )
The interpretation of namespace segments is defined by the publisher or
applicable KNOL Profile. Consumers MUST treat the complete
data-key value as the assertion address and MUST NOT infer
unsupported semantics from individual namespace segments.
identity.name plan.landscape.monthly-premium plan.landscape.partd-deductible.value contract.performance.stars.value contract.performance.hd1.value ma.stats.average-premium snp.stats.dsnp.plan-count publication.last-updated
A data-key value is interpreted within the applicable KNOL,
entity, Fragment, and scope context.
It therefore does not need to encode every contextual dimension into the key
itself.
KNOL
plan:H2406-129-0
ENTITY
plan:H2406-129-0
SCOPE
plan-year:2026
FRAGMENT
CostFragment
ASSERTION
plan.landscape.monthly-premium
The assertion address SHOULD remain stable when human-facing labels or
presentation change without changing the underlying semantic property.
A data-key value is not required to be unique within an HTML
document. The same assertion address MAY appear on multiple manifestations when
those manifestations represent the same semantic assertion within their
respective effective contexts.
For purposes of KNOL v1.0 resolution, the effective identity of an assertion is
determined by the following tuple:
ASSERTION IDENTITY
=
effective data-knol
+
effective data-entity
+
effective data-scope
+
data-key
An unspecified component remains unspecified; it MUST NOT be silently inferred
or replaced with an unrelated value merely to complete the tuple.
Two assertion manifestations MUST NOT be treated as manifestations of the same
effective assertion solely because their known identity components match when
one or more required identity components remain unspecified.
Assertion identity may be considered equivalent only when the applicable
identity components resolve equivalently under the base KNOL v1.0 rules or an
applicable KNOL Profile.
Fragment context, presentation structure, data-value,
data-type, data-unit, provenance, and derivation state
do not, by themselves, create a different assertion identity.
Accordingly, identical data-key values associated with different
entities or scopes do not necessarily identify the same effective assertion.
17. Assertion Manifestations
data-key SHOULD be applied to the native HTML element that most
directly manifests the addressable assertion.
The correct binding therefore depends upon the native HTML structure.
17.1 Assertions in Tables
Within a native HTML table, row and column relationships SHOULD be expressed
using standard table semantics.
The value cell SHOULD ordinarily carry the assertion address.
<table>
<tbody>
<tr>
<th scope="row"&>Monthly Premium</th>
<td
data-key="plan.landscape.monthly-premium"
data-value="295.00"
data-unit="USD">
$295.00
</td>
</tr>
</tbody>
</table>
The native table establishes:
Monthly Premium
|
v
$295.00
KNOL adds:
ASSERTION
plan.landscape.monthly-premium
CANONICAL VALUE
295.00
UNIT
USD
The <th> SHOULD NOT ordinarily receive a
data-key merely to duplicate the row or column identity already
expressed by native table semantics.
The <td> carries data-key because the cell is
the native manifestation of the addressable value.
Where the visible cell content faithfully and unambiguously represents the
canonical value, data-value MAY be omitted.
17.2 Assertions in Definition/Value Structures
Within a native definition/value structure, the
<dt> SHOULD provide the human-facing term and the
<dd> SHOULD ordinarily manifest the corresponding
addressable assertion.
<dl>
<dt>Average Monthly Premium</dt>
<dd
data-key="ma.stats.average-premium"
data-value="23.41"
data-unit="USD">
$23.41
</dd>
</dl>
The native definition list establishes:
Average Monthly Premium
|
v
$23.41
KNOL establishes:
ASSERTION
ma.stats.average-premium
CANONICAL VALUE
23.41
UNIT
USD
The <dt> SHOULD NOT ordinarily carry
data-key merely to identify the human-facing label.
The assertion is manifested by the corresponding
<dd>.
17.3 Assertions Embedded in Prose
A <p> element represents prose and SHOULD remain responsible
for that native role.
When an addressable assertion is embedded within prose, an appropriate inline
element such as <span> SHOULD ordinarily carry the KNOL
assertion state.
<p>
The monthly premium for this plan is
<span
data-key="plan.landscape.monthly-premium"
data-value="295.00"
data-unit="USD">$295.00</span>
for 2026.
</p>
The paragraph remains human prose.
The <span> identifies the precise manifestation of the
addressable assertion within that prose.
<p>
→ prose
<span>
→ inline assertion manifestation
data-key
→ assertion address
data-value
→ canonical value when required
Implementations SHOULD NOT indiscriminately apply
data-key to paragraphs merely because the paragraph contains
factual information.
Where a precise fact can be bound to an appropriate inline manifestation, that
binding SHOULD be preferred.
17.4 Assertions Expressed Through Native Time Semantics
When an assertion concerns a date or time, native
<time> semantics SHOULD be preserved.
<p>
CMS enrollment data were last updated
<span data-key="publication.last-updated">
<time datetime="2026-07-01">July 2026</time>
</span>.
</p>
The datetime attribute already provides a canonical temporal
representation.
KNOL SHOULD NOT duplicate that value through
data-value="2026-07-01" merely to restate semantics already
provided by native HTML.
The enclosing <span> gives the temporal fact an assertion
address while <time> retains responsibility for the date
representation.
18. data-value — Canonical Machine Value
data-value identifies the canonical machine value represented by a
human-facing manifestation when the visible representation differs from, or
does not sufficiently express, that canonical value.
data-value is assertion state and MUST be associated with an
assertion identified by data-key. An element carrying
data-value MUST therefore also carry data-key.
data-value MUST NOT be used as a standalone mechanism for attaching
machine-readable values to HTML that has no corresponding KNOL assertion
address.
The governing rule is:
When native element content faithfully and unambiguously represents the
canonical value,data-valueMAY be omitted. When presentation
transforms, decorates, localizes, abbreviates, symbolizes, or otherwise obscures
the canonical value,data-valueSHOULD provide the canonical
machine value.
When data-value is present, it MUST represent the same canonical
knowledge as the human-facing manifestation to which it is bound.
data-value MUST NOT contradict, substitute for, or introduce
knowledge that is not faithfully manifested by the associated native HTML.
Presentation differences are permitted. Semantic differences are not.
18.1 Faithful Visible Values
<dd
data-key="plan.performance.stars.value">3.5</dd>
If 3.5 is itself the canonical value, an additional
data-value="3.5" is unnecessary.
18.2 Transformed Presentation
<span
data-key="plan.performance.stars.value"
data-value="3.5"
data-type="number"
data-unit="stars">
★★★½☆
</span>
The human-facing presentation is graphical.
The canonical state is numeric.
HUMAN PRESENTATION
★★★½☆
CANONICAL VALUE
3.5
TYPE
number
UNIT
stars
This permits human presentation and canonical knowledge to differ without
becoming different assertions.
18.3 Formatted Currency
<span
data-key="plan.landscape.partd-deductible.value"
data-value="600.00"
data-type="number"
data-unit="USD">
$600.00
</span>
The visible representation includes presentation formatting and a currency
symbol.
The canonical lexical value is 600.00, while
data-unit="USD" supplies the associated currency.
18.4 Canonical Value Is Not a Complete Data Model
data-value SHOULD be interpreted as the canonical lexical value
associated with the assertion manifestation.
The lexical content of data-value is serialized as an HTML
attribute value. Its semantic interpretation is determined by the applicable
data-type, KNOL Profile, or other explicitly defined value rules.
Consumers MUST NOT infer a datatype solely from the lexical appearance of
data-value when no datatype is otherwise established.
For example, the lexical value 00123 MUST NOT automatically be
interpreted as the integer 123; it may represent a string
identifier for which leading zeros are significant.
Its complete semantic interpretation MAY depend upon additional state:
data-key
→ assertion identity
data-value
→ canonical lexical value
data-type
→ datatype
data-unit
→ measurement or scale
data-scope
→ applicability
data-source
→ provenance
data-derived
→ derivation status
data-digest
→ version or integrity state
The absence of data-value does not prohibit the use of
data-type or data-unit. When either attribute is
present without data-value, it qualifies the canonical state
faithfully manifested by the associated native HTML.
In all cases, data-type and data-unit qualify the
assertion identified by data-key; they MUST NOT be interpreted as
independent assertions.
19. data-type — Canonical Value Datatype
data-type identifies the datatype of an associated canonical value
when that datatype is useful and is not already unambiguously established by
native HTML or applicable context.
data-type is assertion state and MUST be associated with an
assertion identified by data-key. An element carrying
data-type MUST therefore also carry data-key.
When data-value is present, data-type describes the
datatype of that canonical value. When data-value is omitted
because native HTML faithfully exposes the canonical value,
data-type describes the datatype of that native value
manifestation.
The base KNOL v1.0 datatype vocabulary defines the following values:
string number integer boolean date datetime
These datatype tokens are case-sensitive and MUST be serialized in lowercase.
When data-type="string" is used, the canonical lexical value is
the character sequence represented by the associated native manifestation or
data-value.
String values are case-sensitive. Consumers MUST NOT trim, case-fold,
numerically coerce, or otherwise normalize a string value unless such
normalization is explicitly defined by the applicable KNOL Profile.
When data-type="boolean" is used, the permitted canonical lexical
values are true and false. Boolean values are
case-sensitive and MUST be serialized in lowercase.
The lexical values 1, 0, yes,
no, and other implementation-specific representations MUST NOT be
interpreted as boolean values under the base KNOL v1.0 vocabulary.
When data-type="integer" is used, the canonical lexical value MUST
represent a base-10 integer without grouping separators, currency symbols,
unit symbols, or other presentation characters.
When data-type="number" is used, the canonical lexical value MUST
represent a base-10 numeric value without grouping separators, currency symbols,
unit symbols, or other presentation characters.
A leading minus sign MAY be used for negative integer or number values. A
decimal point MAY be used for number values. A decimal point MUST
NOT be used for integer values.
integer
297
-12
number
4.0
295.00
-23.41
The base KNOL v1.0 numeric lexical form does not use locale-specific decimal
marks, thousands separators, currency symbols, unit suffixes, or scientific
notation.
When data-type="date" is used, the canonical lexical value MUST use
the ISO 8601 calendar-date form:
YYYY-MM-DD
For example:
2026-09-10
When data-type="datetime" is used, the canonical lexical value MUST
use an ISO 8601 date-and-time representation that includes a time-zone
designator or numeric UTC offset.
For example:
2026-09-10T14:30:00Z 2026-09-10T07:30:00-07:00
A datetime value lacking time-zone information is not a conforming
base KNOL v1.0 canonical datetime value.
When native <time datetime> already provides the applicable
canonical temporal representation, KNOL SHOULD use that native value rather
than duplicate it through data-value.
An applicable KNOL Profile MAY define additional datatype tokens where required.
Additional datatype tokens MUST NOT redefine the semantics of datatype tokens
defined by the base KNOL v1.0 vocabulary.
Datatype vocabularies SHOULD remain stable and SHOULD NOT be used merely to
repeat obvious presentation information.
<span
data-key="plan.performance.stars.value"
data-value="4.0"
data-type="number"
data-unit="stars">
★★★★☆
</span>
20. data-unit — Unit, Measurement, Currency, or Scale
data-unit identifies the unit, measurement, currency, score,
population unit, or other scale associated with a canonical value.
data-unit is assertion state and MUST be associated with an
assertion identified by data-key. An element carrying
data-unit MUST therefore also carry data-key.
When data-value is present, data-unit describes the
unit associated with that canonical value. When data-value is
omitted because native HTML faithfully exposes the canonical value,
data-unit describes the unit associated with that native value
manifestation.
Examples include:
USD percent stars beneficiaries plans days months years
KNOL v1.0 does not define a universal unit vocabulary. Unit tokens MUST be
non-empty and MUST NOT contain ASCII whitespace.
The meaning, case sensitivity, normalization, and permitted values of
data-unit SHOULD be defined by the applicable KNOL Profile or by
an established external unit or currency vocabulary adopted by that Profile.
Consumers MUST NOT assume that differently serialized unit tokens are
semantically equivalent unless that equivalence is defined by the applicable
KNOL Profile or adopted vocabulary.
A unit SHOULD be supplied only where it materially contributes to interpretation
of the value.
The unit SHOULD describe the canonical value rather than the typography used to
display it.
21. data-derived — Derivation Status
data-derived distinguishes knowledge reported directly by a source
from knowledge calculated, normalized, aggregated, classified, inferred, or
otherwise derived by the publisher.
data-derived="false"
indicates that the applicable assertion is represented as source-reported
knowledge.
data-derived="true"
indicates that the applicable assertion is publisher-derived.
The permitted lexical values of data-derived in KNOL v1.0 are
true and false. Values are case-sensitive and MUST be
serialized in lowercase.
Any other value is invalid under the base KNOL v1.0 vocabulary.
data-derived is local assertion state and MUST be associated with
an assertion identified by data-key. An element carrying
data-derived MUST therefore also carry data-key.
data-derived does not inherit from ancestor elements. A Fragment
Class such as DerivedStatsFragment MAY describe the semantic role
of a composition without causing every assertion within that Fragment to acquire
data-derived="true".
Derivation status SHOULD be represented where the distinction is material to
the interpretation or provenance of the assertion.
An implementation SHOULD NOT assume that the absence of
data-derived means either true or
false unless another applicable profile explicitly establishes
such a default.
22. data-scope — Applicability Context
data-scope identifies the applicability or contextual boundary
under which knowledge is valid or intended to be interpreted.
If no effective data-scope can be resolved for an assertion,
relationship, Fragment, or KNOL, its scope is unspecified. Consumers MUST NOT
infer a scope solely from surrounding prose, URL structure, publication date,
or other document context unless an applicable KNOL Profile explicitly defines
such a resolution rule.
An unspecified scope does not, by itself, make a KNOL assertion or relationship
invalid under the base KNOL v1.0 specification. An applicable KNOL Profile MAY
require scope for particular classes of knowledge.
Examples include:
plan-year:2026 county:04027 state:AZ population:standard-ma audience:medicare-beneficiary effective-date:2026-01-01
Scope SHOULD be declared at the highest unambiguous structural level and
inherited downward where practical.
<main
data-knol="plan:H2406-129-0"
data-entity="plan:H2406-129-0"
data-scope="plan-year:2026">
...
</main>
Assertions within this boundary inherit the 2026 plan-year scope unless a
nearer applicable element declares a new data-scope value.
In the base KNOL v1.0 model, a locally declared data-scope value
replaces the inherited data-scope value in full. Scope values MUST
NOT be implicitly merged, concatenated, or composed by a consumer.
Where multiple independent scope dimensions are required, an applicable KNOL
Profile MAY define a stable lexical representation and explicit composition
rules for expressing those dimensions within a single
data-scope value.
Implementations SHOULD avoid encoding contextual dimensions redundantly into
every data-key when those dimensions are already established by
scope.
23. data-source — Provenance Binding
data-source binds a KNOL, Fragment, assertion, relationship, or
other applicable semantic structure to a provenance resource.
A data-source value MUST be a non-empty provenance reference and
MUST NOT contain ASCII whitespace.
A data-source MAY identify a provenance resource within the
current document, a separately addressable provenance resource, or another
source identifier form defined by an applicable KNOL Profile.
When data-source uses a fragment reference beginning with
#, the referenced identifier MUST resolve to an element in the
current document.
KNOL v1.0 does not require a single universal provenance-resource format. The
applicable KNOL Profile MAY define the structure, vocabulary, and resolution
rules for provenance resources.
data-source="#source-cms-landscape"
The provenance resource MAY separately identify:
- source identity;
- publisher;
- dataset name;
- dataset version;
- retrieval or publication date;
- source URL;
- methodology;
- derivation process;
- license or usage conditions; or
- other lineage information.
Where multiple assertions share the same provenance, the source SHOULD be
declared at the highest unambiguous common boundary rather than repeated on
every assertion.
<section
data-fragment="DataFragment"
data-source="#source-cms-landscape">
...
</section>
data-source is inheritable context. A local
data-source declaration replaces the inherited
data-source value for that element and its applicable descendants.
It does not alter inherited data-knol,
data-entity, or data-scope context.
Individual descendants MAY declare a different data-source when
their knowledge has different provenance.
24. data-digest — Version, Snapshot, and Integrity State
data-digest identifies a version, snapshot, digest, or integrity
state associated with a KNOL or applicable manifestation.
data-digest is local semantic state and does not inherit from
ancestor elements. A data-digest value applies only to the KNOL,
Fragment, assertion, relationship, manifestation, or other semantic structure
on which it is explicitly declared.
A descendant MUST NOT be interpreted as carrying an ancestor’s
data-digest merely because it inherits other semantic context from
that ancestor.
The exact digest algorithm, encoding, comparison semantics, or validation
procedure is outside the minimum KNOL v1.0 HTML vocabulary unless defined by an
applicable profile.
A data-digest value SHOULD NOT imply cryptographic integrity unless
the applicable profile explicitly defines the digest as cryptographic and
specifies the required algorithm and canonicalization procedure.
The attribute exists so that implementations may identify and compare semantic
states without expanding the core HTML vocabulary into a complete validation
system.
25. Relationships and Semantic Edges
KNOL distinguishes navigation from semantic relationships.
A native HTML anchor:
<a href="/cms-contracts/H2406/">
CMS Contract H2406
</a>
establishes a navigable relationship between web resources.
It does not, by itself, explicitly state the semantic predicate connecting the
applicable knowledge context to the linked target.
KNOL adds that state using data-rel and
data-ref.
<a
href="/cms-contracts/H2406/"
data-rel="contract"
data-ref="contract:H2406">
CMS Contract H2406
</a>
The responsibilities are distinct:
href
→ Where can a browser navigate?
data-rel
→ Why is the target semantically connected?
data-ref
→ What identified entity, node, or resource is the semantic target?
26. data-rel — Relationship Predicate
data-rel identifies the predicate of a semantic relationship
manifested by an HTML element.
The source of a semantic relationship MUST be resolved from the effective
semantic context of the element carrying data-rel.
Relationship source is determined in the following order:
- If an effective
data-entityexists, that entity is the
relationship source. - Otherwise, if an effective
data-knolexists, that KNOL is
the relationship source. - Otherwise, the relationship source is unspecified and the relationship
is contextually incomplete.
A complete KNOL semantic relationship consists of three semantic components:
SOURCE
→ resolved from effective data-entity or data-knol context
PREDICATE
→ data-rel
TARGET
→ data-ref
KNOL semantic relationships are directed. A relationship expressed using
data-rel and data-ref is asserted from the resolved
relationship source to the identified target.
SOURCE
|
| data-rel
v
TARGET
The existence of a relationship from source to target MUST NOT be interpreted
as asserting the inverse relationship from target to source unless that inverse
relationship is separately asserted or explicitly defined by an applicable
KNOL Profile.
Likewise, consumers MUST NOT assume that a relationship predicate is symmetric,
transitive, reflexive, or otherwise possesses graph properties not explicitly
defined by the applicable KNOL Profile.
<main
data-knol="plan:H2406-129-0"
data-entity="plan:H2406-129-0">
<a
href="/cms-contracts/H2406/"
data-rel="contract"
data-ref="contract:H2406">
CMS Contract H2406
</a>
</main>
The semantic projection is:
SOURCE
plan:H2406-129-0
RELATIONSHIP
contract
TARGET
contract:H2406
Relationship predicates SHOULD be stable and SHOULD express the most specific
relationship that the publisher can justify.
In the base KNOL v1.0 vocabulary, a data-rel value MUST be a
non-empty relationship predicate and MUST NOT contain ASCII whitespace.
Relationship predicates SHOULD use lowercase ASCII letters and MAY additionally
contain ASCII digits and hyphens.
relationship-predicate = predicate-token
Relationship predicates are case-sensitive. Implementations MUST NOT assume
that differently serialized predicates are semantically equivalent unless an
applicable KNOL Profile explicitly defines that equivalence.
Examples MAY include:
contract offered-by available-in part-of member-of defined-by derived-from supersedes related
KNOL v1.0 does not require a universal ontology of relationship predicates.
Domain profiles MAY define controlled predicate vocabularies.
27. Generic related Relationship
The relationship predicate related MAY be used when an intentional
semantic relationship exists but a more-specific supported predicate is
unknown, unjustified, unavailable, or intentionally not asserted.
<a
href="/medicare-advantage/arizona/mohave-county/"
data-rel="related"
data-ref="county:arizona-mohave-04015">
Medicare Advantage plans in Mohave County
</a>
The related predicate SHOULD be treated as a deliberately
low-commitment semantic edge.
The related predicate is directed in the base KNOL v1.0 model.
Its use asserts that the resolved source is related to the identified target.
It does not, by itself, assert the inverse relationship from the target to the
source.
An applicable KNOL Profile MAY define a relationship predicate with symmetric
semantics when such behavior is required. Consumers MUST NOT infer symmetry
from the lexical meaning of the word related.
It SHOULD NOT become the default merely because an implementation has not
performed appropriate relationship classification.
Prefer a truthful broad relationship to an unjustified specific
relationship, but prefer a justified specific relationship to
related.
28. data-ref — Semantic Relationship Target
data-ref identifies the semantic target of a relationship or
reference.
A data-ref target is a semantic identity. The target MAY identify
an entity, a KNOL, or another semantic resource permitted by the applicable
KNOL Profile.
The presence of data-ref does not imply that the target is itself
a KNOL or that a corresponding data-knol manifestation exists.
Consumers MUST NOT infer a KNOL boundary or KNOL identity solely from the
presence of a semantic reference to that target.
data-rel and data-ref form a semantic relationship
pair in KNOL v1.0.
- An element carrying
data-relMUST also carry
data-ref. - An element carrying
data-refas a semantic relationship
target MUST also carrydata-rel.
A relationship lacking either its predicate or its target is incomplete and
MUST NOT be interpreted as a complete KNOL semantic edge.
<a
href="/cms-contracts/H2406/"
data-rel="contract"
data-ref="contract:H2406">
H2406
</a>
The distinction between href and data-ref is
intentional.
href
→ publication location
data-ref
→ semantic identity
A publication URL may change while the semantic identity remains stable.
Likewise, multiple publication URLs may manifest knowledge concerning the same
semantic target.
Accordingly, href and data-ref SHOULD NOT be treated
as interchangeable identifiers.
A data-ref value MUST be a non-empty semantic reference and MUST
NOT contain ASCII whitespace.
A data-ref MAY use a typed semantic identifier defined by this
specification, such as contract:H2406, or another reference form
defined by an applicable KNOL Profile.
When data-ref uses a typed semantic identifier, it MUST follow the
typed-identifier rules defined by this specification.
A relative or absolute URL used by href does not automatically
become the semantic data-ref. Publication location and semantic
target identity remain distinct unless an applicable KNOL Profile explicitly
defines a URL as the semantic identifier.
29. RelatedFragment and Graph Neighborhoods
A RelatedFragment provides a native semantic composition for
grouping intentional relationships associated with the applicable KNOL or
entity context.
<section data-fragment="RelatedFragment">
<h2>Related Medicare Information</h2>
<ul>
<li>
<a
href="/cms-contracts/H2406/"
data-rel="contract"
data-ref="contract:H2406">
CMS Contract H2406
</a>
</li>
<li>
<a
href="/organizations/unitedhealthcare/"
data-rel="offered-by"
data-ref="organization:unitedhealthcare">
UnitedHealthcare
</a>
</li>
<li>
<a
href="/medicare-advantage/arizona/mohave-county/"
data-rel="related"
data-ref="county:arizona-mohave-04015">
Medicare Advantage plans in Mohave County
</a>
</li>
</ul>
</section>
The native HTML expresses a thematic section containing a list of navigable
resources.
KNOL adds two semantic layers:
FRAGMENT
RelatedFragment
RELATIONSHIPS
contract
→ contract:H2406
offered-by
→ organization:unitedhealthcare
related
→ county:arizona-mohave-04015
The Fragment indicates that the collection represents an intentional semantic
neighborhood rather than incidental page navigation.
Each <a> independently identifies the predicate and target
of one semantic edge.
A consumer SHOULD NOT infer that every ordinary link within a
RelatedFragment represents a KNOL semantic edge. A semantic edge
is explicitly established when the applicable relationship semantics are
present.
30. Native HTML Binding Rules
Native KNOL HTML binds knowledge semantics to the strongest appropriate native
HTML structure.
The following table summarizes the ordinary division of responsibility:
| HTML Structure | Native HTML Responsibility | Typical KNOL Responsibility |
|---|---|---|
<main> |
Primary document content | SDT / primary KNOL, entity, and scope context |
<article> |
Self-contained content | KNOL or entity boundary where the self-contained content manifests a distinct knowledge object |
<section> |
Thematic grouping | Semantic Fragment; optionally refined entity or scope context |
<table> |
Tabular relationships | Context for addressable assertions and canonical values manifested by cells |
<th> |
Row or column identity | Usually none |
<td> |
Table value | data-key and, where required, canonical value/type/unit/source state |
<dl> |
Definition/value collection | Knowledge grouping or inherited context where needed |
<dt> |
Human-facing term | Usually none |
<dd> |
Definition/value | data-key and optional canonical state |
<p> |
Human prose | Usually none; assertions within prose SHOULD ordinarily be bound to an appropriate inline manifestation |
<span> |
Inline text or presentation boundary | Inline assertion address and canonical state where appropriate |
<strong> |
Strong importance | Usually none; MAY also manifest an assertion only when the emphasized content itself is the precise assertion manifestation |
<a> |
Navigation | data-rel and data-ref when the link manifests a semantic edge |
<time> |
Date/time semantics | Participates in an addressable temporal assertion without duplicating datetime |
<ul> |
Unordered collection | Usually none beyond applicable inherited Fragment/context semantics |
<ol> |
Ordered collection or sequence | Usually none beyond applicable inherited Fragment/context semantics |
<li> |
Member of a native list | MAY manifest an assertion, membership relationship, or other semantic state when the list item itself represents that knowledge |
This table is guidance for ordinary Native KNOL HTML authoring. It is not a
closed list of permissible HTML elements.
Other native HTML elements MAY carry KNOL state when the element is the
appropriate native manifestation of the knowledge.
Start with the strongest native HTML structure that represents the
knowledge. Then add only the KNOL state that HTML cannot express
unambiguously.
31. Tables and Addressable Semantic Values
Native HTML tables already provide strong relational structure.
A table can establish:
- the identity of the table through its caption and surrounding context;
- column identities;
- row identities;
- the structural intersection at which a value appears; and
- grouping among related values.
KNOL SHOULD NOT reconstruct those relationships through redundant attributes.
Instead, KNOL adds assertion-level semantic addressing to the appropriate value
manifestations.
<table id="table-office-visits">
<caption>Office Visit Costs</caption>
<thead>
<tr>
<th scope="col">Covered Service</th>
<th scope="col">In-Network Cost</th>
</tr>
</thead>
<tbody>
<tr>
<th scope="row">Specialist</th>
<td
data-key="plan.benefits.specialist.in-network-cost">
$25 copay
</td>
</tr>
</tbody>
</table>
Native HTML expresses:
Specialist
×
In-Network Cost
=
$25 copay
KNOL adds:
ASSERTION
plan.benefits.specialist.in-network-cost
VALUE MANIFESTATION
$25 copay
When combined with inherited context:
KNOL
plan:H2406-129-0
ENTITY
plan:H2406-129-0
SCOPE
plan-year:2026
ASSERTION
plan.benefits.specialist.in-network-cost
MANIFESTATION
$25 copay
This is an addressable semantic table: a native relational
table whose individual knowledge values have stable assertion-level semantic
addresses.
31.1 Canonical Values in Tables
Where table presentation is lossy or transformed, the value cell SHOULD expose
canonical state.
<tr>
<th scope="row">
Staying Healthy: Screenings, Tests, Vaccines
</th>
<td
data-key="contract.performance.hd1.value"
data-value="4"
data-type="number"
data-unit="stars">
★★★★☆
</td>
</tr>
The human-facing table remains optimized for presentation.
The machine-addressable state does not require a consumer to reconstruct the
numeric value from visual star characters, CSS, images, or other presentation
mechanisms.
32. Definition Lists and Addressable Values
Native definition lists provide another strong structure for KNOL assertions.
<dl>
<dt>Monthly Premium</dt>
<dd
data-key="plan.landscape.monthly-premium"
data-value="295.00"
data-unit="USD">
$295.00
</dd>
<dt>Part D Deductible</dt>
<dd
data-key="plan.landscape.partd-deductible.value"
data-value="600.00"
data-unit="USD">
$600.00
</dd>
</dl>
The definition list provides the human-readable term/value relationships.
KNOL provides stable semantic addresses for the values.
Authors SHOULD NOT apply data-key to
<dt> merely to restate the visible label.
33. Prose and Inline Assertion Binding
Human prose SHOULD remain human prose.
KNOL does not require paragraphs to become semantic records.
When an addressable fact occurs inside prose, the narrowest appropriate native
inline manifestation SHOULD ordinarily carry the assertion state.
<p>
The Part D deductible is
<span
data-key="plan.landscape.partd-deductible.value"
data-value="600.00"
data-unit="USD">$600.00</span>.
</p>
This preserves a useful distinction:
PARAGRAPH
→ human explanation
SPAN
→ precise fact manifestation
DATA-KEY
→ semantic address of that fact
DATA-VALUE
→ canonical value when presentation requires it
A paragraph SHOULD NOT be treated as an assertion container merely because it
contains one or more factual statements.
If an entire prose proposition is itself intentionally modeled as one
addressable assertion and no more precise native manifestation exists, a domain
profile MAY define an appropriate binding. Such use SHOULD be deliberate rather
than the default authoring pattern.
34. Fragment Composition and Native Structures
A Fragment is not a replacement for the native structures contained within it.
For example, a PerformanceFragment may contain explanatory prose,
structured metadata, and an addressable semantic table:
<section
data-fragment="PerformanceFragment"
data-entity="contract:H2406">
<h2>CMS Star Ratings</h2>
<p>
Medicare Advantage and Part D plans are rated each year by CMS
on a 5-star scale.
</p>
<table>
...
<tr>
<th scope="row">2026 Overall Rating</th>
<td
data-key="contract.performance.stars.value"
data-value="4.0"
data-unit="stars">
★★★★☆
</td>
</tr>
...
</table>
</section>
The semantic hierarchy is:
KNOL
plan:H2406-129-0
|
+-- FRAGMENT
PerformanceFragment
ENTITY
contract:H2406
SCOPE
plan-year:2026
|
+-- PROSE
|
+-- TABLE
|
+-- ASSERTION
contract.performance.stars.value
=
4.0 stars
The Fragment provides semantic composition.
The table provides native relational structure.
The cell provides the assertion manifestation.
KNOL attributes provide the semantic address and canonical state.
35. FAQFragment Example
An FAQFragment demonstrates that Fragment Classes describe
semantic composition rather than source taxonomy.
<main
data-knol="plan:H2406-129-0"
data-entity="plan:H2406-129-0"
data-scope="plan-year:2026">
<section data-fragment="FAQFragment">
<h2>
Plan Cost and Coverage Details
</h2>
<h3>
Is there a monthly premium for this plan in 2026?
</h3>
<p>
The plan's monthly premium is
<span
data-key="plan.landscape.monthly-premium"
data-value="295.00"
data-unit="USD">$295.00</span>
for 2026.
</p>
<h3>
What is the CMS star rating for this plan?
</h3>
<p>
For 2026, CMS Contract H2406 has a CMS star rating of
<span
data-entity="contract:H2406"
data-key="contract.performance.stars.value"
data-value="4.0"
data-unit="stars">4.0 out of 5 stars</span>.
</p>
<h3>
How many beneficiaries are enrolled in this plan?
</h3>
<p>
Total enrollment is
<span
data-key="plan.enrollment.total"
data-value="297"
data-type="integer"
data-unit="beneficiaries">297 beneficiaries</span>
based on the latest CMS data.
</p>
</section>
</main>
The effective composition is:
KNOL
plan:H2406-129-0
ENTITY
plan:H2406-129-0
SCOPE
plan-year:2026
FRAGMENT
FAQFragment
|
+-- ASSERTION
| plan.landscape.monthly-premium
| = 295.00 USD
|
+-- ASSERTION
| contract.performance.stars.value
| = 4.0 stars
| entity = contract:H2406
|
+-- ASSERTION
plan.enrollment.total
= 297 beneficiaries
The Fragment does not become a
CostFragment, PerformanceFragment, or
EnrollmentFragment merely because it contains assertions from
those domains.
Its semantic role is FAQ composition.
36. Identity, Fragment, Assertion, and Relationship Boundaries
A conforming implementation SHOULD preserve the distinction among the principal
semantic boundaries of KNOL.
KNOL
→ identifiable knowledge object
ENTITY
→ subject of applicable knowledge
FRAGMENT
→ coherent semantic composition within that knowledge
ASSERTION
→ addressable semantic property or fact
RELATIONSHIP
→ semantic edge to another identified target
These concepts SHOULD NOT be collapsed merely because a particular HTML
document could technically express them using the same element.
For example, a <section> may ordinarily manifest a Fragment:
<section data-fragment="FAQFragment">
...
</section>
The same native element may establish a more-specific entity context:
<section
data-fragment="PerformanceFragment"
data-entity="contract:H2406">
...
</section>
And a <section> may establish a genuinely distinct KNOL when
the section manifests an independently identifiable knowledge object:
<section
data-knol="analysis:2026-yuma-snp-landscape"
data-entity="county:arizona-yuma-04027"
data-scope="plan-year:2026">
...
</section>
The native HTML element alone does not determine which KNOL role applies.
The knowledge semantics attached to that element determine the applicable
knowledge boundary.
37. Minimal Markup and Semantic Economy
Native KNOL HTML SHOULD use the smallest sufficient semantic vocabulary.
An implementation SHOULD NOT add an attribute merely because the attribute
could describe information that is already unambiguously available from native
HTML or inherited context.
For example:
<main
data-knol="plan:H2406-129-0"
data-entity="plan:H2406-129-0"
data-scope="plan-year:2026">
<section data-fragment="CostFragment">
<dl>
<dt>Monthly Premium</dt>
<dd
data-key="plan.landscape.monthly-premium">
$295.00
</dd>
</dl>
</section>
</main>
The assertion does not need to repeat:
data-knol="plan:H2406-129-0" data-entity="plan:H2406-129-0" data-scope="plan-year:2026" data-fragment="CostFragment"
because those values are already established by applicable ancestors.
Likewise, the <dd> does not require
data-value="295.00" if the visible value is considered a faithful
and unambiguous manifestation of the canonical value under the applicable
serialization profile.
Semantic economy reduces markup duplication, lowers maintenance burden, and
reduces the possibility that duplicated semantic state will diverge.
Declare knowledge semantics once, at the strongest and highest
unambiguous location, and inherit them wherever possible.
38. Progressive Semantic Enrichment
Native KNOL HTML is a progressive semantic enrichment model.
A document SHOULD remain useful to consumers that do not recognize KNOL
attributes.
VISIBLE CONTENT
|
v
NATIVE HTML
|
v
NATIVE STRUCTURAL SEMANTICS
|
v
KNOL FRAGMENT COMPOSITION
|
v
ASSERTION ADDRESSABILITY
|
v
CANONICAL STATE
|
v
ENTITY + SCOPE + PROVENANCE
|
v
SEMANTIC RELATIONSHIPS
Each layer adds semantic precision without requiring the preceding layer to be
discarded.
A consumer that ignores KNOL attributes still receives ordinary native HTML.
A consumer capable of inspecting KNOL attributes may additionally resolve
explicit knowledge identity, Fragment composition, assertion addresses,
canonical values, entity context, scope, provenance, and semantic
relationships.
KNOL v1.0 does not require or assume that every web consumer recognizes the
KNOL vocabulary.
39. Semantic Distance
One design objective of Native KNOL HTML is to reduce the semantic distance
between human-facing presentation and the publisher’s intended canonical
knowledge state.
Consider a fact represented only in prose:
Members who receive specialty care generally pay a $25 copay.
A machine consumer may need to reconstruct:
SUBJECT PREDICATE OBJECT ENTITY SCOPE QUALIFIERS VALUE UNIT
A native table reduces some of that reconstruction:
Specialist | In-Network Cost
-----------+----------------
| $25 copay
Native KNOL HTML can reduce the remaining ambiguity further:
ENTITY
plan:H2406-129-0
SCOPE
plan-year:2026
ASSERTION
plan.benefits.specialist.in-network-cost
MANIFESTATION
$25 copay
The purpose is not to eliminate human presentation.
The purpose is to permit the publisher’s intended semantic state to coexist
with that presentation rather than requiring every machine consumer to
reconstruct the state independently.
40. Canonical Knowledge and Presentation Independence
KNOL distinguishes an assertion from the particular presentation through which
the assertion is manifested.
Two manifestations MAY present the same canonical assertion differently.
ASSERTION
contract.performance.stars.value
CANONICAL VALUE
4.0
MANIFESTATION A
4.0 stars
MANIFESTATION B
★★★★☆
MANIFESTATION C
Four out of five stars
These presentations do not necessarily represent different assertions.
Where the presentation itself does not faithfully expose canonical state,
data-value and related attributes SHOULD preserve that state.
This separation permits human presentation to evolve without requiring the
semantic identity of the underlying assertion to change.
41. Multiple Manifestations
A KNOL MAY be manifested through more than one serialization mode.
KNOL v1.0 recognizes at least the following conceptual modes:
41.1 Native Manifestation
A Native KNOL manifestation binds semantic state directly to human-facing HTML.
HUMAN HTML
+
KNOL ATTRIBUTES
|
v
NATIVE KNOL HTML
41.2 Encapsulated Manifestation
An encapsulated manifestation represents knowledge separately from the
human-facing manifestation.
HUMAN DOCUMENT
+
SEPARATE MACHINE-ORIENTED REPRESENTATION
|
v
ENCAPSULATED KNOL
An HTML <template> is one possible container for an
encapsulated manifestation, but KNOL does not define
<template> as the knowledge object itself.
41.3 Linked Manifestation
A linked manifestation makes the KNOL or an equivalent semantic representation
available through a separately addressable resource.
HUMAN DOCUMENT
|
| reference
v
LINKED KNOL REPRESENTATION
41.4 Hybrid Manifestation
A hybrid manifestation uses more than one serialization strategy for the same
knowledge object.
KNOL
|
+------------+------------+
| |
v v
NATIVE ASSERTIONS SEPARATE ASSERTIONS
| |
v v
HUMAN DOCUMENT ENCAPSULATED / LINKED
Native serialization SHOULD be preferred where existing human-facing HTML can
faithfully manifest the knowledge.
Encapsulated or linked serialization MAY be used where the knowledge cannot be
faithfully or appropriately manifested through the human-facing document.
42. Semantic Data Template (SDT)
The Semantic Data Template (SDT) is the page-level semantic
composition represented by the Fragments, assertions, relationships, and
applicable semantic context associated with a publication surface.
The SDT is a logical knowledge-composition concept and MUST NOT be defined by a
single serialization container.
In an encapsulated WebMEM manifestation:
SDT
|
v
<template>
|
+-- Fragment
+-- Fragment
+-- Fragment
In an ordinary Native KNOL HTML page:
SDT
|
v
<main>
|
+-- <section data-fragment="...">
|
+-- <section data-fragment="...">
|
+-- <section data-fragment="...">
The semantic composition is conceptually continuous even though the
serialization container changes.
In Native KNOL HTML, the document’s <main> element SHOULD
ordinarily serve as the primary native structural container for the SDT when
the page has one dominant knowledge composition.
This does not redefine the native HTML meaning of
<main>. The element remains the primary content of the
document. KNOL identifies the semantic composition manifested by that content.
43. Fragment Membership in the SDT
A Fragment manifested by a qualifying <section> within the
applicable SDT container is a semantic component of that SDT.
<main
data-knol="plan:H2406-129-0"
data-entity="plan:H2406-129-0"
data-scope="plan-year:2026">
<section data-fragment="IdentityFragment">
...
</section>
<section data-fragment="CostFragment">
...
</section>
<section data-fragment="PerformanceFragment">
...
</section>
<section data-fragment="FAQFragment">
...
</section>
<section data-fragment="RelatedFragment">
...
</section>
</main>
Conceptually:
SDT | +-- IdentityFragment | +-- CostFragment | +-- PerformanceFragment | +-- FAQFragment | +-- RelatedFragment
Fragment membership describes semantic composition. It does not imply that all
Fragments use the same internal HTML structure, source dataset, entity
refinement, or assertion namespace.
44. Fragment Class Versus Fragment Instance
A Fragment Class identifies the semantic kind of composition.
A particular section in a particular KNOL manifestation is an instance of that
Fragment Class.
FRAGMENT CLASS
FAQFragment
FRAGMENT INSTANCE
the FAQ section manifested within plan:H2406-129-0
under scope plan-year:2026
KNOL v1.0 does not require every Fragment instance to have a separate globally
unique identifier.
Where a Fragment requires independent identity, provenance, addressing,
versioning, or reuse beyond its enclosing composition, an implementation MAY
provide additional identity through an applicable profile or MAY model that
resource as a distinct KNOL when appropriate.
Authors SHOULD NOT create separate KNOL identities for ordinary Fragment
instances merely to make every section independently identifiable.
45. Nested KNOLs
A KNOL MAY contain a native structure that establishes another KNOL.
A nested KNOL SHOULD be used only when the subordinate knowledge is genuinely
an independently identifiable knowledge object rather than merely another
Fragment or contextual refinement.
<main
data-knol="county:arizona-yuma-04027"
data-entity="county:arizona-yuma-04027"
data-scope="plan-year:2026">
<section data-fragment="ExplainerFragment">
...
</section>
<section
data-knol="analysis:2026-yuma-snp-landscape"
data-entity="county:arizona-yuma-04027"
data-scope="plan-year:2026">
...
</section>
</main>
The subordinate analysis is not merely another topic section.
It is independently identifiable knowledge concerning the same entity.
A consumer encountering a new data-knol boundary SHOULD treat
that element and its applicable descendants as belonging to the newly
established KNOL context until another applicable boundary changes that
context.
46. Entity Refinement Without a New KNOL
Changing entity context does not necessarily create a new KNOL.
A Fragment MAY contain knowledge concerning a related entity while remaining
part of the enclosing KNOL composition.
<main
data-knol="plan:H2406-129-0"
data-entity="plan:H2406-129-0"
data-scope="plan-year:2026">
<section
data-fragment="PerformanceFragment"
data-entity="contract:H2406">
...
</section>
</main>
Conceptually:
KNOL
plan:H2406-129-0
|
+-- FRAGMENT
PerformanceFragment
ENTITY
contract:H2406
SCOPE
plan-year:2026
This permits a publication about one primary entity to accurately manifest
knowledge whose canonical subject is another entity without artificially
splitting every contextual change into a separate KNOL.
47. Assertion Identity Versus Display Labels
Human-facing labels and canonical assertion addresses perform different jobs.
A human-facing label MAY change for editorial, accessibility, localization, or
presentation reasons while the underlying assertion remains the same.
HUMAN LABEL
Monthly Premium
ASSERTION ADDRESS
plan.landscape.monthly-premium
Another publication might display:
HUMAN LABEL
Plan Premium
ASSERTION ADDRESS
plan.landscape.monthly-premium
The stable data-key permits both manifestations to address the
same semantic property.
Implementations SHOULD therefore avoid deriving canonical assertion identity
directly from mutable display labels when a stable semantic address is
available.
48. Semantic References Versus Publication Locations
KNOL distinguishes the identity of knowledge from the location at which a
manifestation happens to be published.
SEMANTIC IDENTITY
contract:H2406
PUBLICATION LOCATION
/cms-contracts/H2406/
The publication location MAY change:
/cms-contracts/H2406/ /contracts/H2406/ /medicare/contracts/H2406/
without necessarily changing:
contract:H2406
This distinction applies throughout the KNOL model:
data-knol
→ knowledge-node identity
data-entity
→ entity identity
data-ref
→ semantic target identity
href
→ navigable publication location
49. Provenance and Derivation
KNOL permits provenance and derivation state to be associated with knowledge at
multiple levels.
A source MAY apply to an entire KNOL:
<main
data-knol="..."
data-source="#source-primary">
A source MAY apply to a Fragment:
<section
data-fragment="DataFragment"
data-source="#source-cms-landscape">
Or a source MAY apply to one assertion:
<span
data-key="..."
data-source="#source-specific">
...
</span>
The most-specific applicable provenance binding SHOULD take precedence over a
more-general inherited binding.
Publisher-derived knowledge SHOULD distinguish derivation from source-reported
knowledge where that distinction materially affects interpretation.
<dd
data-key="ma.stats.average-premium"
data-value="23.41"
data-unit="USD"
data-derived="true"
data-source="#source-cms-landscape">
$23.41
</dd>
The source identifies the underlying provenance resource.
The derivation flag identifies the value as publisher-derived rather than a
directly reproduced source assertion.
50. KNOL Conformance Model
A Native KNOL HTML implementation conforms to KNOL v1.0 when it follows the
required semantic and structural rules defined by this specification.
Conformance does not require use of every KNOL attribute or every Fragment
Class.
50.1 Conformance Classes
KNOL v1.0 defines three conformance classes:
- KNOL Publisher
- An implementation that produces or publishes KNOL manifestations
conforming to this specification. - KNOL Consumer
- An implementation that parses, resolves, extracts, validates, or
otherwise interprets KNOL semantic state according to this
specification. - KNOL Profile
- A domain-specific or implementation-specific specification that
constrains or extends KNOL v1.0 without redefining the semantics of
the KNOL v1.0 core vocabulary.
An implementation MAY conform to more than one conformance class.
A claim of KNOL Publisher conformance concerns the semantic state emitted by
the publisher. A claim of KNOL Consumer conformance concerns the resolution and
interpretation behavior of the consumer. Neither claim implies conformance by
the other party.
A conforming KNOL Publisher:
- MUST preserve valid native HTML semantics;
- MUST NOT replace native HTML semantics with KNOL attributes;
- MUST preserve the distinction between KNOL identity and entity identity;
- MUST treat
data-keyas an assertion/property address rather than merely a display label; - MUST treat
data-relas a semantic relationship predicate anddata-refas its semantic target; - SHOULD use the strongest appropriate native HTML structure before adding KNOL semantics;
- SHOULD manifest ordinary semantic Fragments through appropriate native
<section>structures; - SHOULD declare semantic context at the highest unambiguous structural level and inherit it downward;
- SHOULD avoid duplicating semantics already expressed unambiguously by native HTML;
- SHOULD use
data-valuewhen presentation does not faithfully expose canonical value state; - SHOULD preserve stable semantic identifiers independently of mutable publication URLs or display labels;
- MAY use only the subset of extended attributes required by the knowledge being manifested; and
- MAY define domain-specific assertion namespaces, relationship vocabularies, Fragment Classes, scope conventions, and profiles consistent with this specification.
A conforming KNOL Consumer:
- MUST resolve inheritable context according to the effective-context
algorithm defined by this specification; - MUST distinguish local semantic attributes from inheritable context
attributes; - MUST resolve assertion identity according to the KNOL v1.0 assertion
identity rules; - MUST resolve relationship source, predicate, target, scope, and identity
according to the KNOL v1.0 relationship rules; - MUST preserve unspecified semantic state as unspecified rather than
silently inferring missing identity or context; - MUST NOT infer semantic equivalence from differences in case, lexical
form, publication URL, display label, or presentation unless that
equivalence is defined by this specification or an applicable KNOL
Profile; - MUST NOT treat repeated manifestations of the same effective assertion
or relationship as distinct semantic objects solely because they occur
in different Fragments or document locations; - SHOULD preserve and expose native HTML semantics when those semantics
contribute to interpretation of the KNOL manifestation; and - MAY ignore KNOL extensions it does not understand, provided doing so
does not cause the Consumer to assert unsupported semantic state.
50.1 Native HTML Conformance
KNOL conformance does not excuse invalid or semantically inappropriate HTML.
For example, an implementation SHOULD NOT use:
<div data-fragment="FAQFragment">
when the content is legitimately a thematic section and
<section> is the stronger native structure.
Likewise, an implementation SHOULD NOT replace a genuine table with generic
containers merely because assertion values can be annotated using
data-key.
KNOL conformance begins with semantic HTML.
50.2 Semantic Conformance
KNOL attributes MUST describe the knowledge actually manifested by the element
or applicable structural context.
For example:
<span
data-key="plan.landscape.monthly-premium"
data-value="295.00"
data-unit="USD">
$295.00
</span>
is semantically conforming only if the visible manifestation actually represents
the monthly premium assertion for the applicable entity and scope.
A publisher MUST NOT attach an unrelated assertion address merely to influence
machine interpretation.
50.3 Context Conformance
Inherited context MUST remain unambiguous.
Where an assertion applies to an entity or scope different from the inherited
context, the applicable structure MUST refine that context sufficiently to
prevent the assertion from being attributed to the wrong entity or scope.
For example:
<main
data-knol="plan:H2406-129-0"
data-entity="plan:H2406-129-0"
data-scope="plan-year:2026">
<section
data-fragment="PerformanceFragment"
data-entity="contract:H2406">
...
</section>
</main>
The entity refinement prevents contract-level performance assertions from being
incorrectly represented as plan-level assertions.
51. KNOL Profiles
KNOL v1.0 defines a general knowledge architecture and Native HTML
serialization vocabulary.
A domain or implementation MAY define a KNOL Profile that
constrains or extends the general specification for a particular knowledge
domain, publication system, or interoperability requirement.
A profile MAY define:
- entity identifier conventions;
- KNOL identifier conventions;
- assertion namespaces;
- permitted or recommended Fragment Classes;
- relationship predicates;
- scope vocabularies;
- datatype vocabularies;
- unit vocabularies;
- provenance conventions;
- digest algorithms;
- required attributes for particular knowledge types;
- validation rules; and
- serialization or manifestation requirements.
A conforming KNOL Profile MUST preserve the fundamental
semantics and resolution rules of the KNOL v1.0 core vocabulary.
A KNOL Profile MAY constrain the base specification by requiring optional
attributes, restricting permitted values, defining controlled vocabularies,
establishing cardinality, or imposing additional validation requirements.
A KNOL Profile MAY extend the base specification with domain-specific entity
types, assertion namespaces, Fragment Classes, relationship predicates, scope
forms, datatypes, units, provenance conventions, or other semantic rules.
A KNOL Profile MUST NOT redefine the semantic responsibility of a KNOL v1.0
core attribute, change the base effective-context resolution algorithm, or
assign contradictory semantics to a base vocabulary token.
For example, a Medicare profile may define:
ENTITY TYPES
plan
contract
county
carrier
SCOPE
plan-year
geography
population
ASSERTION NAMESPACES
plan.landscape.*
plan.pbp.*
plan.enrollment.*
contract.performance.*
ma.stats.*
snp.stats.*
RELATIONSHIPS
contract
offered-by
available-in
Those domain conventions refine KNOL without making Medicare semantics part of
the general KNOL v1.0 vocabulary.
52. Identifier Rules
KNOL identifiers, entity identifiers, assertion addresses, Fragment Classes,
relationship predicates, and semantic references SHOULD be designed for
stability.
52.1 Typed Identifiers
KNOL and entity identifiers SHOULD ordinarily use a compact typed form:
type:identifier
In the base KNOL v1.0 vocabulary, a typed semantic identifier consists of a
non-empty type token, a single colon separator, and a non-empty identifier
token:
typed-identifier = type ":" identifier
The type token SHOULD use lowercase ASCII letters and MAY additionally contain
ASCII digits and hyphens. It MUST begin with an ASCII letter.
The identifier token MUST NOT contain ASCII whitespace. The interpretation,
case sensitivity, normalization, and additional permitted characters of the
identifier token MAY be defined by the applicable KNOL Profile.
Typed semantic identifiers are opaque identifiers unless an applicable KNOL
Profile defines additional internal structure. Consumers MUST NOT infer
semantics from substrings within the identifier token unless such semantics are
defined by that profile.
Examples:
plan:H2406-129-0 contract:H2406 county:arizona-yuma-04027 organization:unitedhealthcare analysis:2026-yuma-snp-landscape
52.2 Stability
Semantic identifiers SHOULD NOT change merely because:
- a page URL changes;
- a heading changes;
- a visual template changes;
- content is moved within the document;
- a CSS selector changes;
- a publication system changes; or
- the same knowledge is serialized through another manifestation.
52.3 Assertion Addresses
Assertion addresses SHOULD identify semantic properties rather than document
locations.
Preferred:
plan.landscape.monthly-premium
Not preferred as a canonical semantic address:
table-2-row-4-cell-2 faq-answer-3 right-column-premium
Document selectors MAY be useful for manifestation binding or validation, but
they SHOULD NOT substitute for stable semantic assertion identity.
52.4 Fragment Class Names
Fragment Class names SHOULD describe reusable semantic composition roles.
Fragment Class names defined by KNOL v1.0 use UpperCamelCase and the
Fragment suffix.
fragment-class = class-name "Fragment"
A Fragment Class name MUST be non-empty, MUST NOT contain ASCII whitespace,
and SHOULD use ASCII letters and digits.
Custom Fragment Classes defined by an implementation or KNOL Profile SHOULD
follow the same naming convention unless that Profile explicitly defines an
alternative convention.
FAQFragment DerivedStatsFragment IdentityFragment RelatedFragment
Fragment Classes SHOULD NOT ordinarily encode page-specific identifiers or
presentation details.
53. Native HTML and Schema.org
KNOL does not replace Schema.org or other established structured-data
vocabularies.
A publication MAY use native HTML, Schema.org structured data, and KNOL
simultaneously when each layer serves a distinct purpose.
For example:
NATIVE HTML
→ establishes table structure
SCHEMA.ORG
→ may describe the table as an identifiable structured-data object
KNOL
→ identifies the canonical assertions manifested by individual values
and establishes their entity, scope, Fragment, and provenance context
Example:
<section
data-fragment="PerformanceFragment"
data-entity="contract:H2406">
<h2>CMS Star Ratings</h2>
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "Table",
"@id": "#table-medicare-star-ratings",
"name": "2026 Medicare Star Ratings for Contract H2406",
"url": "#table-medicare-star-ratings"
}
</script>
<table id="table-medicare-star-ratings">
<caption>
2026 Medicare Star Ratings for Contract H2406
</caption>
...
<tr>
<th scope="row">2026 Overall Rating</th>
<td
data-key="contract.performance.stars.value"
data-value="4.0"
data-unit="stars">
★★★★☆
</td>
</tr>
...
</table>
</section>
The layers are complementary.
HTML
→ What structure is this?
SCHEMA.ORG
→ What structured object is this?
KNOL
→ What knowledge does this structure manifest?
54. Serialization Manifest
A Serialization Manifest may describe how canonical KNOL
assertions are bound to one or more publication manifestations.
The Serialization Manifest is conceptually related to KNOL but is not defined
in full by the minimum KNOL v1.0 HTML vocabulary.
A manifest may identify:
- canonical assertion identity;
- serialization mode;
- manifestation format;
- binding location;
- expected canonical value;
- invariant state;
- provenance;
- validation status;
- fidelity classification;
- digest state; or
- other controls required to preserve semantic state across manifestations.
Conceptually:
CANONICAL ASSERTION
plan.landscape.monthly-premium
|
+-- MANIFESTATION
| mode: native
| format: html
| binding:
| [data-key="plan.landscape.monthly-premium"]
|
+-- MANIFESTATION
mode: api
format: json
binding:
...
The control objective is:
Preserve and verify assertion-level canonical semantic state across
changing and heterogeneous publication manifestations.
KNOL v1.0 does not require a Serialization Manifest for basic Native KNOL HTML
conformance.
55. Semantic Fidelity Across Manifestations
Multiple manifestations of the same assertion SHOULD preserve equivalent
canonical semantic state even when their presentation or serialization differs.
For example:
CANONICAL ASSERTION
contract.performance.stars.value
CANONICAL VALUE
4.0
NATIVE HTML
★★★★☆
JSON
4.0
API
{
"stars": 4.0
}
HUMAN PROSE
4.0 out of 5 stars
The manifestations differ.
The intended canonical assertion does not.
A future KNOL validation or manifest profile MAY define formal fidelity classes,
comparison rules, canonicalization procedures, or error conditions.
56. Non-Goals
KNOL v1.0 does not attempt to define every layer of a complete knowledge
publishing system.
This specification does not, by itself, define:
- a required database schema;
- a canonical storage engine;
- a universal ontology;
- a universal taxonomy;
- a universal relationship vocabulary;
- a universal Fragment Class registry;
- a transport protocol;
- a required API format;
- a required standalone file format;
- a universal provenance vocabulary;
- a canonical assertion store;
- a complete Serialization Manifest format;
- an invariant profile;
- a fidelity classification system;
- a validation engine;
- a change-propagation system;
- a crawler implementation;
- a retrieval algorithm;
- a ranking algorithm;
- an answer-engine optimization method; or
- a required machine-consumption implementation.
Those systems MAY operate above, below, or alongside KNOL.
The purpose of KNOL v1.0 is narrower:
To define an identifiable knowledge object, its semantic composition,
and a compact mechanism for manifesting addressable knowledge through native
HTML without replacing native HTML semantics.
57. Consumer Independence
KNOL defines publisher-side semantic state.
It does not require a particular crawler, search engine, language model,
retrieval system, browser, agent, or other consumer to interpret that state.
A conforming publisher MAY emit Native KNOL HTML even when some or all
downstream consumers ignore KNOL attributes.
The native HTML SHOULD remain independently useful in that condition.
CONSUMER RECOGNIZES KNOL
|
v
NATIVE HTML
+
EXPLICIT KNOWLEDGE SEMANTICS
CONSUMER IGNORES KNOL
|
v
NATIVE HTML
|
v
NORMAL HTML CONSUMPTION
This progressive-enhancement property is a deliberate design characteristic of
Native KNOL HTML.
58. Claims and Interpretation
Conformance with KNOL v1.0 permits a publisher to state that the publication
makes intended semantic state explicit through the KNOL vocabulary.
A publisher MAY state that Native KNOL HTML:
- adds knowledge-node identity to native HTML;
- adds semantic Fragment composition to native HTML sections;
- adds assertion-level semantic addresses to appropriate native manifestations;
- preserves canonical values where human presentation differs from canonical state;
- supports explicit entity and scope context;
- supports provenance and derivation metadata;
- supports explicit semantic relationships and references; and
- preserves ordinary native HTML for consumers that do not interpret KNOL.
Conformance alone does not establish that a particular external consumer
recognizes, interprets, indexes, retrieves, ranks, cites, or otherwise uses KNOL
semantics.
Claims concerning specific consumer behavior SHOULD be supported by separate
observation or testing.
59. Reference Native KNOL HTML Example
The following example illustrates the principal KNOL v1.0 composition model in
one native HTML document.
<main
data-knol="plan:H2406-129-0"
data-entity="plan:H2406-129-0"
data-scope="plan-year:2026">
<section data-fragment="IdentityFragment">
<h1>
AARP Medicare Advantage Access from UHC AZ-15 (PPO)
</h1>
<dl>
<dt>Contract ID</dt>
<dd>
<a
href="/cms-contracts/H2406/"
data-rel="contract"
data-ref="contract:H2406">
H2406
</a>
</dd>
</dl>
</section>
<section data-fragment="CostFragment">
<h2>Plan Costs</h2>
<dl>
<dt>Monthly Premium</dt>
<dd
data-key="plan.landscape.monthly-premium"
data-value="295.00"
data-type="number"
data-unit="USD">
$295.00
</dd>
<dt>Part D Deductible</dt>
<dd
data-key="plan.landscape.partd-deductible.value"
data-value="600.00"
data-type="number"
data-unit="USD">
$600.00
</dd>
</dl>
</section>
<section
data-fragment="PerformanceFragment"
data-entity="contract:H2406">
<h2>CMS Star Ratings</h2>
<p>
Medicare Advantage and Part D plans are rated each year by CMS
on a 5-star scale.
</p>
<table>
<caption>
2026 Medicare Star Ratings for Contract H2406
</caption>
<thead>
<tr>
<th scope="col">CMS Measure</th>
<th scope="col">Star Rating</th>
</tr>
</thead>
<tbody>
<tr>
<th scope="row">2026 Overall Rating</th>
<td
data-key="contract.performance.stars.value"
data-value="4.0"
data-type="number"
data-unit="stars">
★★★★☆
</td>
</tr>
<tr>
<th scope="row">
Staying Healthy: Screenings, Tests, Vaccines
</th>
<td
data-key="contract.performance.hd1.value"
data-value="4"
data-type="number"
data-unit="stars">
★★★★☆
</td>
</tr>
</tbody>
</table>
</section>
<section data-fragment="FAQFragment">
<h2>Plan Cost and Coverage Details</h2>
<h3>
Is there a monthly premium for this plan in 2026?
</h3>
<p>
The plan's monthly premium is
<span
data-key="plan.landscape.monthly-premium"
data-value="295.00"
data-type="number"
data-unit="USD">$295.00</span>
for 2026.
</p>
<h3>
What is the CMS star rating for this plan?
</h3>
<p>
For 2026,
<a
href="/cms-contracts/H2406/"
data-rel="contract"
data-ref="contract:H2406">CMS Contract H2406</a>
has a CMS star rating of
<span
data-entity="contract:H2406"
data-key="contract.performance.stars.value"
data-value="4.0"
data-type="number"
data-unit="stars">4.0 out of 5 stars</span>.
</p>
<h3>
How many beneficiaries are enrolled in this plan?
</h3>
<p>
Total enrollment is
<span
data-key="plan.enrollment.total"
data-value="297"
data-type="integer"
data-unit="beneficiaries">297 beneficiaries</span>
based on the latest CMS data.
</p>
</section>
<section data-fragment="RelatedFragment">
<h2>Related Medicare Information</h2>
<ul>
<li>
<a
href="/cms-contracts/H2406/"
data-rel="contract"
data-ref="contract:H2406">
CMS Contract H2406
</a>
</li>
<li>
<a
href="/organizations/unitedhealthcare/"
data-rel="offered-by"
data-ref="organization:unitedhealthcare">
UnitedHealthcare
</a>
</li>
<li>
<a
href="/medicare-advantage/arizona/"
data-rel="related"
data-ref="geography:arizona">
Medicare Advantage in Arizona
</a>
</li>
</ul>
</section>
</main>
This example contains one primary Native KNOL HTML composition:
SDT
|
+-- KNOL
| plan:H2406-129-0
|
+-- ENTITY
| plan:H2406-129-0
|
+-- SCOPE
| plan-year:2026
|
+-- IdentityFragment
| |
| +-- RELATIONSHIP
| contract
| → contract:H2406
|
+-- CostFragment
| |
| +-- ASSERTION
| | plan.landscape.monthly-premium
| | = 295.00 USD
| |
| +-- ASSERTION
| plan.landscape.partd-deductible.value
| = 600.00 USD
|
+-- PerformanceFragment
| |
| +-- ENTITY
| | contract:H2406
| |
| +-- ASSERTION
| | contract.performance.stars.value
| | = 4.0 stars
| |
| +-- ASSERTION
| contract.performance.hd1.value
| = 4 stars
|
+-- FAQFragment
| |
| +-- ASSERTION
| | plan.landscape.monthly-premium
| | = 295.00 USD
| |
| +-- RELATIONSHIP
| | contract
| | → contract:H2406
| |
| +-- ASSERTION
| | contract.performance.stars.value
| | = 4.0 stars
| | entity = contract:H2406
| |
| +-- ASSERTION
| plan.enrollment.total
| = 297 beneficiaries
|
+-- RelatedFragment
|
+-- RELATIONSHIP
| contract
| → contract:H2406
|
+-- RELATIONSHIP
| offered-by
| → organization:unitedhealthcare
|
+-- RELATIONSHIP
related
→ geography:arizona
The same canonical assertion MAY appear in more than one Fragment when the
human-facing publication legitimately manifests that fact in multiple semantic
contexts.
For example:
plan.landscape.monthly-premium
|
+-- CostFragment
| → $295.00
|
+-- FAQFragment
→ $295.00
These are multiple manifestations of the same assertion within one publication
composition. They SHOULD preserve equivalent canonical semantic state.
60. Repeated Assertions Within a Publication
Native documents frequently repeat important facts in multiple human-facing
contexts.
KNOL does not require publishers to eliminate legitimate repetition.
When the same canonical assertion is manifested more than once, each
manifestation MAY carry the same data-key.
Each occurrence is a distinct manifestation of the assertion,
not necessarily a distinct assertion.
KNOL v1.0 does not require a separate semantic identifier for every assertion
manifestation. Native document identity mechanisms such as id MAY
be used when a particular manifestation requires independent document-level
addressability.
Document location, HTML id, Fragment context, or DOM position MUST
NOT, by themselves, be interpreted as creating a new assertion identity.
<section data-fragment="CostFragment">
<dd
data-key="plan.landscape.monthly-premium"
data-value="295.00"
data-unit="USD">
$295.00
</dd>
</section>
<section data-fragment="FAQFragment">
<p>
The monthly premium is
<span
data-key="plan.landscape.monthly-premium"
data-value="295.00"
data-unit="USD">$295.00</span>.
</p>
</section>
Both elements manifest:
ASSERTION
plan.landscape.monthly-premium
CANONICAL VALUE
295.00
UNIT
USD
Their structural and compositional contexts differ:
MANIFESTATION A
Fragment = CostFragment
Structure = definition/value
MANIFESTATION B
Fragment = FAQFragment
Structure = prose / inline assertion
A conforming publication SHOULD preserve equivalent canonical state across
repeated manifestations of the same assertion under the same applicable entity
and scope.
Where repeated manifestations intentionally differ because their entity, scope,
source, or other semantic context differs, the differing context MUST be made
sufficiently explicit to prevent them from being interpreted as contradictory
manifestations of the same canonical state.
61. Contradictory Manifestations
Two manifestations of the same effective assertion SHOULD expose equivalent
canonical semantic state.
The base KNOL v1.0 specification does not define whether a particular assertion
is single-valued or multivalued. An applicable KNOL Profile MAY define value
cardinality for specific assertion addresses or assertion classes.
Where an assertion is defined as single-valued, multiple manifestations of that
assertion MUST NOT expose contradictory canonical values within the same
effective context.
Where an assertion is defined as multivalued, multiple distinct values are not
inherently contradictory when they conform to the cardinality and interpretation
rules of the applicable KNOL Profile.
For example, the following semantic state is ordinarily contradictory:
KNOL
plan:H2406-129-0
ENTITY
plan:H2406-129-0
SCOPE
plan-year:2026
ASSERTION
plan.landscape.monthly-premium
MANIFESTATION A
295.00 USD
MANIFESTATION B
310.00 USD
A publisher SHOULD resolve such contradictions or refine the semantic context
to explain why the values legitimately differ.
Possible distinguishing context might include:
- different effective periods;
- different geographic scopes;
- different population scopes;
- different source versions;
- different derivation methods; or
- different entities.
KNOL v1.0 does not define a complete contradiction-resolution algorithm.
It provides sufficient semantic addressing for validation systems to identify
when apparently equivalent assertion manifestations disagree.
62. Fragment and Assertion Reuse
A semantic Fragment Class MAY be reused across many KNOLs.
plan:H2406-129-0
|
+-- FAQFragment
plan:H5587-002-0
|
+-- FAQFragment
county:arizona-yuma-04027
|
+-- FAQFragment
The Fragment Class identifies the semantic role of each composition. The
enclosing KNOL, entity, and scope establish the knowledge context of each
Fragment instance.
Likewise, a stable assertion namespace MAY be reused across many entities:
plan:H2406-129-0
plan.landscape.monthly-premium
plan:H5587-002-0
plan.landscape.monthly-premium
plan:H0609-038-0
plan.landscape.monthly-premium
The assertion address identifies the semantic property.
The entity context identifies which subject the property applies to.
This separation is fundamental to KNOL addressability.
63. Knowledge Resolution Model
A KNOL-aware consumer can conceptually resolve an assertion manifestation by
combining local semantic state with inherited context.
Given:
<main
data-knol="plan:H2406-129-0"
data-entity="plan:H2406-129-0"
data-scope="plan-year:2026">
<section data-fragment="CostFragment">
<dl>
<dt>Monthly Premium</dt>
<dd
data-key="plan.landscape.monthly-premium"
data-value="295.00"
data-unit="USD">
$295.00
</dd>
</dl>
</section>
</main>
the effective semantic state can be resolved as:
1. Locate assertion manifestation
|
v
data-key
plan.landscape.monthly-premium
2. Resolve nearest applicable Fragment
|
v
CostFragment
3. Resolve nearest applicable entity
|
v
plan:H2406-129-0
4. Resolve nearest applicable scope
|
v
plan-year:2026
5. Resolve canonical value state
|
v
295.00
6. Resolve unit
|
v
USD
7. Resolve applicable provenance if present
|
v
source / derivation / digest
8. Produce effective assertion
|
v
plan:H2406-129-0
plan-year:2026
plan.landscape.monthly-premium
=
295.00 USD
This conceptual resolution model does not require a particular parser
implementation.
It defines the semantic interpretation intended by the publisher.
64. Relationship Resolution Model
A semantic relationship can likewise be resolved from local relationship state
and inherited source context.
Given:
<main
data-knol="plan:H2406-129-0"
data-entity="plan:H2406-129-0">
<a
href="/cms-contracts/H2406/"
data-rel="contract"
data-ref="contract:H2406">
CMS Contract H2406
</a>
</main>
the semantic relationship is:
SOURCE
plan:H2406-129-0
PREDICATE
contract
TARGET
contract:H2406
The corresponding href supplies:
NAVIGATION
/cms-contracts/H2406/
The semantic relationship and navigable destination are associated but remain
distinct.
The same semantic relationship MAY be manifested more than once within a
publication.
For purposes of KNOL v1.0 resolution, relationship identity is determined by
the following tuple:
RELATIONSHIP IDENTITY
=
resolved source
+
effective data-scope
+
data-rel
+
data-ref
Multiple manifestations that resolve to the same source, effective scope,
predicate, and target represent repeated manifestations of the same semantic
relationship rather than distinct relationships solely because they occur in
different Fragments, elements, or document locations.
An unspecified scope remains part of the unresolved relationship context and
MUST NOT be treated as equivalent to a specific scope.
Two relationship manifestations MUST NOT be treated as manifestations of the
same effective relationship solely because their known identity components
match when one or more identity components remain unspecified.
Relationship identity may be considered equivalent only when the resolved
source, effective scope, predicate, and target resolve equivalently under the
base KNOL v1.0 rules or an applicable KNOL Profile.
Fragment context, href, HTML id, DOM position, and
presentation structure do not, by themselves, create a different relationship
identity.
65. Fragment Resolution Model
A Fragment is resolved through its Fragment Class and inherited knowledge
context.
Given:
<main
data-knol="plan:H2406-129-0"
data-entity="plan:H2406-129-0"
data-scope="plan-year:2026">
<section data-fragment="FAQFragment">
...
</section>
</main>
the effective Fragment is:
KNOL
plan:H2406-129-0
ENTITY
plan:H2406-129-0
SCOPE
plan-year:2026
FRAGMENT CLASS
FAQFragment
If the section refines entity context:
<section
data-fragment="PerformanceFragment"
data-entity="contract:H2406">
the effective Fragment becomes:
KNOL
plan:H2406-129-0
ENTITY
contract:H2406
SCOPE
plan-year:2026
FRAGMENT CLASS
PerformanceFragment
If the section establishes a new data-knol, the new KNOL boundary
takes effect for applicable descendants.
66. Validation Principles
KNOL v1.0 does not define a complete validation engine, but it establishes
semantic conditions that a validator MAY evaluate.
A validator MAY test:
- whether required KNOL identifiers are syntactically valid under an applicable profile;
- whether assertion addresses use permitted namespaces;
- whether Fragment Classes are recognized by the applicable profile;
- whether relationship predicates are recognized;
- whether
data-relis accompanied by an appropriatedata-ref; - whether canonical values conform to declared datatypes;
- whether canonical values conform to declared units;
- whether inherited entity and scope context are unambiguous;
- whether repeated manifestations of the same assertion preserve equivalent canonical state;
- whether provenance references resolve;
- whether native HTML structures are used consistently with their semantic roles; and
- whether a manifestation preserves required semantic invariants.
Validation SHOULD distinguish between:
HTML VALIDITY
→ Is the document structurally valid HTML?
KNOL SYNTACTIC VALIDITY
→ Are KNOL attributes and values well formed?
KNOL SEMANTIC VALIDITY
→ Do the annotations accurately describe the manifested knowledge?
PROFILE VALIDITY
→ Does the implementation satisfy domain-specific constraints?
FIDELITY VALIDITY
→ Do multiple manifestations preserve equivalent canonical state?
67. Error Conditions and Ambiguity
A KNOL implementation SHOULD avoid semantic states that cannot be resolved
unambiguously.
Potential errors include:
- an assertion with no determinable entity when entity identity is required;
- an assertion inheriting the wrong scope;
- a relationship with an undefined semantic target;
- conflicting inherited contexts;
- multiple contradictory canonical values for the same effective assertion;
- a
data-valueinconsistent with the knowledge manifested visibly; - a Fragment Class inconsistent with the actual semantic role of the section;
- a new
data-knolboundary used where only a Fragment was intended; - a
data-keyused merely as a mutable presentation label; - a semantic relationship asserted where only navigation exists; or
- KNOL annotations that contradict native HTML semantics.
When semantic state is ambiguous, publishers SHOULD prefer omission over
unsupported precision.
Where a more-specific semantic relationship, entity classification, scope, or
other state cannot be justified, an implementation MAY use a broader truthful
representation or omit the unsupported semantic annotation.
68. Authoring Principles
A publisher implementing Native KNOL HTML SHOULD follow a structure-first
authoring process.
1. IDENTIFY THE KNOWLEDGE OBJECT
|
v
2. IDENTIFY THE PRIMARY ENTITY
|
v
3. IDENTIFY APPLICABLE SCOPE
|
v
4. BUILD THE HUMAN DOCUMENT USING SEMANTIC HTML
|
v
5. IDENTIFY SEMANTIC FRAGMENTS
|
v
6. IDENTIFY ADDRESSABLE ASSERTIONS
|
v
7. IDENTIFY CANONICAL VALUES WHERE PRESENTATION DIFFERS
|
v
8. IDENTIFY SEMANTIC RELATIONSHIPS
|
v
9. ADD PROVENANCE / DERIVATION WHERE MATERIAL
|
v
10. VALIDATE INHERITANCE AND SEMANTIC FIDELITY
The authoring process SHOULD NOT begin by attempting to attach KNOL attributes
to every available HTML element.
The intended sequence is:
Structure the document for people first. Identify the knowledge
composition second. Add only the semantic state required to make that knowledge
explicit and addressable.
69. Anti-Patterns
The following patterns SHOULD be avoided in Native KNOL HTML.
69.1 Attribute Saturation
KNOL attributes SHOULD NOT be indiscriminately attached to every heading,
paragraph, label, list item, or container.
Not recommended:
<p
data-knol="plan:H2406-129-0"
data-entity="plan:H2406-129-0"
data-scope="plan-year:2026"
data-fragment="CostFragment"
data-key="plan.landscape.monthly-premium"
data-value="295.00"
data-unit="USD">
The monthly premium is $295.00.
</p>
Preferred:
<main
data-knol="plan:H2406-129-0"
data-entity="plan:H2406-129-0"
data-scope="plan-year:2026">
<section data-fragment="CostFragment">
<p>
The monthly premium is
<span
data-key="plan.landscape.monthly-premium"
data-value="295.00"
data-unit="USD">$295.00</span>.
</p>
</section>
</main>
69.2 Replacing Native Relationships
KNOL SHOULD NOT recreate relationships that native HTML already expresses
unambiguously.
Not recommended:
<dt data-key="plan.landscape.monthly-premium.label">
Monthly Premium
</dt>
<dd data-key="plan.landscape.monthly-premium.value">
$295.00
</dd>
when the intended assertion is simply:
<dt>Monthly Premium</dt>
<dd data-key="plan.landscape.monthly-premium">
$295.00
</dd>
The <dt>/<dd> relationship already provides
the native term/value structure.
69.3 Treating Every Section as a New KNOL
A thematic section SHOULD NOT receive a new data-knol merely
because it represents a distinct topic.
Not recommended:
<section
data-knol="faq:plan-H2406-129-0"
data-entity="plan:H2406-129-0">
when the section is simply an FAQ Fragment within the existing plan KNOL.
Preferred:
<section data-fragment="FAQFragment">
69.4 Treating Every Link as a Semantic Edge
Ordinary navigation SHOULD remain ordinary navigation.
<a href="#costs">View Plan Costs</a>
No KNOL relationship annotation is required.
Relationship semantics SHOULD be added only when the link actually manifests
an intentional semantic edge:
<a
href="/cms-contracts/H2406/"
data-rel="contract"
data-ref="contract:H2406">
CMS Contract H2406
</a>
69.5 Duplicating Canonical Native Attributes
KNOL SHOULD NOT duplicate canonical state already expressed by an appropriate
native HTML attribute.
Not recommended:
<span
data-key="publication.last-updated"
data-value="2026-06-11">
<time datetime="2026-06-11">
June 11, 2026
</time>
</span>
Preferred:
<span data-key="publication.last-updated">
<time datetime="2026-06-11">
June 11, 2026
</time>
</span>
69.6 Encoding Presentation as Assertion Identity
Assertion addresses SHOULD NOT depend on visual position or mutable document
layout.
Not recommended:
data-key="sidebar-premium-value" data-key="table-row-4-value" data-key="faq-answer-2"
Preferred:
data-key="plan.landscape.monthly-premium"
69.7 Using Fragment Classes as Styling Classes
Fragment Classes identify semantic composition roles, not CSS presentation
patterns.
Not recommended:
data-fragment="BlueBoxFragment" data-fragment="AccordionFragment" data-fragment="TwoColumnFragment"
unless those names independently represent legitimate semantic composition
classes rather than visual treatments.
Presentation SHOULD remain the responsibility of HTML structure, CSS, and the
applicable user interface.
70. Separation of Structural and Knowledge Semantics
The foundational distinction in Native KNOL HTML can be summarized as follows:
| Native HTML Answers | KNOL Answers |
|---|---|
| What kind of document structure is this? | What knowledge object does this structure manifest? |
| What is the primary content? | What KNOL/entity/scope does the primary content represent? |
| What content forms a thematic section? | What semantic Fragment does the section manifest? |
| How do table rows, columns, and cells relate? | Which canonical assertions do the values manifest? |
| Which definition belongs to which term? | Which semantic property does the definition/value manifest? |
| What prose does the reader see? | Which precise facts within the prose are addressable assertions? |
| Where does a link navigate? | What semantic relationship and target does the link represent? |
| What date/time does a native temporal element represent? | Which addressable assertion does that temporal value manifest? |
The two semantic systems are complementary.
HTML describes the document. KNOL identifies the knowledge manifested
by the document.
71. KNOL Semantic Projection
A Native KNOL HTML document can be conceptually projected into a knowledge view
without requiring that the human-facing document itself be reorganized around
that projection.
Given:
<main
data-knol="plan:H2406-129-0"
data-entity="plan:H2406-129-0"
data-scope="plan-year:2026">
<section data-fragment="CostFragment">
<dl>
<dt>Monthly Premium</dt>
<dd
data-key="plan.landscape.monthly-premium"
data-value="295.00"
data-unit="USD">
$295.00
</dd>
</dl>
</section>
<section data-fragment="RelatedFragment">
<a
href="/cms-contracts/H2406/"
data-rel="contract"
data-ref="contract:H2406">
CMS Contract H2406
</a>
</section>
</main>
the semantic projection is approximately:
KNOL
plan:H2406-129-0
ENTITY
plan:H2406-129-0
SCOPE
plan-year:2026
FRAGMENT
CostFragment
ASSERTION
plan.landscape.monthly-premium
VALUE
295.00
UNIT
USD
FRAGMENT
RelatedFragment
RELATIONSHIP
contract
TARGET
contract:H2406
This projection is a conceptual interpretation of the Native KNOL HTML
semantics.
KNOL v1.0 does not require a consumer to materialize this exact representation.
72. KNOL and the Public Web
Native KNOL HTML is designed to operate within ordinary public web publishing.
A publisher does not need to replace the human document with a machine-only
representation in order to expose canonical semantic state.
Instead:
ONE PUBLICATION SURFACE
|
+--------------------+
| |
v v
HUMAN USE MACHINE USE
| |
v v
NATIVE HTML NATIVE HTML
+
KNOL SEMANTICS
The same document can therefore serve both human presentation and
machine-addressable knowledge without requiring those consumers to use the
document in the same way.
This does not prevent a publisher from also providing encapsulated, linked,
API, or other manifestations.
73. WebMEM Composition and KNOL Addressability
WebMEM composition and KNOL addressability perform complementary functions.
WEBMEM COMPOSITION
|
+-- SDT
|
+-- Fragment
+-- Fragment
+-- Fragment
KNOL ADDRESSABILITY
|
+-- KNOL identity
+-- entity identity
+-- assertion identity
+-- canonical state
+-- semantic relationships
+-- provenance
In Native KNOL HTML, these models converge through native document structure:
<main>
|
| SDT
| KNOL
| ENTITY
| SCOPE
|
+-- <section>
| |
| | FRAGMENT
| |
| +-- ASSERTIONS
| +-- RELATIONSHIPS
|
+-- <section>
|
| FRAGMENT
|
+-- ASSERTIONS
+-- RELATIONSHIPS
The composition architecture and knowledge-addressing architecture therefore
remain distinct while sharing the same native HTML manifestation.
74. Version 1.0 Core Vocabulary Summary
| Attribute | Normative Role |
|---|---|
data-knol |
Identifies a Knowledge-Node Object boundary or root. |
data-entity |
Identifies the subject entity to which applicable knowledge applies. |
data-fragment |
Identifies the semantic Fragment Class manifested by an applicable native structure. |
data-key |
Provides the stable semantic address of an assertion or property. |
data-value |
Provides canonical machine value when the native presentation does not sufficiently expose that value. |
data-rel |
Identifies the predicate of a semantic relationship. |
data-ref |
Identifies the semantic target of a relationship or reference. |
75. Version 1.0 Extended Vocabulary Summary
| Attribute | Normative Role |
|---|---|
data-type |
Identifies the datatype of an applicable canonical value. |
data-unit |
Identifies the unit, currency, measurement, scale, or count associated with a value. |
data-derived |
Identifies whether applicable knowledge is source-reported or publisher-derived. |
data-scope |
Identifies applicability or contextual boundaries. |
data-source |
Binds applicable knowledge to a provenance resource. |
data-digest |
Identifies version, snapshot, digest, or integrity state. |
76. Version 1.0 Foundational Rules
KNOL v1.0 is governed by the following foundational rules.
- Preserve native HTML.
Use native HTML elements according to their intended structural meaning. - Augment rather than replace.
KNOL attributes SHOULD add knowledge semantics that native HTML does not
already express unambiguously. - Separate knowledge identity from entity identity.
A KNOL and the entity it concerns MAY share an identifier but MUST NOT be
assumed to be the same conceptual object. - Preserve semantic composition.
The SDT represents the page-level semantic composition; Fragments
represent coherent semantic units within that composition. - Use native sections for native Fragments.
A legitimate thematic<section>SHOULD ordinarily
manifest the corresponding semantic Fragment. - Address assertions, not presentation labels.
data-keySHOULD identify stable semantic properties. - Bind assertions to their strongest native manifestation.
Table assertions ordinarily belong on value cells, definition/value
assertions on<dd>, and assertions embedded in prose
on an appropriate inline element such as<span>. - Keep prose as prose.
<p>SHOULD remain responsible for human prose rather
than becoming a generic semantic record container. - Separate canonical value from presentation when necessary.
data-valueSHOULD expose canonical state when human
presentation transforms or obscures that state. - Inherit context where unambiguous.
KNOL, entity, scope, provenance, and other applicable semantic state
SHOULD be declared at the highest unambiguous structural level and
inherited downward. - Refine context without creating unnecessary KNOLs.
A Fragment MAY refine inherited entity or scope context without becoming
a new knowledge node. A newdata-knolSHOULD be introduced
only when the subordinate knowledge is genuinely an independently
identifiable knowledge object. - Separate navigation from semantic relationships.
hrefidentifies a navigable location.
data-relidentifies the semantic predicate and
data-refidentifies the semantic target. - Prefer specific justified relationships.
data-rel="related"MAY express a truthful broad
relationship when a more-specific predicate is unavailable or
unjustified, but SHOULD NOT replace a more-specific relationship that
the publisher can support. - Separate semantic identity from publication location.
KNOL, entity, assertion, and reference identifiers SHOULD remain stable
independently of mutable URLs, selectors, headings, or visual layout. - Use the smallest sufficient vocabulary.
KNOL annotations SHOULD NOT duplicate semantic state already expressed
unambiguously by native HTML or inherited context. - Preserve fidelity across repeated manifestations.
Multiple manifestations of the same assertion under equivalent entity
and scope context SHOULD preserve equivalent canonical semantic state. - Make provenance and derivation explicit when material.
Source identity and publisher derivation SHOULD be represented when
those distinctions materially affect interpretation of the knowledge. - Permit heterogeneous manifestations.
A KNOL MAY be manifested through native, encapsulated, linked, API, or
other serialization modes without changing the identity of the
underlying knowledge object. - Preserve useful fallback behavior.
Native KNOL HTML SHOULD remain meaningful and structurally useful when a
consumer does not recognize or interpret KNOL attributes. - Do not assert unsupported precision.
When semantic state cannot be justified unambiguously, publishers SHOULD
prefer a broader truthful representation or omission over an unsupported
entity, assertion, relationship, scope, or canonical value.
77. Compact Native KNOL Grammar
The ordinary Native KNOL HTML composition can be summarized as:
DOCUMENT
|
v
<main
data-knol="..."
data-entity="..."
data-scope="...">
|
| SDT
| PRIMARY KNOL CONTEXT
|
+-- <section data-fragment="...">
| |
| | FRAGMENT
| |
| +-- native HTML structure
| |
| +-- ASSERTION
| | data-key
| | data-value?
| | data-type?
| | data-unit?
| | data-derived?
| | data-source?
| |
| +-- RELATIONSHIP
| data-rel
| data-ref
|
+-- <section data-fragment="...">
|
| FRAGMENT
|
+-- native HTML structure
+-- assertions
+-- relationships
</main>
The question mark in this diagram indicates optional semantic state rather than
an HTML syntax operator.
A more-specific entity or scope MAY be established at any appropriate
descendant boundary:
<section
data-fragment="PerformanceFragment"
data-entity="contract:H2406">
A genuinely independent subordinate knowledge object MAY establish a new KNOL:
<section
data-knol="analysis:2026-yuma-snp-landscape"
data-entity="county:arizona-yuma-04027"
data-scope="plan-year:2026">
78. Semantic Resolution Summary
The effective meaning of an assertion manifestation is determined by combining
its local semantic state with applicable inherited context.
EFFECTIVE ASSERTION
=
KNOL CONTEXT
+
ENTITY CONTEXT
+
SCOPE
+
FRAGMENT CONTEXT
+
DATA-KEY
+
CANONICAL VALUE STATE
+
TYPE / UNIT
+
DERIVATION
+
PROVENANCE
Not every component is required for every assertion.
The minimum sufficient state depends upon the knowledge being represented and
the semantics already supplied by native HTML and applicable context.
Likewise:
EFFECTIVE RELATIONSHIP
=
SOURCE CONTEXT
+
DATA-REL
+
DATA-REF
where the source context is ordinarily inherited from the applicable entity or
KNOL.
79. Serialization-Neutral Knowledge Model
Although this specification defines Native KNOL HTML in detail, the knowledge
model itself is serialization-neutral.
The following semantic state:
KNOL
plan:H2406-129-0
ENTITY
plan:H2406-129-0
SCOPE
plan-year:2026
FRAGMENT
CostFragment
ASSERTION
plan.landscape.monthly-premium
VALUE
295.00
TYPE
number
UNIT
USD
may be manifested through Native KNOL HTML:
<main
data-knol="plan:H2406-129-0"
data-entity="plan:H2406-129-0"
data-scope="plan-year:2026">
<section data-fragment="CostFragment">
<dl>
<dt>Monthly Premium</dt>
<dd
data-key="plan.landscape.monthly-premium"
data-value="295.00"
data-type="number"
data-unit="USD">
$295.00
</dd>
</dl>
</section>
</main>
or through another serialization capable of preserving equivalent canonical
state.
The serialization changes.
The intended knowledge does not.
80. Relationship to the Canonical Knowledge Object
Native KNOL HTML is a manifestation of a Knowledge-Node Object. It is not
necessarily the canonical storage representation of that object.
CANONICAL KNOWLEDGE-NODE OBJECT
|
| serialization
v
NATIVE KNOL HTML
|
+-- human presentation
|
+-- semantic composition
|
+-- assertion manifestations
|
+-- relationship manifestations
An implementation MAY construct Native KNOL HTML from:
- a relational database;
- a document database;
- a graph store;
- a canonical assertion store;
- structured files;
- an API;
- a content-management system;
- publisher-derived calculations;
- human-authored knowledge; or
- any combination of these.
KNOL v1.0 does not require the publication representation to mirror the
publisher’s internal storage model.
81. Versioning and Evolution
KNOL identifiers and assertion addresses SHOULD be designed to survive ordinary
changes in presentation, templates, URLs, and serialization technology.
A new KNOL identifier SHOULD NOT be created merely because:
- the HTML template changes;
- a Fragment moves within the page;
- a table becomes a definition list while preserving the same knowledge;
- prose wording changes without changing canonical meaning;
- a page receives a new URL;
- a CSS implementation changes; or
- a new manifestation is added.
A new KNOL identity MAY be appropriate when the knowledge object itself becomes
a materially different identifiable object under the applicable domain model.
Likewise, assertion addresses SHOULD remain stable across presentation changes
when the semantic property remains the same.
82. Extensibility
KNOL v1.0 is intentionally extensible.
Implementations MAY define:
- new Fragment Classes;
- new entity types;
- new assertion namespaces;
- new relationship predicates;
- new scope vocabularies;
- new datatypes;
- new units;
- new provenance conventions;
- new serialization modes; and
- new domain profiles.
Extensions SHOULD preserve the semantic responsibilities of the KNOL v1.0 core
attributes.
An extension SHOULD NOT redefine:
data-knol
as something other than knowledge-node identity
data-entity
as something other than subject identity
data-fragment
as something other than Fragment Class / semantic composition
data-key
as something other than assertion/property address
data-value
as something other than canonical value state
data-rel
as something other than relationship predicate
data-ref
as something other than semantic relationship/reference target
Where an extension requires substantially different semantics, it SHOULD define
a separate attribute or profile rule rather than overload an existing KNOL
attribute.
83. Forward Compatibility
A KNOL Consumer encountering an unrecognized extension attribute, Fragment
Class, relationship predicate, datatype, unit, scope form, or other extension
value MAY preserve or ignore that unrecognized semantic state.
A Consumer MUST NOT assign inferred KNOL semantics to an unrecognized extension
solely from its lexical form, human-readable label, surrounding prose, or
apparent similarity to a recognized KNOL construct.
Ignoring an unrecognized extension MUST NOT cause the Consumer to reinterpret
recognized KNOL v1.0 semantic state in a manner inconsistent with this
specification.
Publishers SHOULD preserve native HTML meaning independently of whether a
consumer recognizes the complete KNOL vocabulary.
Domain profiles SHOULD be designed so that unrecognized optional extensions do
not invalidate the fundamental KNOL composition where possible.
Future versions of KNOL MAY add vocabulary, conformance rules, serialization
profiles, validation mechanisms, or manifest capabilities while preserving the
semantic responsibilities established by the v1.0 core.
84. Security and Trust Considerations
KNOL annotations express publisher-asserted semantic state.
The presence of a KNOL annotation does not independently prove that an
assertion is true, authoritative, current, complete, safe, or trustworthy.
Consumers MAY evaluate:
- publisher identity;
- source provenance;
- derivation methodology;
- publication date;
- effective scope;
- digest or integrity state;
- cross-source consistency;
- domain authority;
- validation status; or
- other trust signals.
Publishers MUST NOT use KNOL attributes to intentionally misrepresent the
knowledge visibly manifested by the document.
A canonical data-value SHOULD correspond faithfully to the
knowledge represented by the human-facing manifestation.
A data-rel predicate SHOULD describe a relationship the publisher
can justify.
A data-ref SHOULD identify the intended semantic target rather
than an unrelated entity or resource.
85. Accessibility Considerations
KNOL does not replace accessibility semantics.
Publishers SHOULD continue to use appropriate:
- heading structure;
- table headers and scope attributes;
- captions;
- labels;
- link text;
- native disclosure controls;
- ARIA attributes where appropriate;
- alternative text;
- language attributes; and
- other established accessibility mechanisms.
KNOL attributes SHOULD NOT be treated as substitutes for accessibility
metadata.
The same foundational principle applies:
Use the native web platform for the semantics it already provides.
Use KNOL for knowledge semantics the platform does not otherwise express.
86. Implementation Independence
KNOL v1.0 does not require a particular publishing stack.
A conforming Native KNOL HTML document MAY be produced by:
- a static-site generator;
- a content-management system;
- a server-side application;
- a client-side application;
- a knowledge-management system;
- a data pipeline;
- a template engine;
- a human authoring system;
- an automated publishing system; or
- another implementation capable of producing conforming HTML.
The implementation technology is not part of KNOL identity.
87. Reference Conceptual Model
The KNOL v1.0 architecture can be summarized as:
PUBLICATION
|
v
<main>
|
| SDT
|
+---------+---------+
| |
v v
KNOL ENTITY
| |
+---------+---------+
|
SCOPE
|
+---------------+---------------+
| | |
v v v
FRAGMENT FRAGMENT FRAGMENT
| | |
+-----+-----+ +----+----+ +----+----+
| | | | | |
v v v v v v
ASSERTION RELATION ASSERTION RELATION ASSERTION RELATION
| | | | | |
v v v v v v
CANONICAL TARGET CANONICAL TARGET CANONICAL TARGET
STATE STATE STATE
Native HTML structures remain present throughout this model.
KNOL does not require the human document to expose this conceptual hierarchy
visually.
The hierarchy describes the semantic state manifested through that document.
88. Reference Attribute Model
IDENTITY
data-knol
data-entity
COMPOSITION
data-fragment
ASSERTION
data-key
CANONICAL STATE
data-value
data-type
data-unit
data-derived
CONTEXT
data-scope
PROVENANCE / STATE
data-source
data-digest
RELATIONSHIPS
data-rel
data-ref
These categories describe semantic responsibility. They do not require
different HTML containers for each category.
89. Reference HTML Binding Model
<main>
→ SDT / primary KNOL context
<section>
→ semantic Fragment
<article>
→ self-contained knowledge object where appropriate
<table>
→ native relational data structure
<th>
→ native row/column identity
<td>
→ addressable table assertion manifestation
<dl>
→ native definition/value collection
<dt>
→ human-facing term
<dd>
→ addressable definition/value assertion manifestation
<p>
→ prose
<span>
→ inline assertion manifestation
<a>
→ navigation
→ semantic relationship when data-rel + data-ref are present
<time>
→ native canonical temporal representation
<ul> / <ol>
→ native collection / sequence
<li>
→ native collection member
This binding model SHOULD be interpreted according to native HTML semantics,
not as a replacement content model.
90. Version 1.0 Definition
A Knowledge-Node Object (KNOL) is an identifiable, addressable unit of
canonical knowledge concerning one or more entities, assertions, relationships,
contexts, and provenance conditions. A KNOL exists independently of any
particular storage format or publication representation.
KNOL HTML Serialization provides a compact vocabulary for manifesting KNOL
identity, entity identity, semantic composition, assertion identity, canonical
values, scope, provenance, and relationships through HTML.
In Native KNOL HTML, those semantics bind directly to the human-facing HTML
structures that already manifest the knowledge.
The ordinary native composition is:
<main>
→ SDT / KNOL context
<section>
→ Fragment<table> / <dl> / native structures
→ structural relationships
<td> / <dd> / <span>
→ assertion manifestations
<a>
→ relationship manifestation when appropriate
The resulting architecture can be summarized as:
SDT
|
+-- KNOL
|
+-- ENTITY
|
+-- SCOPE
|
+-- FRAGMENT
| |
| +-- ASSERTION
| | |
| | +-- CANONICAL STATE
| |
| +-- RELATIONSHIP
| |
| +-- TARGET
|
+-- FRAGMENT
|
+-- ASSERTION
+-- RELATIONSHIP
Native HTML determines how the document is structured.
WebMEM composition determines how the publication is organized into an SDT and
semantic Fragments.
KNOL identifies and addresses the knowledge manifested through that structure.
91. Relationship to WebMEM
KNOL does not replace WebMEM.
WebMEM defines a web-publication architecture for exposing resolvable machine
knowledge alongside human-readable publication.
KNOL supplies the identifiable and addressable knowledge object used within
that architecture.
Native KNOL HTML provides a manifestation in which the WebMEM composition model
is bound directly to native document structure.
WEBMEM
→ publication architecture
SDT
→ page-level semantic composition
FRAGMENT
→ coherent semantic unit within the SDT
KNOL
→ identifiable knowledge object
KNOL HTML
→ serialization vocabulary
NATIVE KNOL HTML
→ direct binding of knowledge semantics to human-facing HTML
Earlier WebMEM implementations MAY use encapsulated machine-facing
representations such as HTML <template> containers.
Those implementations remain valid examples of alternative manifestations.
The transition from an encapsulated manifestation to Native KNOL HTML changes
the serialization strategy rather than discarding the underlying semantic
composition.
EARLIER ENCAPSULATED MANIFESTATION
<template>
|
| SDT
|
+-- Fragment
+-- Fragment
+-- Fragment
NATIVE KNOL HTML MANIFESTATION
<main>
|
| SDT / KNOL CONTEXT
|
+-- <section data-fragment="...">
+-- <section data-fragment="...">
+-- <section data-fragment="...">
The container changes.
The semantic composition remains.
92. Version 1.0 Design Summary
KNOL v1.0 establishes the following architectural commitments:
- Knowledge identity is independent of publication representation.
- Native HTML remains responsible for document and structural semantics.
- KNOL adds knowledge semantics rather than recreating HTML semantics.
<main>ordinarily provides the native page-level
boundary for the SDT and primary KNOL context.<section>ordinarily provides the native structural
boundary for a semantic Fragment.- Fragment Classes identify the semantic role of sections rather than
their visual presentation or source taxonomy. - Assertions receive stable semantic addresses through
data-key. - Assertions SHOULD be bound to the native element that most directly
manifests their value. - Canonical values MAY differ in representation from human-facing values
without becoming different assertions. - Entity, scope, provenance, and other context SHOULD be inherited where
unambiguous. - A Fragment MAY refine entity or scope context without becoming a new
KNOL. - A new
data-knolboundary indicates a genuinely distinct
knowledge object. - Navigation and semantic relationships remain distinct.
- Semantic relationships are expressed through a predicate and an
identified target. - Multiple manifestations of the same assertion SHOULD preserve
equivalent canonical semantic state. - KNOL remains serialization-neutral even though Native KNOL HTML is
formally defined by this specification. - Consumers that ignore KNOL SHOULD continue to receive useful,
semantically appropriate native HTML.
93. Compact Publisher Mental Model
A publisher implementing Native KNOL HTML can use the following mental model:
WHAT AM I PUBLISHING?
|
+-- data-knol
|
v
KNOWLEDGE NODE
WHAT IS IT ABOUT?
|
+-- data-entity
|
v
ENTITY
WHEN / WHERE / FOR WHOM DOES IT APPLY?
|
+-- data-scope
|
v
SCOPE
WHAT SEMANTIC PART OF THE PUBLICATION IS THIS?
|
+-- <section>
+-- data-fragment
|
v
FRAGMENT
WHAT FACT IS THIS?
|
+-- data-key
|
v
ASSERTION
WHAT IS ITS CANONICAL VALUE?
|
+-- visible native value
|
+-- data-value when required
|
+-- data-type / data-unit when required
|
v
CANONICAL STATE
HOW IS THIS KNOWLEDGE CONNECTED TO SOMETHING ELSE?
|
+-- <a href>
+-- data-rel
+-- data-ref
|
v
SEMANTIC RELATIONSHIP
WHERE DID IT COME FROM?
|
+-- data-source
+-- data-derived
+-- data-digest
|
v
PROVENANCE / STATE
94. Compact Consumer Mental Model
A KNOL-aware consumer can interpret Native KNOL HTML using the inverse model:
1. READ NATIVE HTML
|
v
understand document structure
2. LOCATE KNOL CONTEXT
|
v
data-knol
3. RESOLVE SUBJECT
|
v
data-entity
4. RESOLVE APPLICABILITY
|
v
data-scope
5. RESOLVE FRAGMENT
|
v
data-fragment
6. RESOLVE ASSERTIONS
|
v
data-key
7. RESOLVE CANONICAL STATE
|
v
native value
or
data-value + type + unit
8. RESOLVE RELATIONSHIPS
|
v
data-rel + data-ref
9. RESOLVE PROVENANCE
|
v
data-source + data-derived + data-digest
A consumer MAY perform only a subset of these steps.
KNOL v1.0 does not require a particular consumer implementation or processing
order.
95. Final Foundational Principle
The central design rule of KNOL v1.0 is:
Start with the strongest native HTML structure that faithfully represents the
knowledge for people. Preserve that structure. Then add only the semantic state
required to identify, compose, address, contextualize, preserve, and relate the
knowledge for machines.
This produces a publication in which human presentation and machine-addressable
knowledge share the same document without requiring either representation to
replace the other.
ONE DOCUMENT
|
+-----------------------+
| |
v v
HUMAN STRUCTURE KNOWLEDGE SEMANTICS
| |
v v
NATIVE HTML KNOL
| |
+-----------+-----------+
|
v
NATIVE KNOL HTML
96. KNOL v1.0
KNOL v1.0 defines an architecture in which knowledge is not merely present in a
document but can be explicitly identified within that document.
A page can identify its knowledge object.
A knowledge object can identify its subject and scope.
A publication can identify its semantic Fragments.
A Fragment can contain addressable assertions and explicit relationships.
An assertion can preserve canonical state independently of presentation.
A relationship can identify both its predicate and its semantic target.
Provenance and derivation can travel with the knowledge they qualify.
And all of this can be manifested through ordinary native HTML.
HTML
→ STRUCTURE
WEBMEM
→ COMPOSITION
KNOL
→ KNOWLEDGE
Together:
<main>
|
| SDT
| KNOL
| ENTITY
| SCOPE
|
+-- <section>
| |
| | FRAGMENT
| |
| +-- ASSERTION
| +-- ASSERTION
| +-- RELATIONSHIP
|
+-- <section>
|
| FRAGMENT
|
+-- ASSERTION
+-- RELATIONSHIP
Use HTML to describe the document.
Use WebMEM to compose the semantic publication.
Use KNOL to identify the knowledge.
End of KNOL v1.0 Draft Specification