Instance Record Forms Format

From OSF Wiki
Jump to: navigation, search

Introduction

The Instance Record Forms Format (IRFF) is used to describe forms describing different characteristics of instance records to be generated and added to web pages. The IRFF forms are generally used to describe (add/update/delete) information about instance records. These forms are currently used by OSF-Drupal modules such as structCreate, structUpdate and structScones.

These forms are written by the system administrators and are specially tailored for the needs of a particular OSF-Drupal node.

The general workflow utilizing IRFF is:

Ontologies act to generate a forms file --> Forms file enables admins to edit forms for different purposes --> Final forms

Then:

Final forms --> Create/Update page --> Updated record in OSF Web Service

Using IRFF makes it easier to develop and maintain domain nodes.

Overview

A forms XML file describes a set of forms that can be used by an application to describe an instance record. Each form of that set outlines a list of fields that belonsg to the form.

Each form has a type. The type of a form is used by a system to determine what form should be selected for a given type of instance record.

Each field is related to an HTML input control. Each field is also related to an attribute that is used to describe an instance record of the type of the form.

A (form->type)->(field->rel) will result in a (instance record)--attribute-->(value) triple.

Format

This IRFF is serialized in XML. This section explains all the XML elements and attributes that compose the format.

<forms />

The <forms /> element includes all the forms and prefixes. This is the root element of the XML document.

<prefixes/>

The <prefixes/> element includes all the prefixes binding elements.

<prefix/>

A <prefix/> element bind a prefix "foo:" to the base URI it should be extended to, by any system that uses the IRFF.

In IRFF, form type and field rel can be shortened by using prefixes. A prefix is the short-hand version of a URI. The prefixes are at the beginning of an URI identifier, and are seperated by a column ":".

Lets take a look at this example. Lets say that we have these prefixes defined for our example:

  <prefixes>
    <prefix prefix="peg" uri="http://purl.org/ontology/peg#" />
    <prefix prefix="bibo" uri="http://purl.org/ontology/bibo/" />
    <prefix prefix="iron" uri="http://purl.org/ontology/iron#" />
    <prefix prefix="sco" uri="http://purl.org/ontology/sco#" />
    <prefix prefix="umbel" uri="http://umbel.org/umbel#" />
    <prefix prefix="geonames" uri="http://www.geonames.org/ontology#" />
  </prefixes>

Now, let say that we have this field defined in our IRFF file:

    <field control="text">
      <prefLabel>City name</prefLabel>
      <description></description>
      <rel>geonames:name</rel>
    </field>

In this case, the <rel /> element's real URI reference is no "geonames:name" but "http://www.geonames.org/ontology#name". Any system that uses a IRFF file has to extend these references to their full URI.

prefix

The prefix attribute of the <prefix/> element is used to define the prefix used within the same IRFF file.

uri

The uri attribute of the <prefix/> element is used to base URI to use to replace the prefix when the form get processed by any syste.

<form />

The <form /> element describe the form to use to describe an instance record of a certain type. This form as a <prefLabel /> and a <description />. It also includes a series of <fields />.

Note: the order of the fields in a form is kept once the form get rendered to the user.

type

The type attribute is used to bind the form to a given instance record type. This type refers to the kind of instance records for which we can use that form to describe them.

<field />

The <field /> element defines each attribute that can be used to describe a record of the type of the parent <form /> element. Each <field /> element can have a <prefLabel /> and a <description /> element. These two elements are normally used to name and describe the field presented to the user. It also includes a required <rel /> element that relates a field to an attribute that describes the instance record.

Lets take that example:

    <field control="text">
      <prefLabel>City name</prefLabel>
      <description></description>
      <rel>geonames:name</rel>
    </field>

In this example, the field is related to the geonames:name attribute. This means that the value of this field will be used as the value of the geonames:name attribute, so we would end-up with a triple:

  <instance-record> <geonames:name> <value-of-the-field>

control

The control attribute of the <field /> element is used to specify what is the HTML input form control that should be used to handle this field. This value can be one of:

  1. text. This is a single line input text box.
  2. textarea. This is a multi-lines input text box with possible scroll-bars.
  3. resource. This is a single line input text box where the value is a reference to another instance record.
  4. separator. This is a section header that is used to split cluster of attributes. The prefLabel of this field can be used as a section title.

<prefLabel/>

The <prefLabel /> element is used to specify a preferred label we would like to use to refers to this thing in a user interface. A <prefLabel/> element can be used to describe a <form /> or a <field /> element.

<description />

The <description /> element is used to specify a description we would like to use to describes this thing in a user interface. A <description /> element can be used to describe a <form /> or a <field /> element.

<rel />

The <rel /> element is used to specify the attribute that the field refers to. Check the <form /> section of this specification for more information.. A <rel /> element can be used to describe a <field /> element.

<maxValues />

The <maxValues /> element is used to specify the maximum cardinality of that attribute. If no maxValues, nor minValues attributes are defined for a field, it means that no cardinality restrictions can be applied to it (i.e it can have no, or an infinite number of values).

<minValues />

The <minValues /> element is used to specify the minimum cardinality of that attribute. If no maxValues, nor minValues attributes are defined for a field, it means that no cardinality restrictions can be applied to it (i.e it can have no, or an infinite number of values).

<values />

The <values /> element is used to specify an enumeration of possible values to use as a value, for the property represented by this field. All the values are displayed in a drop-down selection box.

Here is an example of how the <values /> field can be defined:

<forms>
  <form>
    <prefLabel>Gender</prefLabel>
    <rel>foaf:gender</rel>
    <values>
      <value>Men</value>
      <value>Women</value>
    </values>
  </form> 
</forms>

Note: the <values /> element is only effective with a fields of control type text.

An Example

Here is an example that describes a set of forms. Such a file is used by structCreate and structUpdate to let users create, or update, instance records of these types in a OSF-Drupal node.

<?xml version="1.0" encoding="utf-8"?>
 
<forms>
  <prefixes>
    <prefix prefix="foo" uri="http://purl.org/ontology/foo#" />
    <prefix prefix="bibo" uri="http://purl.org/ontology/bibo/" />
    <prefix prefix="iron" uri="http://purl.org/ontology/iron#" />
    <prefix prefix="sco" uri="http://purl.org/ontology/sco#" />
    <prefix prefix="geonames" uri="http://www.geonames.org/ontology#" />
  </prefixes> 
 
  <form type="foo:Neighborhood">
    <prefLabel>Neighborhood</prefLabel>
    <description></description>
 
    <field control="text">
      <prefLabel>Neighborhood name</prefLabel>
      <description></description>
      <rel>geonames:name</rel>
    </field>      
    <field control="text">
      <prefLabel>Neighborhood's Wikipedia page</prefLabel>
      <description></description>
      <rel>geonames:wikipediaArticle</rel>
    </field>      
 
    <field control="text">
      <prefLabel>population in 1971 </prefLabel>
      <description></description>
      <rel>foo:population_year_1971</rel>
    </field>      
    <field control="text">
      <prefLabel>population in 1976</prefLabel>
      <description></description>
      <rel>foo:population_year_1976</rel>
    </field>      
    <field control="text">
      <prefLabel>population in 1981</prefLabel>
      <description></description>
      <rel>foo:population_year_1981</rel>
    </field>      
    <field control="text">
      <prefLabel>population in 1986</prefLabel>
      <description></description>
      <rel>foo:population_year_1986</rel>
    </field>      
    <field control="text">
      <prefLabel>population in 2001</prefLabel>
      <description></description>
      <rel>foo:population_year_2001</rel>
    </field>      
    <field control="text">
      <prefLabel>population in 2006</prefLabel>
      <description></description>
      <rel>foo:population_year_2006</rel>
    </field>    
 
    <field control="text">
      <prefLabel>population density in 1971</prefLabel>
      <description></description>
      <rel>foo:populationDensity_year_1971</rel>
    </field>      
    <field control="text">
      <prefLabel>population density in 1976</prefLabel>
      <description></description>
      <rel>foo:populationDensity_year_1976</rel>
    </field>      
    <field control="text">
      <prefLabel>population density in 1981</prefLabel>
      <description></description>
      <rel>foo:populationDensity_year_1981</rel>
    </field>      
    <field control="text">
      <prefLabel>population density in 1986</prefLabel>
      <description></description>
      <rel>foo:populationDensity_year_1986</rel>
    </field>      
    <field control="text">
      <prefLabel>population density in 2001</prefLabel>
      <description></description>
      <rel>foo:populationDensity_year_2001</rel>
    </field>      
    <field control="text">
      <prefLabel>population density in 2006</prefLabel>
      <description></description>
      <rel>foo:populationDensity_year_2006</rel>
    </field>       
 
    <field control="text">
      <prefLabel>Neighborhood area number</prefLabel>
      <description></description>
      <rel>foo:area</rel>
    </field>      
    <field control="text">
      <prefLabel>Neighborhood GIS map URL</prefLabel>
      <description></description>
      <rel>foo:gisMap</rel>
    </field>      
    <field control="text">
      <prefLabel>Neighborhood number</prefLabel>
      <description></description>
      <rel>foo:neighborhoodNumber</rel>
    </field>      
 
  </form>
 
  <form type="foo:City">
    <prefLabel>City</prefLabel>
    <description></description>
 
    <prefLabel>City</prefLabel>
    <description></description>
 
    <field control="text">
      <prefLabel>City name</prefLabel>
      <description></description>
      <rel>geonames:name</rel>
    </field>      
    <field control="text">
      <prefLabel>City's Wikipedia page</prefLabel>
      <description></description>
      <rel>geonames:wikipediaArticle</rel>
    </field>      
 
    <field control="text">
      <prefLabel>population in 1971 </prefLabel>
      <description></description>
      <rel>foo:population_year_1971</rel>
    </field>      
    <field control="text">
      <prefLabel>population in 1976</prefLabel>
      <description></description>
      <rel>foo:population_year_1976</rel>
    </field>      
    <field control="text">
      <prefLabel>population in 1981</prefLabel>
      <description></description>
      <rel>foo:population_year_1981</rel>
    </field>      
    <field control="text">
      <prefLabel>population in 1986</prefLabel>
      <description></description>
      <rel>foo:population_year_1986</rel>
    </field>      
    <field control="text">
      <prefLabel>population in 2001</prefLabel>
      <description></description>
      <rel>foo:population_year_2001</rel>
    </field>      
    <field control="text">
      <prefLabel>population in 2006</prefLabel>
      <description></description>
      <rel>foo:population_year_2006</rel>
    </field>    
 
    <field control="text">
      <prefLabel>population density in 1971</prefLabel>
      <description></description>
      <rel>foo:populationDensity_year_1971</rel>
    </field>      
    <field control="text">
      <prefLabel>population density in 1976</prefLabel>
      <description></description>
      <rel>foo:populationDensity_year_1976</rel>
    </field>      
    <field control="text">
      <prefLabel>population density in 1981</prefLabel>
      <description></description>
      <rel>foo:populationDensity_year_1981</rel>
    </field>      
    <field control="text">
      <prefLabel>population density in 1986</prefLabel>
      <description></description>
      <rel>foo:populationDensity_year_1986</rel>
    </field>      
    <field control="text">
      <prefLabel>population density in 2001</prefLabel>
      <description></description>
      <rel>foo:populationDensity_year_2001</rel>
    </field>      
    <field control="text">
      <prefLabel>population density in 2006</prefLabel>
      <description></description>
      <rel>foo:populationDensity_year_2006</rel>
    </field>       
 
  </form>
 
  <form type="foo:Country">
    <prefLabel>Country</prefLabel>
    <description></description>
 
    <prefLabel>Country</prefLabel>
    <description></description>
 
    <field control="text">
      <prefLabel>Country name</prefLabel>
      <description></description>
      <rel>geonames:name</rel>
    </field>      
    <field control="text">
      <prefLabel>Country's Wikipedia page</prefLabel>
      <description></description>
      <rel>geonames:wikipediaArticle</rel>
    </field>      
 
    <field control="text">
      <prefLabel>population in 1971 </prefLabel>
      <description></description>
      <rel>foo:population_year_1971</rel>
    </field>      
    <field control="text">
      <prefLabel>population in 1976</prefLabel>
      <description></description>
      <rel>foo:population_year_1976</rel>
    </field>      
    <field control="text">
      <prefLabel>population in 1981</prefLabel>
      <description></description>
      <rel>foo:population_year_1981</rel>
    </field>      
    <field control="text">
      <prefLabel>population in 1986</prefLabel>
      <description></description>
      <rel>foo:population_year_1986</rel>
    </field>      
    <field control="text">
      <prefLabel>population in 2001</prefLabel>
      <description></description>
      <rel>foo:population_year_2001</rel>
    </field>      
    <field control="text">
      <prefLabel>population in 2006</prefLabel>
      <description></description>
      <rel>foo:population_year_2006</rel>
    </field>    
 
    <field control="text">
      <prefLabel>population density in 1971</prefLabel>
      <description></description>
      <rel>foo:populationDensity_year_1971</rel>
    </field>      
    <field control="text">
      <prefLabel>population density in 1976</prefLabel>
      <description></description>
      <rel>foo:populationDensity_year_1976</rel>
    </field>      
    <field control="text">
      <prefLabel>population density in 1981</prefLabel>
      <description></description>
      <rel>foo:populationDensity_year_1981</rel>
    </field>      
    <field control="text">
      <prefLabel>population density in 1986</prefLabel>
      <description></description>
      <rel>foo:populationDensity_year_1986</rel>
    </field>      
    <field control="text">
      <prefLabel>population density in 2001</prefLabel>
      <description></description>
      <rel>foo:populationDensity_year_2001</rel>
    </field>      
    <field control="text">
      <prefLabel>population density in 2006</prefLabel>
      <description></description>
      <rel>foo:populationDensity_year_2006</rel>
    </field>       
  </form> 
 
  <form type="foo:Province">
    <prefLabel>Province</prefLabel>
    <description></description>
 
    <prefLabel>Province</prefLabel>
    <description></description>
 
    <field control="text">
      <prefLabel>Province name</prefLabel>
      <description></description>
      <rel>geonames:name</rel>
    </field>      
    <field control="text">
      <prefLabel>Province's Wikipedia page</prefLabel>
      <description></description>
      <rel>geonames:wikipediaArticle</rel>
    </field>      
 
    <field control="text">
      <prefLabel>population in 1971 </prefLabel>
      <description></description>
      <rel>foo:population_year_1971</rel>
    </field>      
    <field control="text">
      <prefLabel>population in 1976</prefLabel>
      <description></description>
      <rel>foo:population_year_1976</rel>
    </field>      
    <field control="text">
      <prefLabel>population in 1981</prefLabel>
      <description></description>
      <rel>foo:population_year_1981</rel>
    </field>      
    <field control="text">
      <prefLabel>population in 1986</prefLabel>
      <description></description>
      <rel>foo:population_year_1986</rel>
    </field>      
    <field control="text">
      <prefLabel>population in 2001</prefLabel>
      <description></description>
      <rel>foo:population_year_2001</rel>
    </field>      
    <field control="text">
      <prefLabel>population in 2006</prefLabel>
      <description></description>
      <rel>foo:population_year_2006</rel>
    </field>    
 
    <field control="text">
      <prefLabel>population density in 1971</prefLabel>
      <description></description>
      <rel>foo:populationDensity_year_1971</rel>
    </field>      
    <field control="text">
      <prefLabel>population density in 1976</prefLabel>
      <description></description>
      <rel>foo:populationDensity_year_1976</rel>
    </field>      
    <field control="text">
      <prefLabel>population density in 1981</prefLabel>
      <description></description>
      <rel>foo:populationDensity_year_1981</rel>
    </field>      
    <field control="text">
      <prefLabel>population density in 1986</prefLabel>
      <description></description>
      <rel>foo:populationDensity_year_1986</rel>
    </field>      
    <field control="text">
      <prefLabel>population density in 2001</prefLabel>
      <description></description>
      <rel>foo:populationDensity_year_2001</rel>
    </field>      
    <field control="text">
      <prefLabel>population density in 2006</prefLabel>
      <description></description>
      <rel>foo:populationDensity_year_2006</rel>
    </field>       
  </form>
 
  <form type="bibo:Document">
    <prefLabel>Story</prefLabel>
    <description></description>
 
    <field control="text">
      <prefLabel>preferred label</prefLabel>
      <description></description>
      <rel>iron:prefLabel</rel>
    </field>   
    <field control="textarea">
      <prefLabel>abstract</prefLabel>
      <description></description>
      <rel>bibo:abstract</rel>
    </field>      
    <field control="text">
      <prefLabel>Story teller</prefLabel>
      <description></description>
      <rel>foo:storyTeller</rel>
    </field>
    <field control="text">
      <prefLabel>Submitter's name</prefLabel>
      <description></description>
      <rel>foo:submitterName</rel>
    </field>
    <field control="text">
      <prefLabel>Submitter's ID</prefLabel>
      <description></description>
      <rel>foo:submitterID</rel>
    </field>
    <field control="text">
      <prefLabel>Collection Method</prefLabel>
      <description></description>
      <rel>foo:collectionMethod</rel>
    </field>   
    <field control="resource">
      <prefLabel>is about</prefLabel>
      <description></description>
      <rel>umbel:isAbout</rel>
    </field>   
    <field control="text">
      <prefLabel>story's text URL</prefLabel>
      <description></description>
      <rel>sco:storyTextUri</rel>
    </field>   
    <field control="text">
      <prefLabel>story's annotated text URL</prefLabel>
      <description></description>
      <rel>sco:storyAnnotatedTextUri</rel>
    </field>   
  </form>  
</forms>