This documentation starts with a short practical example by which basic features of ROGER are illustrated. This is followed by two parts in which all available features are explained: First the two shapes types, then the various properties.
Within this document, the following namespace prefix bindings are used:
| Prefix | Namespace |
|---|---|
rdf: |
http://www.w3.org/1999/02/22-rdf-syntax-ns# |
rdfs: |
http://www.w3.org/2000/01/rdf-schema# |
sh: |
http://www.w3.org/ns/shacl#
|
dash: |
http://datashapes.org/dash#
|
xsd: |
http://www.w3.org/2001/XMLSchema# |
ex: |
http://example.com/ns# |
exshapes: |
http://beispiel.de/ns# |
roger: |
https://www.sub.uni-goettingen.de/roger/schema |
In this document, color-coded boxes are used to show RDF-graphs in Turtle. These Turtle-fragments use the prefixes listed above.
# This box represents shapes graphs.
# This box represents data graphs.
# This box represents XML code.This section is non-normative.
On the basis of the following RDFS data model, persons (ex:Person) shall be described. For this purpose, the name (ex:name), gender (ex:gender), GND-ID (ex:gndID) and friendship relations (ex:friend) to other persons shall be described.
ex:Person a rdfs:Class ;
rdfs:label "Person" .
ex:name a rdf:Property ;
rdfs:domain ex:Person ;
rdfs:label "Name" ;
rdfs:range rdfs:Literal .
ex:gender a rdf:Property ;
rdfs:domain ex:Person ;
rdfs:label "Gender" ;
rdfs:range rdfs:Literal .
ex:friend a rdf:Property ;
rdfs:domain ex:Person ;
rdfs:label "Friend" ;
rdfs:range ex:Person .
ex:gndID a rdf:Property ;
rdfs:domain ex:Person ;
rdfs:label "GND-ID" ;
rdfs:range xsd:anyURI .
This section is non-normative.
On the basis of the RDFS data model, the data and the corresponding form fields are described in ROGER: For each class of the RDFS data model with which the instances shall be generated with a form, a unique form is required. The form contains various form fields, which correspond to the properties of the RDFS data model.
The name of a form is generated from the value of rdfs:label
of the respective class from the RDFS data model.
The node shape describing the form for ex:Person:
exshapes:PersonShape
a sh:NodeShape ;
rdfs:label "Person Shape" ;
sh:targetClass ex:Person ;
roger:formNode true ;
sh:property exshapes:nameShape ,
exshapes:genderShape ,
exshapes:friendShape ,
exshapes:gndIDShape .
A node shape is always an instance of sh:NodeShape.
rdfs:label specifies a label for the node shape.
(Attention: This is the label for the node shape, not for the form.
The label of the form is generated from the value of rdfs:label
of the respective class of the RDFS data model). sh:targetClass
declares which class in the RDFS data model this node shape shall be applied to.
This means that all instances of this class shall be validated on the basis
of this node shape. Whether or not a unique form shall be generated on the
basis of this node shape results from the property roger:formNode
("true" generates a unique form, "false" doesn't). The property sh:property
describes which form fields this form shall contain by listing the
property shapes for those edges of the graph which can be connected to this node.
This section is non-normative.
Property shapes serve for describing the data and the corresponding form fields.
Shapes are identified as property shapes via a sh:PropertyShape.
exshapes:nameShape
a sh:PropertyShape ;
sh:path ex:name ;
sh:datatype xsd:string ;
dash:editor dash:TextFieldEditor ;
sh:name "Name" ;
sh:minCount 1 ;
sh:maxCount 1 ;
sh:description "Enter the name" ;
sh:order "0"^^xsd:decimal .
For each property shape, sh:path declares which
of the properties defined in the RDFS data model is described by this
property shape. sh:datatype names the data type allowed.
The kind of input field which the form should display is
described in dash:editor. In the case shown here, with
dash:TextFieldEditor, a one line free text input field is selected.
sh:name describes the label which should be displayed for
this input field. The two properties sh:minCount and
sh:maxCount declare how often this property can be
used minimally and maximally with an instance of the class specified in
sh:targetClass (i.e. its cardinality). Once sh:minCount
is set to a value higher than 0, this property is obligatory.
sh:description contains an additional explanation of the form
field. In the application, this explanation is displayed via a pop-over.
sh:order describes the order of the form fields in the form.
"0" means here that this form field should be shown right at the top.
The value set here applies to all the forms in which the respective
form is used because property shapes can be used multiple times in a
shapes graph. (If on the other hand one would want to specify a different
order in another form, one would need to formulate a new property shape
for the same property: in the same way as property shapes can be (re-)used
in several node shapes, conversely there can also be several different
property shapes for the same property).
The form field which is generated on the basis of this property shape looks like this:
This section is non-normative.
exshapes:genderShape
a sh:PropertyShape ;
sh:path ex:gender ;
sh:datatype xsd:string ;
sh:description "Choose the gender" ;
sh:in ( "female" "male" "other" ) ;
sh:maxCount 1 ;
sh:name "Gender" ;
sh:order "1"^^xsd:decimal .
In this example, there are three options for the gender: "female",
"male" and "other", which are listed in sh:in
(Attention: The values are separated via spaces here). The property
ex:gender can take only one of the values given in
sh:in due to the statement in sh:maxCount.
Accordingly, a form field with a selection list is generated.
The form field which is generated on the basis of this property shape looks like this:
This section is non-normative.
exshapes:friendShape
a sh:PropertyShape ;
sh:path ex:friend ;
sh:name "Friend" ;
sh:class ex:Person ;
dash:editor dash:AutoCompleteEditor ;
sh:nodeKind sh:IRI ;
sh:description "Select another person as a friend" ;
sh:order "2"^^xsd:decimal .
When entering of friendship relationships, the person which is being
described is connected with another person. The fact that the value of
the property ex:friend has to be a resource represented by
an IRI (and therefore mustn't be a literal) is described by the value
sh:IRI of the property sh:nodeKind. The class
to which this resource needs to belong is described by the property
sh:class. The property dash:editor takes the
value dash:AutoCompleteEditor in order to generate a form
field which supports the selection of a clearly defined amount of
possible URIs (IRIs) by the completion of the user input.
The form field which is generated on the basis of this property shape looks like this:
This section is non-normative.
exshapes:gndIDShape
a sh:PropertyShape ;
sh:path ex:gndID ;
dash:editor [
a roger:SelectInstanceFromRemoteDatasetEditor ;
roger:searchQueryURL "https://portal.dnb.de/opac.atom?currentResultId=per%3D%22{searchTerms}%22%26any%26persons&method=search&" ;
roger:searchQueryType "application/atom+xml"
] ;
sh:datatype xsd:anyURI ;
sh:nodeKind sh:Literal ;
sh:description "Select an entry from the GND (Gemeinsame Normdatei) of the German National Library." ;
sh:name "GND" ;
sh:order "3"^^xsd:decimal .
The user shall select the GND-ID for the person from an external
database (of the GND). For this, the ROGER software offers a
special form element, the roger:SelectInstanceFromRemoteDatasetEditor.
roger:searchQueryURL describes how exactly the
application should search in the database and roger:searchQueryType
describes how the search results should be returned from the
external database. For this it is important that these properties
are a property of the class roger:SelectInstanceFromRemoteDatasetEditor
(and not of sh:PropertyShape).
The form field looks like this:
This section is non-normative.
The form application in this example requires two files in total: The ROGER specification and the RDFS data model. The entire form looks like this:
Node Shapes structure the form and declare the classes from the RDFS data model which the respective object in the form corresponds to.
exshapes:PersonShape
a sh:NodeShape ;
rdfs:label "Person Shape" ;
sh:targetClass ex:Person ;
roger:formNode true ;
sh:property exshapes:nameShape ,
exshapes:genderShape ,
exshapes:friendShape ,
exshapes:gndIDShape .
A node shape has the following obligatory properties in the context of ROGER:
-
sh:targetClassdeclares for which class from the underlying RDFS data model should be generated -
sh:propertydescribes the edges originating from the node - and thereby the input fields or the subforms, respectively, of the form to be generated
The optional property roger:formNode declares whether on the basis of
this node shapes a form shall be generated (true). Node shapes
which shall only serve for the generation of subforms can receive
roger:formNode false.
Property Shapes describe the form fields and the data which shall be entered there.
exshapes:nameShape
a sh:PropertyShape ;
sh:path ex:name ;
sh:name "Name" ;
sh:order "0"^^xsd:decimal ;
...
A property shape has the following obligatory properties in the context of ROGER:
-
sh:pathdeclares which property from the underlying RDFS data model is described with the property shape - i.e. for which property data is generated by the form field sh:namedeclares the name of the form field-
sh:orderdescribes the position of this form field in the form
sh:name
is the label of the form field. The name of the form field
is displayed in the form as a label of the corresponding input field.
In ROGER, sh:name is an obligatory property for
property shapes.
exshapes:genderShape
a sh:PropertyShape ;
sh:name "Gender" ;
...
sh:path
declares which property from the underlying
RDFS data model is described with the property shape - i.e. for which property
data is generated by the form field
In ROGER, sh:path is an obligatory property for
property shapes.
exshapes:nameShape
a sh:PropertyShape ;
sh:path "ex:name" ;
...
sh:minCount
declares the minimal amount of values. With it, it is specified
how often the respective form field has to be filled in at least.
By entering a value higher than 0, the respective form field becomes
obligatory. In the application, this is marked via a red asterisk.
In ROGER, sh:minCount is an optional property for
property shapes.
exshapes:nameShape
a sh:PropertyShape ;
sh:minCount 1 ;
...
sh:maxCount
declares the maximum amount of the value. With it, it is specified
how often the respective form field can be filled out at most.
If sh:maxCount is specified, its value must always be
higher than 0. If sh:maxCount is not specified, the
respective form field is repeatible any number of times. If both
sh:minCount and sh:maxCount are specified,
the value of sh:maxCount has to be higher or equal to
the value of sh:minCount.
In ROGER, sh:maxCount is an optional property for
property shapes.
exshapes:nameShape
a sh:PropertyShape ;
sh:maxCount 1 ;
...
sh:defaultValue
provides a default value. This value is pre-entered into the
form fields or pre-selected in the selection fields, respectively.
In ROGER, sh:defaultValue is an optional property
for property shapes.
exshapes:maritalStatusShape
a sh:PropertyShape ;
sh:defaultValue "single" ;
...
sh:pattern
declares a regular expression against which the values entered have to
validate.
In ROGER, sh:pattern is an optional property for
property shapes.
exshapes:birthShape
a sh:PropertyShape ;
sh:pattern "\d{4}" ;
...
sh:datatype
declares the data type allowed.
In ROGER, sh:datatype is an optional property for
property shapes.
As a matter of principle, all data types are allowed which are defined in RDF 1.1 Concepts and Abstract Syntax. However, the data types are restricted according to the input field. In the explanations to the input fields, the allowed data types are listed.
Attention: If sh:datatype is used,
sh:nodekind can only have the value
sh:Literal. The specification via
sh:nodekind is optional in this case.
If values are prescribed, for example via
sh:in, these values need to conform
to the data type specified.
exshapes:nameShape
a sh:PropertyShape ;
sh:datatype xsd:string ;
...
sh:nodekind
declares what type of node the value has to conform to.
In ROGER, sh:nodekind is an optional property for
property shapes.
As a matter of principle, all data types are allowed which are defined in RDF 1.1 Concepts and Abstract Syntax. However, the data types are restricted according to the input field. In the explanations to the input fields, the allowed data types are listed.
Attention: If sh:datatype is used,
sh:nodekind can only have the value
sh:Literal haben. The specification via
sh:nodekind is optional in this case.
exshapes:friendShape
a sh:PropertyShape ;
sh:nodeKind sh:IRI ;
...
sh:class
declares the class (from the RDFS data model) which the value of the
property has to be an instance of.
In ROGER, sh:class is an optional property for
property shapes.
exshapes:friendShape
a sh:PropertyShape ;
sh:class ex:Person ;
...
sh:node
describes which node shape the value of the property has to
conform to.
In ROGER, sh:node is an optional property for
property shapes.
exshapes:addressShape
a sh:PropertyShape ;
sh:node exshapes:AddressShape ;
...
sh:message
contains the text of an error message which is diplayed
when a validation error is found.
In ROGER, sh:message is an optional property for
property shapes.
exshapes:birthShape
a sh:PropertyShape ;
sh:message "The year of birth needs to be specified by a number consisting of four digits." ;
...
sh:in
declares possible values for the property shape. In ROGER, this is
displayed as an selection field.
Attention: The values are separated via spaces here.
In ROGER, sh:in is an optional property for
property shapes.
In combination with sh:in,
sh:datatype needs to take
one of the following values:
xsd:stringxsd:decimalxsd:integerxsd:doublexsd:floatxsd:intxsd:longxsd:anyURI
Via sh:minCountsh:maxCount, it can be specified
how many values need to/can be selected.
If sh:in is used together with
sh:defaultValue, the
value which is specified in
sh:defaultValue is pre-selected.
exshapes:genderShape
a sh:PropertyShape ;
sh:in ( "female" "male" "other" ) ;
...
Input elements are described via the property
dash:editor.
It specifies the type of the input field.
In ROGER, dash:editor is an optional property for
property shapes.
dash:TextAreaEditor
is a multiline text input field.
In combination with dash:TextAreaEditor,
sh:datatype has to take the value
xsd:string.
If dash:TextAreaEditor is used in combination with
sh:defaultValue,
the value specified there is pre-entered in the form field
but can be modified.
exshapes:commentShape
a sh:PropertyShape ;
dash:editor dash:TextAreaEditor ;
sh:datatype xsd:string ;
...
dash:TextFieldEditor
is a single-line text input field.
In combination with
dash:editor dash:TextFieldEditor,
sh:datatype has to take
one of the following values:
xsd:stringxsd:decimalxsd:integerxsd:doublexsd:floatxsd:intxsd:longxsd:anyURI
If dash:TextFieldEditor is used in combination with
sh:defaultValue,
the value specified there is pre-entered in the form field
but can be modified.
exshapes:nameShape
a sh:PropertyShape ;
sh:datatype xsd:string ;
dash:editor dash:TextFieldEditor ;
...
dash:RichTextEditor
is an input field which allows for the entering of formatted text.
In combination with dash:RichTextEditor,
sh:datatype has to take the value
rdf:HTML.
exshapes:curriculumVitaeShape
a sh:PropertyShape ;
dash:editor dash:RichTextEditor ;
sh:datatype rdf:HTML ;
...
dash:AutoCompleteEditor
is a search field with an autocomplete feature for the linking to
instances of classes whose RDFS data model is known and which are
stored in the same data store.
In combination with dash:AutoCompleteEditor,
sh:nodeKind has to take the value sh:IRI.
The class which the instances stem from which can be linked to
is specified in
sh:class.
exshapes:friendShape
a sh:PropertyShape ;
sh:class ex:Person ;
dash:editor dash:AutoCompleteEditor ;
sh:nodeKind sh:IRI ;
...
roger:SelectInstanceFromRemoteDatasetEditor is a
search field for the linking with data from an external database
(in TURTLE: URI with angle brackets) or for the acquisition of
data from an external database (in TURTLE: Literal in
quotation marks).
roger:SelectInstanceFromRemoteDatasetEditor has to
be configurated: Via roger:searchQueryURL, it is
described which database is queried in which way. Via
roger:searchQueryType, it is described which type the
search results shall have. Two values are possible:
-
If
application/atom+xmlis specified, the result is an Atom feed. The form application resorts to the following child ements ofentryto display the results:titleand, if present,content. The content of the child elementidis adopted as value. -
If
application/rss+xmlis specified, the result is an RSS feed. The form application resorts to the following child ements ofitemto display the results:titleand, if present,description. The content of the child elementidis adopted as value.
If a linking to data from an external database is establed via the form field,
sh:nodeKind has to take the value
sh:IRI.
If data from an external database is acquired via the form field,
sh:nodeKind has to take the value
sh:Literal .
sh:datatype can take one of the
following values:
xsd:stringxsd:decimalxsd:integerxsd:doublexsd:floatxsd:intxsd:longxsd:anyURIxsd:datexsd:dateTime
Only data that have the same property can be adopted. This is
defined via sh:path. For the adoption of for
example the surname of a GND entry, the respective property
(gndo:surname) needs to be defined via
sh:path.
exshapes:gndSurnameShape
a sh:PropertyShape ;
dash:editor [
a roger:SelectInstanceFromRemoteDatasetEditor ;
roger:searchQueryURL "https://portal.dnb.de/opac.atom?currentResultId=per%3D%22{searchTerms}%22%26any%26persons&method=search&" ;
roger:searchQueryType "application/atom+xml" ;
] ;
sh:path gndo:surname;
...
dash:DatePickerEditor
is an selection field in the shape of a calendar for the selection
of dates.
In combination with dash:DatePickerEditor,
sh:datatype has to take the value
xsd:date.
exshapes:birthdayShape
a sh:PropertyShape ;
dash:editor dash:DatePickerEditor ;
sh:datatype xsd:date ;
...
dash:editor dash:DateTimePickerEditor
is an selection field in the shape of a calendar for the selection
of dates, including a time of day.
In combination with dash:DateTimePickerEditor,
sh:datatype has to take the value
xsd:dateTime.
exshapes:nextExamShape
a sh:PropertyShape ;
dash:editor dash:DateTimePickerEditor ;
sh:datatype xsd:dateTime ;
...
dash:URIEditor
generates a form field for the entering of IRIs or URIs, respectively,
which mustn't be understood as a representation of a resource
in the RDF sense (i.e. this field is for URLs or URNs of web resources
or similar).
In combination with dash:editor dash:URIEditor,
sh:nodekind has to take the value
sh:Literal.
In combination with dash:editor dash:URIEditor,
sh:datatype has to take the value
xsd:anyURI.
exshapes:homepageShape
a sh:PropertyShape ;
dash:editor dash:URIEditor ;
sh:nodeKind sh:Literal ;
sh:datatype xsd:anyURI
...
dash:BooleanSelectEditor
generates a form field for the entering of true/false values.
In combination with dash:BooleanSelectEditor,
sh:datatype has to take the value
xsd:boolean.
exshapes:aliveShape
a sh:PropertyShape ;
dash:editor dash:BooleanSelectEditor ;
sh:datatype xsd:boolean ;
...
roger:formNode specifies whether a form is generated
from a node shape. For this, the value is set to true.
For subforms,
roger:formNode false can be specified.
In ROGER, roger:formNode is an optional property for
property shapes.
exshapes:PersonShape
a sh:NodeShape ;
roger:formNode true ;
...
sh:property
specifies which property shapes a node shape refers to. This means,
which form fields the (sub)form should have.
In ROGER, sh:property is an obligatory property for
node shapes and can be repeated any number of times.
exshapes:PersonShape
a sh:NodeShape ;
sh:property exshapes:nameShape ,
exshapes:genderShape ,
exshapes:friendShape ,
exshapes:gndIDShape ;
...
sh:targetClass
specifies the class in the RDFS data model whose instances the
node shape should be applied to.
In ROGER, sh:targetClass is an obligatory property for
node shapes.
exshapes:PersonShape
a sh:NodeShape ;
sh:targetClass ex:Person ;
...
dash:DetailsEditor
describes a subform.
sh:node refers to the node shape
on whose basis the subform is generated.
In combination with dash:DetailsEditor,
sh:nodekind has to take the value
sh:BlankNode.
exshapes:addressShape
a sh:PropertyShape ;
dash:editor dash:DetailsEditor ;
sh:node exshapes:AddressShape ;
sh:nodeKind sh:BlankNode ;
...
sh:description
describes the form field. This description is displayed in a pop-over
in the ROGER application.
In ROGER, sh:description is an optional property for
property shapes.
exshapes:nameShape
a sh:PropertyShape ;
sh:description "Enter the name" ;
...
sh:order
specifies the order of the form fields. For this, the value of
sh:order is taken relative to the values of the various
other property shapes of the same node shapes.
Attention! Each property shape always receives only exactly one
sh:order value. The value of
sh:order therefore applies to all node shapes that use
this property shape.
In ROGER, sh:order is an obligatory property
for property shapes.
Type: Decimal
exshapes:nameShape
a sh:PropertyShape ;
sh:order "0"^^xsd:decimal ;
...