---
title: 'Data Language Block'
url: 'https://code-evolve.com/developer-tools/urm/data-language-block'
markdown: 'https://code-evolve.com/developer-tools/urm/data-language-block.md'
date: '2026-09-25'
description: 'Data Language Block URM uses a declarative approach for working with data within an application. URM defines a data language block specification that allows the platform to manage boilerplate functionality The language block also allows developers to manage the granularity of data functionality f…'
---

# Data Language Block

URM uses a declarative approach for working with data within an application.

URM defines a data language block specification that allows the platform to manage boilerplate functionality The language block also allows developers to manage the granularity of data functionality from a centralized location. The declarative approach also facilitates code reuse.

Data can be defined using many fields such as persistence, groups, network shaping, debugging, etc. Data definitions are referenced using their ID from multiple places within the codebase.

The Data Block API provides an API provides methods to interact with data definitions, the client, and providers.

# Data Management

Data Block can automatically manage many concerns. Here is a comprehensive list.

\[todo descriptions\]

- Availability
- Structure
- Validation
- Searchable Options
- Initialization
- Persistence
- Error Handling
- Synchronization
- Sharing
- Shaping
- Binding (To UI and other data sources)
- Security
- Plugin / Tapping
- Monitoring
- Identification / Organization
- Reusability
- UI Generation
- Conflict Resolution
- Undo/Redo
- Loading State
- Error State
- Transactions
- Dirty state
- SAS (Selective Aspect Synchronization)
- Hysteresis
- Creation factories
- Memory and object tracking
- i8n - internationalization for language strings
- Documentation
- Context sensitive help

# The <data> block

The current approach used by modern web technologies is to combine three types of language blocks into one or more files. This structure follows the *"separation of concerns"* principle. For an example, see <https://vuejs.org/guide/scaling-up/sfc.html>

```xml
<template>
<!-- structure and content (typically HTML) -->
</template>

<script>
<!-- logic, executable code and data declarations (typically Javascript) -->
</script>

<style>
<!-- style directives (typically CSS) -->
</style>
```

URM adds an additional `Data Language Block` type to the standard language blocks.

```xml
<data>
<!-- data binding, persistence, shaping, flow control, validation, provider, ui hints, etc.  -->
</data>
```

---

# Data Block Syntax

The syntax of a data block resembles CSS and Javascript. Whereas CSS defines `selectors`, a data block defines `data block definitions`. Each `data block definition` is comprised of a `dataId`, followed by `data block definition fields`.

```css
<dataId> { 
  <field-name>: <field-value>;
  <field-name-n>: <field-value-n>;
}

<dataId-n> { 
  <field-name>: <field-value>;
  <field-name-n>: <field-value-n>;
}
```

Whitespace is optional.

```
name{displayName:Name;description:Your full name;}age{type:number;}
```

## DataId and Field Names

This regular expression describes valid id and field names: `[a-zA-Z_][a-zA-Z_0-9\-]*`

Examples of valid values

```plaintext
a
_a
ab
a-b
a_b
a8
a_
a-
```

Examples of invalid values

```plaintext
-a
-8
8a
hello.world
```

## Field Values

A field value is always interpreted as a string, with any surrounding whitespace trimmed.

If the field name is prefixed with a `:`, the field value will be evaluated using either `eval(...)` or `JSON.parse(...)`. If the evaluated value returns a `function`, the function will invoked to resolve the actual value.

```
name_eval {
  displayName: () => "Some" + " Person"
}
name_json {
  displayName: "Some Person"
}
```

Field values terminate with a `;`. If a field value uses a `;` or `\` character, the character must be escaped with a `\` character. This applies to strings, parsed strings, and evaluated strings

```plaintext
name {
  description: I have a \; and a \\ in my description;
}
```

## Default Field Values

Default field values may be defined using the reserved DataId `*`. These field values apply to any definition in the Data Block that omits the field.

```plaintext
* {
  provider: some_provider;
  namespace: some_namespace;
}
```

## Examples

An example Data Block with options.

```xml
<data>
* {
  provider: LocalStorage;
}

my-string {
 scope: workspace;
 :debounce: 100;
 :validate: myValidateFunction;
 bind: #some-element
 default: () => {message: 'Hello World'}
}
</data>

<script>
// get the provided value
const myString = await dataBlock.get('my-string')

// 2-way bind
await dataBlock.bind('my-string', '#my-element')

// autobind definitions that use the bind field
await dataBlock.autobind();
</script>
```

## Preprocessing Existing Source Code

Until the data block becomes a web standard, the data block content can be added via a script. Furthermore, an HTML preprocessor can replace the data block with a script.

```xml
<html>
<head>
<script>
window.urm_data_block_string = `
my-text-area {
 scope: workspace;
 debounce: 100;
 validate: myValidateFunction;
 default: () => {message: 'Hello World'}
}
...
`
window.urm_data_block = parseDataBlock(wi dow.urm_data_block_string)
</script>
<script
</head>
</html>
```

---

# Data Definition Fields

The following section outlines a comprehensive list of currently supported data definition fields.

## Identity Fields

### id

*type: string*

A unique identifier used to reference the definition. This identifier must be unique within the data block it is defined in.

An id must conform to the regular expression `[a-zA-Z_][a-zA-Z0-9_-]*` or the reserved id `*`

```
* {
  ...
}

dataId-1 {
  ...
}

dataId-n {
  ...
}
```

### namespace

*type: string*\\ *default: undefined*

An optional namespace to use. Namespaces are used to resolve ids within multiple data block instances and declarations.

## User Interface Fields

### displayName

*type: string*\\ *default: undefined*

A human readable name used in reports and user interfaces. A variant of the id will be used if not specified.

### description

*type: string*\\ *default: undefined*

A brief description of the property. The description is used in tooltips, detail sections, and documentation.

### hint

*type: string*\\ *default: undefined*

A description of the property to be displaying in user interface hint areas.

### type

*type: string*\\ *default: undefined*

The type of data. This can be inferred from the default value.

### type<2..n>

*type: string*\\ *default: undefined*

The subtype of data.

For example

```css
{
  type: string;
  type2: password;
}
```

## Value Fields

Value fields affect how a value is loaded or saved

### provider

*type: string*\\ *default: undefined*

Specifies the resource provider that manages the data.

### provider-props

*type: object*\\ *default: undefined*

Provider specific properties

### scope

*type: string* \\ *default: undefined*

Specifies the accounts, applications, sessions, and devices that share the data. Scope is meant to augment provider settings with common parameters. See \[\[Data Language Block Scopes\]\]

Scope does not define persistence

### persist

Indicates how data is stored and loaded between instantiations

### default

*type: any | function*\\ *default: undefined*

The default value of the data. This value will be used in several circumstances:

- to initialize a provider
- when resetting the data
- when a provider cannot be reached
- to determine if a value is not the default

### validate

*type: function*\\ *default: undefined*

A function to validate data integrity when initializing it from an external source. This function can modify the incoming value or properties on the incoming value.

The signature the function is:

```
(value:T, context:Context) => T | undefined
```

A validate function can return a new or replaced value. It can also throw an exception.

If the validate function returns undefined, the value is considered valid.

### bind

*type: selector-string | element | (selector-string | element)\[\] | function*\\ *default: undefined*

Targets to use when autobinding data to elements. Multiple targets may be set for the same dataId.

## Shaping Fields

### shaping

*type: object*\\ *default: undefined*

The following fields may be set in the shaping object. They are all optional.

#### commit

type: boolean

Only persist the value when `commit` is called. This event may be attached to an element blur (losing focus), to an `enter` keypress on a text field, or by pressing a `commit` button, etc. When commit is enabled, no other shaping parameters are considered.

#### debounce

*type: number*

Delays sending updates until time based conditions are met.

#### throttle

type: number

Limits the frequency of updates sent. Throttling does not alter content.

#### immediate

*type: boolean*

Indicates if the value is sent immediately, before and timeouts.

#### threshold

*type: number*

Indicates the change between 2 set values required to trigger an `immediate` send.

### compress

Indicates if, when, and how data is compressed before transfering or storing. Also indicates compression parameters and protocol.

### accumulate

Indicates if and how cached updates are combined or replaced before sending them.

## Developer Fields

### debug

*type: true | false*\\ *default: undefined*

Indicates if the data should be debugged. This includes tracing operations such as lifecycle, initialization, validation, reads, writes, and errors.

### log

*type: true | false | (read | write | permission|error)\[\]*\\ *default: undefined*

Indicates if data access (reads, writes, permissions, errors) of the data should be logged.

## Unfiled Fields

### primary

?

### loading

?

### filter

?

---

# Data Block API

The Data Block API provides functionality to manage data, data definition fields, and interactive services.

## Standard API methods

### get

Retrieve the data associated with a data definition

### set

Set the data associated with a data definition

### getDefinition

Retrieve a data definition

### getDefinitions

Retrieve all data definitions

### getFields

Retrive a data definition fields (not the realized field value)

### getField

Retrive a data definition field (not the realized field value)

### getFieldValue

### watch

### getRef (todo)

### bind

### autobind

## Standard API Messages

### dataBlockParsed

### dataBlockBound

## Syntactic Sugar

To allow for terse code, several shortcut macros have been added to the other three language block sections. As with the data language block, a preprocessor can replace the shortcut macros with valid code.

### <Script>

```javascript
<script>
const myTextArea = ^description // getDataRef('description')
const myTextArea = ^^description // getDataValue('description')
^description = 'Some description' // setDataValue('description', 'Some description')
const debounce = ^description.debounce // getDataProperty('description', 'debounce') 
const debounce = ^description.* // getDataProperties('description')
const defaultValue = ^description?.default() // getDataProperty('description', 'default')?.()
</script>
```

### <Template>

```xml
<template>
  <div ^description /> <!-- v-model="getDataRef('description')" -->
  <div ^^description /> <!-- v-model="getDataValue('description')" -->
</template>
```

### <Style>

```xml
<style>
.some-class::before {
  content: ^description
}
.another-class::before {
  url(^some-data-source)
}
</style>
```

---

## Navigation

- Parent: [URM](https://code-evolve.com/developer-tools/urm.md)