Introduction to BlockML

A universal language for describing Blocks

BlockML is a universal declarative language for describing parametric, composable semantic units called Blocks, independently of how any particular domain later manifests them. Authors write Blocks in BML, the human- and editor-friendly authoring format, and the compiler turns that BML into the BOM, its canonical, immutable, and lossless representation. That compiler is domain-agnostic — it makes no domain-specific decisions itself, because all domain knowledge lives exclusively in the render targets that later manifest a Block into something concrete.

BML and BOM

BML, the Block Markup Language, is what authors write and edit directly; every BML file uses the .bml extension, and XML is currently its sole serialization. Parsing a BML file produces the BOM, the Block Object Model — the canonical, immutable model the parser builds from that document. Because the parser makes no semantic decisions of its own, a BML document can be converted to its BOM and back again without losing or reinterpreting anything, so the two forms remain losslessly convertible into one another.

How to read this handbook

This handbook moves from a first orientation, through BlockML's foundational Block concepts, into the type and member model, and finally into the BML authoring format itself, with each page building on the mental model the previous one established.

Getting Started
What BlockML is and why it exists.
Foundations
Blocks, definitions and instances, inheritance, and identity.
The Type System and Members
The four ValueType kinds and the Property, Aggregation, Association, and Capability member model.
BML: The Authoring Format
The authoring format itself, once every concept it expresses is known.

A first look at BML

Every BML document opens with a root Block element that states its own name, its type identity, and the type it extends, before anything else follows. This identity — name, type, and baseType — always comes first, ahead of the is and documentation fields that describe what the Block means.

<!-- Root Block: name, type identity, and the type it extends -->
<acme:Widget xmlns="http://blockml.org/bml"
  xmlns:acme="com.acme.example"
  xmlns:core="org.blockml.bml.core">

  <baseType>
    core:Block
  </baseType>
</acme:Widget>

The element tag acme:Widget names the Block and its type in one step, and baseType states that Widget extends core:Block — nothing else is declared. Reading the example, the document's identity is fully stated before anything else is added; this is the pattern every later page in the handbook builds on.

What to carry into the next pages

After this page, readers should be able to say what BlockML is for and keep BML, the authoring format, distinct from BOM, its canonical representation.