MML Syntax

Modality Modeling Language (MML) uses a simple, human-readable syntax to define data models and their relationships.

Basic Structure

MML files are composed of blocks that define different aspects of your data model. Each block has a type, optional identifier, and a body enclosed in curly braces.

Block Syntax

block_type identifier {
  attribute_name = "value"
  nested_block {
    attribute = "value"
  }
}

Blocks

Blocks are the fundamental building blocks of MML. They define domains, entities, and their properties.

Block Definition

• Block Type: The kind of block (e.g., domain, entity)
• Identifier: A unique name for the block (optional for some block types)
• Body: Contains attributes and nested blocks

Example:

domain sales {
  name = "Sales Domain"
  description = "All sales-related entities"
}

Attributes

Attributes define properties of blocks. They use a key-value syntax.

Attribute Syntax

attribute_name = "value"

Attribute Types

• String: Text values enclosed in double quotes

  name = "Customer"
  description = "Customer information"

• Boolean: true or false (no quotes)

  is_active = true

• Number: Numeric values (no quotes)

  version = 1

• List: Comma-separated values in square brackets

  tags = ["important", "core", "validated"]

Comments

MML supports both single-line and multi-line comments.

Single-line Comments

// This is a single-line comment
domain analytics {
  name = "Analytics" // Inline comment
}

Multi-line Comments

/*
  This is a multi-line comment
  that spans multiple lines
*/
domain reporting {
  name = "Reporting"
}

Strings

String values must be enclosed in double quotes.

Basic Strings

name = "Customer"
description = "Represents a customer entity"

Multi-line Strings

For longer text, you can use multi-line strings:

business_logic = """
  This entity represents the total revenue
  generated from all sales transactions,
  aggregated by product and region.
"""

Relationships

Relationships define connections between entities using special relationship blocks.

Relationship Syntax

entity customer {
  type = "entity"

  belongs-to domain.sales
}

entity order {
  type = "entity"

  contains entity.customer
}

Relationship Types

• belongs-to: Indicates an entity belongs to a domain
• derived-from: Indicates an entity is derived from other entities
• contains: Indicates an entity contains or references another entity

Relationship References

References use dot notation to specify the target:

belongs-to domain.domain_name
derived-from entity.source_entity
contains entity.related_entity

Identifiers

Identifiers are names given to blocks. They must follow these rules:

• Start with a letter or underscore
• Contain only letters, numbers, and underscores
• Be unique within their scope
• Use snake_case convention (recommended)

Valid identifiers:

customer
order_line_item
revenue_2024
_internal_metric

File Organization

Single File

Small projects can use a single MML file:

// model.mml

domain sales {
  name = "Sales"
}

entity customer {
  type = "entity"
  belongs-to domain.sales
}

Multiple Files

Larger projects can split definitions across multiple files. All .mml files in a project are automatically merged.

project/
  ├── domains/
  │   ├── sales.mml
  │   └── marketing.mml
  └── entities/
      ├── customers.mml
      └── orders.mml

Best Practices

1. Use meaningful identifiers: Choose clear, descriptive names

   // Good
   entity monthly_revenue
   
   // Avoid
   entity mr

2. Add descriptions: Document the purpose of each block

   entity customer {
     description = "Represents a customer with purchase history"
   }

3. Group related entities: Use domains to organize entities logically

   domain sales {
     name = "Sales Domain"
     description = "Sales and revenue tracking"
   }

4. Consistent formatting: Use consistent indentation (2 or 4 spaces)

   domain analytics {
     name = "Analytics"
   
     entity pageview {
       type = "entity"
       description = "User page view events"
     }
   }

5. Comment complex logic: Explain business rules and derivations

   entity net_revenue {
     type = "metric"
     // Net revenue excludes refunds and discounts
     business_logic = "SUM(gross_revenue) - SUM(refunds) - SUM(discounts)"
   }