AOF Language specification

Table of Contents

Document history

Abstract

This document specifies the structure and content of App-Descriptions for App-Orchestration. The goal is to have a reference specification that all creators of App-Descriptions can refer to.

Contacts

Dipl.-Ing. Johannes Pfeffer is responsible for this document.

E-Mail:

Phone: +49 351 463 33387

At a glance

An App-Description semantically describes an app. It at least contains the following information: about the name of the app, a textual description, the creator, the type of the app, location of binaries and screenshots, entry points and exit points.

App-Descriptions are modeled in W3C’s RDF-format, usually in turtle notation.

App-Descriptions adhere to the open-world assumption, meaning there is no limit to what can be asserted about an app. However, this specification defines a minimum of information that must be given and provides a recommendation on additional information to provide about an app.

App-Descriptions are used in App-Ensembles (see App-Ensemble specification) to provide information about an app, such as available inputs and outputs.

Usage

Introduction

App-Descriptions are described as RDF and are usually written (serialized) in Turtle-format. They are named according to the following schema:

NameOfApp.ttl

An App-Description model consists of the following main parts:

• Definition of prefixes

• Identifier

• Information about the role of the app

• Type and role of the app

• Label and textual description

• Binary location and version

• Dependencies

• Information about the creator(s) of the app

• Entry-Points (with inputs)

• Exit-Points (with outputs)

• Icon and screenshots

• Additional statements about the app

Used Vocabularies & ontologies

The main vocabulary for App-Descriptions is the Application-Orchestration-Framework-Vocabulary with the preferred prefix aof and the base URI http://eatld.et.tu-dresden.de/aof/.

@prefix aof: <http://eatld.et.tu-dresden.de/aof/> .

For describing the creator and her/his contact information, the Dublin-Core Metadata Format (elements and terms) and the FOAF RDF-Schema are used.

@prefix dc: <http://purl.org/dc/elements/1.1/> .

@prefix dcterms: <http://purl.org/dc/terms/>  .
@prefix foaf: <http://xmlns.com/foaf/0.1/> .

To describe android-related properties of an app the Android apk namespace is used.

@prefix android: <http://schemas.android.com/apk/res/android> .

In addition the rdf, rdfs schemas are used as a basic language and the xsd schema is used to define value types.

Definition of Prefixes

It is good practice to add a section with prefixes used in the App-Description.

This section may look like the following listing:

# AOF namespace
@prefix aof: <http://eatld.et.tu-dresden.de/aof/> .

# Used ontologies
@prefix dc: <http://purl.org/dc/elements/1.1/> .

@prefix dcterms: <http://purl.org/dc/terms/>  .
@prefix foaf: <http://xmlns.com/foaf/0.1/> .
@prefix android: <http://schemas.android.com/apk/res/android> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .

In addition, it has proven useful to define some namespaces that may be used only in a certain App-Ensemble.

# Namespaces for THIS App-Ensemble
@prefix ex: <http://example/

Identifier

An App-Description always starts with the following triple:

<http://url_that_uniquely_identifies_the_app> a aof:App .

The subject of this statement is important because it is the main identifier that is used by tools that work with App-Descriptions. It should be long-living and if possible resolve to information about the app. Possibilities are the URL to an App-Store where the app can be downloaded or to a job on a build-server that creates the app.

In this specification we will use ex-prefix (<http://example/>) and the app name ExApp for all examples.

Type and role of the App

There are two bits of information that should be provided about an app. First the rdf:type relation¹ and second the aof:hasAppEnsembleRole relation. Both are optional.

All apps are of type aof:App. Additionally, Android apps are of type aof:AndroidApp. Other platforms are not yet included in this specification. Please note, while this statement is optional it is highly recommended because applications may use it to determine the platform of the app.

ex:ExApp a aof:App, aof:AndroidApp .

There are some special roles for apps that are important for App-Ensembles. Normal apps don’t need this statement.

ex:ExApp aof:hasAppEnsembleRole aof:Conductor .

The aof:Conductor role means that the app can execute App-Ensembles by itself. Also available is aof:AppEnsembleInstaller which implies that the app is able to install App-Ensembles on a platform.

Label and textual description

All apps must have a label (rdfs:label) and description (rdfs:comment).

ex:ExApp rdfs:label "App-Description Specification Example App" ;
  rdfs:comment """
    The rdfs:comment should give a short textual description 
    about the functionality of the app. It may contain *markdown* markup """ .

Binary location and version

If available, the location of a resource where the current binary can be downloaded should be given via the aof:hasInstallableArtifact property. Preferably, this is a direct link to a binary. This property is optional but highly recommended.

ex:ExApp aof:hasInstallableArtifact <http://example/example.apk> .

The version number must be an integer. Version information may be provided in two different ways. The first option is to provide an http-URL to a resource that delivers the version code in the body part of the http response using aof:hasVersion. The second way is to provide a version code integer directly via aof:version. The aof:hasVersion variant supersedes aof:version.

ex:ExApp aof:hasVersion jenkins:AppEnsembleInstaller/buildNumber .

# The alternative:
ex:ExApp aof:version "1"^^xsd:integer .

Dependencies

If the app has dependencies in other apps, i.e. these other apps are required for it to function properly, they may be stated using aof:hasAppDependency.

ex:ExApp aof:hasAppDependency <http://openintents.org/~oi/filemanager> .

The object of this statement should be a URI that is unique and is used in other App-Descriptions when referring to this app.

Creator

Information about the creator(s) is added by asserting one or more of the following statements:

ex:ExApp dc:creator <mailto:max.mustermann@example.org> .

The object of a dc:creator relation is a URI that uniquely identifies a creator (e.g. an e-mail address or a website). At the end of the App-Description resource should be detailed using the FOAF-vocabulary:

<mailto:max.mustermann@example.org> a foaf:Person ;
  foaf:name "Max Mustermann" ;
  foaf:mbox <mailto:max.mustermann@example.org> ;
  foaf:homepage <http://maxmustermann.info/> .

Creator information is optional but highly recommended.

Entry Points

Entry points provide information on how the app is started and what information it can use as input. There must be at least one entry point. Currently, entry points are only specified for Android apps.

A basic entry point looks like this:

ex:ExApp aof:hasEntryPoint [
  a aof:EntryPoint, android:action ;
  android:name "org.aof.action.EXAMPLE_ACTION" ;
  rdfs:label "Example label" ;
  rdfs:comment "
    The comment should give a concise but conclusive description about what the 
    entry point does. """ ;
] .

An entry point may have zero or more inputs. If an entry point is given aof:Input, android:extra, rdfs:comment, aof:isRequired, android:name and aof:hasDatatype are all mandatory.

ex:entry_point_1 aof:hasInput [
  a aof:Input, android:extra ;
  rdfs:comment "Description of the input" ;
  aof:isRequired "False" ;
  android:name "org.aof.extra.POI" ;
  aof:hasDatatype xsd:anyURI 
] .

The statement ex:entry_point_1 a aof:Input, android:extra asserts that the resource is an entry point and also an android extra. Currently, only this type of input is specified and, therefore, must be provided if entry points are given. aof:isRequired states if this input must be provided, android:name gives the name of the extra, i.e. the key to look up the extra data field. There may be a naming convention for android:name that should be followed. For details see the App-Ensemble specification. The property aof:hasDatatype states the data type the extra must have using the xsd: notation.

Exit points

Exit points provide information on data that is generated by an app. When apps provide information on exit points it is assumed that they have been created specifically for App-Orchestration and provide the output data after an orchestration specific user interaction, such as a Done-Button.

Currently exit points are only specified for Android apps.

An exit point must have at least one output. All properties in the example below are mandatory if an exit point is described.

A typical exit point looks like this:

ex:ExApp aof:hasExitPoint [
  a aof:ExitPoint;
  rdfs:label "Main exit point" ;
  rdfs:comment "Description of the exit point" ; 
  aof:hasOutput [
    a aof:Output, android:extra ;
    rdfs:comment "Description of the output" ;
    aof:isGuaranteed "False" ;
    android:name "org.aof.extra.POI" ;
    aof:hasDatatype xsd:anyURI 
  ]
] .

The property aof:isGuaranteed is used to specify if an output will always be available or not. The property android:name is used to give the key for the data field. For the other properties, please see the section on entry points. There may be a naming convention for android:name that should be followed. For details see the App-Ensemble specification.

Icon and screenshots

It is recommended to provide a URI of an icon and some screenshots for all apps because this improves the display in lists, app-stores, etc. greatly. The icon is optional (aof:hasIcon). There may be 0 or 1 main screenshot (aof:hasMainScreenshot) and 0 or more additional screenshots (aof:hasScreenshot).

Example:

# Icon
ex:exApp aof:hasIcon <http://example/icon_placeholder.svg> .

# Screenshots: 1 main screenshot, 2 additional screenshots
ex:exApp aof:hasMainScreenshot [
  foaf:depiction <http://example/sc1.jpg> ; 
  rdfs:comment "Main screenshot"
] . 
ex:exApp aof:hasScreenshot [
  foaf:depiction <http://example/sc2.jpg> ; 
  rdfs:comment "2nd screenshot"
] .
ex:exApp aof:hasScreenshot [
  foaf:depiction <http://example/sc3.jpg> ; 
  rdfs:comment "3rd screenshot"
] .

Additional statements

Since an App-Description lives in the open world assumption, there may be unlimited other statements about an app. Here are some examples:

# References to resources describing the same thing or related things
ex:ExApp owl:sameAs <http://otherExample.org/app > .
ex:ExApp rdfs:seeAlso <http://alternativeAppStore/otherApp .

Terms

A-Z of AOF terms

Classes:

AndroidApp, App, AppEnsembleInstaller, AppEnsembleRole, Conductor, EntryPoint, ExitPoint, Icon, Input, InstallableArtifact, MainScreenshot, Output, Screenshot

Object Properties:

hasAppDependency, hasAppEnsembleRole, hasIcon, hasInstallableArtifact, hasEntryPoint, hasExitPoint, hasInput, hasMainScreenshot, hasOutput, hasScreenshot, hasVersion

Data Properties:

isGuaranteed, isRequired, version

Classes

Template:

Class – Comment

Class: aof:AndroidApp

AndroidApp – An Android App

Class: aof:App

App – An App

Class: aof:AppEnsembleInstaller

AppEnsembleInstaller – The role of being an app that can install App-Ensembles

Class: aof:AppEnsembleRole

AppEnsembleRole – A role in an App-Ensemble

Class: aof:Conductor

Conductor – The role of being an app that can execute (conduct) App-Ensembles

Class: aof:EntryPoint

EntryPoint – An entry point to an app

Class: aof:ExitPoint

ExitPoint – An exit point of an app

Class: aof:Icon

Icon – An icon for an app

Class: aof:Input

Input – An input to an app entry point

Class: aof:InstallableArtifact

Installable Artifact – An artifact that can be installed as an app

Class: aof:MainScreenshot

MainScreenshot – The main screenshot of an app

Class: aof:Output

Output – An output of an app exit point

Class: aof:Screenshot

Screenshot – A screenshot of an app

Object Properties

Template:

Property – Comment

Property: aof:hasAppDependency

hasAppDependency – Indicates an app dependency the object this app needs to be able to function correctly.

The aof:hasAppDependency property relates an aof:App with other apps that it depends upon.

Property: aof:hasAppEnsembleRole

hasAppEnsembleRole – Indicates a role in an App-Ensemble that this app has.

The hasAppEnsembleRole property relates an aof:App to a role it has in an App-Ensemble.

Property: aof:hasIcon,

hasIcon – Indicates an icon for this app.

The aof:hasIcon property relates an aof:App with an icon image, e.g. for use in app stores.

Property: hasInstallableArtifact

hasInstallableArtifact – Indicates an installable artifact, such as a binary executable or an APK-file of this app.

The aof:hasInstallableArtifact relates an aof:App with a binary file that can install it.

Property: aof:hasEntryPoint,

hasEntryPoint – Indicates an entry point this app has.

The aof:hasEntryPoint property relates a aof:App to an entry point that app provides.

Property: hasExitPoint

hasExitPoint – Indicates an exit point this app has.

The aof:hasExitPoint property relates a aof:App to an exit point that app provides.

Property: aof:hasInput

hasInput – Indicates an Input this app has.

The aof:hasInput property relates a aof:EntryPoint to an input it provides.

Property: aof:hasMainScreenshot

hasMainScreenshot – Indicates the main screenshot of this app.

The aof:hasMainScreenshot property relates a aof:App to the screenshot that represents the app best (e.g. in an app store).

Property: aof:hasOutput

hasOutput – Indicates an output that this exit point of an app provides.

The aof:hasOutput property relates a aof:ExitPoint to an output, usually with a key and a value.

Property: aof:hasScreenshot

hasScreenshot – Indicates a screenshot of this app.

The aof:hasScreenshot property relates a aof:App to a screenshot of a view of the app.

Property: aof:hasVersion

hasVersion – Indicates a resource that represents the version of this app.

The aof:hasVersion property relates a aof:App to a http resource that provides an integer representation of the version it its http response body.

Data Properties

Template:

Property – Comment

Property: aof:isGuaranteed

isGuaranteed – Indicates if this output is guaranteed.

This property has the value True if this aof:Output of this exit point of an app is guaranteed, otherwise it is False.

Property: aof:isRequired

isRequired – Indicates if this input is required.

This property has the value True if this aof:Input of this entry point of an app is required, otherwise it is False.

Property: aof:version

version – Indicates the version of some app.

The version of an app is an integer value. It may, e.g., be a build number.

Examples

The following examples provide complete App-Descriptions that may be used as a starting point.

Conductor App

This example describes a conductor app, i.e. an app that executes App-Ensembles. Therefore, it has a aof:hasAppEnsembleRole aof:Conductor statement.

# AOF prefixes
@prefix aof: <http://eatld.et.tu-dresden.de/aof/> .

# Used Ontologies
@prefix dc: <http://purl.org/dc/elements/1.1/> .
@prefix foaf: <http://xmlns.com/foaf/0.1/> . 
@prefix android: <http://schemas.android.com/apk/res/android> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix xml: <http://www.w3.org/XML/1998/namespace> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> . 

# App description
<http://dev.plt.et.tu-dresden.de:8085/jenkins/job/ExampleConductor/LastSuccessfulBuild>
  a aof:App, aof:AndroidApp ;
  aof:hasAppEnsembleRole aof:Conductor ;
  
  # Name and textual description
  rdfs:label "AOF Conductor" ;
  rdfs:comment """
    The *Conductor* is an app that executes App-Ensembles on Android devices.
    """ ;

  # Reference to binary and version information
  aof:hasInstallableArtifact <http://example/Conductor.apk> ;

  # This App-Description provides the version as a http-resource
  aof:hasVersion <http://Example/buildNumber> ;
  # The alternative:
  # aof:version "1"^^xsd:integer ; 

  # Dependencies
  aof:hasAppDependency play:org.openintents.filemanager ;

  # Creator reference, this is detailed at the end of the App-Description
  dc:creator <mailto:johannes.pfeffer@tu-dresden.de> ;  

  # Entry points
  aof:hasEntryPoint [
    a aof:EntryPoint, android:action ;
    android:name "org.aof.action.EXAMPLE_ACTION" ;
    rdfs:label "Start Workflow" ;
    rdfs:comment """
      The comment should give a concise but conclusive description about what the 
      entry point does. """ ;
    aof:hasInput [
      a aof:Input, android:extra ;
      rdfs:comment "Description of the input" ;
      aof:isRequired "False" ;
      android:name "org.aof.extra.POI" ;
      aof:hasDatatype xsd:anyURI 
    ]
  ] ;
  
  # Exit points
  aof:hasExitPoint [
    a aof:ExitPoint;
    rdfs:label "Main exit point" ;
    rdfs:comment "Description of the exit point" ; 
    aof:hasOutput [
      a aof:Output, android:extra ;
      rdfs:comment "Description of the output" ;
      aof:isGuaranteed "False" ;
      android:name "org.aof.extra.POI" ;
      aof:hasDatatype xsd:anyURI 
    ]
  ] ;

  # Icon
  aof:hasIcon <http://example/icon_placeholder.svg> ;

  # Screenshots: 1 main screenshot, 2 other screenshots
  aof:hasMainScreenshot [
    foaf:depiction <http://example/sc1.jpg> ; 
    rdfs:comment "Main screenshot"
    ] ;
  aof:hasScreenshot [
    foaf:depiction <http://example/sc2.jpg> ; 
    rdfs:comment "2nd screenshot"
    ] ;
  aof:hasScreenshot [
    foaf:depiction <http://example/sc3.jpg> ; 
    rdfs:comment "3rd screenshot"
    ] ;

# Additional statements
# Creator
<mailto:johannes.pfeffer@tu-dresden.de> a foaf:Person ;
  foaf:name "Johannes Pfeffer";
  foaf:mbox <mailto:johannes.pfeffer@tu-dresden.de>;
  foaf:homepage <http://www.et.tu-dresden.de/ifa/index.php?id=jp> .

# References to resources describing the same thing or related things
<http://dev.plt.et.tu-dresden.de:8085/jenkins/job/ExampleConductor/LastSuccessfulBuild>

  owl:sameAs <http://appStore/Conductor> ;
  rdfs:seeAlso <http://alternativeAppStore/OtherConductor .

Workflows

Typical lifecycle of App-descriptions

Already during specification of an app a rudimentary app description with entry and exit points can be created. The URI of the app should be fixed already. Then, the App-Description should be updated with every public release of the app.

integrating app-descriptions into the build-process

It may be sensible to integrate publication of the App-Description in the build process of the app. E.g. the App-Description may reside in the project structure for the app and is automatically published to an web server during a release or build process.

Glossary

For an always up-to-date version of the glossary refer to:

https://eatplt02.et.tu-dresden.de/intrawiki/doku.php?id=wiki:documentation:aof:glossary