Skip to content

docs: add a guide answering common objections to RDF - #195

Merged
EthanThatOneKid merged 2 commits into
mainfrom
objections-guide
Oct 19, 2026
Merged

EthanThatOneKid merged 2 commits into
mainfrom
objections-guide

Conversation

@EthanThatOneKid

@EthanThatOneKid EthanThatOneKid commented Oct 19, 2026 •

Copy link
Copy Markdown
Contributor

Closes #192.

Adds guides/rdf-objections, which answers three objections developers from SQL or a document store raise, with runnable examples:

  • Is a missing fact false? Open vs closed world. An OPTIONAL query shows Sandra's missing email as unbound ("not recorded"), not "has none".
  • Will a schemaless graph turn into a mess? Start without a schema, then add SHACL shapes once the model settles. It says plainly that Worlds does not validate writes yet and validation runs before import; on-write validation is planned in feat: validate every write against a world's SHACL shapes, on by default with a per-world opt-out worlds-sdk-ts#151.
  • How does a schema change work? Add givenName/familyName beside name, read either shape with COALESCE, require the new shape for new data with a SHACL shape validated by a TypeScript script on rdf-validate-shacl (the wiki CLI's SHACL library), with Node.js, Deno, and Bun install commands, then backfill and retire name whenever you choose.

Left out deliberately

Verification

  • Every code block was executed. I ran the page's literal jq | curl commands against QA (data-qa.wazoo.dev, host swapped; prod runs the same build) in a throwaway namespace, which was cleaned up afterwards. Every response shown on the page matches the QA output byte-for-byte after formatting.
  • A script confirmed each .rq/.ttl block is identical to the file that was run.
  • The validator's Node.js, Deno, and Bun commands were extracted from the formatted page and run unchanged in empty directories (Node 24.11, Deno 2.9.6, Bun 1.3.14). All three print the documented output and exit 1 for the old-shape record and 0 for the new one. pySHACL is mentioned only as an alternative conforming processor.
  • pnpm run precommit and mintlify broken-links pass.
  • Not observed: the page against prod, and how it renders in a Mintlify preview.

🤖 Generated with Claude Code

EthanThatOneKid and others added 2 commits October 18, 2026 21:31
Covers open vs closed world, starting schemaless and adding SHACL before
import, and changing a schema without a migration. Every example was run
against QA.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… instead of pyshacl

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@EthanThatOneKid
EthanThatOneKid merged commit 52bc8c2 into main Oct 19, 2026
4 checks passed
@EthanThatOneKid
EthanThatOneKid deleted the objections-guide branch October 19, 2026 06:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: add a guide answering evaluator objections (open world, SHACL, schema changes, performance)

1 participant