Schema instances in HTML

A schema instance is an HTML element marked up with Microdata that pagelove.mjs recognizes as an addressable record.

When to reach for it

Reach for an instance whenever a record needs to live on the page. Use one per note, post, comment, or any other typed item the renderer will bind to a template and the patch pipeline will mutate in place.

Anatomy of an instance

An instance is an HTML element carrying Microdata attributes; <article> is a common wrapper. create(typeUrl, values, { tag }) defaults to <article>, and the optional tag selects another wrapper, such as section.

Attribute Required Purpose
itemscope yes Marks the element as a Microdata item.
itemtype yes Names the schema URL. Must match a registered template.
id only if the instance will be edited, deleted, or bound Routing key for patches and view binding.

Instances created by create() receive an auto-generated id of the form item-<base36-timestamp><random>.

How instances are discovered

On load, pagelove.mjs runs #discoverInstances() against the document. The selector is:

[itemscope][itemtype]:not(template):not([itemprop])

Discovery rules:

The renderer locates a template by exact itemtype URL match against <template itemtype="…"> elements already indexed by #discoverTemplates().

Property elements inside an instance

create() processes the discovered properties for the requested schema. For each property it evaluates the declared default, calling it if it is a function, and then uses the supplied value unless that value is null or undefined. Default functions are evaluated even when a supplied value is ultimately used. A 0..n property with no value after that fallback is omitted; the other branches below decide what is appended.

Declared property type Constructor behavior
Exactly https://pagelove.org/Text, Integer, Number or Boolean under that same URL prefix Creates <meta itemprop="…" content="…">, using String(value ?? ''). These are string conversions, not type validation.
Exactly https://pagelove.org/Date or https://pagelove.org/DateTime Creates <time itemprop="…" datetime="…">. If the resolved value is still nullish, it uses the current timestamp as an ISO string.
Any other type URL beginning with https://pagelove.org/ Appends the resolved value itself when it is an HTMLElement. Other values, including plain objects or an absent value, produce no child for that property.
Any other URL, including an external nested-schema URL, or an unspecified type Creates a scalar <meta> with itemprop and String(value ?? '') in content. It does not build a nested item for that URL.

The element branch does not construct an article or add itemprop, itemscope or itemtype to the supplied node. Author those attributes on the element before passing it in. Because it appends the existing node, that node is moved if it already has a parent.

For example, a property typed https://schema.host/Person takes the scalar branch even when its value is an HTMLElement or plain object; those values become strings such as [object HTMLElement] or [object Object]. Declaring a nested type in a schema does not by itself enable nested construction for that URL. You can author nested Microdata directly, as in the example below.

These rules can omit property children; create() does not guarantee one child for every declaration. A cardinality declaration does not make the constructor expand an array into repeated children. See Schema definitions in HTML for the declaration grammar and the class reference for construction and persistence boundaries.

Examples

Primitive properties only

<article itemscope
         itemtype="https://schema.host/Note"
         id="item-lxk3p2m1-a7b4">
  <meta itemprop="title" content="Grocery list">
  <meta itemprop="body" content="Bread, olives, lemons.">
  <meta itemprop="color" content="#ffd166">
</article>

Nested item

This example is authored HTML. It is not the output of create() for an external nested-schema URL such as https://schema.host/Person.

<article itemscope
         itemtype="https://schema.host/Post"
         id="item-lxk3p9zq-f2c8">
  <meta itemprop="title" content="On discovery">
  <time itemprop="publishedAt" datetime="2026-04-08T09:15:00Z"></time>
  <article itemprop="author"
           itemscope
           itemtype="https://schema.host/Person"
           id="item-lxk3pa11-91de">
    <meta itemprop="name" content="Ada Park">
    <meta itemprop="handle" content="ada">
  </article>
</article>

The nested <article> carries both itemprop="author" (tying it to the parent) and its own itemscope/itemtype. Automatic instance discovery excludes [itemprop] elements. With an explicit schema root, discovery instead scans that root's direct itemscope children; this nested article remains inside its parent.

See also