Custom Forms Management

The need to go beyond ontology-driven modeling

The editing capabilities of ontology editors are usually...ontology-driven. That is, data-entry forms are painted on the screen, and options for filling them are provided, by analyzing the axioms defined in the ontology vocabularies loaded in the dataset being managed, including both the W3C basic modeling vocabularies (RDF, RDFS, OWL, SKOS, SKOS-XL) and domain-specific ones. However, a purely ontology-driven approach has some limitations.

One typical limitation is the lack of axioms on annotation properties. The range of some properties is known "de facto", such as the use of language literals for RDFS and SKOS labeling properties, or rdfs:Resource in the case of rdfs:seeAlso, but no axiom is stating this information. We have solved this in previous versions of Semantic Turkey by introducing some hard-wired ranges in the system, taking precedence over the analysis of available axioms.

Yet, in many scenarios, users would benefit from a greater level of customization when valueing properties, as some objects only make sense when built according to well-known templates. For instance, a general-purpose RDF editor, would prompt the user with the possibility to select an existing skosxl:Label when valuing the skosxl:preLabel property, or to create a new one. However, a skosxl:Label instance only makes sense if a skosxl:literalForm is provided for it. Hence, a pattern with the mandatory skosxl:prefLabel --> skosxl:literalForm should be specified somehow. This is not limited to creation, but also to viewing: indeed, such kind of objects only makes sense if, in a view of the resource described by them, the skosxl:literalform linked to the skosxl:Label is explicitly shown, and not the URI/bnode describing it. Again, we have solved such typical cases with built-in solutions tailored over notable vocabularies (such is the case of SKOS-XL). However, we felt the need for giving users the possibility to tailor the UI of Semantic Turkey to their specific needs.

User-Customizable Forms

Custom Forms are a flexible data-driven form definition mechanism that we devised for VocBench, allowing users to perform a declarative specification of the key elements that concur to the creation of a complex RDF resource. In particular, custom forms rely on the combination of the following four key elements:

Custom Ranges have been implemented in VocBench through a (rather unhortodox :-) ) use of CODA, the UIMA-based framework for Unstructured Information Acquisition, Management and RDF-Triplification. In UIMA, information acquired from unstructured content is processed and stored inside feature structures that can be later retrieved and stored into a target repository according to different technologies and models. CODA extends UIMA by focusing on the triplification of UIMA feature structures. CODA provides a highly-expressive transformation language, PEARL, thought specifically for transforming feature-structures into RDF graphs.

The implementation of Custom Ranges in VocBench exploits all the power of PEARL, to build forms by means of UIMA feature structures. User-defined feature structures are parsed by VB and used to create a form for filling their content. The rest of the PEARL rule describes how the user prompted content is converted into RDF nodes and then composed into an RDF graph

The construction of new resources in VB through Custom Forms is managed through two solutions:

Data Architecture

In this section we describe the components realizing the data architecture of Custom Ranges in ST.

The PEARL rule defining the templates for these structured objects is embedded into an XML file called Custom Range Entry (see figure below). The binding between an entry and each specific property is defined in another XML file, called Custom Range. In the next section, we will see how to create these files in Semantic Turkey.

Custom Range concept

Usage: the Custom Form Management Page

To configure Custom Forms, a management page is accessible through the VocBench Tools menu.

Custom Forms Page

The panel is composed of three main sections:

The Custom Form section lists available custom forms. The greyed ones are factory-provided custom forms that cannot be altered, yet their content can be inspected (in order to use them as examples), or they can be adopted as-is.

The following action buttons are available for interacting with the listed forms and for cresating new ones:

Created custom forms are project-local. If users want to reuse a custom form across different projects, they can export them from a project and reimport them into a new project.

A click on the create button produces the following form for describing a Custom Form:

Custom Forms Page

Here follows a description of the fields in the form:

Editing Custom Forms

As anticipated earlier, Custom Forms are defined by specifying a PEARL document, declaring a set of RDF nodes that are created from a set feature structures. In fact, the node section of the CODA rule determines the fields that will compose the form. The graph section will then specify how these nodes are arranged into an RDF graph.

Custom Forms Editing

Let's explain how it works with an example, by considering the nodes and graph sections of the Form in the previous picture:

		...
nodes = {
    reifNoteId uri(coda:randIdGen["note", {}]) .
    noteLit literal userPrompt/note .
    source literal userPrompt/source .
    related uri userPrompt/related .
    modified literal^^xsd:datetime userPrompt/modified .
    created literal(coda:datetime["yyyy-MM-dd"]) .
}
graph = {
    $reifNoteId rdf:value $noteLit .
    OPTIONAL { $reifNoteId dc:related $related . }
    OPTIONAL { $reifNoteId dc:source $source . }
    OPTIONAL { $reifNoteId dc:modified $modified . }
    $reifNoteId dc:created $created.
}
...		
	

The nodes section is composed of various lines, each with three elements:

In the graph section, the placeholders for the created ndoes are then used to assemble the description of the resource created through the form. The CODA placeholders that appears in OPTIONAL block in this section will be optional in the input form too. So, in this case, there will be five fields: note, source, related, modified and created and only the first will be mandatory.

Note that the refiedNoteId and the created nodes are not created by transforming some user input, as the userPrompt element is missing from their rows. This means that these elements will be generated from scratch, as some converters are actually generators able to create new RDF nodes on the sole basis of some configuration (e.g. the coda:dateTiem converter generates the representation for the current date and time when not dateTime expression is passed as the third argument of the node declaration).

The Form Editor supports syntax highlighting, though it does not currently provide syntax completion. A syntax helper for the converters has however been provided, in the form of a converter picker, that lists all the available converters already loaded into the system, their possible invocation signatures (converters supports invocation overloading) and copying their syntaxes on the editing textarea, as shown in figure below:

Custom Forms Page

For each converter, it is possible to select the proper signatureby clicking on the pencil symbol besides the signature textfield, showing a chooser window like in figure below

Custom Forms Page

Overlaying Default Forms

Skos concepts, schemes, collections, etc.. all these kind of resources share default forms that expose advanced editing characteristics that cannot be (currently) represented through custom forms and that, in any case, should not be overridden by them. For instance, the concept creation form shows a list of schemes that will be associated to the new concept: this list. though editable, is defaulted to all schemes inherited from its parent concept (the one on which the "create child concept" action has been performed). Clearly this particular behavior *should* always be part of the concept creation form. In order to keep the peculiar characteristic of each resource's form, and yet to allow for a certain degree of customization, custom form adopt an overlaying mechanism in which the basic structure of known-resources' forms is kept, and the additional specification of a custom constructor is added to it.

In such overlaid custom forms, some of the information that is produced by the default part of the form could be necessary for computing some aspects of the custom part. E.g. the localname of a concept could be reused in the node section of the custom form, in order to create another resource connected to the concept whose URI is similar to the one of the concept. In order to support this possibility, all default forms fields are also mapped as

In the following figure, an editor opened on a new form cloned from the basic factory-based template for extending default forms

Custom Forms Page

Custom Form in action: customizing the reifiedNote CustomForm

In this section we learn how to reuse an existing custom form and to modify it for our own purposes. We will customize the "reified note" custom form.

A reified note is a skos:note modeled after the second pattern described in advanced documentation of the SKOS Primer, that is an RDF resource described in turn by other properties, the main one being rdf:value and having as object the literal content of the note. The basic reified note available with the standard installation of the system contains only the basic reification pattern:
<resource being described> --> skos:note --> <resource representing the note> --> rdf:value --> <the literal value of the note>
What we wil do in this section is to create our own version of the note and to add to it a few more metadata properties.

In order to create and use a new Custom Form, it is necessary to:

If a Custom Form and Form Collection are already available, the only step to be performed is the third and last one, which is the one we are going to show in the next section, before diving into the more elaborated aspects of customization.

Mapping a Custom Form

In order to associate an existing custom form, available in an existing Custom Collection, we need to associate this last element to a resource. The Form Collections can be managed from the top-right panel of the Custom Forms Management page.

A Form Collection consists of the following:

As shown in the following image, the factory-provided Form Collection for the reified notes is composed by only one Custom Form (it.uniroma2.art.semanticturkey.customform.form.reifiednote) and according to the suggestions, it is advisable to use it with the skos note properties (skos:note and its sub-properties).

Custom Collection editor

The Form Collection needs thus to be mapped to a resource: property or class. This operation can be performed through the bottom panel, which allows for creation/deletion of such mappings.

When creating a new mapping, if the Form Collection that is going to be mapped has suggested classes or properties declared, the UI offers the possibility to exploit these suggestions.

A mapping to a class generates a "Custom Constructor". When an instance of that class is being created, the form is layered on top of the original form for creating instances of that class.

A mapping to a property generated a "Custom Range", that is, whenever that property is going to be valued, the Custom Form will be presented as an alternative to the usual range. In the case of Custom Ranges an additional option allows to "replace" the ordinary range (i.e. the range expressed by the owl:range property or derived by inference), thus directly prompting the user with the Custom Form.

Form Mapping editor

In the image below, the note Collection has been associated to the skos:note property and the "Replace" option has not been ticked.

Form Mapping panel

The Custom Form (in this specific case a Custom Range) is now ready to be used. After valuing the skos:note property (on any resource), a dialog for selecting the range type is shown. All the Custom Ranges contained in the Form Collection are listed among the available ranges (like we said, this step would have been skipped if the replace flag had been checked).

In this case the only CustomRange defined in the FormCollection is Reified note.

CustomRange range selection

Once the Reified note element has been selected, the Custom Form is prompted to the user.

CustomRange form

After filling the Custom Form, the prompted data has been added to the dataset and it is visible in the Resource View. The basic value shown is determined by the Show Property chain field of the Custom Form editor (we will see it in the next section when creating a new Custom Form). The preview can also be expanded, showing other values that characterized the Custom Form (in this case, only the literal value of the reified note was present in the Custom Form so this is the only element being show in the expanded preview).

CustomForm in ResourceView

Customizing the Custom Form fields

As stated before, the Custom Forms mechanism was designed to allow the user to tailor the UI of Semantic Turkey to their specific needs. With the following example, it will be shown how to extend the factory-provided reifiednote Custom Form in order to add a further field.
By first, since the new form will be based on the existing one for refied notes, it is advisable not to start from scratch, rather to clone the original one. This can be done by selecting the original form and clicking on the "clone" button on the Custom Forms panel. As a start, the only information that needs to be prompted is the ID for the new Form.

Note that all forms have an ID characterized by a namespace and a localname. By default, a namespace is provided (the one of semanticturkey, the backed system of VocBench), to allow users simply prompting a local name. However, by clicking on the lock button, it is possible to change the full name of the form.

Clone CustomForm

After creating the form, it is possible to edit its characteristics through the PEARL editor: the name, the description and the PEARL reference that will determine the prompted form.

The addenda to the original PEARL are highlighted in the previous image:

Now, as already shown for the standard reified note, it is necessary to add this new Custom Form to a Form Collection. Since it is not possible to edit the factory-provided it.uniroma2.art.semanticturkey.customform.collection.note collection, it is necessary to create a new one or simply to clone the latter and add the new created CF.

After mapping this new collection to skos:note, the new custom form will be added to the range of possible values

...and then, the new form can be filled.

The resulting preview (the set of properties shown when a target node is expanded in the resource view) of the reified note will be the following, thus showing also the source element

PEARL annotations

From version 8.0.0, Custom Forms have been enhanced with the introduction of PEARL annotations. By annotating a node declaration it could be possible to add semantic to the same node and this will be reflected on the produced Form. For instance it could be possible to state that a node can take only values x, y or z, or that it can only be an instance of a certain class, or even that it must be a resource taken from a specific external project.

The available annotations are:

For each of them we will see how they can be used and how they affect the Form. Combination of these annotations are allowed. For example Foreign can be combined with Range in order to constrain the selection from an external project of the instance of a given class, or again Collection with Role in order to allows the selection of multiple resources of a type.

In the examples that will follow the annotations will be tested by customizing the factory-provided Custom Form for reified note.

Collection

This annotation allows for prompting more values for the same element. It takes two optional numeric arguments: min and max (if not provided their value is assumed to be 0). Value 0 for min means that it is not necessary to provide at least one value, namely the form field will be optional. Value 0 for max means there’s no limit restriction on the number of values to create.

Now, let's extend the reifiednote Custom Form PEARL as follow (changes in yellow):

      
    rule it.uniroma2.art.semanticturkey.customform.form.reifiedNoteExt id:reifiednote {
      nodes = {
        reifNoteId uri(coda:randIdGen("note", {})) .
        noteLang literal userPrompt/lang .
        noteLit literal(coda:langString($noteLang)) userPrompt/note .
        @Collection(min = 2, max = 4)
        listNode uri userPrompt/list .
      }
      graph = {
        $reifNoteId rdf:value $noteLit .
        OPTIONAL { $reifNoteId rdfs:comment $listNode . }
      }
    }
      
    

As it is highlighted, it has been added a new listNode node annotated with @Collection. This will be reflected in a new list field in the form. The annotation here determines that the field will allow multiple values, precisely from 2 to 4 values. Then these values will be linked to the reified note through the rdfs:comment property (for illustration purpose only). Side note: rdfs prefix is not declared in the original reified note Custom Form, it has to be manually added.

The resulting Form is the following

The list field has initially two textfields which allow the selection of IRI resources. The "trashbin" buttons are disabled since the minimum declared by the annotation is 2. It is possible to add up to 4 further elements to the list (through the plus button), then the add button will be disabled.

If confirmed, the result of this addition is the following:

DataOneOf

This annotation declares a set of possible literal values that can be assigned to the related node. The Custom Form can be changed as follow

      
    rule it.uniroma2.art.semanticturkey.customform.form.reifiedNoteExt id:reifiednote {
      nodes = {
        reifNoteId uri(coda:randIdGen("note", {})) .
        noteLang literal userPrompt/lang .
        noteLit literal(coda:langString($noteLang)) userPrompt/note .
        @DataOneOf({ "example"@en, "esempio"@it, "ejemplo"@es })
        dataOneOfNode literal userPrompt/dataOneOf .
      }
      graph = {
        $reifNoteId rdf:value $noteLit .
        OPTIONAL { $reifNoteId rdfs:comment $dataOneOfNode . }
      }
    }
      
    

Here it has been added a new dataOneOfNode node annotated with @DataOneOf. This determines that the new dataOneOfNode field will accept only the values specified as argument. As in the previous case, the value will be linked to the reified note through the rdfs:comment property.

The resulting Form is the following

And once submitted it will produce the following

Foreign

Foreign annotation constrains the selection of a resource value from an external project (hosted on VB). The argument of this annotation is the ID of a project.

      
    rule it.uniroma2.art.semanticturkey.customform.form.reifiedNoteExt id:reifiednote {
      nodes = {
        reifNoteId uri(coda:randIdGen("note", {})) .
        noteLang literal userPrompt/lang .
        noteLit literal(coda:langString($noteLang)) userPrompt/note .
        @Foreign("TestProject")
        foreignNode uri userPrompt/foreign .
      }
      graph = {
        $reifNoteId rdf:value $noteLit .
        OPTIONAL { $reifNoteId rdfs:comment $foreignNode . }
      }
    }
      
    

A foreignNode node has been annotated with @Foreign with argument TestProject. This will add in the form a new dataOneOfNode field allowing the selection of a resource from the target project TestProject. Obviously in order to works, the ID of the project must identify an existing project, moreover the target project must grant access to the source project (see documentation about ACL).

As shown in the following image, next to the dataOneOfNode field a button with an arrows (in place of the usual "pencil") suggests that the value will be picked from an external source.

Once clicked, the selection of the project is prompted, then user needs to choose the type of picked resource and finally he can browse the desired tree/list.

Finally, the submission of the form will produce the following. You can see the namespace http://test.project# of the foreign value that is indeed the one of the external project.

ObjectOneOf

This annotation is very similar to DataOneOf previously seen. In fact it declares a set of possible IRI values that can be assigned to the related node. Custom Form pearl could be changed as follow.

      
    rule it.uniroma2.art.semanticturkey.customform.form.reifiedNoteExt id:reifiednote {
      nodes = {
        reifNoteId uri(coda:randIdGen("note", {})) .
        noteLang literal userPrompt/lang .
        noteLit literal(coda:langString($noteLang)) userPrompt/note .
        @ObjectOneOf({ skos:ConceptScheme, <http://www.w3.org/2004/02/skos/core#Concept> })
        objOneOfNode uri userPrompt/objOneOf .
      }
      graph = {
        $reifNoteId rdf:value $noteLit .
        OPTIONAL { $reifNoteId rdfs:comment $objOneOfNode . }
      }
    }
      
    

The objOneOfNode node, annotated with @ObjectOneOf will add in the form a field objOneOf that through a combobox allows the selection of the only values provided as annotation argument. As shown in the previous PEARL code, arguments of the annotation can be both IRI and qname (in case of qname the prefix must be declared in the PEARL).

The added reified note will be rendered as follow

Range

This annotation describes the class that is meant to be used for feeding potential values to the annotated node. Its argument must be an IRI (or qname) that identifies a class.

      
    rule it.uniroma2.art.semanticturkey.customform.form.reifiedNoteExt id:reifiednote {
      nodes = {
        reifNoteId uri(coda:randIdGen("note", {})) .
        noteLang literal userPrompt/lang .
        noteLit literal(coda:langString($noteLang)) userPrompt/note .
        @Range( skos:ConceptScheme )
        rangeNode uri userPrompt/range .
      }
      graph = {
        $reifNoteId rdf:value $noteLit .
        OPTIONAL { $reifNoteId rdfs:comment $rangeNode . }
      }
    }
      
    

The above is an example of how the annotation can be used in order to constrain the selection of values to the only instances of skos:ConceptScheme class.

In this way the picker of the range field opens a browsing modal allowing the selection of any instances of skos:ConceptScheme class, both from current and external project.

RangeList

This annotation is the extension of the previous with the only difference that can specify multiple classes as argument (e.g. @RangeList( { skos:ConceptScheme, skos:Concept } )) and the browsing modal allows the selection of their instances.

Role

This annotation constrain the role(s) that a certain node may assume. The only argument represents a list of string among those available in SemanticTurkey.

Assuming you want to restrict the selection to concepts, schemes or collections, the PEARL rule can be modified as follow

      
    rule it.uniroma2.art.semanticturkey.customform.form.reifiedNoteExt id:reifiednote {
      nodes = {
          reifNoteId uri(coda:randIdGen("note", {})) .
        noteLang literal userPrompt/lang .
        noteLit literal(coda:langString($noteLang)) userPrompt/note .
        @Role({'concept', 'conceptScheme', 'skosCollection'})
        roleNode uri userPrompt/role .
      }
      graph = {
        $reifNoteId rdf:value $noteLit .
        OPTIONAL { $reifNoteId rdfs:comment $roleNode . }
      }
    }
      
    

By doing that, the usual resource picker placed next to the form field (that in this case will be labeled with role) will prompt a modal for selecting the type of resource among those specified as annotation argument.