Definition of constraint ecore annotations schema for model validation purposes.

## Package Specification

This package defines special ecore annotations for use in GMF models validation. These annotation forms the client API GMF Validation framework which can be involved in validation by using {@link org.eclipse.papyrus.gmf.validate.GMFValidator}. This class follows the standard EMF validator contract and its {@link org.eclipse.papyrus.gmf.validate.GMFValidator#validate validate} operation can be either called directly on a model element or it can be registered as a standard {@link org.eclipse.emf.ecore.EValidator} in {@link org.eclipse.emf.ecore.EValidator.Registry} for a desired ecore package `nsURI`. Both approaches involve constraint annotations defined in validated element's ecore meta-model while only the latter one ensures that these constraints get involved in the standard EMF validation using {@link org.eclipse.emf.ecore.util.Diagnostician} class.

### Constraint annotations

GMF Validation introduces special constraint annotations enabling the use of boolean type expressions further restricting the model contents, usually complementing or refining standard EMF constraints. The usage on exemplary use-case and semantics of GMF constraint annotations is demonstrated in the example bellow using an ecore model fragment in `Emfatic` notation.

    @EmfaticAnnotationMap(constraints="http://www.eclipse.org/gmf/2005/constraints")

    @constraints(
    	ocl="birthDate <> null && hireDate <> null implies birthDate <= hireDate",
    	severity="warning",
    	description="An unborn person ''{0}'' was hired!!!"
    )
    // additional "Person" constraints go here ...
    class Person {
    	@constraints(
    		ocl="nick <> null imlies nick.size() < 5",
    		description="The ''{0}'' nick name is too long"
    	)
    	// additional constraints related to "nick" go here ...
    	attr String[1] nick;
    	attr String[1] name;
    	attr Date[1] birthDate;
    	attr Date hireDate;
    }

The constraint on `Person` class complements the EMF cardinality constraint on `birthDate` which is guarded by the basic EMF validator but is also dependent on `hireDate` existence. Therefore the OCL expression parsed in the context of `Person` checks whether both are defined and only then it enforce the restriction based on their comparison. Another common example of EMF complementing constraints could a be mutual exclusion rules for related structural features. The `Person::nick` feature's constraint refines the required constraint on `nick` by restricting the length of its string value. The corresponding OCL expression is defined again in the context of `Person` class. Note: Both constraints mentioned above are parsed in the context of `Person` as it is the only valid OCL expression context `[oclIsKindOf(EClassifier)]` in the nearest outer-scope. The structuring used in the example is purely based on the logical scope of the restrictions. For instance, the rule for `birthDate`, `hireDate` involves both attributes, thus is rather consider class-wide. The is mainly because of the clarity aspect, but could be also helpful when removing ecore elements involved in GMF constraints. However, the broken annotations are detected and reported by `GMFValidator`.

#### Annotation Semantics

GMF constraints are defined as EAnnotation elements with `source=http://www.eclipse.org/gmf/2005/constraints`. and attached either to `EClass` or its `EStructuralFeature`, in which case the containing EClass is allways the context for OCL expressions evaluation. Constraint annotations details (key : value) is listed bellow.

- ocl : OCL expression defined in the context of the nearest outer EClass. The expression must produce result of `Boolean` type, otherwise is considered invalid.
- description : Optional textual description providing additional info and used as the message when constraint is violated. The text can follow `java.text.MessageFormat` pattern and use {0} argument, which in runtime corresponds to the validated model element.
- severity : Optional severity level of the constraint. Accepted values: `error, warn, info`. If not specified, the default `error` is applied.

The contextual instance that violates some constraints during validation is allways the source object encoded in the data of {@link org.eclipse.emf.common.util.Diagnostic} object resulting from validation.

GMF constraints are inheritable. Once a constraint is defined in the context of EClass instance, all sub-classes of this class are restricted as well. So it's possible to add the most common constraints to super-class and spread the specializing constraints to particular sub-classes.

In some cases in OCL, the user might need to reference a classifier from a meta-model, which is not loaded automatically if the validated model has no references this meta-model's elements. By default, OCL implementation performs classifier lookup in the global `EPackage.Registry`. Only initialized packages are involved in the lookup, those whose instances are put to the registry instead of `EPackage.Descriptor`. For instance, there might be an `OCL` constraint like `self.oclIsKindOf(model::Foo)` while there is no reference to `model::Foo` in the validated model. If the model has not been initialized in the registrey yet, the `OCL` will report an error on uknown classifier. To solve this issue, an import annotation can be used, `source=http://www.eclipse.org/gmf/2005/constraints` Import annotations details (key : value) is listed bellow.

- import : nsURI of the meta-model to be imported.

The import annotation is to be located in the EPackage element of the annotated ecore model. This enables the imported classifiers in the OCL environments of all constraint annotation attached to the package contained ecore elements. For instance, the annotation below ensures access to the runtime diagram notation meta-model.

    @constraints("import"="http://www.eclipse.org/gmf/runtime/1.0.0/notation")