Json App Development

DSL Value Types

All dynamic values use one of four structured formats.

1. $ref — Reference Values

Reference state, props, or computed.

{ "$ref": "state.count" }
{ "$ref": "props.userId" }
{ "$ref": "computed.fullName" }
{ "$ref": "state.formData.username" }

Rules:

• Must contain a dot . separating prefix from variable
• Valid prefixes: state, props, computed
• Format: prefix.variable or prefix.variable.nested.path
• Without a dot, the value is silently returned unchanged (invalid)

2. $expr — Expression Values

JavaScript expressions evaluated at runtime via new Function().

{ "$expr": "$state.count > 0" }
{ "$expr": "$state.user?.name || 'Anonymous'" }
{ "$expr": "$props.title" }

Auto-transformations in expressions:

Available context: props, state, computed, methods, emit, slots, attrs, provide, coreScope

Note: state is a Proxy that auto-unwraps .value. Write $state.count, not $state.count.value.

3. $fn — Function Values

Inline JavaScript function bodies.

Shorthand (no params):

{ "$fn": "state.count++" }

With params (object format):

{
  "$fn": {
    "params": ["event", "data"],
    "body": "console.log(event, data)"
  }
}

With params (inline triple-brace JSON):

{ "$fn": "console.log(args[0])", "params": "{{{ {\"event\": null} }}}" }

Auto-transformations in function body:

Available context: props, state, computed, methods, emit, slots, attrs, provide, args, coreScope

Validation rules:

• body must be a string
• params must be an object (or {{{...}}} JSON string)

4. $scope — Service Injection

Access core services.

{ "$scope": "core.api" }
{ "$scope": "core.storage" }

Available scope names: core, goal

CoreScope services (via $_core):

Component Schema Structure

{
  "name": "MyComponent",
  "props": { ... },
  "emits": { ... },
  "state": { ... },
  "computed": { ... },
  "methods": { ... },
  "watch": { ... },
  "provide": { "items": [...] },
  "inject": { "items": [...] },
  "lifecycle": { ... },
  "components": { ... },
  "render": { ... },
  "styles": { "css": "...", "scoped": true }
}

Required: name (non-empty string), render (object)

State

"state": {
  "count": { "type": "ref", "initial": 0 },
  "formData": { "type": "reactive", "initial": { "name": "", "age": 0 } },
  "user": { "type": "shallowRef", "initial": null },
  "config": { "type": "shallowReactive", "initial": { "theme": "dark" } },
  "nameRef": { "type": "toRef", "source": "props", "key": "name" },
  "allRefs": { "type": "toRefs", "source": "props" },
  "readOnlyConfig": { "type": "readonly", "source": "state.formData" }
}

Computed

"computed": {
  "isValid": {
    "get": { "$fn": "return state.count > 0" }
  },
  "fullName": {
    "get": { "$fn": "return state.firstName + ' ' + state.lastName" },
    "set": { "$fn": "var parts = args[0].split(' '); state.firstName = parts[0]" }
  }
}

• get required, set optional
• Values must be $fn format

Methods

"methods": {
  "increment": { "$fn": "state.count++" },
  "loadData": {
    "$fn": "$_core._api.get('/api/data').then(function(res) { state.items = res.data })"
  }
}

Watch

"watch": {
  "watchCount": {
    "source": { "$expr": "$state.count" },
    "handler": { "$fn": "console.log('changed:', args[0])" },
    "immediate": true,
    "deep": false,
    "flush": "post",
    "type": "watch"
  }
}

• type: "watch" | "effect" (default "watch")
• flush: "pre" | "post" | "sync"

Lifecycle

"lifecycle": {
  "onMounted": { "$fn": "methods.loadData()" },
  "onUnmounted": { "$fn": "console.log('cleanup')" }
}

Each hook accepts a single $fn or $fn[] array.

Valid hooks: onMounted, onUnmounted, onUpdated, onBeforeMount, onBeforeUnmount, onBeforeUpdate, onErrorCaptured, onActivated, onDeactivated.

Props

"props": {
  "title": {
    "type": "String",
    "required": false,
    "default": "Default Title",
    "validator": { "$fn": "return typeof args[0] === 'string'" }
  }
}

type values: "String" | "Number" | "Boolean" | "Array" | "Object" | "Function" | "Symbol" | "BigInt"

Components

"components": {
  "MyButton": { "type": "local", "source": "./components/MyButton.vue" },
  "AsyncChart": {
    "type": "async",
    "source": "./components/Chart.vue",
    "loadingComponent": "LoadingSpinner",
    "errorComponent": "ErrorFallback",
    "delay": 200,
    "timeout": 3000
  }
}

Styles

"styles": {
  "scoped": true,
  "css": ".my-component { color: red; }"
}

VNode Definition

{
  "type": "div",
  "props": {
    "class": "container",
    "style": "color: red"
  },
  "children": [
    "Hello",
    { "type": "span", "children": ["World"] }
  ],
  "directives": { ... },
  "key": "unique-key",
  "ref": "myRef"
}

• type (required): HTML tag name or registered component name
• props: static or dynamic properties
• children: text, numbers, VNodes, or expressions
• directives: Vue directives
• key: Vue key for list rendering
• ref: template ref name

Special: type: "template" renders children directly without a wrapper element.

Directive System

vIf / vElseIf / vElse

{ "type": "div", "directives": { "vIf": { "$expr": "$state.step === 1" } }, "children": ["Step 1"] },
{ "type": "div", "directives": { "vElseIf": { "$expr": "$state.step === 2" } }, "children": ["Step 2"] },
{ "type": "div", "directives": { "vElse": true }, "children": ["Other"] }

• vIf / vElseIf values must be $expr
• vElse value must be boolean true
• Must appear consecutively in children array; non-conditional siblings reset the chain

vFor

{
  "type": "div",
  "directives": {
    "vFor": {
      "source": { "$expr": "$state.items" },
      "alias": "item",
      "index": "idx"
    }
  },
  "children": [{ "type": "span", "children": [{ "$expr": "$state.item.name" }] }]
}

• source must be $expr, evaluates to array or object
• alias is the per-item variable name (injected into render context state)
• index optional, index variable name

vModel

{
  "type": "AInput",
  "directives": {
    "vModel": {
      "prop": { "$ref": "state.formData.username" },
      "arg": "value",
      "event": "update:value"
    }
  }
}

Or multiple bindings:

"vModel": [
  { "prop": { "$ref": "state.value" }, "arg": "modelValue" },
  { "prop": { "$ref": "state.checked" }, "arg": "checked" }
]

• prop must be $ref format (StateRef or PropsRef)
• arg defaults to "modelValue"
• event defaults to "update:${arg}"

vOn

{
  "type": "button",
  "directives": {
    "vOn": {
      "click": { "$fn": "methods.handleClick()" },
      "submit.prevent": { "$fn": "methods.handleSubmit()" }
    }
  }
}

• Keys: event names, optional .prevent / .stop modifiers
• Values: $fn format
• Generates onClick, onSubmit etc.

vBind

{
  "directives": {
    "vBind": {
      "class": { "$expr": "$state.isActive ? 'active' : ''" },
      "disabled": { "$expr": "$state.loading" }
    }
  }
}

• Keys: attribute/prop names
• Values: $expr

vShow

{ "directives": { "vShow": { "$expr": "$state.isVisible" } } }

Sets style.display = 'none' when falsy; element still renders.

vHtml / vText

{ "directives": { "vHtml": { "$expr": "$state.htmlContent" } } }
{ "directives": { "vText": { "$expr": "$state.text" } } }

Override children completely.

vSlot

{
  "type": "template",
  "directives": {
    "vSlot": {
      "name": "headerCell",
      "props": ["column"]
    }
  },
  "children": [...]
}

• name: slot name (default "default")
• props: array of slot prop variable names to expose

vOnce

{ "directives": { "vOnce": true } }

Boolean true.

Render Definition

"render": {
  "type": "template",
  "content": { "type": "div", "children": ["Hello"] }
}

Or function-based:

"render": {
  "type": "function",
  "content": { "$fn": "return h('div', null, 'Hello')" }
}

• type: "template" | "function"

Common Patterns

Form with Validation

{
  "name": "LoginForm",
  "state": {
    "formData": { "type": "reactive", "initial": { "username": "", "password": "" } },
    "loading": { "type": "ref", "initial": false }
  },
  "computed": {
    "isValid": {
      "get": { "$fn": "return state.formData.username && state.formData.password" }
    }
  },
  "methods": {
    "submit": {
      "$fn": "state.loading = true; $_core._api.post('/login', state.formData).then(function(res) { state.loading = false })"
    }
  },
  "render": {
    "type": "template",
    "content": {
      "type": "AForm",
      "children": [
        {
          "type": "AFormItem",
          "children": [
            {
              "type": "AInput",
              "directives": {
                "vModel": { "prop": { "$ref": "state.formData.username" } }
              }
            }
          ]
        },
        {
          "type": "AButton",
          "props": { "disabled": { "$expr": "!$state.isValid || $state.loading" } },
          "directives": {
            "vOn": { "click": { "$fn": "methods.submit()" } }
          },
          "children": [{ "$expr": "$state.loading ? 'Loading...' : 'Login'" }]
        }
      ]
    }
  }
}

Conditional Rendering Chain

"children": [
  { "type": "ASpin", "directives": { "vIf": { "$expr": "$state.loading" } } },
  { "type": "div", "directives": { "vIf": { "$expr": "!$state.loading && $state.items.length" } }, "children": [...] },
  { "type": "AEmpty", "directives": { "vElse": true } }
]

vFor + vSlot

{
  "type": "ATable",
  "props": { "dataSource": { "$ref": "state.items" } },
  "children": [
    {
      "type": "template",
      "directives": { "vSlot": { "name": "renderItem", "props": ["item"] } },
      "children": [
        { "type": "span", "children": [{ "$expr": "$state.item.name" }] }
      ]
    }
  ]
}

Validation Rules

When writing JSON schemas, enforce these rules:

1. Top-level: name non-empty string, render required
2. render.type: only "template" or "function"
3. VNode.type: non-empty string
4. vIf/vElseIf: values must be $expr
5. vFor: source is $expr, alias is string
6. vModel.prop: must be $ref format
7. vOn handlers: must be $fn
8. vBind values: must be $expr
9. vHtml/vText: must be $expr
10. $fn.body: must be string
11. $fn.params: must be object
12. $ref: must contain dot separating prefix and variable
13. $ref prefix: only state, props, computed
14. state reactive/shallowReactive: initial must be object
15. state toRef/toRefs: must have source field
16. computed: must have get as $fn
17. watch: must have source ($expr) and handler ($fn)

Common Mistakes

Validation Tool

After writing or modifying a JSON schema, always validate it using the validate-schema tool:

validate-schema file_path="path/to/schema.json"

The tool checks all validation rules listed above and reports errors with exact paths. Run validation before considering a schema complete.

Guardrails

• Always validate schemas with the validate-schema tool after writing
• Use $ref, $expr, $fn, $scope formats exclusively — no other dynamic value formats exist
• State is auto-unwrapped via Proxy; never use .value in expressions or functions
• Keep conditional chains (vIf/vElseIf/vElse) consecutive in children arrays
• Test schemas with real data to verify expression evaluation
• Component names in VNode type must match registered component names exactly