semantic mesh

Overview

A semantic mesh is a pseudo-immutable collection of (possibly-versioned) linked-data resources. It organizes these resources in a publishable way, such that a mesh can be used as a semantic site where every HTTP IRI returns meaningful content.

Key characteristics

• Addressable: Every mesh resources has an identifier; when a mesh is published, every mesh resources then gets a globally unique, human-readable IRI
• Versioned: Changes are managed through the Weave Process process, and node flow are versioned by default
• Publish-ready: Can be served directly via GitHub Pages or similar static hosting; or via a local web server like live-server

Core Concepts

Mesh Resources

The primary constituents of a mesh are mesh nodes. Nodes contain their own node components, and may also contain other nodes.

Mesh Nodes

Mesh nodes extend Namespaces and serve as containers.

• bare nodes: Empty containers for organizing other mesh nodes
• reference nodes: Nodes that refer to entities (people, places, concepts, etc.)
• payload nodes: Nodes containing data distributions with optional versioning

Node components

Node components help define, support, and systematize nodes.

Example Mesh

Mesh resources have at least one identifier and (usually) a Referent.

Example:

• ns/ = bare node for organizing content and minting IRIs; refers to itself as a namespace
• ns/djradon/ = refers to Dave the person (payload node)
• ns/djradon/index.html = resource page about Dave (content)
• ns/djradon/pics/ = refers to Dave's biographical dataset (payload node)
• ns/djradon/pics/_payload/ = abstract dataset (DatasetSeries) containing Dave's "music picks" data
• ns/djradon/pics/_payload/_default/ = current concrete dataset snapshot
• ns/djradon/pics/_payload/2025-11-24_0142_07_v1/picks.jsonld = RDF distribution from version 1
• ns/djradon/_assets/images/headshot.jpg = an image asset; "attached" to the mesh, but not a mesh resource

Naming Resources

• node flow and their FlowShot
  • metadata flow: System-related administrative and structural metadata for mesh nodes
  • Version datasets: Versioned snapshots of datasets
• working snapshots: Draft workspaces for ongoing changes to versioned datasets
• Node handles: Components that provide referential indirection, allowing references to nodes as mesh resources rather than their referents
• Asset trees: Collections of arbitrary files and folders attached to the mesh

File Resources

Terminal mesh resources that cannot contain other resources:

• Resource pages: index.html files present in every mesh folder after weaving
• Distribution files: Data files in various RDF formats
• README.md and CHANGELOG.md: Documentation files providing context

Filesystem Structure

Meshes may be constituted as a set of filesystem mesh folders and mesh files.

Folder Mapping

• Mesh nodes correspond physically to mesh folders
• Folder names become namespace segments and IRI path components
• The local intramesh identifier for a node matches its containing folder name

File Organization

• Datasets are represented by folders containing at least one distribution file
• Distribution files must be named using the dataset's namespace segment
• Resource pages (index.html) should be present in every mesh folder after weaving

Reserved Names

• All system identifiers begin with an underscore (_)
• Examples: _assets/, _meta/, _default, _working

Logical Structure

Namespace Extension

• Mesh folders always extend the namespace with a segment corresponding to the folder name
• This creates a hierarchical IRI structure for addressing resources
• Each resource has a unique Intramesh based on its path and local name

Containment Rules

• Mesh nodes are always containers of components (i.e., at least metadata flow and node handle) and potentially containers of other nodes
  • bare nodes: no additional containment requirements
  • reference nodes: must have reference flow where the referenced entity can be described
  • payload nodes: must have payload flow with at least one distribution
• Asset tree components: Cannot contain nodes
• all resource folders should contain a mesh resource page that makes there IRIs servable/dereferenca

Rules & Constraints

System vs User Boundaries

• System components: Generated and managed by the weave process, not intended for user modification
• User components: Directly modifiable by users (default snapshot, README.md, CHANGELOG.md)
• The weave process maintains system components and generates missing required flows

Versioning Requirements

• flow versioning is managed through the Flow Version system
  • turning versioning on and off is controlled in the Node Config Defaults
  • Version history is realized in snapshot with numbered snapshots
  • Version history metadata is kept in the node's metadata flow

Addressing Requirements

• Every mesh resource must be addressable via its IRI path
• IRIs must return meaningful content when dereferenced
  • mesh resource page provide human-readable information for folder resource facet-based resources
    • resource pages are always index.html files generated by "on weave" from the CHANGELOG and README Documentation Resource, templates in assets tree and any scoped template mappings specified in Node Config Defaults files
  • file resource facet

Integration Points

Weave Process

The Weave Process process maintains mesh integrity by:

• Checking for required system resources and creating them if missing
• Generating resource pages for changed resources
• Managing dataset versioning and metadata
• Ensuring all resources remain addressable and dereferenceable

Publishing Workflow

• Meshes are designed to be served directly as static sites
• GitHub Pages integration allows immediate publishing after repository updates
• No static site generator required, though resource page generation occurs during weaving
• The repository structure directly maps to the published IRI structure

Dataset Integration

Meshes support multiple RDF formats and follow DCAT v3 (Private) standards for dataset organization. Datasets within meshes include both standalone datasets and those embedded as node components.

1. Assets
2. embedded mesh
3. loose mesh
4. submesh

• mesh resources
• Semantic Flow Documentation
• Concept Summary
• Product Brief
• Project Brief
• pseudo-immutability
• transposability
• Use Case: Radio Show Websiste
• dataset facet