#482 path grammar

[VladimirAlexiev]

Related to #482, here are 2 variants:

• plantuml

  • pros: can automate with make file, the base case predicate comes first
  • cons: worse rendering, ugly EBNF source (took some staring at https://plantuml.com/ebnf to write it), have to put it in 1 line

  @startEbnf
  path = predicate | "(", {path}-, ")" | "[", 
  ("sh:inversePath"|"sh:alternativePath"|"sh:zeroOrMorePath"|"sh:oneOrMorePath"), path, "]" ;
  @endEbnf
  

  

• rr

  • pros: better rendering (I like the yellow), easy to write source, can split in multiple lines
  • cons:
    • made by hand at https://www.bottlecaps.de/rr/ui (check SVG, uncheck Embedded, download), need to build & deploy to automate;
    • preserve order of alternative clauses GuntherRademacher/rr#62: the base case predicate is shown second and I can't control that

  path ::= predicate | 
    '(' path* ')' | 
    '[' ('sh:inversePath'|'sh:alternativePath'|'sh:zeroOrMorePath'|'sh:oneOrMorePath') path ']'
  

  

[VladimirAlexiev]

@HolgerKnublauch do you like this sort of thing?

• @afs , @jeswr I think we definitely want it for some aspects of the SHACLC grammar? (I added such to Andy's RULEs gist).
• I personally think it's also useful for SHACL RDF constructs! Reading through those pfps-inspired obtuse clauses is not easy...

[afs]

Does not work in dark mode.

[HolgerKnublauch]

I have mixed feelings about all this TBH. We are adding more and more work to keep all this consistent and correct.

[afs]

for some aspects of the SHACLC grammar?

The rules compact syntax is standalone and has EBNF generated from the same source as the HTML.

SHACL-C style is more towards "abbreviated Turtle". It may be too constraining (on either side) to have one compact syntax that works for both. The rule language can change its name to avoid the word "compact".

The use of SPARQL keywords may not fit with the editors of SHACL-C view of writing node expressions. Restricting the filters to node expression syntax is "unintuitive" and also a barrier to a compact-rules-syntax only implementation based on conjunctive query generation whereas for SHACL-C maybe the right thing to do. There is already keyword clash between the two.

Other W3C specs (RDF ones, XML, ...) use this W3C EBNF: https://www.w3.org/TR/xml11/#sec-notation

puml ebnf looks to be different and has it's own features.

[VladimirAlexiev]

hi @afs!

• PlantUML has a "dark mode", eg see https://www.plantuml.com/plantuml/duml/SoWkIImgAStDuNBAJrBGjLDmpCbCJbMmKiX8pSd9vt98pKi1IW80

  

  I don't yet know whether it's adaptive (i.e. interrogates @media in the browser) but it seems so: Is there a way for the plantuml diagrams to honor the context style (light or dark)? plantuml/plantuml#882

• RR doesn't have "dark mode", but the diagram looks nearly ok, only the edges need to be made more prominent.

  

  I posted adapt or change colors to work in "dark mode" GuntherRademacher/rr#58

---

PUML ebnf is indeed weird and I much prefer the RR ebnf.

• So far the only real benefit of PUML grammar diagrams is "dark mode" support. But I hope @GuntherRademacher addresses this, or I could try to tackle it.
• I'll

@HolgerKnublauch, @afs , @jeswr I think every effort should be made to make the specs easier for the reader.
Perhaps active authors are "unqualified" to judge how difficult the pfps-inspired sequential clauses are to a new reader!
I will undertake to keep all diagrams up to date.

[afs]

Perhaps active authors are "unqualified" to judge how difficult the ...

The purpose of a standard is first-and-foremost to define.

No other document can do that.

The responsibility of the working group is achieve that goal. Sooner is better. If other work is taking time and attention away from reviewing then that detracts from the quality and timeliness of the standard.

[HolgerKnublauch]

At the very minimum any such diagram needs to be wrapped with a warning that this is purely informative, illustrative and if it contains errors then the written spec has precedence.

[VladimirAlexiev]

@afs

If other work is taking time and attention away from reviewing then that detracts from the quality and timeliness of the standard.

So Andy, are you saying the readability of a standard doesn't matter? That readability has no import on adoption and correct implementation?

I've done it and I undertake to keep it up to date. So your argument "it will take time to do" doesn't really apply.

@HolgerKnublauch

warning that this is purely informative,

Agree!

---

PS: The discussion taking part here needs to play out, because it sets a precedent.
If it's accepted, my intent is to pepper the specs with illustrations (I also added a ValidationResult UML diagram).

[simonstey]

this doesn't necessarily has anything todo with #482 but as it's just fixing typos I guess that's fine

[simonstey]

looks good to me!

[YoucTagh]

I think it's missing sh:zeroOrOnePath

[YoucTagh]

@VladimirAlexiev, could you update the PR to include the sh:zeroOrOnePath to merge it?

[TallTed]

@VladimirAlexiev — I'm sad to say that the time it's taking you to add the missing sh:zeroOrOnePath, as requested Aug 13, doesn't bode well for your promised maintenance of this and any other images you PR — which saddens me because I think this and various other images would increase speed and depth of comprehension for new readers. Can you please respond here with at least an estimated time to delivery on the sh:zeroOrOnePath addition?

[VladimirAlexiev]

Hi! sorry about the delay, I've been out of this WG for two months...

Here it is: https://raw.githack.com/VladimirAlexiev/data-shapes/refs/heads/issue-482-path-grammar/shacl12-core/index.html#property-paths

@YoucTagh or @TallTed would you like to take a last look, or should I merge it?

• The image is introduced by this paragraph

This syntax diagram shows how they can be used together (PredicatePath is the basic case consisting of a single predicate, SequencePath uses a parenthesized list of paths, and the rest use a blank node and a specific sh: term):

• which do you like better: the yellow (RR) or the black-and-white (PlantUML)? Pros and cons are discussed on top of this issue. I've used the yellow, but we can easily switch by changing images/path-EBNF-rr.svg to images/path-EBNF.svg.

[YoucTagh]

Thank you @VladimirAlexiev.

We can use this comment to vote for the preferred style:

• the yellow (RR) => 👀
• the black-and-white (PlantUML) => 🚀

[afs]

We need to have a system that is reproducible, both now and in the future (5+ year timeframe), where anyone can build the diagrams.

One SVG is the primary version and may in the future be edited by other means.
The tools are helpers, not authoritative. Tools go through cycles.

At a minimum there should be document about the tools needed (release location, versions) and how to invoke them.

Personally, I think only the SVG should be in this git repository. One version of the truth. The rest can go in a separate place (the wiki?).

(( Added an item to the agenda for 2025-10-20 ))

[VladimirAlexiev]

@afs
I agree that better documentation is needed. I'll add images/README.md.

I disagree we should evict the sources and keep only the target SVGs. Then I can't use "make" to build them. And it makes no sense: if in 20 years the tools cease to exist, only then and there some unhappy soul would have to grapple with the SVG. Until then we use the tools.

As for the 2 variants of syntax diagram (Plantuml vs RR): I agree to keep only 1, but do we have a clear winner?

[VladimirAlexiev]

RR makes clearly better output, but there are 2 issues that need to be resolved:

• adapt or change colors to work in "dark mode" GuntherRademacher/rr#58
• add web API or command-line tool GuntherRademacher/rr#65

[afs]

I disagree we should evict the sources and keep only the target SVGs. Then I can't use "make" to build them.

Firstly - I can't use "make" to build them at the moment.

Secondly - I'm not suggesting throwing the tool chain away, they should go in a different place in this repo or some other public place.

As mentioned in the telecon yesterday, fixing SVGs in small ways (changing a spelling, maybe rewording) is typical maintenance. There are (many) SVG editors these days, not need to edit the SVG text.

[VladimirAlexiev]

@afs

I can't use "make" to build them at the moment.

After I document what tools are needed, you can install them and do make if you so desire

There are (many) SVG editors these days

• If someone tweaks the SVGs then we cannot later edit the source files (and preserve the tweaks).
  It's easier to do bigger changes in the sources (eg add fields, add nodes, add relations)
• There are good reasons to generate the 3 diagrams from textual sources, rather than edit directly in SVG, right?
• There might be bytecode editors, but you only ever edit the Jena source files, right?