This is a development version of the documentation and may contain inaccuracies! Please find the official documentation at https://opendatahub.readthedocs.io/en/latest/

Guidelines for Developers

Open Data Hub is a collection of software, databases, and services coordinated and hosted by IDM Südtirol / Alto Adige. Currently, Open Data Hub systems are related to mobility and tourism. In the future Open Data Hub might diversify into more fields.

Companies and developers contributing to Open Data Hub must follow the guidelines listed in the documents as close as possible.

The aim of the Open Data Hub Developer’s Guidelines (“The Guidelines”) is to simplify the hosting and maintenance of the software, databases, and services by the Open Data Hub developers and maintainers at IDM (“the Open Data Hub team”).

The Guidelines describe the conventions to which a developer must adhere, to be able to become an active Open Data Hub developer or to see his work being incorporated into the Open Data Hub. They are split in two parts:

  • Platform Guidelines explain the preferred programming languages, how to expose the data after you manipulated them, the use of third-party libraries or plugins, and so on.
  • Database Guidelines clarify how to design a database that shall become part of the Open Data Hub platform.

Both of them are summarised in the remainder of this section, and can be found in full version in the pages Platform Guidelines - Full Version and Database Guidelines - Full Version respectively

Platform Guidelines - Bignami Version

The Platform Guidelines contain the software and programming language requirements, coding conventions, and directions for development. This section contains only the most important points.

Please check the full version of this document at Platform Guidelines - Full Version if you want to know more details, if you have some doubt or if what you were looking for is not mentioned in this summary.

  • Programming Language is Java, in its latest or second to last version.
  • The source code must be documented according to the Javadoc style guide and tags.
  • Java components of Open Data Hub can be developed as libraries, standalone applications, or server applications running in Apache Tomcat.
  • The source code is built nightly; build configuration should be provided in either Ant or Maven (preferred), Makefile, or shell script.
  • Third party libraries can be used, provided they are established, FOSS-licenced, and do not overlap functionalities. This applies also to third party libraries used in application developed in other languages.
  • Front-end applications can be deployed in Javascript, version EC 2015, and must support modern browsers.
  • Node.js can be used to deploy headless or server applications.
  • Web front ends use the latest HTML and CSS versions, must work on mobile devices (responsive design) and should implement some basic accessibility principle.
  • JSON must be used as exchange language, while XML is welcomed as well.
  • The latest or second to last version Apache Tomcat is used to run server application; only API/REST end points have direct access to the database server.
  • There’s no file system persistence, everything must be stored in the DB. JDBC data source and passwords should be stored in environmental variables.
  • Pay attention to RAM usage, applications will undergo load testing.
  • PostgreSQL RDBMS is used, but not in its recent release (expect to use 2-3 versions before the latest), PostGIS spatial extension is required as well.
  • Developers will have an unprivileged role to access the DB and must follow best practices to query the DB from Java/Javascript.

Database Guidelines - Bignami Version

The Database Guidelines contain the database design and database programming principles along with software version requirements. This section contains only the most important points.

Please check the full version of this document at Database Guidelines - Full Version if you want to know more details, if you have some doubt or if what you were looking for is not mentioned in this summary.

  • The database can be designed with one of the Relational Model, Object-Relational Mapping (ORM), or Semi-structured Data methodologies.
  • A database designed with either methodology must be shipped with DDL - schema files containing the CREATE statements.
  • Each database must include a version table and indices on tables.
  • All (SQL) source code must be well-documented, with in-line comments and higher level documentation.
  • Use standard database features - Sequences, primary and foreign keys, constraints (unique, check, not null), default values, views, and so on and so forth.
  • Separate business logic from database design; avoid stored procedure as much as possible.
  • Small procedures and functions, if needed. must be written in PL/PgSQL.
  • Do not use foreign data wrappers.
  • Consider using declarative partitioning for large tables - and contact Open Data Hub team beforehand to discuss it.
  • Always use UTF8 character encoding and do not override it.
  • Default collation is en_US, which works well for German and Italian as well.
  • Never use money type, but numeric.
  • Dates and time stamps must be store to avoid ambiguity. Never store them as text, but rather use their data types, date (in UTC format) and timestamp with timezone. Unix timestamp is accepted as well.
  • When using or manipulating JSON data always follow ISO_8601 standard.