HSON Features

To provide a full bridge between Webflow's CMS Data and structured JSON objects, HSON has support for typed values ( string, number, boolean ), null values, nested objects, and multiline strings.

Typed Values

By default, values are interpreted as string values, and JavaScript objects are created accordingly. However you can identify any field as a numeric or boolean type when appropriate.

This is done by adding a symbol immediately after the : delimiter;

: or :$ indicate a string value
:# indicates a numeric value
:? indicates a boolean value

Here's an example structure;

<script type="application/hson">
name:$ John Doe
age:# 23
isActive:? true
description: <John is a software engineer
from Springfield. He loves coding and
is passionate about technology.>
</script>

Null Values

Blank values are expressed as nulls in your object, regardless of the type.

Here, age and isActive are nulls;

<script type="sygnal/sa5-data">
name:$ John Doe
age:# 
isActive:? 
description: <John is a software engineer
from Springfield. He loves coding and
is passionate about technology.>
</script>

Nested Objects

SA5 Data also supports nested objects.

To indicate a nested object,

Place your field key on a line by itself, with a double-colon :: suffix
Indent the fields within your nested object beneath it

Here address and postalCode are both nested objects.

<script type="sygnal/sa5-data">
name:$ John Doe
age:# 23
isActive:? true
address::
    street: 
    city: Springfield
    country: 
    postalCode::
        code:# 
        region: 
</script>

Generates the following JSON object;

{
  "name": "John Doe",
  "age": 23,
  "isActive": true,
  "address": {
    "street": null,
    "city": "Springfield",
    "country": null,
    "postalCode": {
      "code": null,
      "region": null
    }
  }
}

Multiline Content

There is an edge case problem here, which is that in Webflow a CMS text field can be set to multiline, and can contain line breaks. To resolve this unambiguously, wrap Webflow's embedded variable in angle brackets < >

Objects can be nested by specifying the object key on one line, and indenting the nested object beneath it;

<script type="sygnal/sa5-data">
name: The Catcher in the Rye
author: J.D. Salinger
description: <In "The Catcher in the Rye," the protagonist, Holden Caulfield, 
recounts his experiences in New York City after being expelled 
from an elite prep school.> 
</script>

Which is parsed as;

{
  "name": "The Catcher in the Rye",
  "author": "J.D. Salinger",
  "description": "In \"The Catcher in the Rye,\" the protagonist, Holden Caulfield,\nrecounts his experiences in New York City after being expelled\nfrom an elite prep school."
}

The use of angle brackets was chosen because Webflow HTML encodes all values it embeds, which means that by definition, angle brackets cannot exist in the embedded content itself.

Also use angle brackets if whitespace characters at the start or end of your field content are an essential part of your data.

Technical Guide

SA5 Data is a custom notation designed to represent structured data in a human-readable format. It is designed specifically to work with Webflow's Custom Code areas and HTML Embeds, and to work with Webflow's HTML-encoded CMS field embeds.

This syntax combines elements of traditional data representation formats like JSON, YAML and HCL, and simplifies them for ease of use. SA5 Data is particularly suitable for configuration, data representation, and other scenarios where clear, concise data structures are desired.

Design features;

Is very easy to work with in Webflow's HTML Embed editor
It reliably handles Webflow's innate HTML encoding in embedded CMS fields
It handes line breaks in multiline embed content
It is easily translated directly to JavaScript objects

Sygnal designed SA5 Data because other approaches like raw JSON embeds created too many risks for broken, unparseable data structures. SA5 Data safely transports HTML Encoded CMS data from Webflow's Collection lists into JavaScript objects with zero risk of data loss, damage, or broken scripts.

Basic Rules

Script Tag:

Every SA5 Data block starts with a <script type="sygnal/sa5-data"> tag and ends with a </script> tag.

Key-Value Pairs:

Represent data as key: value pairs.
Each pair should be on a new line.
Whitespace will be trimmed from both the key and the value
The first colon on the line is a delimiter, thus the key cannot contain a : but the value can

Values:

Do not enclose values in quotes. They are not needed and would be considered part of the string content.
All values must be HTML-encoded. This happens automatically with Webflow's embedded fields. If you have static string content;
- < must be encoded as <
- > must be encoded as >
- & must be encoded as &
If a value is delimited by < and > characters, the whitespace and line feeds within those angle brackets are considered part of the value.
Copy
```
multi-line-value: <This is a
multi-line value with preserved whitespace and line breaks.>
```
Value type defaults to strings, and will be created in the JavaScript object accordingly. However you can also define numeric and boolean types by appending a type identifier to the value separator;
- : or :$ indicates a string value
- :# indicates a numeric value
- :? indicates a boolean value
Empty values of any time resolve to null values.

Indentation & Nesting:

Nested structures are indicated by indentation.
Use consistent indentation (preferably spaces) to represent nested structures. The level of indentation indicates the depth of nesting.
For each nested level, increase the indentation consistently (e.g., by two or four spaces).

No Commas or Brackets:

Unlike JSON, SA5 Data doesn't use commas to separate key-value pairs or brackets to denote objects.

Technical Notes

In the resulting JavaScript object-

Value types are all string, unless identified as boolean or numeric
Empty values are always null
Webflow's HTML encoded fields are decoded
Line breaks are encoded as

Future

Support for process-assembled objects. In rare cases, some pieces of the object may be outside of the sa5-data block, particularly items that cannot be Field-embedded such as rich text content.

In this case, we might support a special attribute on those elements such as [wfu-data-item] along with field, db, dsn identifiers, and specify the field for an object-merge. e.g. article.text would indicate the nested article object, with a text field. Objects would be created as needed. I am probably in favor of an object-merge approach.

As multiline string delimiters, < > are concise and unambiguous, however we are also considering the use of """, ``` or \\\ delimiters to make them more visible.

HSON Features

Typed Values

Null Values

Nested Objects

Multiline Content

Technical Guide

Basic Rules

Technical Notes

Future

Comments

Arrays