Skip to content

Add GitHub workflow to keep Turtle and JSON-LD examples sync #318

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
bergos opened this issue Mar 10, 2025 · 1 comment · May be fixed by #386
Open

Add GitHub workflow to keep Turtle and JSON-LD examples sync #318

bergos opened this issue Mar 10, 2025 · 1 comment · May be fixed by #386

Comments

@bergos
Copy link
Contributor

bergos commented Mar 10, 2025

As we use two serializations (Turtle, JSON-LD) in our examples, we should create a script that checks if both formats are in sync and add that script to a GitHub workflow.

@gkellogg
Copy link
Member

JSON-LD does just this, for example in Example 3. The markup uses the aside element with selectors for the different serialization, other formats, and constructs a call to the JSON-LD Playground to see the results that are being described.

  <aside class="example ds-selector-tabs"
         title="Sample JSON-LD document using full IRIs instead of terms">
    <div class="selectors">
      <button class="selected" data-selects="expanded">Expanded (Input)</button>
      <button data-selects="statements">Statements</button>
      <button data-selects="turtle">Turtle (Result)</button>
      <a class="playground" target="_blank" href="">PG</a>
    </div>
    <pre class="expanded input selected nohighlight" data-transform="updateExample">
    <!--
    {
      "****http://schema.org/name****": "Manu Sporny",
      "****http://schema.org/url****": ****{
        "@id": ****"http://manu.sporny.org/"
        ####↑ The '@id' keyword means 'This value is an identifier that is an IRI'####
      ****}****,
      "****http://schema.org/image****": ****{
        "@id": ****"http://manu.sporny.org/images/manu.png"
      ****}****
    }
    -->
    </pre>
    <table class="statements"
           data-result-for="Sample JSON-LD document using full IRIs instead of terms-expanded"
           data-to-rdf>
      <thead><tr><th>Subject</th><th>Property</th><th>Value</th></tr></thead>
      <tbody>
        <tr><td>_:b0</td><td>schema:image</td><td>http://manu.sporny.org/images/manu.png</td></tr>
        <tr><td>_:b0</td><td>schema:name</td><td>Manu Sporny</td></tr>
        <tr><td>_:b0</td><td>schema:url</td><td>http://manu.sporny.org/</td></tr>
      </tbody>
    </table>
    <pre class="turtle"
         data-content-type="text/turtle"
         data-result-for="Sample JSON-LD document using full IRIs instead of terms-expanded"
         data-transform="updateExample"
         data-to-rdf>
    <!--
    @prefix schema: <http://schema.org/> .
    @prefix xsd: <http://www.w3.org/2001/XMLSchema#> .


     [
       schema:image <http://manu.sporny.org/images/manu.png>;
       schema:name "Manu Sporny";
       schema:url <http://manu.sporny.org/>
     ] .
    -->
    </pre>
  </aside>

The updateExample method cleans up comments, which might not parse (certainly for JSON-LD).

Other tabbed elements of attributes that allow comparing the results with another example, and to describe the transformation necessary. This includes data-content-type which identifies the serialization format.

This is run through a GH action which runs the extract-examples.rb Ruby file to parse and compare the results. Basically, in this case, to parse each into a graph and they verify that the resulting graphs are isomorphic (could also be done with RDF Dataset Canonicalization).

The most common problem found is basic syntax errors introduced during hand editing.

The playground links are created by this bit from common.js when ReSpec starts up, along with some other workflows.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants