One Data Model, Many Representations

From PiRho Knowledgebase
Jump to navigationJump to search

Modern web systems often create unnecessary separation between websites and APIs. In reality, both are simply different representations of the same underlying data. When designed correctly, a website can function as an API, and an API can render a complete website — without semantic loss, duplication, or inconsistency. This article explores that principle and the machine‑readable HTML technologies that make it viable.

The Fundamental Principle

At the heart of a well‑designed web system is a simple idea:

There should be one canonical data model.

HTML, JSON, XML, and other formats are not competing truths — they are **projections** of that model, tailored for different consumers.

Problems arise when:

  • HTML says one thing
  • APIs say another
  • Metadata exists in isolation
  • Meaning is duplicated instead of shared

When this happens, systems drift, documentation lies, and maintenance cost grows quietly but relentlessly.

The Website as an API

A properly structured HTML document is already machine‑readable.

Browsers, crawlers, screen readers, and assistive technologies all parse:

  • Document structure
  • Element relationships
  • Headings and landmarks
  • Links and identifiers

When semantic meaning is embedded directly into HTML — using Microformats or RDFa — the document becomes a self‑describing data source.

In this model:

  • The content is the data
  • The markup expresses meaning
  • Machines consume the same source as humans

This approach is resilient by design:

  • It works without JavaScript
  • It survives partial rendering
  • It degrades gracefully
  • It remains readable decades later

The document does not pretend to be an API — it simply is one.

The API as a Website

The inverse approach is equally valid.

When an API exposes:

  • Stable identifiers
  • Explicit relationships
  • Meaningful field names
  • A coherent domain model

…then rendering HTML from it becomes a presentation concern, not a data problem.

The same endpoint can legitimately serve:

  • JSON to machines
  • HTML to humans
  • XML to legacy systems
  • Other formats as required

Nothing new is invented — only rendered.

This is not duplication. It is **representation**.

Machine‑Readable HTML Technologies in Context

Different technologies support this model in different ways.

Microformats

Microformats embed meaning using existing HTML elements and class names.

Their strengths are simplicity and longevity:

  • No parallel data structures
  • No special parsers required
  • No loss of human readability

If the machine disappears, the document remains correct.

This makes Microformats ideal for:

  • Human‑centric documents
  • Long‑lived content
  • Systems that value resilience

RDFa

RDFa extends this idea by allowing richer expression of relationships.

Crucially, it still:

  • Annotates existing content
  • Avoids data duplication
  • Keeps the document authoritative

Edits to content are edits to data — a powerful alignment that reduces drift over time.

JSON‑LD

JSON‑LD serves a different purpose.

It exists primarily for automated consumers that:

  • Do not want to parse HTML
  • Prefer fast, predictable extraction
  • Operate at web scale

JSON‑LD works best when treated as:

  • An optimisation layer
  • A reflection of existing truth
  • A convenience for external systems

Problems arise only when JSON‑LD becomes the *primary* source of meaning rather than a projection of it.

Microdata

Microdata introduced attribute‑based semantics alongside HTML5.

In practice, it:

  • Adds verbosity without clarity
  • Introduces new concepts without solving new problems
  • Competes with simpler, more mature approaches

It is supported, but rarely preferred in real‑world systems.

Avoiding Parallel Realities

The most common architectural failure is semantic duplication.

Examples include:

  • Content updated but metadata forgotten
  • API fields drifting from UI labels
  • SEO data diverging from visible truth
  • Accessibility annotations bolted on late

The cure is not tooling — it is alignment.

When:

  • HTML and API share identifiers
  • Meaning is expressed once
  • Representations are derived, not rewritten

…the system becomes calm and legible.

Progressive Enhancement as Architecture

This approach naturally supports progressive enhancement.

A document‑first system:

  • Works without scripts
  • Improves with them
  • Never depends on them

An API‑first system:

  • Scales cleanly
  • Supports automation
  • Remains renderer‑agnostic

Both are valid — and both can coexist — as long as they project the same underlying model.

Design Guidance

A pragmatic strategy looks like this:

  • **Human‑first content** → Microformats or RDFa
  • **Crawler‑first metadata** → JSON‑LD
  • **Single source of truth** → Canonical identifiers and models
  • **Long‑term systems** → Embedded meaning over external declarations

There is no universal winner — only informed trade‑offs.

Final Thought

The web does not suffer from a lack of standards. It suffers from a lack of honesty.

Systems last when:

  • Meaning is not duplicated
  • Data is not reinvented
  • Documents say exactly what they mean

When the website and the API tell the same story, the web works as it always should have — as a shared space for humans and machines alike.

Retrieved from "https://knowledgebase.pirho.net/index.php?title=One_Data_Model,_Many_Representations&oldid=295"