Serialization

Part of the WebMEM® Protocol
Location: /protocol/serialization/
Status: Current Draft
Last Updated: 2026-08-24

Overview

Serialization is the process of representing the WebMEM conceptual knowledge model in a concrete syntax suitable for publication, exchange, parsing, validation, or other machine use.

WebMEM separates the meaning of its knowledge model from the syntax used to encode that model.

The distinction is:

WebMEM Knowledge Model
        ↓
Serialization
        ↓
Concrete Representation

The knowledge model defines:

the Semantic Data Template (SDT);
WebMEM fragments and Fragment Classes;
assertions and structures;
identity;
provenance;
relationships;
applicability;
composition;
and resolution-relevant distinctions.

Serialization defines how those concepts are represented in a particular syntax.

The knowledge model defines what the knowledge means. Serialization defines how that knowledge is represented.

Why Serialization Is a Separate Layer

A protocol becomes unnecessarily fragile when its conceptual model is inseparable from one syntax.

If:

Semantic Data Template
=
particular markup syntax

then changing the syntax risks changing the architecture itself.

WebMEM avoids that coupling.

Instead:

Semantic Data Template
        ↓
Conceptual Knowledge Model
        ↓
Serialization Mapping
        ↓
Concrete Syntax

This allows the conceptual architecture to remain stable while serialization methods evolve independently.

For example:

Identity
≠ a particular attribute

Provenance
≠ a particular metadata block

Relationship
≠ a particular field name

DataFragment
≠ a particular HTML element

SDT
≠ <template>

The syntax may represent those concepts.

It does not define them.

The Serialization Contract

Every conforming WebMEM serialization must preserve the semantic distinctions established by the WebMEM knowledge model.

This requirement forms the WebMEM serialization contract.

A serialization may:

use different element names;
use different attribute names;
represent values using syntax native to the serialization format;
organize references differently;
use different mechanisms for nesting or grouping;
or encode relationships using different structural conventions.

But it must not change the semantic meaning of the represented knowledge.

A conforming serialization may change syntax. It must not change semantics.

Semantic Preservation

Semantic preservation is the primary requirement of serialization.

For example, if the conceptual model contains:

Fragment Class:
DerivedStatsFragment

Entity:
county:04015

Assertion:
average_monthly_premium = 15.26 USD

Derived:
true

Source:
CMS Landscape

Method:
arithmetic mean

Plan Year:
2026

a conforming serialization must not transform that representation into something semantically equivalent to:

DataFragment

average_monthly_premium = 15.26 USD

source-observed = true

The numerical value survived.

The semantics did not.

Likewise, a serialization must not collapse:

plan:H5521-290
→ hasSegment
→ segment:H5521-290-001

into:

plan:H5521-290
→ equivalentTo
→ segment:H5521-290-001

The participating identifiers survived.

The relationship meaning did not.

Serialization fidelity is measured by preservation of meaning, not merely preservation of strings.

What a Serialization Must Preserve

Where present and semantically material in the WebMEM knowledge model, a conforming serialization must preserve or make recoverable:

SDT identity;
fragment identity;
Fragment Class;
entity identity;
entity type and identity scope when material;
assertions;
structured values;
datatypes;
units when material;
shared and assertion-specific context;
temporal applicability;
geographic applicability;
jurisdictional or population scope when material;
provenance;
source-observed versus derived distinctions;
derivation relationships and methods when material;
relationships;
relationship direction;
relationship scope;
collection membership;
canonical-resource relationships;
resolution-relevant distinctions;
and unresolved ambiguity when that ambiguity is part of the represented knowledge.

Not every WebMEM representation contains every one of these concepts.

The requirement applies when the concept exists and is necessary to preserve the meaning of the represented knowledge.

Serialization Must Preserve Fragment Semantics

The 15 WebMEM Fragment Classes define semantic roles within the knowledge model.

A serialization must preserve those roles.

For example:

DataFragment
→ source-observed factual knowledge

DerivedStatsFragment
→ calculated or derived knowledge

IdentityFragment
→ identity knowledge

IndexFragment
→ collection membership

PolicyFragment
→ policy knowledge

ProcedureFragment
→ procedural knowledge

A serialization may encode those classes differently.

It may not silently merge them into one generic fragment type if doing so destroys the semantic distinction represented by the class.

Fragment Class is semantic information, not merely a formatting choice.

Read the WebMEM Fragments specification →

Serialization Must Preserve Identity

A serialization must preserve the identity distinctions required by the represented knowledge.

For example:

Web Resource
≠ Dataset / SDT
≠ Fragment
≠ Plan
≠ Segment

A serialization that collapses:

plan:H5521-290
segment:H5521-290-001

into one undifferentiated identity has changed the knowledge model.

Likewise, a serialization that replaces entity identity with a human-readable name may introduce ambiguity where the conceptual model was precise.

Serialization must preserve what the knowledge is about.

Read the Identity specification →

Serialization Must Preserve Provenance

A serialization must preserve material evidentiary distinctions.

For example:

Assertion A
→ sourcedFrom
→ CMS PBP

Assertion B
→ derivedFrom
→ CMS Landscape
→ generatedBy
→ Publisher Calculation

must not become:

Assertion A
source: CMS

Assertion B
source: CMS

if doing so erases the distinction between source-observed and publisher-derived knowledge.

Likewise, multiple source lineages should not be flattened merely because a target serialization provides a convenient single source field.

A serialization limitation is not permission to erase provenance.

Read the Provenance specification →

Serialization Must Preserve Relationships

Relationships must retain their semantic meaning through serialization.

For example:

Contract
→ hasPlan
→ Plan

must remain distinguishable from:

Plan
→ belongsToContract
→ Contract

and from:

Contract
→ equivalentTo
→ Plan

The participating objects alone are insufficient.

The relationship predicate and applicable direction are part of the knowledge.

A conforming serialization must preserve the connection and what that connection means.

Read the Relationships specification →

Serialization Must Preserve Resolution-Relevant Distinctions

A serialization must not remove distinctions necessary for correct resolution.

Consider:

Plan
├── Segment A
│   ├── appliesIn → County X
│   └── premium = 18.50 USD
│
└── Segment B
    ├── appliesIn → County Y
    └── premium = 32.00 USD

A serialization that reduces this structure to:

Plan
premium:
  - 18.50
  - 32.00

has preserved the values while destroying the resolution structure necessary to determine which premium applies.

The serialization must preserve the segment identities and geographic relationships when those distinctions govern applicability.

Resolution-relevant structure is semantic information.

Read the WebMEM Resolution Model →

Serialization Must Preserve Ambiguity

Serialization must not convert an unresolved state into false certainty.

For example:

Plan
├── Segment A → 18.50 USD
└── Segment B → 32.00 USD

Required Context:
geography

Known Geography:
none

Resolution State:
UNRESOLVED

must not be serialized as:

premium = 18.50 USD

merely because the target format makes one value easier to represent.

The unresolved candidates or missing applicability context must remain recoverable where that ambiguity is material to the represented knowledge.

A serialization must preserve uncertainty that the knowledge model has not resolved.

Shared Context and Inheritance

WebMEM allows context to be established at different levels of the knowledge model.

For example:

SDT
  plan_year: 2026
  geography: county:04015

  DataFragment
    source: CMS PBP
    entity: plan:H5521-290-0

    assertion
    assertion
    assertion

A serialization may represent this shared context through containment, references, attributes, parent structures, or another mechanism appropriate to the format.

It does not need to duplicate:

plan_year = 2026
geography = county:04015
source = CMS PBP

beside every assertion if inheritance remains explicit and unambiguous.

However, if one assertion differs materially:

enrollment
  source: CMS Monthly Enrollment
  applicable_month: 2026-07

the serialization must preserve that override.

Shared context may be serialized efficiently. Material exceptions must remain explicit.

Ordering

Serialization order does not automatically imply semantic order.

For example, the order in which independent DataFragments appear within an SDT does not necessarily establish a relationship among them.

Likewise:

Fragment A
Fragment B
Fragment C

does not inherently mean:

A precedes B
B precedes C

When order is semantically meaningful, the serialization must preserve that meaning explicitly or through a structure whose ordering semantics are defined.

This is particularly important for:

procedural steps;
ranked structures;
historical sequences;
ordered decision paths;
or other knowledge where sequence affects interpretation.

Document order should not be mistaken for semantic order unless the serialization defines it as such.

References

A serialization may use references to avoid unnecessary duplication of stable knowledge objects.

For example:

MetaFragment
  id: dataset:cms-pbp-2026

DataFragment
  provenance_ref: dataset:cms-pbp-2026

or:

IdentityFragment
  entity: plan:H5521-290-0

DataFragment
  entity_ref: plan:H5521-290-0

The syntax used for the reference may differ by serialization.

The reference must nevertheless resolve unambiguously to the intended object within the applicable WebMEM context.

A serialization should not require duplication where stable reference preserves the same semantics more accurately and efficiently.

Internal and External References

References may point to objects represented within the same SDT or to identifiable objects represented elsewhere.

For example:

Internal Reference

DerivedStatsFragment
→ derivedFrom
→ MetaFragment within same SDT

or:

External Reference

Plan
→ canonicalResource
→ https://example.org/plans/H5521-290-0/

A serialization should preserve enough information to distinguish local object references from external resource references where that distinction affects interpretation or resolution.

Serialization and Dataset Declaration

Schema.org Dataset JSON-LD and WebMEM serialization perform different functions.

Under the current publishing architecture:

Schema.org Dataset JSON-LD
        ↓
Declares and describes the page-level machine dataset

WebMEM Serialization
        ↓
Represents the internal WebMEM knowledge model

For example:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Dataset",
  "@id": "https://example.org/resource/#webmem",
  "url": "https://example.org/resource/"
}
</script>

<template
  data-webmem-sdt
  data-sdt-id="https://example.org/resource/#webmem">

  ...

</template>

The shared identity binds the Dataset declaration to the SDT.

The JSON-LD block is not itself the serialization of the WebMEM knowledge model.

Dataset JSON-LD declares the dataset. The WebMEM serialization represents its WebMEM knowledge structure.

Read Dataset Declaration and SDT Mapping →

Current WebMEM Serialization

The current defined WebMEM serialization is HTML-in-HTML.

HTML-in-HTML represents the SDT and its fragments using structured HTML contained within inert HTML <template> elements.

Conceptually:

WebMEM Knowledge Model
        ↓
HTML-in-HTML Mapping
        ↓
HTML DOM Representation

A simplified example:

<template
  data-webmem-sdt
  data-sdt-id="https://example.org/resource/#webmem">

  <template
    data-webmem-fragment
    data-fragment-class="DataFragment"
    data-fragment-id="plan-benefits">

    ...

  </template>

</template>

The HTML serialization specification defines the concrete elements, attributes, nesting, references, values, and parsing expectations used by this representation.

Read the HTML-in-HTML Serialization specification →

Why HTML-in-HTML Replaced YAML-in-HTML

WebMEM 1.x used YAML embedded within inert HTML <template> containers.

Conceptually, that architecture required multiple representation layers:

The knowledge model has not become HTML-specific.

HTML is the current concrete syntax used to represent that model.

The change removes a second embedded data language while preserving the architectural separation between WebMEM semantics and serialization.

This distinction is important:

WebMEM 1.x

WebMEM Concepts
      ↓
YAML Vocabulary
      ↓
YAML-in-HTML


Current WebMEM

WebMEM Concepts
      ↓
Serialization Mapping
      ↓
HTML-in-HTML

The current architecture does not define an SDT as an HTML <template>, a DataFragment as a particular HTML element, or provenance as a particular set of data-* attributes.

Those constructs serialize the concepts.

HTML-in-HTML is an implementation of the WebMEM knowledge model, not the definition of the WebMEM knowledge model.

Serialization Independence

The WebMEM conceptual model is serialization-independent.

This does not mean that every possible serialization is automatically supported or conforming.

It means that the concepts defined by the protocol are not inherently dependent on HTML, YAML, JSON, XML, RDF, or another particular syntax.

The current protocol defines one normative serialization:

HTML-in-HTML

Additional serializations may be defined in the future if they can preserve the semantic requirements of the WebMEM knowledge model.

No additional serialization should be assumed to exist merely because the conceptual model permits one.

Future Serializations

A future WebMEM serialization would require its own specification defining how the conceptual model maps into that syntax.

Such a specification would need to define, at minimum:

how an SDT is identified and bounded;
how fragments are identified;
how Fragment Classes are represented;
how assertions and structured values are represented;
how identity is represented and referenced;
how shared context and overrides are represented;
how provenance is represented;
how relationships are represented;
how applicability is represented;
how collections and ordered structures are represented;
how internal and external references are resolved;
how unresolved ambiguity is preserved;
and how conformance can be validated.

A new serialization would not be conforming merely because it contains equivalent-looking values.

It would need to preserve the semantic distinctions required by the protocol.

Semantic Equivalence Across Serializations

If multiple WebMEM serializations are defined in the future, equivalent representations should preserve the same material knowledge.

Conceptually:

WebMEM Knowledge Model
        │
        ├──→ Serialization A
        │
        └──→ Serialization B

Parsing either conforming representation should recover a semantically equivalent WebMEM knowledge model.

This does not require the serialized documents to be textually identical.

For example, one serialization might represent a relationship through nesting while another uses an explicit source-predicate-target structure.

The syntax differs.

The semantic relationship must remain the same.

A useful conceptual test is:

WebMEM Model
      ↓
Serialize
      ↓
Parse
      ↓
Recovered WebMEM Model

The recovered model should preserve all material semantic distinctions present in the original representation.

This principle provides the foundation for future interoperability and round-trip validation without requiring the current protocol to define serializations that do not yet exist.

Serialization Is Not Transformation

Serialization represents existing knowledge in a concrete syntax.

Transformation changes the knowledge representation, structure, or content before or during serialization.

For example:

Source:
"$4,900"

Normalization:
value = 4900
unit = USD

Serialization:
<data value="4900" data-unit="USD">$4,900</data>

The normalization changed the representation of the source value into the WebMEM conceptual form.

The serialization then encoded that conceptual value in HTML.

Likewise:

Source Records
        ↓
Publisher Calculation
        ↓
average_premium = 15.26 USD
        ↓
HTML Serialization

The calculation is a derivation.

Encoding the resulting assertion in HTML is serialization.

Serialization should not obscure transformations by making them appear to be properties of the syntax itself.

Serialization Is Not Derivation

A serialization must preserve whether knowledge was derived, but serialization does not itself make the knowledge derived.

For example:

DerivedStatsFragment
  average_premium = 15.26 USD
  derivedFrom = CMS Landscape
  method = arithmetic mean

remains derived knowledge whether represented in HTML-in-HTML or another future conforming serialization.

The derivation belongs to the knowledge and provenance model.

The serialization merely represents it.

Serialization Is Not Presentation

Serialization and human-facing presentation are different concerns.

A human-facing page may use:

headings;
paragraphs;
tables;
cards;
charts;
navigation;
interactive controls;
or other presentation structures.

The WebMEM serialization represents the machine-facing knowledge model.

Under the current HTML-in-HTML serialization, both exist within the same HTML resource, but they perform different jobs.

Conceptually:

HTML Resource
│
├── Human-Facing HTML
│   └── Presentation
│
└── WebMEM HTML-in-HTML
    └── Machine Knowledge Representation

The machine-facing representation should not depend on visual styling, CSS layout, screen position, or other presentation cues to establish semantic meaning that the WebMEM structure can represent explicitly.

Serialization Is Not Dataset Declaration

Schema.org Dataset JSON-LD and WebMEM serialization coexist on a WebMEM-enabled resource but remain separate architectural components.

The Dataset declaration answers:

What page-level machine dataset is being published here?

The WebMEM serialization answers:

How is the WebMEM knowledge associated with that dataset represented?

They may share identity:

Dataset @id
=
SDT identity

without becoming the same representation.

This separation allows WebMEM to use an established external vocabulary for dataset discovery while maintaining its own knowledge architecture.

Serialization Is Not a Consumer Requirement

A WebMEM serialization defines how the publisher represents WebMEM knowledge.

It does not prescribe how a consuming system must process that representation.

A consuming system may:

parse the entire SDT;
inspect selected fragments;
extract particular assertions;
traverse relationships;
compare provenance;
resolve canonical resources;
validate conformance;
transform the representation internally;
or ignore the WebMEM representation.

The serialization specification defines publisher-side syntax and semantics.

It does not prescribe consumer-side reasoning, retrieval, indexing, storage, or execution behavior.

Serialization Failure Modes

Several patterns can produce syntactically valid output while violating the WebMEM serialization contract.

Semantic Flattening

Distinct Fragment Classes, identities, provenance relationships, or applicability structures are reduced to generic fields that no longer preserve their meaning.

Identity Loss

Distinct entities are merged or replaced by ambiguous labels during serialization.

Provenance Loss

Source-observed, normalized, and derived knowledge become indistinguishable.

Relationship Loss

The source and target objects survive but the relationship predicate or direction disappears.

Applicability Loss

Geographic, temporal, jurisdictional, population, segment-level, or other context required for correct interpretation is omitted.

Inheritance Leakage

Shared context is applied to knowledge objects for which it is not actually valid.

False Ordering

Document or serialization order is treated as semantic sequence when no such relationship exists.

Reference Ambiguity

A reference cannot be resolved uniquely to the intended fragment, entity, source, or resource.

Ambiguity Collapse

Multiple unresolved candidates are serialized as though one candidate had been uniquely resolved.

Syntax-Model Conflation

A particular element, attribute, property, or container is treated as though it defines the conceptual WebMEM object rather than serializing it.

These failures may preserve much of the visible data while destroying the semantic structure that makes the representation WebMEM.

Minimum Serialization Model

A conforming WebMEM serialization specification must define enough syntax and processing expectations to allow a conforming representation to preserve and recover the applicable WebMEM knowledge model.

At minimum, the serialization specification must define:

how an SDT is identified;
how the boundaries of the SDT are determined;
how fragments are identified and bounded;
how Fragment Classes are declared;
how assertions and structured values are represented;
how datatypes and units are represented when material;
how entity identity and references are represented;
how shared context and more-specific overrides operate;
how provenance is represented or referenced;
how relationships are represented;
how internal and external references are distinguished;
how semantically meaningful ordering is preserved;
how applicability distinctions are preserved;
how resolution-relevant ambiguity remains representable;
how malformed or ambiguous structures are treated;
and how serialization conformance can be evaluated.

Serialization Conformance

A conforming serialization of WebMEM knowledge must preserve the semantics of the represented WebMEM model.

Specifically, a conforming serialization must:

preserve SDT identity and boundaries;
preserve fragment identity and Fragment Class;
preserve the subjects of assertions and structures;
preserve structured values, datatypes, and units where material;
preserve material context and applicability;
preserve provenance and source-versus-derivation distinctions;
preserve relationship predicates, direction, and scope where material;
preserve distinctions among entities, fragments, datasets, SDTs, and resources;
preserve collection membership and semantic ordering where material;
preserve resolution-relevant distinctions;
preserve unresolved ambiguity when the conceptual representation remains unresolved;
allow references to resolve unambiguously within their applicable scope;
avoid introducing semantic claims that do not exist in the conceptual representation;
and avoid discarding semantic information merely because the target syntax lacks a convenient native construct for representing it.

A serialization that is syntactically valid but materially changes the meaning of the WebMEM knowledge is not conforming.

Relationship to WebMEM 1.x

WebMEM 1.x used YAML-in-HTML as its principal machine-facing representation.

The approach established several concepts that remain important:

machine-facing knowledge can coexist with human-facing content in the same web resource;
HTML <template> provides an inert publication container;
fragment identity and Fragment Class should be explicit;
machine-facing knowledge should preserve provenance and relationships;
and publishers should be able to expose structured knowledge without forcing that structure into visible human presentation.

However, WebMEM 1.x allowed the YAML representation to become closely coupled to the conceptual model.

Concepts such as:

ProvenanceMeta
Fields
related_fragments
inherits_from
fragment_scope
digest
retrieval_hint

were often described simultaneously as semantic concepts and YAML structures.

The current protocol separates those concerns.

Durable semantic concepts remain part of the WebMEM knowledge model.

Retired retrieval, memory, digest, and execution mechanisms are not carried forward merely because they existed in the earlier serialization.

HTML-in-HTML is now defined as a serialization of the current model rather than the model itself.

This separation allows WebMEM to preserve its architecture while changing how that architecture is represented.

Serialization and Protocol Integrity

Serialization is the boundary at which the conceptual WebMEM knowledge model becomes concrete machine-facing syntax.

If that boundary fails, the conceptual model may be correct while the published representation becomes semantically incomplete.

For example:

Conceptual Model
→ correct identity
→ correct provenance
→ correct relationships
→ correct applicability
→ correct resolution structure

Poor Serialization
→ identity flattened
→ provenance removed
→ relationships generalized
→ applicability lost
→ values remain

The result may still look structured.

It is no longer a faithful representation of the original knowledge.

This gives serialization a precise responsibility within the protocol:

Knowledge Model
→ defines meaning

Serialization
→ preserves meaning in concrete syntax

Conformance
→ verifies that required meaning survives representation

The job of serialization is not merely to encode data. Its job is to carry the WebMEM knowledge model across the boundary from conceptual structure to published representation without semantic loss.

Current Serialization Specification

The current normative WebMEM serialization is HTML-in-HTML.

The HTML-in-HTML specification defines the concrete mapping between the WebMEM knowledge model and its representation within HTML.

It covers:

SDT containers;
fragment containers;
Fragment Class declarations;
identifiers;
entity context;
assertions;
structured values;
datatypes and units;
provenance references;
relationships;
context inheritance;
internal and external references;
nesting;
parsing expectations;
validation;
and HTML serialization conformance.

Read the HTML-in-HTML Serialization specification →

Overview

Why Serialization Is a Separate Layer

The Serialization Contract

Semantic Preservation

What a Serialization Must Preserve

Serialization Must Preserve Fragment Semantics

Serialization Must Preserve Identity

Serialization Must Preserve Provenance

Serialization Must Preserve Relationships

Serialization Must Preserve Resolution-Relevant Distinctions

Serialization Must Preserve Ambiguity

Shared Context and Inheritance

Ordering

References

Internal and External References

Serialization and Dataset Declaration

Current WebMEM Serialization

Why HTML-in-HTML Replaced YAML-in-HTML

Serialization Independence

Future Serializations

Semantic Equivalence Across Serializations

Serialization Is Not Transformation

Serialization Is Not Derivation

Serialization Is Not Presentation

Serialization Is Not Dataset Declaration

Serialization Is Not a Consumer Requirement

Serialization Failure Modes

Semantic Flattening

Identity Loss

Provenance Loss

Relationship Loss

Applicability Loss

Inheritance Leakage

False Ordering

Reference Ambiguity

Ambiguity Collapse

Syntax-Model Conflation

Minimum Serialization Model

Serialization Conformance

Relationship to WebMEM 1.x

Serialization and Protocol Integrity

Current Serialization Specification

Related Protocol Documents