Backstack - App schemas

Application schemas encapsulate all pre-authentication and feature distribution information necessary for your codebase to serve your application directly from the client, eliminating the need for an API calls.

The API will handle the login process and provide a unique Session object for post-authentication logic processing.

Creating app schemas

Use the Backstack dashboard to specify all elements of your application, then download the schema for integration into your codebase.

Schemas are compiled using values from various resources, and the dashboard alerts you when any changes impact an existing applications schema.

Codebase implementation

Incorporate the schema values into your codebase using the method of your choice.

// javascript
<script type="text/javascript" src="configs/app-schema.json"></script>

// react
import {app, uri} from '@/configs/app-schema.json'

...

console.log(app.title, uri.login)

The App Schema object

// app schema object
{
  "schema_version": "0.8.1",
  "app": {
    "id": "app_1234567890",
    "title": "Acme Service",
    "pub_key": "pub_key_1234567890",
    "alow_signup": true,
    ...
  },
  "domains": {
    "dom_1234567890": {
      "title": "App",
      "allow_signup": true,
      ...
      "versions": {
        "ver_1234567890": {
          "title": "App",
          ...
        },
        ...
      },
      "network": {
        "dom_2345678901": {
          "monetized": true
        },
        ...
      }
    },
    ...
  },
  "optional_features": {
    "distribution": {
      "ver_1234567890": [
        "account-invoices",
        ...
      ],
      ...
    },
    "list": {
      "account-invoices": {
        "title": "Account Invoices",
        "description": null
      },
      ...
    }
  },
  "access": {
    "ver_1234567890": {
      "account-versions": {
        "rol_1234567890": "crud",
        ...
      },
      ...
    },
    ...
  },
  "roles": {
    "distribution": {
      "ver_1234567890": [
        "rol_1234567890",
        ...
      ],
      ...
    },
    "list": {
      "rol_1234567890": {
        "title": "Super User",
        "description": "The Super User can do anything on the system."
      },
      ...
  }
}

Property	Type	Description
`schema_version`	string	The version of the compiled schema.
`app.id`	string	The application ID,
`app.title`	string	The application title.
`app.description`	string	The application description.
`app.pub_key`	string	The Backstack public API key for the application.
`app.allow_signup`	Boolean	Whether there are domains configured for signup. Use this value to determine displaying signup information during login.
`domains`	Array	The application domains. Keys are domain IDs and values are domain details.
`domains[domain_id].title`	String	The domain title.
`domains[domain_id].description`	String	Te domain description.
`domains[domain_id].allow_signup`	Boolean	Whether the domain allows public signup.
`domains[domain_id].signup_help`	String	The domain signup help.
`domains[domain_id].versions`	Array	An array of versions configured for the domain. Keys are version IDs and values are additional data.
`domains[domain_id].versions[version_id].title`	String	The version title.
`domains[domain_id].versions[version_id].description`	String	The version description.
`domains[domain_id].network`	Array	An array of domains configured as child domains. The `session.account.domain_id` will be able to create networked accounts in these domains.
`domains[domain_id].network[domain_id].monetized`	Boolean	Whether the network allows fees. Use this value for displaying the fee percentage option during account network creation.
`optional_features.distribution[version_id]`	Array	Keys are version IDs and values are an array of feature IDs available optionally for the version. Use these values coupled with the `optional_features.list` data to compile an HTML list for managing account subscriptions.
`optional_features.list[feature_id].title`	String	The feature title.
`optional_features.list[feature_id].description`	String	The feature description.
`access[version.id]`	Array	Keys are the version IDs and values are an array of feature IDs and the assigned RBAC.
`access[version.id][feature_id]`	Array	Keys are role IDs and values access permissions.
`roles.distribution[version_id]`	Array	Keys are version IDs and values are an array of role IDs available for the version. Use these values coupled with the `roles.list` data to compile an HTML list for managing user roles.
`roles.list[role.id].title`	Array	The role title.
`roles.list[role.id].description`	Array	The role description.

Extracting data from the schema

The schema is structured to offer valuable data with minimal file size.

Provide a select using the following logic. Show a help div and change the form action with the select onChange() event.

// extracting app schema values for creating a signup domain dropdown

let options = []
Object.keys(domains).map((id) => {
    if (domains[id].allow_signup) {
        options.push({
            value: id,
            label: domains[id].title
        })
    }
})

// select.onChange event
console.log({
  "domainDesc": domains[select.value].description;
  "domainHelp": domains[select.value].help;
});

User role assignment

The following logic will provide for a group of checkboxes when assigning roles.

// extracting app schema values for creating role checkboxes

Object.keys(roles.distribution[session.account.version_id]).map((id) => {
  console.log({
    "name": "roles",
    "value": id,
    "selected": session.user.roles.includes(id),
    "text": roles.distribution[session.account.version_id][id].title + ': ' + roles.distribution[session.account.version_id][id].description
  });
}

Version subscription

Provide radios to allow accounts to change versions. Indicate the current selection.

// extracting app schema values for account versioning options

Object.keys(domains[session.account.domain_id].versions).map((id) => {
  console.log({
    "active": session.account.version_id === id,
    "title": domains[session.account.domain_id].versions[id].title,
    "description": domains[session.account.domain_id].versions[id].description
  });
});

Optional feature subscription

If the accounts version has optional features available, you'll want to offer methods for activating/deactivating them on your page.

// extracting app schema vaues  for creating an optional features list

optional_features.distribution[session.account.version_id].map((id) => {
  console.log({
    "id": id,
    "title": optional_features.list[id].title,
    "description": optional_features.list[id].description,
    "active": session.account.optional_features.contains(id)
  });
});