Language

Application

PropertyTypeDescription
idStringunique application identifier
kindApplicationKinddefines the kind of an application, potentially changing some of the application aspects below
infoApplicationInfodefines user-readable information about the app
permissionsApplicationPermissionsdefines what the application can do, in the form of roles granted and/or data debit requested
setupApplicationSetuphow does one start using the app?
statusApplicationStatushow does the HAT tell if the app is active

ApplicationKind

Defines the kind of an application, potentially changing some of the application behaviour

PropertyTypeDescription
kindString (App, DataPlug or Tool)defines the kind of an application, potentially changing some of the application aspects below. Options include:
App - a full, external application that uses HAT as a backend
DataPlug - a DataPlug that pulls data in from a remote source on behalf of the user
Tool - a tool that has UI integrated within a HAT application, but may need to rely on a separate backend service for processing data
urlStringURL where general information about the application can be found
iosUrlString, OptionalURL where iOS-specific information about the application can be found, e.g. the Applciation’s App Store page
androidUrlString, OptionalURL where Android-specific information about the application can be found

ApplicationInfo

Defines user-readable information about the app

PropertyTypeDescription
versionStringuses three-number, dot-separated versioning in the spirit of semantic versioning to track changes to application requirements and allow to signal backward-compatibility or required updates as the application evolves
publishedBooleanBoolean flag indicating whether this version if the application has been published
nameStringhuman-readable name of the application
headlineStringone sentence description of what the application does
descriptionFormattedTextformatted text (currently plaintext and optionally Markdown and HTML) with full details of the application
dataPreviewList of DataFeedItema sequence of items main data feed structure, to show a generic preview of what data created by the application on the HAT will include
graphicsApplicationGraphicsgraphical elements to build the UI from, primarily images. Each follows the format of a “Drawable” object, which has a url to the “normal” size image as well as optional ones sized as small, large and extra-large, targeting different screen sizes

FormattedText

Provides text formatted for the various formats used: plaintext, markdown, html…

PropertyTypeDescription
textStringPlaintext (unformatted) text
markdownString, OptionalMarkdown-formatted text
htmlString, OptionalHTML-formatted text

ApplicationGraphics

Graphical elements to build the UI from, primarily images. Each follows the format of a “Drawable” object, which has a url to the “normal” size image as well as optional ones sized as small, large and extra-large, targeting different screen sizes

PropertyTypeDescription
bannerDrawableBanner image to be shown in application listing
logoDrawableLogo of the app
screenshotsList of DrawableA list of screenshots demoing the application

Drawable

PropertyTypeDescription
normalURL (String)URL to a normal-size (default) graphic element to use
smallURL (String), OptionalURL to a small-size graphic element to use, targeted at small screens (less than 576px)
largeURL (String), OptionalURL to a large graphic element to use, targeted at large screens (above 992px)
xlargeURL (String), OptionalURL to an extra-large graphic element to use, targeted at largest screens (above 1200px)

ApplicationPermissions

defines what the application can do, in the form of roles granted and/or data debit requested

PropertyTypeDescription
rolesGrantedList of UserRolea list of roles granted for the application (/the HAT owner using the application), such as “Owner” or “DataDebit”. Although it would be the owner user in majority of cases when using those apps, they all have limited permissions depending on what has been approved
dataRequiredDataDebitRequest, Optionala data debit request information for the application when it operates as a “Data Acquirer” and downloads the data somewhere else (e.g. Notables backend service). Such Data Debits always have an ID of “app-

ApplicationSetup

Setup process - how does one start using the app?

PropertyTypeDescription
kindStringthe kind of application setup: Internal or External
onboardingList of OnboardingStep, Optionala few onboarding steps with simple heading, illustration, text, to explain to the user what the application does and how it interacts with them
preferencesApplicationPreferencesa list of preferences, with default values
url/iosUrl/androidUrlURL (String), Optionalidentifying the setup URL for the different platforms available

The main difference between Internal and External is that Internal setup happens without leaving the app, where all controls are presented in the controlling UI, while External is an external process, where the user is sent off to another interface to set up. In both cases, “Permissions” needs an explicit approval step

ApplicationStatus

Status check process - how does the HAT tell if the app is active.

PropertyTypeDescription
kindStringthe kind of application status check: Internal or External
compatibilityVersionindicates the lowest version number this version is compatible with, primarily - in case of permission changes
recentDataCheckEndpointHAT Data Endpoint (String), Optionalwhich HAT data endpoint to check for the most recent timestamp of data saved, e.g. to see that the application has recently been active
statusUrlURL (String), Set when kind=Externalidentifying the status check URL. The URL is called with x-auth-token encoding user’s token in a header
expectedStatusHTTP Status code (Numeric), Set when kind=Externalidentifying the expected status code in response to status check request

In both cases, HAT has the responsibility of checking: - if the application has been enabled - if the currently set up version is compatible with the one available publicly - timestamp of the most recent data available, if the setting is included - whether the Data Debit has been setup, enabled and matches the currently required one - making an authenticated call to status URL, checking the status reported by the remote system