entity-graph-constraint-language.bs

<pre class='metadata'>
Title: Entity Graph Constraint Language
Shortname: uda
Level: 1
Status: LS
URL: https://open.mimiro.io/specifications/entity-graph-data-model
Editor: Graham Moore, graham.moore @ mimiro.no
Repository: https://github.com/mimiro-io/universal-data-api-specification, Specification Repository
Abstract: Specification for entity graph constraint language. A data model and validation semantics for constraining instances of the Entity Graph Data Model.
Boilerplate: copyright no
</pre>


# Entity Graph Constraint Language

The Entity Graph Constraint Language is a vocabulary for expressing constraints over instances of the Entity Graph Data Model [1]. The constraints are defined as number of constraint classes, and along with each constraint class are formal validation semantics. The validation of constraints is defined in terms of the formal semantics and the result of validation is a set of violation entities that are instances of the constraint violation class. To aid in describing the validation semantics a number of logical functions are defined along with a number of base identifiers. These base identifiers are used to bootstrap the type system. 

# Bootstrapping

To bootstrap the constraint classes and the evaluation semantics the following base formalisms and identifiers are defined.

## The EGCL Base Namespace

All constraint classes and the data model that comprises the constraints are defined using the entity graph data model. A key element of that is the use of URIs to denote things.

The base URI from which all other EGCL identifiers are derived is defined as follows:

`http://data.mimiro.io/egcl/`

In this document in cases where an entity data model context is not defined the prefix:

`egcl:`

Should be considered as the namespace prefix that expands to the base URI `http://data.mimiro.io/egcl/`.

As an example:

```
"rdf:type" : "egcl:EntityClass"
```

Would be expanded to:

```
"rdf:type" : "http://data.mimiro.io/egcl/EntityClass"
```


## The Type Relationship

An Entity can have relationships to other entities. These relationships are typed. To indicate that one entity is an instance of a class the `rdf:type` relationship MUST be used. 

The following example shows an entity connected to its EntityType via the `rdf:type`reference type.

```json
{
    "id" : "http://example.org/people/bob",
    "refs" : {
        "rdf:type" : "http://example.org/schema/Person"
    }        
}
```

## Entity Class

To indicate that an entity is an Entity Class then it MUST have an `rdf:type` reference whose value is `egcl:EntityClass` .

```json
{
    "id" : "http://example.org/schema/Person",
    "refs" : {
        "rdf:type" : "egcl:EntityClass"
    }        
}
```

## SubClass Relationship

To convey that an EntityClass is a subclass of another entity class the relationship type `egcl:subClassOf` must be used.

The following example shows how to express that the `Person` class is a subclass of the `Thing` class.

```json
{
    "id" : "http://example.org/schema/Thing",
    "refs" : {
        "rdf:type" : "egcl:EntityClass"
    }        
}
,
{
    "id" : "http://example.org/schema/Person",
    "refs" : {
        "rdf:type" : "egcl:EntityClass",
        "egcl:subClassOf" : "http://example.org/schema/Thing"
    }        
}
```

## SubClass Relationship Entailment

The `subClassOf` relationship described above is transitive in nature. Such that if:

```ebnf
a rdf:type B 

and

B egcl:subClassOf C

it follows (or is entailed) that:

a rdf:type C is also true.
```

This means that constraints defined as applying to any super class also apply to any instance of subclasses.

# Validation Semantics

Validation of a entity model instance is formally defined as:

```ebnf
Given:

i := entity model instance
c := constraint model instance
v := validation function
r := validation result

such that

v(i,c) => r
```

Such that given a constraint model instance and an entity model instance applying the validation rules associated with each constraint type yields a validation result. The validation result reports violations in the entity model instance.   

## Validation Semantics Helper Functions

To support expressing validation semantics a small number of functions with clear semantics are introduced. 

### Hop

The `hop` function is used to traverse the entity graph. It takes the URI of a starting entity, the URI of the reference type to follow and an optional parameter to indicate if the traversal should be inverse. The result of the `hop` function returns a list of Entities.

### Properties

The properties function takes an entity and the URI of a property type and returns an array of values corresponding to the values of that property residing on the entity.

The following example would return the list of values assigned to the `schema:name` property of the entity `e`. If the entity only has a single value for the specified property then that value is returned as the only value in the array.

If there are no properties that match the property type provided then the function returns an array of length 0.

```javascript
let namepropvalues = properties(e, "schema:name")
```

### Length

The `len` function takes an array as a parameter and returns the number of elements in the array.

```javascript
let arraylength = len(property_value_array)
```

### Id

The `id` function takes an entity as a parameter and returns the URI of the entity.

```javascript
let entityid = id(e)
```

### Property DataType

The property data type function returns the data type from a property value. The values returned are as defined by the URIs for XML built in primitive datatypes (https://www.w3.org/TR/2004/REC-xmlschema-2-20041028/).

```javascript
let datatype = property_datatype(value)
```

Based on XML primitive datatypes the result will be a URI of one of the following:

```json
http://www.w3.org/2001/XMLSchema#int
http://www.w3.org/2001/XMLSchema#duration
http://www.w3.org/2001/XMLSchema#dateTime
http://www.w3.org/2001/XMLSchema#time
http://www.w3.org/2001/XMLSchema#date
http://www.w3.org/2001/XMLSchema#boolean
http://www.w3.org/2001/XMLSchema#base64Binary
http://www.w3.org/2001/XMLSchema#hexBinary
http://www.w3.org/2001/XMLSchema#float
http://www.w3.org/2001/XMLSchema#double
http://www.w3.org/2001/XMLSchema#decimal
http://www.w3.org/2001/XMLSchema#anyURI
http://www.w3.org/2001/XMLSchema#string
http://www.w3.org/2001/XMLSchema#gYearMonth
http://www.w3.org/2001/XMLSchema#gYear
http://www.w3.org/2001/XMLSchema#gMonthDay
http://www.w3.org/2001/XMLSchema#gDay
http://www.w3.org/2001/XMLSchema#gMonth
```

# Constraint Data Model and Validation Semantics

Each constraint is defined in terms of a data model and an associated validation rule. The validation rule is generic and parameterised. The parameters to the validation rule are retreived from the instance of the constraint data model at run time. Note that the formalism for expressing the constraint is to convey unambiguously the intent of the constraint and not as an implementation specification. 

# Constraint Classes

## IsAbstract Constraint Class

Instances of the `IsAbstract` constraint class are used to indicate that the specified `EntityClass` MUST not have any instanes.

The data model for this constraint defines:
- the entity class that must have no instances.

The entity model representation of this constraint is as follows and indicates placeholders that are used in the formal semantics when validating.

```json
{
    "id" : "schema:constraint-0",
    "refs" : {
        "rdf:type" : "egcl:IsAbstractConstraint",
        "egcl:entityClass" : "$A"
    }
}

```

The formal semantics for this constraint class are defined in terms of the evaluation functions and bind the variable from the constraint instance as a parameter.  

``` javascript
// get the instances of the Entity Class indentified in the constraint instance
let instancesOfClass = hop($A, "rdf:type", true)
let instanceCount = len(instancesOfClass)

assert_true(instanceCount, 0)
```

## Property Constraint

Instances of the `Property Constraint` class are used to ensure that an instance of an Entity Class contains the correct number of the specified properties, and the allowed data type for values of these properties. e.g. that a person must have a name and a date of birth and values of it must be of data type xsd:DateTime.

The data model for this constraint defines:
- the entity class whose instances must meet the constraint
- the property class being constrained
- the min cardinality of properties of the property class that are allowed on an instance
- the max cardinality of properties of the property class that are allowed on an instance
- the required data type of the value of the constrained property

```json
{
    "id" : "schema:constraint-1",
    "refs" : {
        "rdf:type" : "egcl:PropertyConstraint",
        "egcl:entityClass" : "$CLASS",
        "egcl:propertyClass" : "$PROPERTY_CLASS",
        "egcl:datatype" : "$DATA_TYPE"       
    },
    "props" : {
        "egcl:minCard" : "$MIN_CARD",
        "egcl:maxCard" : "$MAX_CARD"
    }
}
```

The formal semantics for this constraint class are defined in terms of the evaluation functions and bind the variable from the constraint instance as parameters.  

``` javascript

// get the instances of the Entity Class indentified in the constraint instance
let instancesOfClass = hop($CLASS, "rdf:type", true)

// for each instance of the specified class get the properties of the specified property class and assert the cardinailty meets the specified values. 
for entityInstance in instancesOfClass {
    let propertiesOfSpecifiedType = properties(entityInstance, $PROPERTY_CLASS)
    let propertiesLength = len(propertiesLength)

    assert_true(propertiesLength >= $MIN_CARD)
    
    assert_true(propertiesLength <= $MAX_CARD)
    
    let dt = property_datatype(value)
    assert_equal(dt, $DATA_TYPE)
}
```

## Reference Constraint

Instances of the `Reference Constraint` class are used to ensure that an instance of an Entity Class contains the correct number of the specified references of a given type. e.g. that a person must have a reference of type `mother` and  constraint the type of the related entity to be `Person`. This constraint can also be used to define the identity of the inverse property type.

The data model for this constraint defines:
- the entity class whose instances must meet the constraint
- the reference class being constrained
- the class of the referenced entity
- the min cardinality of properties of the property class that are allowed on an instance
- the max cardinality of properties of the property class that are allowed on an instance
- the optional oneof list that retricts the set of instances that can be referenced
- the optional inverse reference class
- the optional inverse min cardinality
- the optional inverse max cardinality
 

```json
{
    "id" : "schema:constraint-1",
    "refs" : {
        "rdf:type" : "egcl:ReferenceConstraint",
        "egcl:entityClass" : "$CLASS",
        "egcl:referenceClass" : "$REFERENCE_CLASS",
        "egcl:referencedEntityClass" : "$REFERENCED_ENTITY_CLASS",
        "egcl:inverseReferenceClass" : "$INVERSE_REFERENCE_CLASS"
        "egcl:oneOf" : "$ONE_OF"
    },
    "props" : {
        "egcl:minCard" : "$MIN_CARD",
        "egcl:maxCard" : "$MAX_CARD",
        "egcl:inverseMinCard" : "$INVERSE_MIN_CARD",
        "egcl:inverseMaxCard" : "$INVERSE_MAX_CARD"
    }
}
```

The formal semantics for this constraint class are defined in terms of the evaluation functions and bind the variable from the constraint instance as parameters.  

``` javascript

// get the instances of the Entity Class indentified in the constraint instance
let instancesOfClass = hop($CLASS, "rdf:type", true)

// for each instance of the specified class get the properties of the specified reference class and assert the cardinailty meets the specified values 
for entityInstance in instancesOfClass {
    let references = hop(entityInstance, $REFERENCE_CLASS)
    let referencesLength = len(references)

    assert_true(propertiesLength >= $MIN_CARD)
    assert_true(propertiesLength <= $MAX_CARD)

    // check associated entity has type reference to correct class
    for refvalue in references {
        // get the related entity
        let relatedentity = get_entity(refvalue)

        let entityId = id(relatedentity)
        assert_true(contains($ONE_OF, entityId))

        // get all the classes for the related entity (this is a list of entities)
        let classes = get_classes(relatedentity)

        // get the constraining class that all referenced entities must be an instance of 
        let referenced_class = get_entity($REFERENCED_ENTITY_CLASS)

        // check if the list of classes contains the required constraint class
        let isofclass = contains(classes, referenced_class)

        assert_true(isofclass)
    }
}

// for each instance of the specified referenced class get the referencees and check that the inverse reference cardinality is in the range of the min and max cardinality
let instancesOfReferenceClass = hop($REFERENCED_ENTITY_CLASS, "rdf:type", true)

for entityInstance in instancesOfReferenceClass {
    let inverseReferences = hop(entityInstance, $REFERENCE_CLASS, true)
    let inverseReferencesLength = len(inverseReferences)

    assert_true(inverseReferencesLength >= $INVERSE_MIN_CARD)
    assert_true(inverseReferencesLength <= $INVERSE_MAX_CARD)
}
```

## Property Value Constraint

The property value constraint is used to constrain the value of a property. e.g. that a string value must match some regular expression or that an integer value must be in some range. 

The data model for this constraint defines:
- the (optional) entity class whose instances must meet the constraint
- the property class being constrained
- the (optional) min value allowed
- the (optional) max value allowed
- the (optional) regular expression that the value must match

```json
{
    "id" : "schema:constraint-1",
    "refs" : {
        "rdf:type" : "egcl:PropertyValueConstraint",
        "egcl:entityClass" : "$CLASS",
        "egcl:propertyClass" : "$PROPERTY_CLASS",
    },
    "props" : {
        "egcl:minValue" : "$VALUE_MIN",
        "egcl:maxValue" : "$VALUE_MAX",
        "egcl:regexp"   : "$VALUE_REGEXP"
    }
}
```

The formal semantics for this constraint class are defined in terms of the evaluation functions and bind the variable from the constraint instance as parameters.  

``` javascript

// get the instances of the Entity Class indentified in the constraint instance
let instancesOfClass = hop($CLASS, "rdf:type", true)

// for each instance of the specified class get the properties of the specified property class and assert all values of the constrained property type have a value that meets the value constraints.
for entityInstance in instancesOfClass {
    let propertiesOfSpecifiedType = properties(entityInstance, $PROPERTY_CLASS)
    let propertiesLength = len(propertiesOfSpecifiedType)

    for value in propertiesOfSpecifiedType {
        if ($VALUE_MIN) {
            assert_gteq(value, $VALUE_MIN)
        }

        if ($VALUE_MAX) {
            assert_lteq(value, $VALUE_MAX)
        }

        if ($VALUE_REGEXP) {
            assert_regexp_match(value, $VALUE_REGEXP)
        }
    }
}

```

## Query Constraint

The entity query constraint takes a EGQL (Entity Graph Query Language) expression, evaluates it and assume that any entities returned are in violation of the constraint. NOTE: This is waiting on EQL being finalised but the constraint class can still be defined. 

The data model for this constraint defines:
- the EQL query to be evaluated

```json
{
    "id" : "$CID",
    "refs" : {
        "rdf:type" : "egcl:QueryConstraint"
    },
    "props" : {
        "egcl:query" : "$QUERY"
    }
}
```

The formal semantics for this constraint class are defined in terms of the evaluation functions and bind the variable from the constraint instance as parameters.  

``` javascript

let entities = query($query)
for e in entities {
    new ConstraintViolation($CID, e)
}

```

## Application Constraint

An application constraint class is an application specific non-standardised constraint that is executed by the validation engine and returns instances of type constraint viloation. While of course the actual validation cannot be interchanged the idea is that at least it is described and also allows for extension through the creation of common constraints that are given identity.

The data model for this constraint defines:
- the identifier of the rule to be evaluated

```json
{
    "id" : "$CID",
    "refs" : {
        "rdf:type" : "egcl:ApplicationConstraint",
        "egcl:rule" : "$RULE"
    },
    "props" : {
        "egcl:description" : "$DESCRIPTION"
    }
}
```

The formal semantics for this constraint class are defined such that the system must return evaluate the rule identified by $RULE against an Entity Graph store and return an array of constraint violation instances.

# Compliance

TODO

# References

1. https://open.mimiro.io/specifications/uda/latest.html