SchematronAdmin

Date	14-03-2014	Contacts	Jesse Eichar
Status	Complete	Release	2.12
Resources	Available	Ticket #	https://github.com/geonetwork/core-geonetwork/issues/421
Source code	https://github.com/jesseeichar/core-geonetwork/tree/feature/schematron-admin-refactored-ui
Funding	Swisstopo

Overview

Schematrons are a Geonetwork tool used to verify that a metadata satisfies certain criteria. For example, the iso19139 inspire schematron checks that a metadata satisfies all the criteria required to be inspire compliant.

In the current implementation, a schematron is added by adding the 'sch' file to a schema plugin's schematron folder. All schematrons in the schematron folder will be ran on each metadata (of the correct schema) to determine if the metadata is valid.

This proposal intends to enrich this behaviour in the following ways.

Selective Schematron Application

This feature allows schematrons to be configured to only run on certain metadata that satisfy certain criteria. For example it may be desirable to require that all metadata of a particular group have French translations in order to be considered valid. This feature would make it possible to have a schematron that is only applied to metadata in the specified group and that checks that the French translation requirement is full filled.

Schematron Recommendations

Currently if a schematron is applied to a metadata and an assertion fails the metadata is considered invalid. This feature would allow schematrons to be considered recommendations and the schematron failures would show up in the schematron report as warnings but not failures and the metadata could still be valid. (assuming the other schematron pass)

Schematron admin page

The support these news features an administrative page will be created allowing an administrator to configure the schematrons application criteria and importance.

Schematron title translations

Currently the translations for the schematron rules are in the schematron plugin loc directory in a file with the same name as the schematron name. However the title is not there. This will be changed so that if there is a element in the translations file called schematron.title it will be used in the UI as the title of the schematron. In this way there can be a translation for each language.

Technical Details:

Definitions

Schematron

A set of rules (defined in a .sch file) that can be ran against a metadata to determine if the metadata satisfies those rules and provide advice to fix the errors. Schematrons are declared in the schema plugin's schematron folder.

Schematron Criteria Group

A set of criteria that must all apply for the schematron to be ran against the metadata. A schematron can have multiple rules only one of which has to apply for the schematron to apply to the metadata. You can think of a logical OR, where the criteria in a group must all apply (logical AND).

Schematron Criteria

A rule for determining if a schematron should be applied to a metadata. For example the criteria might be: groupowner == 2. Therefore the criteria will "accept" any metadata that is owned by group 2.

Schematron Application Example

Consider the case where you have a set of custom rules that should apply to a metadata under certain conditions:

If the metadata is part of group 1 it should be not cause the metadata to be invalid but the rules should be applied.
If the metadata contains the keyword "customMetadata" and is part of group 1 then the rules MUST be passed for the metadata to be considered valid.

In order to satisfy these requirements the administrator would create 2 criteria groups.

A group with 1 criteria (group == 1) and the group would have its requirement set to REPORT_ONLY
A group with 2 criteria (group == 1) and (keyword == "customMetadata") and the group would have its requirement set to REQUIRED.

Implementation

Three new tables will be created to sort this feature. A table containing the list of schematrons, a table containing the criteria groups and a table containing the criteria that make up the criteria groups.

A schematron will be applied during validation if the following are true:

The schema of the schematron is the same as the metadata
All the criteria of at least one of the criteria groups are true when evaluated against the metadata.

Each schematron group had a requirement level (SchematronRequirement) which has three values:

Required
Report only
Disabled

Once a schematron is determined to apply to a particular metadata, the requirement level is determined based on the group with the highest requirement. (required is the highest level) Upon start-up the schematrons folder of each schema plugin is scanned and any schematrons not currently in the database will be added to the database. A default requirement level can be chosen by having the requirement name at the end of the schematron rule name. For example:

schematron-rule-mine-REPORT_ONLY.sch will have a requirement level of Report only (the name can be lower-upper, case in the name is unimportant)
schematron-rule-mine-DISABLED.sch will be disabled by default and can be enabled via the admin UI.

Admin UI

The Schematron Administration UI is under the Metadata section of the Administration UI that allows an administrator to configure the Schematron criteria, groups and the order the schematrons reports will appear in the validation UI.

Schematron Administration UI

Criteria Types

When editing a Schematron Criteria Group in the Admin UI you can add criteria.

A criteria is composed of 4 pieces of information:

type - one of the values in the SchematronCriteriaType enumeration. This Type object contains the logic for determining acceptance.
value - a string that is interpreted by SchematronCriteriaType when evaluating if the metadata is acceptable to the criteria.
uitype - a higher-level type value which corresponds to one of the criteria types defined in the criteria-types.xml file in the schema plugins file (see below).
uivalue - the higher-level value which is used by uitype to create a "type" object and "value" object.

The UI contains a "type" combo box. There are always the options: Always accept and XPath.

The other options (keyword, group) are defined in the schema plugin file called criteria-types.xml. These are considered "ui" types because they provide a high-level interpretation of a criteria that is more understandable to the user. For example a "keyword" criteria is actually a simplification of an XPATH criteria. So instead of showing a user a long and confusing XPATH (or even worse, making them write an xpath) the user is show a keyword and expected value.

The UIType can be converted to a "Type" and value from the information in the criteria-types.xml file. In addition to providing a method for converting the UIType and UIValue to Type and Value there are other declarations that allow the UI to provide type-ahead assistance when the user enters data into the criteria value box.

The keyword criteria definition provides the URL for making keyword search queries and a function for parsing the response.
The group criteria definition provides a URL for downloading all the groups and how to interpret those results for the type-ahead assistance.

For those examples in full view the criteria-types.xml file in the iso19139 schema plugin.

The last component is the translations file in the schema plugin loc folder. The file is also called criteria-types.xml and is used to provide a translation for the criteria types label that appears the the Admin UI criteria type combo box.

Metadata Editor

The Validation section in the new AngularJS Metadata Editor has been modified so that there are 3 types of reports. Error, Pass, Warning.

Schematrons with errors that are REQUIRED will have a red error count label and its error text will be red.
Schematrons with no errors will have a green error count label and the passing rules will be black.
Schematrons with errors that are REPORT_ONLY will have a blue error count label and its error text will be blue.

The REPORT_ONLY schematrons will always be after the REQUIRED schematrons so that the important rules are surfaced more readily.

Otherwise, the order that the schematron reports are shown will be the same order as defined in the Administration UI.