building partnerships to regenerate soils
We believe that sustainable partnerships for the support of EarthHealers need a freely accessible, shared digital language. Therefore, we developed and host RAL – the regenerative agriculture language – as non-commercial, open access project.
This language is an ontology-like knowledge representation that enables farmers, regulatory entities, scientists, but also software, AI, and machines to exchange information as structured data. This allows partners to develop interconnected software and machines easily. In contrast to real ontologies, the data structure is lightweight and purely oriented towards ease-of-use, speed, and low demand on computing power.
At the same time, data encoded in RAL is stored at the users site enabling a maximum of data sovereignty and minimum of dependency on centralized structures.
This will optimize workflows and reduces or avoids human mistakes often occurring in complex systems such as the restoration of soil ecosystems. It also allows a high transparency of data to continuously ask the most important question: “Are we really on the right way towards healing the earth?”
RAL is a hierarchy of object- and method-templates describing all possible things and processes in the regenerative agriculture value creation chain.
To make sure that a digital representation of an object or method is unique, you can either request an UID from the RAL host via the API call for the template of this object/method OR you generate your own UID after getting the template from the RAL host using your sitetag as prefix.
The main blocks are objects and methods which itself consist of a set of mandatory blocks that describe the individual object or method.
1. Objects
An object is a description of a real-world or digital object.
All objects consist of the same building blocks:
a) identity (UID, name, siteTag, alternateUIDs)
This block contains the information that makes the individual object unique. It get’s an UID, a name, and contains the siteTag it was generated on. Alternate UID is an array of UIDs that might have been given to the object by others.
b) definition (definitionText, definitionURL)
This block contains the definition of the object in plain text and as URL linking to a valid definition source.
c) template (RALType, version, objectStateTemplates)
The template information contains data about the type of this object and the version of the template that was used. Note that by calling the API without the optional parameter templateVersion, you will always get the most recent version of this object template.
d) specificProperties
This is a list of properties that are unique to this object like a storage path property, a temperature property, an amount property…
Each property consists of KEY, VALUE, UNIT (from unitType), RALType, minItems, maxItems
e) currentGeolocation
This block describes the geolocation of the object, in case locatioHistory is not informative about it’s real-world location. It can contain longitude, latitude, postal address, 3WordAddress, Plus Code.
e) locationHistoryRef (past, present, future)
This is a list of location objects (object references [UID, RALtype, timestamp of moving to this location, past/present/future tag]) the object was/is/will be located at in a chronological order.
f) roleHistoryRef (past present, future)
This is a list of roles the object had (roleType, timestamp of attribution of this role, past/present/future tag) in a chronological order.
g) ownerHistoryRef (past present, future)
This is a list of object references of owners of this object (UID, RALType, timestamp of start of ownership, past/present/future tag) in a chronological order.
h) methodHistoryRef
This is a list of method references (UID, RALType), which have been executed using this object in a chronological order.
i) linkedObjectRef (as object or objectReference)
This is a list of objects that are nested inside this object. This is needed for special relations between object that are not related to location or ownership. The can be either be provided as complete objects or as objectReference (UID, RALType, timestamp of start of nesting, past/present/future tag)
j) objectState
The state the object is current in, selected from objectState childs in objects hierarchy
2. Methods
A method is a description of a process that uses 1-to-many input objects and 1-to-many output objects. It can contain a number of nested methods that describe subprocesses. The connection between the single objects of the main and the nested methods are described using objectConnectors.
Therefore, all methods consist of the following building blocks:
a) identity (UID, name, site tag)
This block contains the information that makes the individual object unique. It get’s an UID, a name, and contains the siteTag it was generated on.
b) definition (definitionText, definitionURL)
This block contains the definition of the method in plain text and as URL linking to a valid definition source.
c) template (RALType, version)
The template information contains data about the type of this method and the version of the template that was used. Note that by calling the API without the optional parameter templateVersion, you will always get the most recent version of this method template.
d) specificProperties
This is a list of properties that are unique to this method like environmental parameters during execution.
Each property consists of KEY, VALUE, UNIT (from unitType), RALType, minItems, maxItems
e) inputObjects
All objects that are used by the method (status prior to execution).
f) outputObjects
All objects that are generated or modified by the method (status after execution).
g) nestedMethods
Each method (also already nested methods) can have an unlimited number of methods nested to it.
h) objectConnectors
Input- and output objects of the main- and nested methods are connected to each other using information inside this block. The block consists of a list of object connectors consisting of sourceObject [methodNb, objectNb], targetObject [methodNb, objectNb].
i) methodState
The state the method is currently in, selected from methodState in objects hierachy
j) methodDuration
The duration of the execution of this method. Has to be provided in ISO 8601 format.
j) executor
This block contains information about the (future) executor of the method as en encapsulated object.
3. Method Processors
Method processors are software that can take a method as input and computes the resulting output objects based on the provided input objects, object connectors and other specific information provided inside the method.
4. Translators
Since not all preexisting data is stored in RAL format, we need translators that take existing data and transform them into consistent RAL data format.
There are 2 general API calls to the RAL host:
1. getHierarchy
This call sends back a JSON or XML of the RAL hierarchy – a tree structure of all object- and method- templates used by RAL. Based on the names of the items, you can request a template of such an item (see getTemplate)
Parameters
a) hierarchyType: “object” or “method”
b) returnAs: “JSON” or “XML”
Returned Data
A string containing JSON or XML of the object- or method-hierarchy as requested. In case of an error, a JSON string describing the error is returned.
Example call
***
2. getTemplate
This call sends back a JSON or XML of the requested object or method
Parameters
a) hierarchyType: “object” or “method”
b) returnAs: “JSON” or “XML”
c) templateName: name of the requested template
d) siteTag: the sitetag you registered at the RAL host [register here]
e) getUID: “true” or “false” – dependent on whether you would like to get a central UID from us or not
f) (optional) templateVersion: if provided, the call returns the requested version of the template. Otherwise, it will return the most current version.
Returned Data
A string containing JSON or XML of the requested template. In case of an error, a JSON string describing the error is returned.
Example call
***
Once you received the template from the API, we recommend to perform the following steps:
1. (optional) generate an UID and persist inside the object/method
***
2. fill the object/method with all necessary individual properties
***
3. persist the individual in your database
***