buildingenvelopedata.org API specification

This specification of an Application Programming Interface (API) is designed to facilitate the exchange of data about building envelopes. Several databases use the same API specification to offer data about components. A metabase manages for example the identifiers of components and institutions which must be the same for all databases.

This API specification consists of GraphQL schemas to specify a GraphQL endpoint and JSON Schemas to specify the format of the responses. GraphQL schemas are in the directory ./apis. There is a visualization of the GraphQL schema of the metabase and of the database. Example GraphQL queries and mutations are in the directory ./requests. You can try the queries of the tutorial at the GraphQL endpoint of the metabase.

GraphQL queries deal with metadata about data sets. They are used to find suitable data sets. The response to a GraphQL query is in JSON. For example, optical.json defines the metadata about an optical data set. It can include a URL as locator to download the pure data.

The format BED-JSON is used for the pure data. solarTransmittanceReflectance.json is an example of a pure data set. It must be valid against the JSON Schema opticalData.json.

JSON schemas are in the directory ./schemas and example JSON files in the directory ./examples. The directory ./tests/valid provides test JSON files that are supposed to be valid and the directory ./tests/invalid JSON files that are supposed to be invalid. A visualization of the JSON Schema of an optical data point is available together with visualizations of examples of optical data points. A visualization of the JSON Schema of a calorimetric data set is available together with visualizations of examples of calorimetric data sets.

The following introduction explains the structure for new users and the section "On your Linux machine" explains how you can work with the API specification.

Table of Contents

I don't want to read this whole thing, I just have a question!

Introduction

How to use this repository

• For beginners
• In your web browser
• On your Linux machine

Code of Conduct

Implementation of the API specification

How to contribute

I don't want to read this whole thing, I just have a question!

If you have a question, please read this README.md and search this repository with its wiki, discussions, Questions and Answers and existing issues for the answer.

If you don't find the answer there and if your question is related to the code, please raise a new issue and add the tag question.

Introduction

The example JSON files ./examples present examples of data formatted according to the JSON schemas and could be part of the response of a GraphQL endpoint. For example, nearnormalHemisphericalSolarReflectanceAccordingToStandard.json is an example of data about a component with an identifier and an optical data set.

Like all data about components, the example is valid against the schema component.json which references optical.json, calorimetric.json and more. In this way, metadata about one component can be exchanged as well as optical data, calorimetric data and more about this component.

An optical data set can include metadata like the standard according to which the optical data was determined. The pure optical data is formatted according to opticalData.json, because optical.json references opticalData.json.

Similarly, calorimetric.json defines the metadata about a calorimetric data set and refers to calorimetricData.json for the pure calorimetric data which is illustrated by the example bistMeasurement.json.

How to use this repository

For beginners

With you web browser, you can search our wiki, the issues and pull requests and contribute to them.

In your web browser

In order to browse the code conveniently with Codespaces, open building-envelope-data/api in your favorite web browser, click on the button "Code" in the top-right corner, select the tab "Codespaces", and on the first usage click on + to create a new codespace and on subsequent usages click on the name of an existing codespace.

If you are developing this repository further, you can follow the description With Docker. For example, you can test and format your contributions with

cp ./.env.sample ./.env
make shell
make compile
make examples
make test
make format

On your Linux machine

In order to use our development tooling, for example, to format code and to run tests, follow the instructions below.

1. Open your favorite shell, for example, good old Bourne Again SHell, aka, bash, the somewhat newer Z shell, aka, zsh, or shiny new fish.
2. Install Git by running

   sudo apt install git-all

   on Debian-based distributions like Ubuntu, or

   sudo dnf install git

   on Fedora and closely-related RPM-Package-Manager-based distributions like CentOS. For further information see Installing Git.
3. Clone the source code by running

   git clone git@github.com:building-envelope-data/api.git

   and navigate into the new directory building-envelope-data by running

   cd building-envelope-data

4. Prepare your environment by running

   cp ./.env.sample ./.env

   and adjusting the copied environment to your needs.

With Docker

5. Install Docker Desktop, and GNU Make.
6. List all GNU Make targets by running

   make help

   The targets name, tag, build, remove, run, shell, remove-containers, remove-volumes, and serve can be used to interface with Docker. The other ones can be used within bash inside a Docker container:
   • compile validates the JSON schemas against the JSON Schema meta-schemas and the GraphQL schemas against the GrahpQL specification,
   • test validates the tests against the schemas,
   • examples validates the examples against the schemas,
   • format formats source files,
   • introspect introspects the GraphQL schemas,
   • dos2unix converts Windows-style to UNIX-style line endings,
   • install-tools installs development tools from the lock file, and
   • update-tools updates development tools to the latest compatible minor versions.
7. Drop into bash with the working directory /app, which is mounted to the host's working directory, inside a fresh Docker container based on Debian Linux everything installed by running

   make shell

   If necessary, the Docker image is (re)built automatically, which takes a while the first time.
8. Do something with the project like validating the schemas by running

   make compile

9. Drop out of the container by running

   exit

   or pressing Ctrl-D.

Without Docker

5. Install GNU Bash, GNU Make, and npm.
6. Install the development tools in package.json by running

   make install-tools
   

   which in particular installs the command-line interface for Another JSON Schema Validator (AJV), namely ajv-cli as Node package to be executed through npx, for example,

   npx ajv --help
   

7. Drop into bash.
8. Do something with the project as elaborated above.

Note that another POSIX-compatible shell than GNU Bash should also do. See also the POSIX specification and the POSIX FAQ.

Also note that GNU Make takes the shell from the variable SHELL or, if not set, the program /bin/sh. See Choosing the Shell

Code of Conduct

Our Code of Conduct is the guideline of our collaboration.

Implementation of the API specification

A database which implements this API specification is presented by https://github.com/building-envelope-data/database . A metadatabase wich implements this API specification is presented by https://www.buildingenvelopedata.org/ (front end) https://www.buildingenvelopedata.org/graphql/ (back end) and https://github.com/building-envelope-data/metabase (source code). The metadatabase manages for example the identifiers for components and institutions which must be the same for all databases. The databases manage the data sets of the components.

How to contribute

If you are interested to contribute by questions, reporting bugs or suggesting enhancements, please see CONTRIBUTING.md for further details.