Validations¶

Dynamic Validators¶

Dynamic validators are meant to execute temporary checks on the database. Mutations may introduce the need for a particular validation, which is no longer relevant once the mutation is executed. The Semantic Objects supports three types of these validators:

• Reference validations: check that objects referenced within a mutation have the correct type.
• SO type validations: check that the objects affected by the mutation have a type that corresponds to the mutation type.
• ID existence validations: check that an ID exists and is of a correct type for delete mutations. Also check that an ID is not reused for create and update mutations.

Those three validations produce the following errors:

• Validation of an object’s properties with object ranges. Raised when the reference is set to point towards an object of an incorrect type, or towards a null object.

mutation createHuman {
    create_Human(objects: {
      rdfs_label: {value: "Lando Calrissian", lang: "en-GB"}
      type: "https://swapi.co/vocabulary/Human"
      species: {
        ids: ["https://swapi.co/vocabulary/WeDontHaveThis"]
      }
    })
    {
        human {
            id
        }
    }
}

• Type errors - preventing an update of an incorrect object. Raised when the type of the object in the database does not match the intended update target’s type.

mutation updateHuman {
  update_Human(objects: {
    type: {value: "https://swapi.co/vocabulary/Droid", replace: true},
    rdfs_label: {value: {value: "Lando Calrissian"}}
  },
  where: {ID: "https://swapi.co/resource/human/88"}) {
    human {
        id
    }
  }
}

• ID existence and type for delete mutations - validating that when trying to delete, the object both exists and is of the correct type.

mutation deleteHuman {
    delete_Human( where: {ID: ["https://swapi.co/resource/human/255"]}) {
        human {
            id
        }
    }
}

• ID existence for create mutations - validating that IDs are not reused when creating an object. Reusing IDs may lead to conflicting data being inserted for an object.

mutation createYoda {
    create_Yodasspecies(objects: {
        id: "https://swapi.co/resource/yodasspecies/20"
        rdfs_label: {value: "Yoda new!"}
    }),
    {
        yodasspecies {
            id
        }
    }
}

In practical terms, those validations are performed by executing queries on the database prior to the mutation execution.

Static Validators¶

Static validators are meant to always be present on the database. They include validations such as cardinality and datatype, and are implemented using SHACL. All static validations happen at the database level. You can read more about the underlying mechanisms in GraphDB’s documentation.

Static validations are carried out for every change to the database, meaning they will be triggered by each mutation. However, it is important to note that they are only carried out on the subset of data that is relevant to the mutation. This ensures that validations are reasonably fast.

The Semantic Objects aim to reduce the need for understanding different specification languages and semantics by using the SOML language. Therefore, it is not necessary to explicitly specify a SHACL schema and bind it to the instance. Just like it does for GraphQL schemas, the Semantic Objects will generate a schema from the input SOML. You can find a comparison between a sample SOML schema and a sample generated SHACL in the next section.

Currently, the following validations are implemented:

• Cardinality checks - min and max - number of data items for a given property. Satisfied in SHACL via sh:minCount and sh:maxCount.
• Type checks - range - the datatype of a given property. For scalars, this is satisfied via sh:datatype. For objects, the converter currently emits sh:node entries. However, the underlying implementation does not cover this constraint yet.
• Pattern checks - pattern - defining a pattern that restricts the values of a given property. Expressed in SHACL via sh:pattern, together with sh:flags. Can be used at the shape or property level. Represented in SOML as a simple string or an array of two strings. If in an array, the second string is considered to correspond to the flags for the pattern.
• Min and max length - minLength and maxLength - for string-based properties. Expressed in SHACL via sh:maxLength and sh:minLength, assuming inclusivity.
• Value range constraints - maxInclusive, minInclusive, maxExclusive, and minExclusive - for literal properties, such as numericals and dates. In SHACL, this can be expressed via the same property names.
• Language configurations - defining that a value is defined in only one language. Expressed via sh:uniqueLang in SHACL.
• List constraints - in and dash:hasValueIn - defining that a property’s values must be a member in a list, either strictly or non-strictly. This is defined with the valuesIn and valuesListExclusive SOML properties.

curl -X GET 'http://localhost:9995/soml/validation/shacl'

curl -X DELETE 'http://localhost:9995/soml/validation/shacl'

curl -X POST 'http://localhost:9995/soml/validation/shacl/rebind'

curl -X PUT 'http://localhost:9995/soml/validation/shacl?enable=true'

id:          /soml/starWars
label:       Star Wars

prefixes:
  # common prefixes
  rdf: "http://www.w3.org/1999/02/22-rdf-syntax-ns#"

specialPrefixes:
  base_iri:          https://starwars.org/resource/
  vocab_iri:         https://starwars.org/vocabulary/
  vocab_prefix:      voc
  shape_prefix:      vocsh
  shape_iri:         https://starwars.org/vocabulary/shacl

objects:
  Character:
    kind: abstract
    name: voc:name
    props:
      voc:name: { min: 1, max: 3 }
      descr: { label: "Description", maxLength: 300, pattern: [".*character.*", "i"] }
      friend: { descr: "Character's friend", max: inf, range: Character }
      homeWorld: { label: "Home World", descr: "Characters home world (planet)", range: Planet }
  Droid:
    regex: "^https://starwars.org/resource/droid/\\w+/"
    regexFlags: "i"
    inherits: Character
    props:
      primaryFunction: { label: "primary function", descr: "e.g translator, cargo", min: 1 }
      droidHeight: {descr: "Height in metres", range: decimal}
  Human:
    inherits: Character
    props:
      height: { descr: "Height in metres", range: decimal }
      mass: { descr: "Mass in kilograms", range: decimal }
  Planet:
    name: voc:name

@prefix : <https://starwars.org/resource/> .
@prefix voc: <https://starwars.org/vocabulary/> .
@prefix vocsh: <https://starwars.org/vocabulary/shacl> .
@prefix sh: <http://www.w3.org/ns/shacl#> .
@prefix dash: <http://datashapes.org/dash#> .
@prefix so: <http://www.ontotext.com/semantic-object/> .
@prefix affected: <http://www.ontotext.com/semantic-object/affected> .
@prefix res: <http://www.ontotext.com/semantic-object/result/> .
@prefix dct: <http://purl.org/dc/terms/> .
@prefix gn: <http://www.geonames.org/ontology#> .
@prefix owl: <http://www.w3.org/2002/07/owl#> .
@prefix puml: <http://plantuml.com/ontology#> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix skos: <http://www.w3.org/2004/02/skos/core#> .
@prefix void: <http://rdfs.org/ns/void#> .
@prefix wgs84: <http://www.w3.org/2003/01/geo/wgs84_pos#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
@prefix voc: <https://starwars.org/vocabulary/> .

vocsh:_CharacterRef
    a sh:NodeShape ;
    sh:target [ a dash:AllSubjectsTarget ] ;
    sh:filterShape [
        a sh:Shape ;
        sh:and( [ sh:path rdf:type ; sh:hasValue voc:Character ; ][ sh:or( [ sh:path rdf:type ; sh:hasValue voc:Droid ; ][ sh:path rdf:type ; sh:hasValue voc:Human ; ] )] ) ] .

vocsh:_Character
    a sh:NodeShape ;
    sh:target [ a dash:AllSubjectsTarget ] ;
    sh:filterShape [
        a sh:Shape ;
        sh:and( [ sh:path rdf:type ; sh:hasValue voc:Character ; ][ sh:or( [ sh:path rdf:type ; sh:hasValue voc:Droid ; ][ sh:path rdf:type ; sh:hasValue voc:Human ; ] )] ) ] ;
    sh:property [
        sh:path voc:name ;
        sh:minCount 1 ;
        sh:maxCount 3 ;
        sh:datatype xsd:string ;
    ] ;
    sh:property [
        sh:path voc:descr ;
        sh:maxCount 1 ;
        sh:datatype xsd:string ;
        sh:maxLength 300 ;
        sh:pattern ".*character.*" ;
        sh:flags "i" ;
    ] ;
    sh:property [
        sh:path voc:friend ;
        sh:node vocsh:_CharacterRef ;
    ] ;
    sh:property [
        sh:path voc:homeWorld ;
        sh:maxCount 1 ;
        sh:node vocsh:PlanetRef ;
    ] .

vocsh:DroidRef
    a sh:NodeShape ;
    sh:target [ a dash:AllSubjectsTarget ] ;
    sh:filterShape [
        a sh:Shape ;
        sh:and( [ sh:path rdf:type ; sh:hasValue voc:Character ; ][ sh:path rdf:type ; sh:hasValue voc:Droid ; ] ) ] .

vocsh:Droid
    a sh:NodeShape ;
    sh:target [ a dash:AllSubjectsTarget ] ;
    sh:filterShape [
        a sh:Shape ;
        sh:and( [ sh:path rdf:type ; sh:hasValue voc:Character ; ][ sh:path rdf:type ; sh:hasValue voc:Droid ; ] ) ] ;
    sh:pattern "^https://starwars.org/resource/droid/\w+/" ;
    sh:flags "i" ;
    sh:property [
        sh:path voc:primaryFunction ;
        sh:minCount 1 ;
        sh:maxCount 1 ;
        sh:datatype xsd:string ;
    ] ;
    sh:property [
        sh:path voc:droidHeight ;
        sh:maxCount 1 ;
        sh:datatype xsd:decimal ;
    ] .

vocsh:HumanRef
    a sh:NodeShape ;
    sh:target [ a dash:AllSubjectsTarget ] ;
    sh:filterShape [
        a sh:Shape ;
        sh:and( [ sh:path rdf:type ; sh:hasValue voc:Character ; ][ sh:path rdf:type ; sh:hasValue voc:Human ; ] ) ] .

vocsh:Human
    a sh:NodeShape ;
    sh:target [ a dash:AllSubjectsTarget ] ;
    sh:filterShape [
        a sh:Shape ;
        sh:and( [ sh:path rdf:type ; sh:hasValue voc:Character ; ][ sh:path rdf:type ; sh:hasValue voc:Human ; ] ) ] ;
    sh:property [
        sh:path voc:height ;
        sh:maxCount 1 ;
        sh:datatype xsd:decimal ;
    ] ;
    sh:property [
        sh:path voc:mass ;
        sh:maxCount 1 ;
        sh:datatype xsd:decimal ;
    ] .

vocsh:PlanetRef
    a sh:NodeShape ;
    sh:target [ a dash:AllSubjectsTarget ] ;
    sh:filterShape [
        a sh:Shape ;
        sh:path rdf:type ; sh:hasValue voc:Planet ;  ] .

vocsh:Planet
    a sh:NodeShape ;
    sh:target [ a dash:AllSubjectsTarget ] ;
    sh:filterShape [
        a sh:Shape ;
        sh:path rdf:type ; sh:hasValue voc:Planet ;  ] ;
    sh:property [
        sh:path voc:name ;
        sh:maxCount 1 ;
        sh:minCount 1 ;
        sh:datatype xsd:string ;
    ] .

Validation Process¶

Upon performing a mutation on a SHACL-enabled repository, the complete workflow of the Semantic Objects is as follows:

1. Perform semantic validation on the mutation at the service level - ensure all mandatory fields have values, no cardinalities are violated within the mutation and scalar types are correct.
2. Perform dynamic validation on the mutation by running queries against the database - validate ID existence and type correspondence.
3. Commit the transaction to the database.
4. Perform static validation on the mutation at the database level - validate cardinality, pattern, value and range.
5. If the transaction fails with a validation error, roll it back and parse the issue.
6. Query the SHACL schema in the database to fetch expected values and constraints.
7. Convert the parsed validation report and emit it as GraphQL-formatted errors.