semantic mesh

Overview

A semantic mesh is a dereferenceable, possibly-versioned, Immutability collection of semantic data and other resources where every HTTP URL returns meaningful content. It serves as the foundational structure for organizing and publishing semantic web resources through semantic sites.

Key characteristics:

Addressable: Every mesh resource has a unique intramesh identifier; when a mesh is published, every mesh resource then gets a globally unique URL
Dereferenceable: All URLs return meaningful content when accessed
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

There are two types of mesh resources: mesh nodes and node components.

Mesh Nodes

Mesh nodes are the primary structural components of a mesh, physically represented as mesh folders. They extend namespaces and serve as containers.

bare nodes: Empty containers for organizing other mesh nodes
data nodes: Nodes containing data distributions with optional versioning

Node components

Node components help define, support, and systematize nodes:

Folder-based

node flow and their flow snapshot
- metadata flow: System-related administrative and structural metadata for mesh nodes
- Version datasets: Versioned snapshots of datasets
next 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

Files

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

Physical Structure

Folder Mapping

Mesh nodes correspond physically to mesh folders
Folder names become namespace segments and URL 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 reserved folder names begin with an underscore (_)
Examples: _assets/, _meta-flow/, _current, _next

Logical Structure

Namespace Extension

Mesh folders always extend the namespace with a segment corresponding to the folder name
This creates a hierarchical URL 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 concept.mesh.resource.folder._node-handle (Private)) and potentially containers of other nodes
- bare nodes: no additional containment requirements
- data nodes: must have data flow with at least one distribution
Asset tree components: Cannot contain nodes
all components can contain

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 (current snapshot, README.md, CHANGELOG.md)
The weave process maintains system components and generates missing required flows

Versioning Requirements

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

Addressing Requirements

Every mesh resource must be addressable via its URL path
URLs 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 URL 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.

Children

Backlinks