Initial structure of README with some content examples

[amivanoff]

README with the Contents and initial structure of sections.

Some sections entries migrated from Updated list of implementations as an examples. It is not a complete migration, just an illustration.

Closes #1

[amivanoff]

Added:

• Semantic shapes shallow definition
• Legend with icons meaning

[tpluscode]

LGTM

The Contribution Guidelines is not there yet and mabe we can piggy back on the awesome manifesto?

[amivanoff]

@TallTed thank you for the corrections! Typos and text improvements are accepted without question. But em-dashes don't pass the awesome-lint linter. So I propose we should go with ordinary dashes.

[amivanoff]

What development process is the most suitable here?

• should I resolve worked out comments by myself
• or the comment's author will decide and reslove (or not) his comments when he'll check commited corrections

[amivanoff]

I added a formatting example in the "SHACL Validators" section

• Jena SHACL Apache-2.0 Java - Supports: SHACL Core, SHACL-SPARQL.
• RDF4J SHACL Sail BSD-3-Clause Java
• TopBraid SHACL API BSD-3-Clause Java - Based on Jena; supports: SHACL Core, SHACL-SPARQL, SHACL rules.
• TopBraid SHACL API Extended BSD-3-Clause Java - Fork of TopBraid SHACL API + added SHACL-JS based on GraalVM Polyglot.
• SHACL for Ruby BSD-3-Clause Ruby - A pure-Ruby library for working with the Shape Constraint Language to validate the shape of RDF graphs.

Or maybe this one is better?

• Jena SHACL - Supports: SHACL Core, SHACL-SPARQL. Apache-2.0 Java
• RDF4J SHACL Sail - BSD-3-Clause Java
• TopBraid SHACL API - Based on Jena; supports: SHACL Core, SHACL-SPARQL, SHACL rules. BSD-3-Clause Java
• TopBraid SHACL API Extended - Fork of TopBraid SHACL API + added SHACL-JS based on GraalVM Polyglot. BSD-3-Clause Java
• SHACL for Ruby - A pure-Ruby library for working with the Shape Constraint Language to validate the shape of RDF graphs. BSD-3-Clause Ruby

Unfortunately, all bages in general are out of line with the text 😞 I could not find any way to align it vertically.

[tpluscode]

Let's not obsess on details. We can improve gradually

[TallTed]

But em-dashes don't pass the awesome-lint linter. So I propose we should go with ordinary dashes.

em-dashes are the correct punctuation where I've put them, where I replaced hyphens, which are not dashes at all.

Previously, there were double-hyphens at these locations which are the ancient typist's stand-in for an em-dash on typewriters which didn't have the extra strikers for en-dash (~1.5 hyphens wide) and em-dash (~2 hyphens wide). Clever software replaces such doubled-hyphens with em-dashes en-route to the viewer. (Some extra-clever software replaces double-hyphens with en-dash, and triple-hyphens with em-dash.) Less clever software requires that we humans do the job.

I'd like to see the error reported by the not-so-awesome linter, so I can raise an appropriate issue against it.

[TallTed]

Unfortunately, all [badges] in general are out of line with the text

Well, that's not awesome!

[amivanoff]

@TallTed, I completely agree that em-dash is way better for the readability and overall.

But there are two problems (numbered below):

The linter's error is:

> awesome-lint                                                                                                                                                                                                                         
✖ Linting
  README.md:1:1
  ✖  32:47  List item link and description must be separated with a dash  remark-lint:awesome-list-item

1 There is even a special check in linter's code List item link and description separated by invalid en-dash or em-dash, which is not throwing this type of error messages in an output stream for some unknown reason.

2 We should also take into consideration that we are planning to submit this list to the community-made aggregators from the issue

• Propose this list to the aggregators after its completion #6.

So, we could end up with attempts to improve all these aggregators.

What do you think, @VladimirAlexiev, colleagues? What we should do, the right thing or the easy one?

[amivanoff]

The best what could be done with the activity bage vertical alignment (as-before and as-improved). But we need to use HTML tags for the bage instead of a markdown image.

• Jena SHACL - Supports SHACL Core, SHACL-SPARQL; Apache-2.0 Java.
• Jena SHACL - Supports SHACL Core, SHACL-SPARQL; Apache-2.0 Java.

Is it good enough?

[amivanoff]

And a bigger list will look like this (the page will be wider)

• Jena SHACL - Supports SHACL Core, SHACL-SPARQL; Apache-2.0 Java.
• RDF4J SHACL Sail - BSD-3-Clause Java.
• TopBraid SHACL API - Supports SHACL Core, SHACL-SPARQL, SHACL rules; based on Jena; BSD-3-Clause Java.
• TopBraid SHACL API Extended - Supports SHACL Core, SHACL-SPARQL, SHACL rules, SHACL-JS; fork of the TopBraid SHACL API with added SHACL-JS, based on GraalVM Polyglot; BSD-3-Clause Java.
• SHACL for Ruby - A pure-Ruby library; BSD-3-Clause Ruby.

[amivanoff]

We have two open questions related to this PR:

1. List entry formatting

Is this last variant (single dashes, bages alignment, semicolons) acceptable as a starter or not? Should we dump bages or not?

2. The entry content question

Rised by @VladimirAlexiev: "We want the link to be most specific, into the SHACL documentation of the concrete product".

Should we make a link to the library's documentation a priority compared to a library's repository link? If so, I could replace repo-links with doc-links whenever it's possible.

Current variant (shaperone from "Declarative UIs" category)

• Jena SHACL - Supports SHACL Core, SHACL-SPARQL; Apache-2.0 Java.
• RDF4J SHACL Sail - BSD-3-Clause Java.
• TopBraid SHACL API - Supports SHACL Core, SHACL-SPARQL, SHACL rules; based on Jena; BSD-3-Clause Java.
• rdf-validate-shacl - Supports SHACL Core; pure JavaScript validator on top of the RDFJS stack; playground; MIT JavaScript.
• shacl-engine - Supports SHACL Core, SHACL-SPARQL; A fast engine for data provided as RDF/JS objects; playground; MIT JavaScript.
• shaperone - SHACL Shapes Form generator; playground; MIT Typescript.

Doc-links variant (Jena, RDF4J, shaperone changed, others do not have any documentation)

• Jena SHACL - Supports SHACL Core, SHACL-SPARQL; Apache-2.0 Java.
• RDF4J SHACL Sail - BSD-3-Clause Java.
• TopBraid SHACL API - Supports SHACL Core, SHACL-SPARQL, SHACL rules; based on Jena; BSD-3-Clause Java.
• rdf-validate-shacl - Supports SHACL Core; pure JavaScript validator on top of the RDFJS stack; playground; MIT JavaScript.
• shacl-engine - Supports SHACL Core, SHACL-SPARQL; A fast engine for data provided as RDF/JS objects; playground; MIT JavaScript.
• shaperone - SHACL Shapes Form generator; playground; MIT Typescript.

[amivanoff]

I have finalized the last version. It will be rendered like this:
https://github.com/w3c-cg/awesome-semantic-shapes/blob/89e8518336025ec1289fdb81141014aa672aedd4/README.md

[VladimirAlexiev]

@amivanoff thanks, you've done a great job!
I think the first link should be to source because the "last commit" shield suggests that, and people will expect it.
And we can add a link "docs" in the description.

I'm ready to merge, but since you've collected both links, could you make this last change?
Thanks!!

[TallTed]

Apache Jena SHACL GitHub last commit - Supports SHACL Core, SHACL-SPARQL; Apache-2.0 Java.

Some punctuation is needed between the license and the language. The single space separator is not sufficient. I suggest the word "license" and a semicolon —

Apache Jena SHACL GitHub last commit - Supports SHACL Core, SHACL-SPARQL; Apache-2.0 license; Java.

— or the word "license" and a "full stop" —

Apache Jena SHACL GitHub last commit - Supports SHACL Core, SHACL-SPARQL; Apache-2.0 license. Java.

[amivanoff]

I think the first link should be to the source because the "last commit" shield suggests that, and people will expect it.

Awesome Linter checks that all list entries have unique links. Complex software like Jena, implements SHACL and ShEx and appears twice in the SHACL Validators and ShEx Validators sections.

With doc-links approach it was OK. With repo-links we have a problem.

We could use links to the corresponding submodules, but they are not so informative for the reader:

• https://github.com/apache/jena/tree/main/jena-shacl
• https://github.com/apache/jena/tree/main/jena-shex

We could use the same "parent" link https://github.com/apache/jena in the SHACL Validators and the ShEx Validators sections but the linter returns an error.

Another option, we could use doc-links and clickable badges with URL links to the repositories. But it is difficult to edit.

Example of markdown and result rendering for 3 cases:

• doc-link + bage (compact markdown, compact rendering)
• doc-link + repo-link bage (verbose markdown, compact rendering)
• repo-link + repo-link bage + doc-link in description (verbose markdown, verbose rendering)

- [Apache Jena SHACL](https://jena.apache.org/documentation/shacl/index.html) <img alt="GitHub last commit" src="https://img.shields.io/github/last-commit/apache/jena" align="top"> - Supports SHACL Core, SHACL-SPARQL; `Apache-2.0` license; `Java`.
- [Apache Jena SHACL](https://jena.apache.org/documentation/shacl/index.html) <a href="https://github.com/apache/jena"><img alt="GitHub last commit" src="https://img.shields.io/github/last-commit/apache/jena" align="top"></a> - Supports SHACL Core, SHACL-SPARQL; `Apache-2.0` license; `Java`.
- [Apache Jena SHACL](https://github.com/apache/jena) <a href="https://github.com/apache/jena"><img alt="GitHub last commit" src="https://img.shields.io/github/last-commit/apache/jena" align="top"></a> - Supports SHACL Core, SHACL-SPARQL; [documentation](https://jena.apache.org/documentation/shacl/index.html); `Apache-2.0` license; `Java`.

• Apache Jena SHACL - Supports SHACL Core, SHACL-SPARQL; Apache-2.0 license; Java.
• Apache Jena SHACL - Supports SHACL Core, SHACL-SPARQL; Apache-2.0 license; Java.
• Apache Jena SHACL - Supports SHACL Core, SHACL-SPARQL; documentation; Apache-2.0 license; Java.

[amivanoff]

@TallTed, I will add "license" and a semicolon to list entries.

[VladimirAlexiev]

Does the validation work with links like
:https://github.com/apache/jena/tree/main/jena-shacl ? If so, let's go for that.
The third markup above is too complex

[amivanoff]

Does the validation work with links like :https://github.com/apache/jena/tree/main/jena-shacl ? If so, let's go for that. The third markup above is too complex

Fixed here https://github.com/w3c-cg/awesome-semantic-shapes/blob/22b7da77fb2ec445cd0c0a26bf8465642435b96f/README.md

• No separate documentation links in item's description.
• List item main link is repository subcomponent link (not doc-link).
• Badge links removed for markdown clarity.
• Switched back from markdown emojis to UTF-8 emojis (plain text emoji is not so visible in the editor).
• Added "license;" to the license SPDX codes (not "tags-like" markup in the end of description but more of a "text-like").
• Added Part 2 SHACL 2017 talk by TopQuadrant.

[amivanoff]

I fixed all the comments from above. Whenever possible, I used shield.io badges for versions and last activity dates because this eliminated the necessity for manual updates.
https://github.com/w3c-cg/awesome-semantic-shapes/blob/09dce6b09215c2ee9a44c075dbcaa0aebe4a3b5c/README.md

[VladimirAlexiev]

Great job @amivanoff ! I'll merge it but first want to pick up all links mentioned, eg by @bergos.
Then I'll submit a second PR with more tools and goodies.

[amivanoff]

@VladimirAlexiev, Thanks!
@bergos links have been added: under the "rdf-ext" bullet in the "SHACL Validators" section and under the bullet "SHACL-related specifications" in the "Specifications" section.