Skip to content

docs(shacl): document rule-to-SHACL-SPARQL constraint generation - #23

Open
jdsika wants to merge 1 commit into
feat/shaclgen-compositional-rule-fallbackfrom
docs/shaclgen-rule-constraints
Open

docs(shacl): document rule-to-SHACL-SPARQL constraint generation#23
jdsika wants to merge 1 commit into
feat/shaclgen-compositional-rule-fallbackfrom
docs/shaclgen-rule-constraints

Conversation

@jdsika

@jdsika jdsika commented Jul 11, 2026

Copy link
Copy Markdown

Summary

The SHACL generator translates LinkML rules: into sh:sparql constraints, but
the generator documentation did not mention it — so the feature was
undiscoverable and its limits undocumented.

Adds a Rule constraints (SHACL-SPARQL) section to docs/generators/shacl.rst
covering:

  • the recognised named patterns (boolean guard, presence implies value,
    exclusive value) and the compositional fallback;
  • the --emit-rules / --no-emit-rules flag (default: on);
  • the skip, never mis-translate contract, and which rule attributes warn
    (bidirectional, open_world, elseconditions) versus are silently skipped
    (deactivated);
  • a worked YAML → Turtle example;
  • the note that sh:sparql needs a processor with SHACL-SPARQL support
    (e.g. pyshacl with advanced=True).

Documentation only — no source or test changes.

Stack position

main
└─ #19  presence-implies-value
   └─ #20  compositional fallback (M1–M5)
      └─ #23  documentation   ← this PR

Important

Depends on #19 and #20. This section documents behaviour introduced by
both, so it should merge last. If #20 is deferred, the paragraph describing the
compositional fallback needs to be dropped from this PR.

The SHACL generator translates LinkML rules into sh:sparql constraints,
but the generator documentation did not mention it, so the feature was
undiscoverable and its limits undocumented.

Describe the recognised named patterns and the compositional fallback,
the --emit-rules flag, the skip-never-mis-translate contract and which
rule attributes warn, with a worked YAML-to-Turtle example.  Note that
SPARQL-based constraints need a processor with SHACL-SPARQL support.
@jdsika
jdsika force-pushed the docs/shaclgen-rule-constraints branch from ada76d6 to 5123d41 Compare September 11, 2026 12:53
@jdsika
jdsika changed the base branch from fix/shaclgen-rule-converter-audit-findings to feat/shaclgen-compositional-rule-fallback September 11, 2026 12:53
@jdsika jdsika changed the title docs(shacl): document rules-to-SHACL-SPARQL constraint generation docs(shacl): document rule-to-SHACL-SPARQL constraint generation Sep 11, 2026
@jdsika jdsika closed this Sep 11, 2026
@jdsika jdsika reopened this Sep 11, 2026
@jdsika

jdsika commented Sep 11, 2026

Copy link
Copy Markdown
Author

Mirrored upstream as linkml#3991.

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