Proposal: OKF semantic web profile — typed fenced blocks, IRI identity, and triplestore deployment (DataBook as reference implementation)

[kurtcagle]

Summary

We have been independently developing a specification called DataBook that converges on OKF's core architecture — markdown + YAML frontmatter, git-hostable, no proprietary runtime, human- and agent-readable — but extends it for semantic web use cases. We would like to propose a formal OKF semantic web profile drawing on this work, and offer DataBook as a reference implementation.

This issue is distinct from #98 (which proposes RDFa inline) and #63 (ontology terminology). We are proposing typed fenced blocks as the payload mechanism, not inline RDFa, and we are bringing a complete working specification and CLI toolchain to the conversation.

---

Background: DataBook

The DataBook specification was developed through the W3C Holon Community Group (inaugural meeting June 19, 2026). It shares OKF's fundamental choices — markdown carrier, --- YAML frontmatter, file-based distribution — but adds a typed fenced block structure for carrying RDF payloads alongside prose:

---
id: https://example.org/datasets/pump-stations
title: "Pump Station Dataset"
type: databook
version: 0.1.0
graph:
  named_graph: urn:ds:pump-stations
  push_mode: replace
---

# Pump Station Ontology

<!-- databook:id: pump-station-shapes -->
` ` `turtle
@prefix ex: <https://example.org/> .
@prefix sh: <http://www.w3.org/ns/shacl#> .

ex:PumpStationShape a sh:NodeShape ;
    sh:targetClass ex:PumpStation ;
    sh:property [ sh:path ex:hasGenerator ; sh:minCount 1 ] .
` ` `

The DataBook CLI (v1.4.4) parses these typed blocks and pushes them to any SPARQL 1.1-compatible triplestore via the Graph Store Protocol, with optional SHACL validation gating the push.

---

What an OKF Semantic Web Profile Would Specify

A small, additive set of conventions on top of OKF v0.1 — backward-compatible with the base spec, invisible to consumers that don't understand it:

1. Extended frontmatter fields (all optional; additional keys the spec already permits):

Field	Type	Purpose
id	URI	IRI-based concept identity (global, dereferenceable)
version	string	Semantic versioning for the document
graph.named_graph	URI	Target named graph for triplestore deployment
graph.push_mode	enum	replace or merge — ingest behaviour
author[].iri	URI	Dereferenceable author identity

2. Typed fenced block convention

Fenced code blocks annotated with a databook:id HTML comment carry typed RDF payloads. A consumer that does not understand typed blocks treats them as ordinary code blocks — the OKF document remains fully valid and readable.

Supported block types: turtle, turtle12, sparql, shacl, json-ld, n-triples.

3. Graph Store Protocol as canonical ingest

The SPARQL 1.1 Graph Store Protocol (HTTP PUT/POST to a named graph endpoint) is the reference mechanism for deploying typed blocks to a triplestore. No new protocol required; this is an existing W3C recommendation.

4. Optional SHACL validation gate

Before push, blocks of type shacl may validate the document's RDF content, surfacing violation reports as structured errors rather than silent ingest failures.

---

What This Unlocks

An OKF bundle conforming to the semantic web profile:

• Remains fully valid OKF — any OKF consumer can read it
• Can be deployed to any SPARQL-compatible triplestore with a single CLI command
• Carries IRI-based identity enabling cross-bundle dereferenceable links (beyond file-path links)
• Supports SHACL constraint validation at ingest time
• Provides named graph scoping for federated multi-dataset deployments

---

Relationship to Existing Issues

• Proposal: Lightweight mechanism to include RDF in OKF #98 (RDFa inline): Complementary but architecturally different. RDFa embeds RDF in HTML fragments within markdown; our approach uses fenced blocks, keeping RDF payloads cleanly separated from prose and renderable as syntax-highlighted code. Both could coexist as conformant approaches within a semantic web profile.
• Proposal - Ontology integration #63 (Ontology integration): Our proposal makes the ontology integration concrete — an OKF ontology (okf:Concept, okf:Bundle, okf:type, etc.) is a natural output of the profile work.

---

Institutional Home

The W3C Holon Community Group is prepared to host the semantic web profile as a Community Group Note, providing a standards-track home for this work independent of any single vendor. We would welcome collaboration with the OKF authors and any other interested parties.

A companion article exploring the convergence between OKF and DataBook is published at The Ontologist: https://ontologist.substack.com

---

Next Steps We Are Proposing

1. Confirm whether the OKF authors see a semantic web profile as in scope for the v0.x roadmap
2. Open a discussion on the typed fenced block naming convention (we are open to adopting OKF-native syntax rather than the DataBook-specific comment annotation)
3. Explore co-authoring a profile document as a contribution to this repo

We are happy to share the full DataBook specification, the CLI toolchain, and working examples.

---

Filed by Kurt Cagle, Acting Chair, W3C Holon Community Group. Contact: kurt.cagle@gmail.com