# Overview

`pgschemapc` is a prototype implementation of PGSchema with support for property constraints.

# Installation and Building

You can download a binary from the download page, where you will also find the compiled packages for the installation on your system using a package manager.

## Building

The project has been implemented in Rust and uses cargo for building. Once you install `cargo`, you can run:

    cargo build

to compile and generate a binary which will be available in `target/debug/pgschemapc`. If you want a more performant binary, you can use the `--release` option.

# Getting started

In order to verify that the installation has been successful, you can run the following command to check that everything is working as expected.

    pgschemapc --version

Once you have `pgschemapc` installed and verified, the next step is to start using the different subcommands that are bundled within the tool. You can run:

    pgschemapc --help
    A simple prototype tool to process and validate PG-Schemas with property constraints

    Usage: pgschemapc [COMMAND]

    Commands:
      pgs       Process and validate property graph schemas
      pg        Process and validate property graphs
      map       Process and validate type map associations
      validate  Validate a property graph with a property graph schema and some associated type map
      help      Print this message or the help of the given subcommand(s)

    Options:
      -h, --help
              Print help (see a summary with '-h')

      -V, --version
              Print version

## pg - Property Graphs

Property graphs contain a list of node or edge declarations separated by `;`.

An example can be:

    (n1: Person { name: "Alice", age: 23 });
    (n2: Person & Student { name: "Bob" });
    (n3: Course { name: "Algebra" });
    [e1: (n1) -[ :knows { since: 2020 }]->(n2)];
    [e2: (n2)-[:knows { start: 2024, end: 2025 }]->(n3)]

Notice that node declarations are declared between parenthesis `(` and `)` while edge declarations are declared between square brackets `[` and `]`.

The full grammar is available here.

# pgs - Property Graph Schemas

A property graph schema contains a list of `CREATE` node/edge/graph `TYPE` statements. It follows the grammar from the PGSchema paper with some extensions for property constraints.

The full grammar is available here.

An example property graph schema is:

    CREATE NODE TYPE ( PersonType : Person {
        name: STRING,
        OPTIONAL age: INTEGER
    }) ;
    CREATE NODE TYPE ( StudentType : Person & Student {
        name: STRING,
        OPTIONAL age: INTEGER
    }) ;
    CREATE NODE TYPE ( CourseType: Course {
        name: STRING
    })

# map - Type map associations

Type map associations are used to trigger validation. They associate nodes/edges in the property graph with type names in the property graph schema.

The full grammar of type maps is available here

An example type map association is:

    n1:PersonType,
    n2:StudentType,
    n3:CourseType

Notice that type maps can also be used to specify the expected result of validation which can be positive or negative. For negative validation results, we use a `!` after the colon. These result type maps are employed in the test-suite which is available here.

# validate property graphs

The `validate` command can be used to validate nodes or edges from a Property Graph to check if they conform with type node declarations in a Property Graph Schema. To trigger validation it is necessary to add a third parameter, which is a type map association file which declares which nodes/edges should be checked against which type names.

An example validation can be run by:

    pgschemapc validate --graph examples/course.pg --schema examples/course.pgs --map examples/course.map

# test-suite

The project contains a list of tests in the folder tests.

The test cases are defined with four files:

- A property graph, usually with the extension `.pg`
- A property graph schema, usually with the extension `.pgs`
- An input type map association file: `.map` which declares which nodes/edges in the property graph should validate with which type names in the property graph schema.
- A result type map association file, which declares the expected result.