Deal Model DSL

The DealModel DSL defines a declarative structure for modeling, validating, and rendering entertainment deal types. Each element represents a composable building block of a complete deal definition.

Why JSON Schema Matters

Each deal type references a JSON Schema in its inputs block. This schema defines the exact shape of data that instances of the deal will provide at runtime.

JSON Schema enables applications to:

Purpose	Description
Flexibility	Each deal type can define its own unique data model without modifying the DSL grammar.
Validation	Ensures inputs for each deal instance conform to expected structures.
Interoperability	Applications and APIs can read schemas to understand the required fields, enumerations, and data relationships for any deal type.
Extensibility	Supports deal-specific data like simple clauses, schedules, or financial parameters, without modifying the base DSL.

Example JSON Schema fragment for simple clauses:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "simple_clauses": {
      "type": "object",
      "properties": {
        "headline_billing": {
          "type": "string",
          "minLength": 1,
          "description": "Deal-specific text for headline billing."
        }
      },
      "additionalProperties": false
    }
  }
}

The example above defines how instance data supplies custom text for a simple clause.

Model Header

Every model begins with a header that defines its type and version.

model { deal_type: "Music Touring Performance Deal", version: 1.0.0 }

Field	Type	Description
deal_type	TEXT or STRING	Human-readable identifier for the deal.
version	SEMVER	Unquoted Semantic Version for version tracking.

The header defines the canonical identity for versioned distribution, code generation, and documentation.

Inputs

Inputs describe the schema of deal instance data.

inputs { ref: "https://schemas.example.com/models/music-touring/performance/1.0.0.json" }

Or inline JSON Schema:

inputs {
  schema: """{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object" }"""
}

Parameter	Description
ref	URL or key reference to a shared JSON Schema.
schema	Inline JSON Schema definition (use triple quotes).

Inputs ensure type safety and validation for all instance-level data provided to the deal runtime.

Overrides

Overrides define model-level template packs for specific clients or contexts.

overrides {
  templates: """
  { "payout": "For the performance at {{ input('/venue_name') }}, Artist shall be paid {{ money(guarantee_amount, 'USD') }} or {{ percent(pct_nbor) }} of NBOR." }
  """
}

Field	Description
templates	JSON object defining template override text.

Overrides are applied before per-instance template customizations.

Selectors

Selectors assign readable names to JSON paths or pointers.

selectors {
  show_revenue: "$.shows[*].revenue"
  fees_path: "$..fees[*]"
}

Field	Description
name	Logical alias used in expressions (e.g., sum(show_revenue)).
value	JSON path or pointer to source data.

Selectors simplify aggregation and computation expressions.

Variables

Variables represent reusable symbols or expressions.

var guarantee_amount
var pct_nbor
var nbor = gross_box_office - taxes - fees

Element	Description
var	Declares a variable binding or computed expression.
name	Symbolic identifier for reuse in computations or conditions.
value	Optional expression assigned to the variable.

Variables act as symbolic placeholders for inputs or derived values.

Operators

Operators define logical or financial relationships for combining clauses.

operator { name: versus display: "vs" type: or }

Field	Description
name	Identifier used in expressions.
display	Label used in contract output or UI.
type	and (additive) or or (exclusive).

Events

Events describe measurable conditions that activate clauses or blocks.

event {
  name: nbor_threshold
  description: "NBOR meets or exceeds the required threshold"
  condition: nbor >= nbor_threshold_value
}

Field	Description
name	Event identifier.
description	Human-readable description of what triggers the event.
condition	Boolean expression determining when the event becomes true.

Events represent both time-based and performance-based triggers.

Clauses

Clauses define individual contract terms. Clauses are categorized by kind:

Kind	Description
simple	Textual only. Renders provided input text via input(); no logic or payout.
guarantee	Always pays when active; may depend on a deliverable.
contingent	Payouts that occur only if an event condition is met.

Example of a simple clause sourcing its text from JSON Schema inputs:

clause {
  name: headline_billing
  kind: simple
  description: "Deal-specific headline billing text"
  template: """
  {{ input("/simple_clauses/headline_billing") }}
  """
}

Example of a financial clause:

clause {
  name: guarantee
  kind: guarantee
  description: "Minimum guaranteed payment to the Artist"
  amount: guarantee_amount
  payable: on performance_date
  template: """
  Artist shall be paid a guaranteed fee of {{ money(guarantee_amount, "USD") }}
  for the performance on {{ date(performance_date) }} at {{ input("/venue_name") }}.
  """
}

Field	Description
name	Identifier for the clause.
kind	Type of clause: simple, guarantee, or contingent.
description	Human-readable summary.
when	Optional event guard controlling activation.
amount	Expression defining the financial value.
payable	Reference to when or how payment is due (on <date> or by_schedule <id>).
template	Triple-quoted contract text.

Clause Blocks

Clause Blocks group one or more clauses or other blocks using operators.

block {
  name: payout
  expr: guarantee versus nbor_share
  template: """
  Artist shall be paid the greater of {{ money(guarantee_amount, "USD") }}
  or {{ percent(pct_nbor) }} of NBOR for the performance on
  {{ date(performance_date) }} at {{ input("/venue_name") }}.
  """
}

Field	Description
name	Block identifier.
expr	Expression combining clauses or blocks via operators.
template	Optional rendering template for this logical grouping.

Blocks can reference other blocks recursively.

Type

The Type defines the top-level composition of the deal model.

type {
  name: touring_performance
  compose: payout
  template: """
  The parties agree to the Performance Deal terms as set forth herein.
  """
}

Field	Description
name	Unique type identifier.
compose	Root clause block or composition expression.
template	Optional contract language for the entire deal.

Computations

Computation Intrinsics

Intrinsic	Purpose
amount(name)	Evaluates a clause or block amount.
input(path)	Reads a value from instance inputs.
sum(path)	Aggregates numeric arrays by summation.
count(path)	Counts elements at a JSON path.
min(path) / max(path)	Retrieves the minimum or maximum numeric value.
plugin(name, ...)	Invokes registered custom computation logic.

Computations define derived metrics and outputs.

computations {
  metric total_show_revenue = sum(show_revenue)
  metric total_fees = sum(fees_path)
  metric nbor_share_amount = pct_nbor * nbor
  output guarantee_value = amount(guarantee)
  output versus_value = amount(payout)
  output total_payout = max(guarantee_value, versus_value)
}

Keyword	Description
metric	Defines a derived intermediate value.
output	Defines a named public result.

Example: Music Touring Performance Deal

This is very, very rough, incorrect, and not complete.

touring1.dm

# touring1.dm

model { deal_type: "Music Touring Performance Deal", version: 1.0.0 }

inputs { ref: "https://schemas.example.com/models/music-touring/performance/1.0.0.json" }

selectors {
  show_revenue: "$.shows[*].revenue"
  fees_path: "$..fees[*]"
}

var performance_date
var venue_name
var guarantee_amount
var pct_nbor
var nbor
var nbor_threshold_value

operator { name: versus display: "vs" type: or }

event {
  name: nbor_threshold
  description: "NBOR meets or exceeds the required threshold"
  condition: nbor >= nbor_threshold_value
}

clause {
  name: headline_billing
  kind: simple
  description: "Deal-specific headline billing text"
  template: """
  {{ input("/simple_clauses/headline_billing") }}
  """
}

clause {
  name: guarantee
  kind: guarantee
  description: "Minimum guaranteed payment to the Artist"
  amount: guarantee_amount
  payable: on performance_date
  template: """
  Artist shall be paid a guaranteed fee of {{ money(guarantee_amount, "USD") }}
  for the performance on {{ date(performance_date) }} at {{ input("/venue_name") }}.
  """
}

clause {
  name: nbor_share
  kind: contingent
  description: "Artist share of Net Box Office Receipts"
  when: nbor_threshold
  amount: pct_nbor * nbor
  payable: by_schedule payout_schedule_id
  template: """
  Artist shall be paid {{ percent(pct_nbor) }} of the Net Box Office Receipts (“NBOR”)
  for the performance on {{ date(performance_date) }} at {{ input("/venue_name") }}.
  """
}

block {
  name: payout
  expr: guarantee versus nbor_share
  template: """
  Artist shall be paid the greater of {{ money(guarantee_amount, "USD") }}
  or {{ percent(pct_nbor) }} of NBOR (“Versus Deal”) for the performance on
  {{ date(performance_date) }} at {{ input("/venue_name") }}.
  """
}

type {
  name: touring_performance
  compose: payout
  template: """
  The parties agree to the Performance Deal terms as set forth herein.
  """
}

computations {
  metric total_show_revenue = sum(show_revenue)
  metric total_fees = sum(fees_path)
  metric nbor_share_amount = pct_nbor * nbor
  output guarantee_value = amount(guarantee)
  output versus_value = amount(payout)
  output total_payout = max(guarantee_value, versus_value)
}