Entity Graph Constraint Language

Living Standard,

This version:
https://open.mimiro.io/specifications/entity-graph-data-model
Editor:

Abstract

Specification for entity graph constraint language. A data model and validation semantics for constraining instances of the Entity Graph Data Model.

1. 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.

2. Bootstrapping

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

2.1. 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"

2.2. 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.

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

2.3. Entity Class

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

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

2.4. 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.

{
    "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"
    }        
}

2.5. SubClass Relationship Entailment

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

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.

3. Validation Semantics

Validation of a entity model instance is formally defined as:

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.

3.1. Validation Semantics Helper Functions

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

3.1.1. 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.

3.1.2. 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.

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

3.1.3. Length

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

let arraylength = len(property_value_array)

3.1.4. Id

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

let entityid = id(e)

3.1.5. 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/).

let datatype = property_datatype(value)

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

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

4. 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.

5. Constraint Classes

5.1. 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 model representation of this constraint is as follows and indicates placeholders that are used in the formal semantics when validating.

{
    "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.

// 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)

5.2. 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:

{
    "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.

// 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)
}

5.3. 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:

{
    "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.

// 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)
}

5.4. 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:

{
    "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.

// 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)
        }
    }
}

5.5. 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:

{
    "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.

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

5.6. 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:

{
    "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.

6. Compliance

TODO

7. References

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

Conformance

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Note, this is an informative note.

References

Normative References

[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://datatracker.ietf.org/doc/html/rfc2119