Core Concepts

Blocks treats domain concepts as first-class, executable artifacts — inspired by Cube.dev, Malloy, and PDDL.

The Two Pillars

Entities

Entities are the "things" in your domain.

domain:
  entities:
    user:
      fields: [id, name, email, created_at]
    resume:
      fields: [basics, work, education, skills]
      optional: [certifications]

Reference entities using entity.<name>:

blocks:
  my_block:
    inputs:
      - name: user
        type: entity.user

Semantics

Semantics define your domain vocabulary — terms and concepts that give meaning to your data.

domain:
  semantics:
    engagement:
      description: "How engaged is the user?"
      extraction_hint: "Based on activity frequency and recency"

    score_0_1:
      description: "Normalized score between 0 and 1"
      schema:
        type: number
        minimum: 0
        maximum: 1

Semantics can be purely conceptual (for AI context) or include constraints (with JSON Schema).

Reference semantics in outputs:

blocks:
  my_block:
    outputs:
      - name: score
        semantics: [score_0_1]

Why Domain Modeling Matters

Without domain modeling:

• Developers hallucinate structures
• Conventions drift over time
• Semantic meaning is lost in code
• No consistency across blocks

With domain modeling:

• ✅ Explicit semantics
• ✅ Drift detection when changes occur
• ✅ Evolutionary design through negotiation
• ✅ Humans and AI agents maintain alignment through validation

Next Steps