From Shapes to Shapes

• Quick Start
• Usage
  • Command Line Interface
  • Application Programming Interface
• Testing and Validation
• Further Reading
  • Tutorial
  • Paper

Quick Start

This section introduces two ways of using Shapes to Shapes (S2S).

Release Version

Running the release version of S2S requires Java.

0. Download the latest universal release.
1. Unzip to a chosen location.

curl -L0 "https://github.com/softlang/s2s/releases/latest/download/s2s.zip" --output "s2s.zip" && unzip s2s.zip && cd s2s

Building from Source

Building S2S from source requires the Scala build tool SBT as well as Java.

0. Install the requirements.
1. Clone this repository.
2. Run sbt stage.

git clone "https://github.com/softlang/s2s" && cd s2s && sbt stage

Running an Example

Run an example using the included launcher script (replacing s2s with s2s.bat on Windows):

./s2s docs/ex/paper/q1.sparql docs/ex/paper/S1.shacl

Similarly, G-CORE and ProGS examples are available in the same folder. Note that for ProGS we support only DL-like notation.

./s2s docs/ex/paper/q.gcore docs/ex/paper/S.progs

Usage

Please also consider reading the full tutorial, which includes more intuitive examples for the method itself. The following examples always refer to simply s2s as an executable; see the quick start section for system-specific information. Note: On Windows, you may want to set the active code page to UTF-8 via command chcp 65001 if this is not already your default. This enables correct display of Unicode symbols in output generated by s2s.

Command Line Interface

Basic usage is as follows: s2s [OPTIONS] ... [query-file] [shapes-file?]. Full documentation of the command line interface is accessible with s2s --help. The primary input for S2S is an (SCCQ) SPARQL query (query-file) and an optional set of SHACL input shapes (shapes-file). The query is encoded via a (subset) of standard SPARQL syntax, e.g.,

CONSTRUCT {
    ?y a :E .
    ?z a :B .
    ?y :p ?z
} WHERE {
    ?w :p ?y .
    ?x :p ?z .
    ?y a :B .
    ?z a :E
}

Prefix definitions are allowed. By default, the prefix : is defined (for usage in examples) and bound to an S2S-specific IRI. Various standard prefixes (e.g., RDF) are predefined. The default prefix can be redefined via --prefix <prefix>, such that : can be rebound for a required domain without requiring explicit prefix definitions in each query.

Simple SHACL shapes are encoded as description logic axioms (one per line), where the target is the left-hand side of a subsumption axiom, and the constraint is on the right-hand side:

:A ⊑ ∃:p.:B
∃:r.⊤ ⊑ :B
:B ⊑ :E

Alternatively, JSON-LD syntax can be used; the equivalent shape specification to the aforementioned axioms is given below. More examples are available. The syntax is determined by file extension, using .json for JSON-LD and .shacl for formal DL notation. Note that JSON-LD support is still experimental.

{
  "@context": {
    "s2s": "https://github.com/softlang/s2s/",
    "sh": "http://www.w3.org/ns/shacl#"
  },
  "@graph": [
    {
      "@id": "s2s:s1",
      "@type": "sh:NodeShape",
      "sh:targetClass": {
        "@id": "s2s:A"
      },
      "sh:property": {
        "sh:path": {
          "@id": "s2s:p"
        },
        "sh:qualifiedValueShape": {
          "sh:class": {
            "@id": "s2s:B"
          }
        },
        "sh:qualifiedMinCount": 1
      }
    },
    {
      "@id": "s2s:s2",
      "@type": "sh:NodeShape",
      "sh:targetSubjectsOf": {
        "@id": "s2s:r"
      },
      "sh:class": {
        "@id": "s2s:B"
      }
    },
    {
      "@id": "s2s:s3",
      "@type": "sh:NodeShape",
      "sh:targetClass": {
        "@id": "s2s:B"
      },
      "sh:class": {
        "@id": "s2s:E"
      }
    }
  ]
}

Another relevant command-line option is --debug. While by default the program outputs only the result shapes, including the --debug option will print detailed information about the internals of the S2S method, including the input, output, vocabulary, all inferred axioms (annotated with the respective step of the method specification in the paper), as well as all generated candidate shapes.

Application Programming Interface

While the CLI application is useful for interacting with the S2S method, S2S can also be accessed through its internal API. Currently, we lack full documentation or an example application for the API, which will be provided in the future. The main entry point for programmatic access to S2S is org.softlang.s2s.infer.Shapes2Shapes, with a usage example (the CLI itself) being available in org.softlang.s2s.main.S2S. Another minimal usage example is given below, using string-encoded inputs for query and shapes. Both constructShapes and constructAxioms can be invoked with formal input as well. To this end, consider org.softlang.s2s.infer.AlgorithmInput.

package org.softlang.s2s.example

import org.softlang.s2s.infer.Shapes2Shapes

/** A minimal example for using the s2s API. */
object Example:

    val q: String = """
        CONSTRUCT {
            ?x a :Person .
            ?y a :Agent
        } WHERE {
            ?x a :Person .
            ?y a :Agent
        }
    """

    val s: Set[String] = Set(":Person ⊑ :Agent")

    // Instantiate shapes 2 shapes with default configuration. 
    val s2s = Shapes2Shapes()

    // Run with side-effects, i.e., printing the results.
    s2s.run(q, s)

    // Return the set of output shapes (and a log).
    val (shapes, log) = s2s.constructShapes(q, s)

    // Return the set of constructed axioms (and a log).
    val (axioms, log) = s2s.constructAxioms(q, s)

Testing and Validation

The test suite can be executed via sbt test. The provided tooling for validating both algorithm and implementation is documented in the respective subproject. The remaining tools can be invoked via sbt "runMain <MAIN-FN>" and configured via their main methods; to this end, see main.

Further Reading

The tutorial, with additional examples and an intuitive description of the underlying method.

The full paper: Philipp Seifer, Daniel Hernández, Ralf Lämmel, and Steffen Staab. 2024. From Shapes to Shapes: Inferring SHACL Shapes for Results of SPARQL CONSTRUCT Queries. In Proceedings of the ACM Web Conference 2024 (WWW ’24). ACM. 10.1145/3589334.3645550.

@inproceedings{SeiferHLS24,
  author       = {Philipp Seifer and
                  Daniel Hern{\'{a}}ndez and
                  Ralf L{\"{a}}mmel and
                  Steffen Staab},
  title        = {From Shapes to Shapes: Inferring SHACL Shapes for Results of SPARQL CONSTRUCT Queries},
  booktitle    = {Proceedings of the {ACM} Web Conference 2024, ({WWW} '24)},
  publisher    = {{ACM}},
  year         = {2024},
  doi          = {10.1145/3589334.3645550},
}

We sometimes refer to this as "Paper1" in this documentation. An extended version is available on arXiv. A shorter summary is available as an extended abstract as well.

Another full paper on extensions to this algorithm for G-CORE and ProGS shapes is to appear and will be referenced here soon. We sometimes refer to this as "Paper2" in this documentation.

@article{SeiferHLS26,
  author       = {Philipp Seifer and
                  Daniel Hern{\'{a}}ndez and
                  Ralf L{\"{a}}mmel and
                  Steffen Staab},
  title        = {Transforming Shape Schemas with Composable Property-Graph Queries},
  year         = {to appear},
}

For external reference, the Git repository is available here.