Skip to content

Spec Schema Definition

This document defines the structure and rules for the JSON format used to represent Devity Specs. This JSON is generated by the Backend, published to the CDN, and consumed by the Client SDKs.

1. Top-Level Structure

The root of a Devity Spec JSON object contains metadata and the main workflow definition.

{
  "specVersion": "1.0.0",       // Semantic version of the spec format itself
  "specId": "onboarding_v2",    // Unique identifier for this specific spec
  "version": 3,                 // Internal version number of this spec content
  "createdAt": "2024-07-28T10:00:00Z", // ISO 8601 timestamp
  "entryPoint": "screen_welcome", // ID of the initial screen to load
  "globalData": { ... },       // Optional: Data available throughout the spec
  "screens": {
    "screen_welcome": { ... },  // Definition for the 'welcome' screen
    "screen_details": { ... }   // Definition for the 'details' screen
    // ... other screens
  },
  "actions": {
    "action_submit": { ... },   // Definition for a 'submit' action
    "action_navigate_details": { ... }
    // ... other reusable actions
  },
  "rules": {
    "rule_enable_submit": { ... } // Definition for a rule
    // ... other rules
  }
}
  • specVersion (String, Required): Specifies the version of the schema this spec adheres to. Ensures SDK compatibility.
  • specId (String, Required): A unique identifier for this particular workflow/spec (e.g., user_profile, product_listing_v3). Managed via the Console.
  • version (Integer, Required): An incremental version number for the content of this specific specId. Managed by the backend publishing process.
  • createdAt (String, Required): ISO 8601 timestamp indicating when this version was published.
  • entryPoint (String, Required): The id of the screen object within the screens map that should be displayed first when the spec is loaded.
  • globalData (Object, Optional): A container for data that can be accessed from anywhere within the spec (e.g., configuration, user info loaded initially).
  • screens (Object, Required): A map where keys are unique screen IDs (strings) and values are Screen Objects.
  • actions (Object, Optional): A map where keys are unique action IDs (strings) and values are Action Objects. Allows defining reusable actions.
  • rules (Object, Optional): A map where keys are unique rule IDs (strings) and values are Rule Objects.

2. Screen Object

Defines a single screen within the workflow.

{
  "id": "screen_welcome",        // String, Required: Unique identifier for this screen within the spec.
  "type": "Screen",             // String, Required: Must be "Screen".
  "backgroundColor": "#FFFFFF", // String, Optional: Screen background color (Hex format, e.g., #RRGGBB, #AARRGGBB).
  "appBar": { ... },          // Object<Widget>, Optional: Definition for the screen's AppBar. Typically a custom AppBar widget or a Row/Stack renderer.
  "body": { ... },            // Object<Renderer|Widget>, Required: Root Renderer or Widget for the screen content.
  "bottomNavBar": { ... },    // Object<Widget>, Optional: Definition for a bottom navigation bar. Typically a custom widget or Row renderer.
  "onLoadActions": [ ... ],   // Array<String>, Optional: Action IDs triggered sequentially when screen initially loads and becomes visible.
  "persistentData": { ... }   // Object, Optional: Data store specific to this screen instance, potentially accessible via `{{state.screenData...}}`. Values might be updated via `SetData` actions targeting this scope.
}
  • id (String, Required): Unique identifier for this screen within the Spec.
  • type (String, Required): Must always be "Screen".
  • backgroundColor (String, Optional): Background color for the screen area. Supports Hex format (e.g., "#FFFFFF", "#80FF0000").
  • appBar (Object, Optional): A standard Widget or Renderer object defining the AppBar.
  • body (Object, Required): The main content of the screen. Must be a single Widget or Renderer object.
  • bottomNavBar (Object, Optional): A standard Widget or Renderer object defining the bottom navigation area.
  • onLoadActions (Array, Optional): An array of action IDs (strings) to be executed sequentially when the screen is first loaded.
  • persistentData (Object, Optional): A key-value store for data associated with this screen instance.

3. Renderer Object

Defines a layout component that arranges child components.

{
  "id": "main_column",        // String, Optional: Unique identifier for referencing this renderer (e.g., from rules).
  "type": "Renderer",         // String, Required: Must be "Renderer".
  "rendererType": "Column",   // String, Required: Specifies the type of layout (e.g., "Column", "Row", "Stack", "Scrollable", "Padding").
  "attributes": { ... },      // Object, Optional: Attributes specific to the `rendererType` (e.g., alignment, spacing).
  "children": [ ... ],      // Array<Object<Renderer|Widget>>, Optional: Child components to be laid out by this renderer.
  "style": { ... }          // Object<Style>, Optional: Common style properties (See [Styling Properties](#9-styling-properties)).
}
  • id (String, Optional): Optional identifier.
  • type (String, Required): Must always be "Renderer".
  • rendererType (String, Required): Determines the layout behavior. Initial supported types:
  • "Column": Arranges children vertically. Attributes might include mainAxisAlignment, crossAxisAlignment, spacing.
  • "Row": Arranges children horizontally. Attributes might include mainAxisAlignment, crossAxisAlignment, spacing.
  • "Stack": Layers children. Children might have positioning attributes.
  • "Scrollable": Makes its single child scrollable. Requires exactly one child. Attributes: scrollDirection (String, Optional: "vertical" (default) or "horizontal").
  • "Padding": Applies padding around its single child. Requires exactly one child. Attributes: padding (Object, Required - See Padding Value). Note: This padding overrides any padding defined in the style object of this renderer.
  • attributes (Object, Optional): Key-value pairs specific to the rendererType.
  • children (Array>, Optional): An array of child Renderer or Widget objects. Required for Column, Row, Stack. Exactly one required for Scrollable and Padding.
  • style (Object