JSON Flow Format

JSON Flow Format

A NotebookFlowKit JSON file contains a flow name and an ordered list of screens.

{
  "name": "StarterFlow",
  "screens": []
}

Basic Example

{
  "name": "StarterFlow",
  "screens": [
    {
      "id": "welcome",
      "type": "text",
      "title": "Welcome",
      "subtitle": "Let's personalize your app",
      "next": "goal"
    },
    {
      "id": "goal",
      "type": "choice",
      "title": "What is your goal?",
      "options": ["Focus", "Fitness", "Learning"],
      "next": "name"
    },
    {
      "id": "name",
      "type": "input",
      "title": "What should we call you?",
      "next": "done"
    },
    {
      "id": "done",
      "type": "completion",
      "title": "You're ready",
      "subtitle": "Your setup is complete"
    }
  ]
}

Screen Fields

Field	Type	Required	Description
id	String	Yes	Unique screen identifier.
type	String	Yes	Screen type.
title	String	Yes	Main title shown on the screen.
subtitle	String	No	Secondary text shown below the title.
options	Array	For choice screens	Available options for choice and multi-choice screens.
placeholder	String	No	Placeholder for input screens.
next	String or Object	No	Next screen ID or conditional route map.
required	Boolean	No	Whether the user must answer before continuing.

Supported Screen Types

Text

{
  "id": "welcome",
  "type": "text",
  "title": "Welcome",
  "subtitle": "Let's get started",
  "next": "goal"
}

Single Choice

{
  "id": "goal",
  "type": "choice",
  "title": "What is your goal?",
  "options": ["Focus", "Fitness", "Learning"],
  "next": "name"
}

Multi Choice

{
  "id": "topics",
  "type": "multiChoice",
  "title": "Pick your topics",
  "options": ["SwiftUI", "Python", "Design"],
  "next": "done"
}

Text Input

{
  "id": "name",
  "type": "input",
  "title": "What should we call you?",
  "placeholder": "Your name",
  "next": "done"
}

Completion

{
  "id": "done",
  "type": "completion",
  "title": "You're ready",
  "subtitle": "Your setup is complete"
}

Accepted Type Aliases

NotebookFlowKit accepts a few aliases to make JSON authoring friendlier:

Alias	Normalized Type
single_choice	choice
singlechoice	choice
multi_choice	multiChoice
multichoice	multiChoice
text_input	input
textinput	input
done	completion

Validation Rules

The JSON loader validates:

• the flow must contain at least one screen
• screen IDs must be unique
• next targets must point to existing screens
• conditional route targets must point to existing screens
• choice and multiChoice screens must include options