Notebook: Customizable web forms for recording observations
Authors: Raitio Olli , Juslén Aino , Sirkiä Päivi , Lehikoinen Aleksi , Tähtinen Marko , Piirainen Esko , Riihikoski Ville-Matti 
Published: August 2019

’Notebook’ is one of the primary data management systems of the Finnish Biodiversity Information Facility (FinBIF). It is a web solution for recording opportunistic as well as sampling-event-based species observations. It is being used for systematic monitoring schemes, various citizen science projects, and platforms for species enthusiasts. Notebook's main software component is LajiForm, which is the engine that renders a given JSON Schema into a web form. LajiForm is a separate, reusable module that is fully independent from other FinBIF systems. Notebook as a whole, includes other features embedded in FinBIF, such as linking users' geographical data to observation documents, spreadsheet document importing and form templates. We will demonstrate how the Notebook system works as a whole and also focus on LajiForm's technical aspects.

Fig. 1

All Notebook forms use FinBIF's ontological schema in JSON Schema format. Rendering user-friendly web forms based on a single schema is a difficult task, because the web form should be asking meaningful questions, instead of just rendering the schema fields according to the form description. We want to present questions in an interactive style. For instance, after drawing a geographical location on a map for a potential flying squirrel nesting tree, we would ask "did you see droppings at the nest?", and answering "yes" would update the document to include a flying squirrel taxon identification with fields "breeding" and "record basis" filled in but not rendered to the form. A simpler form engine without a user interface (UI) customization layer would just render the "taxon", "breeding" and "record basis" fields and the user would have no understanding why there are so many fields to answer and how they relate to their work or study. Some forms are complex, e.g., for experienced biology enthusiasts who need a form that is advanced, customizable, and compact. Some forms are simple, e.g., for elementary school children.

To tackle these challenges, LajiForm uses a separate schema for UI that allows everything from simple customization like:

defining widgets for fields (e.g., date widgets, taxon autocomplete widget, map widget),

changing field order or

customizing field labels; to more complex customization like

transforming the schema object structure,

defining conditions when certain fields are shown or

if updating a field should have an effect on other fields.

defining widgets for fields (e.g., date widgets, taxon autocomplete widget, map widget),

changing field order or

customizing field labels; to more complex customization like

transforming the schema object structure,

defining conditions when certain fields are shown or

if updating a field should have an effect on other fields.

All the functionality is split into a loosely coupled collection of components, which can be either used as standalone components or composed together in order to achieve more advanced customization. The programming philosophy has drawn inspiration from functional programming, which has been helpful in writing isolated, composable functionality.

LajiForm is written with the JavaScript framework React. LajiForm is built on top of react-jsonschema-form (RJSF), which is an open source JSON schema web form library provided by Mozilla. RJSF handles only simple customization, but it is very flexible in design and allows us to build extensions with features that are more powerful. Some features and design proposals were submitted to Mozilla – FinBIF is the largest code contributor to RJSF outside of Mozilla, with a dozen pull requests merged.