Skip to content

Extract the vocabularies and document shapes into linkeddatahub-rdf - #398

Merged
namedgraph merged 3 commits into
developfrom
feat-linkeddatahub-rdf
Sep 29, 2026
Merged

namedgraph merged 3 commits into
developfrom
feat-linkeddatahub-rdf

Conversation

@namedgraph

@namedgraph namedgraph commented Sep 29, 2026 •

Copy link
Copy Markdown
Member

Why

The RDF a client sends to create a container, add a chart or grant an authorization was described in static buildModel methods hanging off picocli @Command classes, reachable only by depending on the CLI. Web-Algebra's ldh-* operations build the same documents through REST-VKG's execution context rather than through Jersey, so they had no way to share those shapes and would have had to restate every one. A shape restated is a shape that drifts.

rdf/ now builds com.atomgraph:linkeddatahub-rdf with Jena as its only dependency. What is shared is the shape of the request body, not how it is sent, so neither consumer inherits the other's transport.

What moved

into rdf/ from
rdf.vocabulary.{A,AC,ACL,DH,LDH,NFO,SD,SP,SPIN} cli.vocab.*
Slugs, SequenceNumbers, Digests, Updates cli.util.*, cli.sparql.*
Subjects.of(...) BaseCommand.createSubject

The eighteen builders come off the command classes into classes named for what they build — Documents (container, item), Blocks, Views, Queries, Services, Imports, Acl, Ontologies. Commands become argument parsing plus a call:

put(getClient(), doc, Documents.container(doc, title, description, block, mode, primaryTopic));

URIRewriter splits rather than moving whole. childURI, encodeSlug and adminBase are conventions the platform itself applies and become rdf.URIs; rewrite is the --proxy option sending a request somewhere other than where its URI says, which stays a CLI concern with origin now private.

What did not move

The platform keeps its own com.atomgraph.linkeddatahub.vocabulary, still duplicated with the library's. Collapsing them would make the platform depend on rdf/, and the Dockerfile builds the webapp from COPY src + COPY pom.xml alone — so the dependency has to point away from the platform rather than at it. Independently fixable later, once the artifact is published.

Build and release

cli/pom.xml resolves the library by ${project.version}, so the two move together or the CLI stops resolving. make cli installs rdf/ first; make cli-version and release.sh's sync_cli_version version both poms. release.sh also deploys the library right after release:perform, which carries reactor modules only — building from the release tag via git archive, since sync_cli_version has moved the working tree on to the next SNAPSHOT by then. Inside the irreversible block on purpose: a platform release whose pinned library is absent is a release whose clients cannot build.

Verification

  • 40 tests in rdf/, including the 25 ModelBuildersTest cases, which assert the exact models and passed unchanged after the move
  • 86 tests in cli/
  • make cli end to end, the shaded jar carrying com/atomgraph/linkeddatahub/rdf/*.class, and ldh --version / ldh create container --help off the launcher
  • mvn -Prelease clean verify builds the main, sources and javadoc jars

Not run: the tests/http suite. Every one of these builders is exercised by it, so that is the real check and it wants a dev stack on 4443. Worth running before this merges.

🤖 Generated with Claude Code

namedgraph and others added 3 commits September 29, 2026 22:26
The RDF a client has to send to create a container, add a chart or grant an
authorization was described in static buildModel methods hanging off picocli
@command classes, reachable only by depending on the CLI - so Web-Algebra's
ldh-* operations, which build the same documents through REST-VKG's execution
context rather than through Jersey, had no way to share them and would have
had to restate every shape. A shape restated is a shape that drifts. rdf/ now
builds com.atomgraph:linkeddatahub-rdf with Jena as its only dependency: what
is shared is the shape of the request body, not how it is sent, so neither
consumer inherits the other's transport.

The eighteen builders move off the command classes into classes named for what
they build - Documents (container, item), Blocks, Views, Queries, Services,
Imports, Acl and Ontologies - with BaseCommand.createSubject becoming
Subjects.of, since fifteen of them needed it. The nine vocabulary classes and
Slugs, SequenceNumbers, Digests and Updates move across unchanged. Commands are
now argument parsing and a call. URIRewriter splits rather than moving whole:
childURI, encodeSlug and adminBase are conventions the platform itself applies
and belong in the library as URIs, while rewrite is the --proxy option sending a
request somewhere other than where its URI says, which stays a CLI concern with
origin now private.

The platform keeps its own com.atomgraph.linkeddatahub.vocabulary, still
duplicated with the library's. Collapsing them would make the platform depend on
rdf/, and the Dockerfile builds the webapp from COPY src and COPY pom.xml alone,
so the dependency has to point away from the platform rather than at it.

cli/pom.xml resolves the library by ${project.version}; make cli installs it
first, and make cli-version and release.sh's sync_cli_version now version both
poms together, since the two must move as one or the CLI stops resolving.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The library had no distributionManagement and no publishing plugin, so a client
outside this machine could not resolve it at all - REST-VKG's ldh-* operations
would have had only a local install to depend on. rdf/pom.xml now declares the
central-portal-snapshots repository and the central-publishing plugin, the
licenses, developers and scm blocks Central rejects a release without, and a
release profile attaching sources, javadoc and GPG signatures, mirroring what
<releaseProfiles>release</releaseProfiles> activates for the platform.

release.sh deploys it immediately after release:perform, which carries reactor
modules only. It builds from the release tag via git archive rather than from
the working tree, because sync_cli_version has moved rdf/pom.xml on to the next
development version by that point. Inside the irreversible zone on purpose: a
platform release whose pinned library is absent is a release whose clients
cannot build.

Building the release profile also caught a javadoc reference to SP#Describe,
which the trimmed vocabulary does not carry - it holds Construct and Select.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
cli/ is its own build, so the platform pom's <repositories> do not reach it, and
it had never needed any of its own: everything it depended on is released to
Maven Central. linkeddatahub-rdf between releases is not - Central serves no
snapshots - so resolution succeeded only where the library happened to be in the
local repository, which is to say on the machine that had just installed it. CI
resolved nothing and failed on the dependency.

Verified against a local repository that never had the install, which is the
state CI starts from: the CLI builds and its 86 tests pass.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@namedgraph
namedgraph merged commit a52b329 into develop Sep 29, 2026
3 checks passed
@namedgraph
namedgraph deleted the feat-linkeddatahub-rdf branch September 29, 2026 21:51
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.

1 participant