App Specs

An App Spec describes an App to the platform and dictates how Studio UI is setup, amongst other things. It is made of
Root spec - Contains top level settings and references to other JSON documents comprising the App Spec.
​Project level settings​
​Event level settings​
​Elements - List of Elements this App supports along with settings for each element.
​Fields - All of Project, Event and Element level settings refer to fields described in this document.
Root Spec
Root spec defines these properties:
Property
Description
Mandatory
Default
name
App name
yes
​
id
Unique app id. All versions of the same app have the same id.
yes
​
version
App version. Only one app with the same id and version can be available within LViS.
yes
​
base_apps_url
Base URL for App location.
yes
​
listings
Number of past and future events to include in listings. If not set then the values can be set via Studio UI.
no
​
project_settings
Project level settings spec URL.
no
no settings
event_settings
Event level settings spec URL.
no
no settings
elements
Elements spec URL.
no
no Elements
fields
Fields spec URL.
no
no fields
embed_url
App embed URL.
no
​
dash_image
App image URL. Image has to be 100 x 100 px. Make sure it works via HTTPS. This is the image displayed on the dashboard.
no
default app image
extensions
List of extensions required by application. Each extension may have additional configuration.
no
empty list
curation
App requires social curation to be activated
no
false
schedule
App requires Event scheduling functionality
no
true
analytics
App requires Analytics functionality
no
true
live_activity
App requires Live Activity section on Timeline and Analytics pages
no
true
localisation
App supports localisation
no
false
{
  "name": "The Big Question",
  "id": "thebigquestion",
  "version": "1.2.3",
  "base_apps_url": "http://12341234.cloudfont.net/apps",
  "listings": { "past": 1, "future": 2 },
  "embed_url": "/app.html",
  "dash_image": "/config/lvis/app-dash.png",
  "fields": "/config/lvis/fields.json",
  "elements": "/config/lvis/elements.json",
  "project_settings": "/config/lvis/project_settings.json",
  "event_settings": "/config/lvis/event_settings.json",
  "services": {
    "leaderboard": {
      "max_score": 500000
    },
    "submissions": {}
  },
  "curation": true,
  "schedule": true,
  "analytics": false,
  "live_activity": false,
  "localisation": false
}
Conventions
These are merely conventions meant to standardise the structure of the apps. They are not enforced and neither used by Studio in any shape or form.
​
​
Root spec
/config/lvis/spec.json
Embed URL
/app.html
Dashboard app image
config/lvis/app-dash.png
Fields
config/lvis/fields.json
Elements
config/lvis/elements.json
Project settings
config/lvis/project_settings.json
Event settings
config/lvis/event_settings.json
Base App URL
Base App URL format
${base-apps-url}/${id}/${version}
Base App URL for above example
http://12341234.cloudfont.net/apps/thebigquestion/1.2.3
URLs
URLs specified in app spec can be absolute or relative. Relative URLs are relative to base app URL.
Dashboard image URL for example above
http://12341234.cloudfont.net/apps/thebigquestion/1.2.3/config/lvis/app-dash.png
Absolute URL may omit schema
//12341234.cloudfont.net/apps/thebigquestion/1.2.3/config/lvis/app-dash.png
Embed URL
​Embedding and Previewing are enabled by adding embed_url to App Spec. They are disabled if embed_url in App Spec is not specified or set to null.
Extensions
Extension configuration object is passed to the Service.
Reload
There are several scenarios which lead to project's App Spec update, such as
App Spec reload
Switching project App to different version
Switching project to different App
Migration rules
When App Spec is updated the content of the following entities is migrated to the latest App Spec:
Project settings.
Not finished events. Finished events are ignored.
Not published elements. Published elements are ignored.
The migration process described below:
Change
Action
Field is added to Element/Project settings/Event settings spec.
The field is added to the corresponding entity with empty (or default if present) value.
Field is removed from Element/Project settings/Event settings spec.
The fields is removed from corresponding entity.
Field's key in a specs is changed.
Same as sequential removing of the old field and adding the new one.
Field properties in the specs are changed.
Field properties are updated, existing value is converted to the new type (if type changed). Type conversion described in the next section.
Field definition removed.
All references to the field are automatically disabled and field disappears from UI, feeds, etc. If later this field definition is re-introduced then old references are automatically restored.
Field type conversion
These take place when new version of App Spec has the same field, but with a different type.
new field type
data conversion
string
string representation of old value is taken
boolean
"true" or "yes" string value converted to true, other values to false
number
value representing a number is converted to number, otherwise value is converted to null

Environment Setup

Field, Field set, Field section

Last modified 3mo ago

Copy link

On this page

Root Spec

Conventions

Base App URL

Base App URL format

Base App URL for above example

URLs

Dashboard image URL for example above

Absolute URL may omit schema

Embed URL

Extensions

Reload

Migration rules

Field type conversion