From early on, the world-wide web cleanly separated static content from its behavior. HTML was invented first to encode the content structure of a document's various elements. A few years later, Javascript, a very different language, was introduced to script the interactive behavior of those elements.

As the interactivity of the web grows, this language-driven division of labor between content and behavior contributes to code bureaucracy, slowing progress. By analogy, then, designing a single language that seamlessly weaves together 3-D content and behavior will make it easier to build rich, interactive worlds, as:

For these reasons, a key design goal for Acorn is seamless support for both content and behavior. For static 3-D content, Acorn's content grammar should compare favorably to the web's most used content languages (XML, JSON and YAML) in simplicity, expressiveness, and readability. As world builders add increasingly advanced features to the static content (such as interactive behaviors, procedural generation, dynamic content changes), Acorn should facilitate these capabilities in an incremental, intuitive and organic way.

This chapter explains how Acorn incorporates lessons learned from XML, JSON and YAML, with regard to three criteria:

Before we begin the assessment, here is a very simple whimsical example implemented in all four languages. It offers a brief taste-test that highlights some of their stylistic differences:

  receipt="Oz-Ware Invoice"
    family-name="Gale" />
      descrip="Water Bucket"
      quantity="4" />

      descrip="Ruby Slippers"
      quantity="1" />
  "receipt":     "Oz-Ware Invoice"
  "date":        "2012-08-06"
  "customer": {
    "first_name":   "Dorothy"
    "family_name":  "Gale"
  "items": [
      "part_no":   "A4786"
      "descrip":   "Water Bucket"
      "price":     1.47
      "quantity":  4
      "part_no":   "E1628"
      "descrip":   "Ruby Slippers"
      "size":      8
      "price":     133.7
      "quantity":  1
--- !invoice
receipt:     Oz-Ware Invoice
date:        2012-08-06
customer: !person
    first_name:   Dorothy
    family_name:  Gale

    - !item
      part_no:   A4786
      descrip:   Water Bucket
      price:     1.47
      quantity:  4

    - !item
      part_no:   E1628
      descrip:   Ruby Slippers
      size:      8
      price:     133.7
      quantity:  1
  receipt:     'Oz-Ware Invoice'
  date:        2012-08-06
  customer: +Person
    first_name:   'Dorothy'
    family_name:  'Gale'

  items: +List <<
      part_no:   'A4786'
      descrip:   'Water Bucket'
      price:     1.47
      quantity:  4
      part_no:   'E1628'
      descrip:   'Ruby Slippers'
      size:      8
      price:     133.7
      quantity:  1

De-serialization Fidelity

The days are long gone when web content's sole purpose is rendering free-form documents. Interactive web sites now require their content languages to serialize complex data structures. It is a great kindness to web developers if these data structures can be automatically, rapidly and accurately de-serialized: converted (when loaded) into an appropriate binary format ready for manipulation by the scripting logic.

This requirement is even more important with 3-D worlds, as 3-D content is often massive, and filled with coordinates and other numbers. Responsive worlds require that this content can be loaded quickly and be ready-to-use.

This section examines several content language design factors that facilitate accurate de-serialization: the use of atomic literals, the syntax for collections, the specification of custom types, and the handling of white space.

Atomic Literals

Atomic literals are powerful aids to deserialization, as they encode both the type and content of simple values in a familiar, succinct and distinguishable syntax. This chart summarizes the atomic data type literals supported by each language:

text text
true, false
true, false
true, false

Like many dynamic languages, Acorn believes the distinction between text and symbols is important. Even though both encode a collection of Unicode characters, they have differently uses. Symbols are lightning fast for keys and comparisons. The price they pay for this speed is that symbols are frozen and unchangeable. Use text any time you want the freedom to alter it. Otherwise, use symbols. Acorn supports both types of literals.

Acorn does not provide a timestamp literal, as it is little needed outside of log files. However, Acorn does provide a simple way to specify a specific time-stamp value, for example: +Time("2012-08-06"). This approach may also be used for representing and de-serializing other values whose type is not listed above.


All four languages support both ordered and indexed collections of values.

XML does so with significant restrictions. It offers only one collection format, the node, which can be given indexed attributes and/or an ordered sequence of nodes (or text). Unfortunately, a node's indexed attribute cannot hold another node. It can only hold text.

Acorn, like JSON and YAML, is free of XML's restrictions. It supports various types of collections (List, Index, Type, and Part) and does not restrict what type of data that indexed collections may carry.

Custom Types

A 3-D content language must support the mapping of content to custom types, particularly for collections. Custom typing improves modularity, allowing a world's parts to share properties and behavior with other similarly typed parts. For example, "animals" can move around and "walls" can block their movement.

Like XML and YAML, Acorn supports the named specification of a value's custom type. It does so using the "+" operator which creates a new value of the specified type.

Text Fidelity

Text does not have the same primacy in 3-D worlds that it has on the web. Despite the reduction in its role, text still plays an important part. When specified, text needs to be formatted and rendered exactly as indicated.

Surprisingly, XML sometimes struggles with this, due to its eagerness to accommodate human readability needs. For example, XML collapses multiple consecutive spaces, new line characters and tabs into a single space, which could be a problem in some situations. Furthermore, certain characters can be undesirably interpreted as tags or entities and therefore not rendered correctly. Sometimes, the syntactically awkward CDATA must be used to overcome these challenges.

JSON has a very different limitation: it does not support multi-line text. Any long text must be placed within a single line, making it potentially inconvenient to view and change.

YAML is the most versatile: it supports many styles for precisely specifying text. It permits text to be free-form and unquoted (like XML) or quoted and precise (like JSON). It supports many variations of multi-line text.

Acorn makes it easy to precisely specify readable text, but (for important reasons) does so with fewer stylistic options than YAML. Being a programming language, Acorn insists that all text literals be quoted. This prevents confusion over whether words are to be interpreted as text or variables. Furthermore, Acorn supports a single style for multi-line text, using a consistent syntax that balances readability with precision. Like JSON and YAML, Acorn supports escape sequences for incorporating special characters.

De-serialization Summary

Given XML's many deficiencies for de-serializing general-purpose data structures, it makes sense that better content languages, such as JSON and YAML, were created and broadly adopted less than five years later. Of these two, YAML supports a richer de-serialization palette, as it supports custom types and multi-line text.

For 3-D content, Acorn provides excellent de-serialization power, comparable to YAML and then some (providing native support for symbols).


Clarity in a content language refers to how concise and comprehensible the content is to another person who might want to understand or change it. Given the tight relationship between content and behavior, it is important that 3-D content be highly readable by the people who maintain and enrich worlds, even when the content is generated by tools.

The criteria for clarity are somewhat subjective, given that people have widely varying opinions about what makes code easy to understand. Nonetheless, several best practice techniques can be employed to improve a language's clarity:

Applying these guidelines to the three web content languages yields this subjective assessment:

Acorn's content is as easy-to-read as YAML, and nearly as concise. Acorn's incremental verbosity, relative to YAML, stems from it being a full programming language: Text must be quoted, collection types must always be explicitly named, and lists require use of the '<<' append operator.

Acorn facilitates readability by keeping its content grammar simple. It supports a single, but powerful style for specifying content. Like YAML, Acorn supports comments.

Dynamic Content

All three web content languages were designed for static content, making them useful for web sites that always present the same pages every time. With the advent of database-driven, interactive web sites, web builders need the ability to dynamically generate content, thereby blurring the line between content and procedural logic. They need their content languages to be able to:

The three web content languages are not built to handle these requirements. As a result, several very different approaches have been taken to address these requirements:

When it comes to 3-D worlds, the need for dynamic generation of content is even stronger: Procedural content generation can greatly improve both a world's performance and realism. 3-d models and materials are often re-used. Content properties are regularly in flux, changing due to human and inter-object interactions.

This is where Acorn truly shines, as it gracefully supports all the dynamic content requirements in a way that avoids the complexities of the listed web solutions. Within the design of a single language is seamless integration of content and procedural logic. In every place where a static value can be placed, Acorn permits the use of a variable, an expression, a method, or a control structure.

Economically, Acorn uses the same language facilities for both static content and procedural logic. Acorn’s content grammar may appear descriptive, but its versatile operators are actually procedural. They serve equally well for building or changing content whenever required. Using these tools, a static world can be incrementally transformed into something rich and interactive as quickly as the world-builder's skill and imagination improves.


With regard to static web content, YAML is the most versatile and readable of the three content languages. It supports creation of concise, easy-to-read content that ready-for-use by a scripting language. However, all three languages stumble to support dynamic content, ultimately requiring them to back into a full programming language (notably Javascript) to get the job done.

Acorn, inspired by and rivaling what other languages have done well, has been carefully designed to provide a single language that addresses all de-serialization, clarity and dynamic content requirements for 3-D content, Its simple, concise grammar is highly readable, yet it also supports the accurate, code-ready loading and de-serialization of a world's modular content. Most importantly, world-builders can incrementally exploit Acorn's procedural capabilities to improve the visual appeal, diversity and engaging interactive behavior of their worlds.