Model one meaningful thing

A semantic node gives one meaningful thing a place to stand. It is not a demand to turn every noun into a record. Begin with something you will need to describe, reuse, or connect independently.

Decide what the thing is

A person, a role, and a project are different things—even when they share a name. Hugo Web is a particular personified identity. Builder is also a role a visitor can inhabit. Sharing a quality does not make two identities interchangeable.

Write one sentence describing your candidate. If it describes several independent things, narrow it before adding fields.

Start with the minimum

This fictional project illustrates the portable envelope:

semantic_node:
  id: example-project
  name: Example Project
  description: A fictional project for learning structured publishing.
  type: entity
  kind: project

A graph accepting this example needs entity/project in its ontology. The current site does not register every example kind automatically.

For Hugo content, the same inner object lives under root front matter node:. Hugo templates read it through .Params.node. Publishing fields such as title and description remain outside the node.

Keep identity stable

Choose an ID once. Do not derive it from a directory or regenerate it when the display name changes. A URL answers “where can I read this?” The ID answers “which thing is this?” Those questions should not be coupled.

Add only useful enrichment

Use properties for intrinsic facts. Use relationships for connections to other nodes. Add purpose or movement when those fields contribute meaningful context; do not invent intention for an object just to fill a form.

Missing optional information is better than fabricated precision. A node with five trustworthy fields is more useful than a richly structured guess.

Try it: model one thing in five fields. Ask another person whether they can distinguish it from related things using only that description. Revise the meaning before expanding the schema.