State Machine JSON Schemas

Overview

This document provides complete JSON schema definitions for the state machine-based touring deal system. These schemas can be used for:

Document validation
API contract definition
Code generation
Database schema design

Part 1: Core Deal Schema

1.1 Deal Document

json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Deal",
  "description": "Top-level container for a touring deal with all versions",
  "type": "object",
  "required": ["deal_id", "deal_type", "artist_id", "promoter_id", "name", "versions"],
  "properties": {
    "deal_id": {
      "type": "string",
      "description": "Unique identifier for the deal",
      "pattern": "^deal_[a-z0-9_]+$"
    },
    "deal_type": {
      "type": "string",
      "description": "Type of deal structure",
      "enum": [
        "flat_guarantee",
        "percentage_of_gross",
        "percentage_of_net",
        "guarantee_vs_percentage_gross",
        "guarantee_vs_percentage_nbor",
        "guarantee_plus_bonus",
        "split_point",
        "merchandise_split",
        "custom"
      ]
    },
    "artist_id": {
      "type": "string",
      "description": "Reference to artist entity"
    },
    "promoter_id": {
      "type": "string",
      "description": "Reference to promoter entity"
    },
    "name": {
      "type": "string",
      "description": "Human-readable deal name",
      "maxLength": 200
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "created_by": {
      "type": "string",
      "description": "User ID who created the deal"
    },
    "initialized_from_template": {
      "type": ["string", "null"],
      "description": "Template ID if deal was initialized from template"
    },
    "version_pointers": {
      "type": "object",
      "description": "Named pointers to specific versions",
      "properties": {
        "primary": {
          "type": ["string", "null"],
          "description": "The main/canonical version"
        },
        "forecast_optimistic": {
          "type": ["string", "null"]
        },
        "forecast_pessimistic": {
          "type": ["string", "null"]
        },
        "final_settlement": {
          "type": ["string", "null"]
        }
      },
      "additionalProperties": {
        "type": ["string", "null"]
      }
    },
    "versions": {
      "type": "array",
      "description": "All versions of this deal (working and submitted)",
      "items": {
        "$ref": "#/definitions/Version"
      },
      "minItems": 1
    }
  }
}

1.2 Version Schema

json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Version",
  "description": "A complete snapshot of deal state",
  "type": "object",
  "required": ["version_id", "status", "clause_blocks"],
  "properties": {
    "version_id": {
      "type": "string",
      "description": "Unique identifier for this version",
      "pattern": "^v_(submitted|working)_[a-z0-9]+$"
    },
    "metadata": {
      "type": "object",
      "description": "Arbitrary key-value pairs for non-calculable information specific to this block.",
      "additionalProperties": true
    },
    "static_variables": {
      "type": "object",
      "additionalProperties": { "type": "number" },
      "description": "Key-value pairs for variables defined in the template."
    },
    "status": {
      "type": "string",
      "enum": ["working", "submitted"],
      "description": "Working = mutable, Submitted = immutable"
    },
    "created_from": {
      "type": ["string", "null"],
      "description": "Version ID this was branched from"
    },
    "submitted_at": {
      "type": ["string", "null"],
      "format": "date-time",
      "description": "When version was submitted (only for submitted versions)"
    },
    "submitted_by": {
      "type": ["string", "null"],
      "description": "User ID who submitted (only for submitted versions)"
    },
    "locked_by": {
      "type": ["string", "null"],
      "description": "User ID who has exclusive lock (only for working versions)"
    },
    "last_auto_save": {
      "type": ["string", "null"],
      "format": "date-time",
      "description": "Last auto-save timestamp (only for working versions)"
    },
    "clause_blocks": {
      "type": "array",
      "description": "All clause blocks in this version",
      "items": {
        "$ref": "#/definitions/ClauseBlock"
      }
    }
  }
}

Part 2: Clause Block Schema

2.1 Clause Block

json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "ClauseBlock",
  "description": "Logical grouping of states, inputs, and financial clauses",
  "type": "object",
  "required": ["clause_block_id", "clause_block_ref", "name", "static_variables", "states", "inputs", "financial_clauses"],
  "properties": {
    "clause_block_id": {
      "type": "string",
      "description": "Unique identifier within the deal",
      "pattern": "^cb_[a-z0-9_]+$"
    },
    "clause_block_ref": {
      "type": "string",
      "description": "Object reference for cross-block references (uppercase)",
      "pattern": "^CB_[A-Z0-9_]+$"
    },
    "name": {
      "type": "string",
      "description": "Human-readable name",
      "maxLength": 200
    },
    "clause_block_type": {
      "type": "string",
      "description": "Type for filtering/categorization",
      "enum": ["show_performance", "merchandise_split", "tour_summary", "custom"]
    },
    "metadata": {
      "type": ["object", "null"],
      "description": "Optional metadata for show/event",
      "properties": {
        "show_id": { "type": "string" },
        "venue": { "type": "string" },
        "city": { "type": "string" },
        "date": { "type": "string", "format": "date" },
        "capacity": { "type": "integer", "minimum": 0 }
      }
    },
    "static_variables": {
      "type": "object",
      "description": "Static values for calculations (v_guarantee, v_artist_percentage, etc.)",
      "additionalProperties": {
        "oneOf": [
          { "type": "number" },
          { "type": "string" },
          { "type": "boolean" }
        ]
      }
    },
    "states": {
      "type": "array",
      "description": "Calculated values with status",
      "items": {
        "$ref": "#/definitions/State"
      }
    },
    "inputs": {
      "type": "array",
      "description": "User-provided or sourced data",
      "items": {
        "$ref": "#/definitions/Input"
      }
    },
    "financial_clauses": {
      "type": "array",
      "description": "Financial obligations",
      "items": {
        "$ref": "#/definitions/Clause"
      }
    },
    "benefit_clauses": {
      "type": "array",
      "description": "Optional non-cash benefits (travel, comps, perks, etc.)",
      "items": {
        "$ref": "#/definitions/BenefitClause"
      }
    },
    "obligation_clauses": {
      "type": "array",
      "description": "Optional obligations and deliverables (performance, promotion, exclusivity, etc.)",
      "items": {
        "$ref": "#/definitions/ObligationClause"
      }
    },
    "other_clauses": {
      "type": "array",
      "description": "Optional deal mechanics (term, territory, options, rights, etc.)",
      "items": {
        "$ref": "#/definitions/OtherClause"
      }
    }
  }
}

Part 3: State Schema

json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "State",
  "description": "Calculated value with status and optional override",
  "type": "object",
  "required": ["state_key", "state_type", "name", "status"],
  "properties": {
    "state_key": {
      "type": "string",
      "description": "Unique key within clause block (uppercase)",
      "pattern": "^[A-Z][A-Z0-9_]*$"
    },
    "state_type": {
      "type": "string",
      "enum": ["boolean", "number", "string", "object"],
      "description": "Data type of the value"
    },
    "name": {
      "type": "string",
      "description": "Human-readable name",
      "maxLength": 100
    },
    "value": {
      "description": "Current value (calculated or overridden)",
      "oneOf": [
        { "type": "boolean" },
        { "type": "number" },
        { "type": "string" },
        { "type": "object" },
        { "type": "null" }
      ]
    },
    "status": {
      "type": "string",
      "enum": ["D", "F", "C", "O"],
      "description": "D=Draft, F=Forecast, C=Confirmed, O=Override"
    },
    "calculation": {
      "description": "Calculation expression or definition",
      "oneOf": [
        { "type": "string" },
        {
          "type": "object",
          "properties": {
            "type": { "type": "string", "enum": ["expression", "aggregate", "reference"] },
            "expression": { "type": "string" },
            "source": { "type": "string" },
            "fields": { "type": "object" }
          }
        },
        { "type": "null" }
      ]
    },
    "calculated_value": {
      "description": "What calculation would produce (shown when status=O)",
      "oneOf": [
        { "type": "boolean" },
        { "type": "number" },
        { "type": "string" },
        { "type": "object" },
        { "type": "null" }
      ]
    },
    "override_active": {
      "type": "boolean",
      "default": false,
      "description": "True when status=O and calculated_value differs from value"
    },
    "calculation_error": {
      "type": ["object", "null"],
      "description": "Error details if calculation failed",
      "properties": {
        "type": {
          "type": "string",
          "enum": ["undefined_reference", "type_mismatch", "division_by_zero", "circular_dependency", "syntax_error", "null_reference"]
        },
        "message": { "type": "string" },
        "field": { "type": "string" },
        "timestamp": { "type": "string", "format": "date-time" }
      }
    },
    "last_calculated_at": {
      "type": ["string", "null"],
      "format": "date-time"
    }
  }
}

Part 4: Input Schema

json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Input",
  "description": "User-provided or externally-sourced data point",
  "type": "object",
  "required": ["input_key", "input_type", "name", "status"],
  "properties": {
    "input_key": {
      "type": "string",
      "description": "Unique key within clause block (uppercase with _INPUT suffix)",
      "pattern": "^[A-Z][A-Z0-9_]*_INPUT$"
    },
    "input_type": {
      "type": "string",
      "enum": ["boolean", "number", "string", "object", "date", "array"],
      "description": "Data type of the input value."
    },
    "name": {
      "type": "string",
      "description": "Human-readable name",
      "maxLength": 100
    },
    "value": {
      "description": "Current value",
      "oneOf": [
        { "type": "boolean" },
        { "type": "number" },
        { "type": "string" },
        { "type": "object" },
        { "type": "null" }
      ]
    },
    "status": {
      "type": "string",
      "enum": ["P", "C", "X"],
      "description": "P=Pending, C=Confirmed, X=Not Required"
    },
    "source": {
      "type": ["object", "null"],
      "description": "Where the input value comes from",
      "properties": {
        "type": {
          "type": "string",
          "enum": ["user", "show", "external_api", "cross_deal", "cross_clause_block"]
        },
        "reference": { "type": "string" },
        "field_path": { "type": "string" },
        "deal_id": { "type": "string" },
        "version_id": { "type": "string" }
      }
    },
    "resolved_at": {
      "type": ["string", "null"],
      "format": "date-time",
      "description": "When external source was resolved"
    }
  }
}

Part 5: Clause Schema

json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Clause",
  "description": "Financial obligation with trigger and calculation",
  "type": "object",
  "required": ["clause_id", "name", "trigger", "calculation"],
  "properties": {
    "clause_id": {
      "type": "string",
      "description": "Unique identifier within clause block",
      "pattern": "^clause_[a-z0-9_]+$"
    },
    "name": {
      "type": "string",
      "description": "Human-readable name",
      "maxLength": 100
    },
    "amount": {
      "type": ["number", "null"],
      "description": "Calculated amount when trigger is true (0 if trigger false)"
    },
    "trigger": {
      "description": "Condition that must be true for clause to apply",
      "oneOf": [
        { "type": "string" },
        {
          "type": "object",
          "properties": {
            "type": { "type": "string" },
            "expression": { "type": "string" }
          }
        }
      ]
    },
    "calculation": {
      "description": "Formula to compute amount when triggered",
      "oneOf": [
        { "type": "string" },
        {
          "type": "object",
          "properties": {
            "type": { "type": "string" },
            "expression": { "type": "string" }
          }
        }
      ]
    },
    "start_date": {
      "type": ["string", "null"],
      "format": "date",
      "description": "When clause becomes effective"
    },
    "end_date": {
      "type": ["string", "null"],
      "format": "date",
      "description": "When clause expires"
    },
    "pre_condition": {
      "type": ["string", "null"],
      "description": "Must be true before trigger is even evaluated"
    },
    "calculation_metadata": {
      "type": ["object", "null"],
      "description": "Transparency data about calculation",
      "properties": {
        "guarantee_component": { "type": "number" },
        "percentage_component": { "type": "number" },
        "winning_path": { "type": "string" },
        "calculation_summary": 
        { 
          "type": "string" ,
          "description": "outline the calculation used like 150 × $25 (adv) + 100 × $30 (door) + 20 × $50 (VIP) = $22,500" 
        },
        "last_calculated_at": { "type": "string", "format": "date-time" }
      },
      "additionalProperties": true
    },
    "payment_terms": {
      "type": "array",
      "description": "Defines the payment schedule for this clause",
      "items": {
      }
    }
  }
}

Part 6: Benefit Clause Schema

json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "BenefitClause",
  "description": "Non-cash value provided to client or buyer (travel, comps, perks, etc.)",
  "type": "object",
  "required": ["benefit_clause_id", "benefit_clause_name", "benefit_type", "benefit_direction", "description"],
  "properties": {
    "benefit_clause_id": {
      "type": "string",
      "description": "Unique identifier for this benefit clause",
      "pattern": "^BEN_[A-Z0-9_]+$"
    },
    "benefit_clause_name": {
      "type": "string",
      "description": "Human-readable name for the benefit",
      "maxLength": 200
    },
    "benefit_type": {
      "type": "string",
      "description": "Category of benefit",
      "enum": [
        "reimbursement",
        "service",
        "goods",
        "access",
        "credit",
        "IP",
        "other"
      ]
    },
    "benefit_direction": {
      "type": "string",
      "description": "Who receives the benefit",
      "enum": ["to_client", "to_buyer", "mutual"]
    },
    "description": {
      "type": "string",
      "description": "Plain-language description of the benefit"
    },
    "trigger": {
      "type": ["string", "null"],
      "description": "Optional condition that must be true for benefit to apply (e.g., 'SHOW_STATE.value == true')"
    },
    "conditions": {
      "type": "array",
      "description": "List of conditions or requirements for the benefit",
      "items": {
        "type": "string"
      }
    },
    "quantitative_terms": {
      "type": ["object", "null"],
      "description": "Numeric limits or quantities associated with the benefit",
      "properties": {
        "caps": {
          "type": "object",
          "description": "Maximum values or limits",
          "additionalProperties": {
            "type": "number"
          }
        },
        "units": {
          "type": "string",
          "description": "Currency or unit of measurement (e.g., 'USD', 'nights', 'tickets')"
        }
      }
    },
    "applicability": {
      "type": ["object", "null"],
      "description": "Scope of where/when the benefit applies",
      "properties": {
        "territory": {
          "type": "string",
          "description": "Geographic scope (e.g., 'US_only', 'worldwide')"
        },
        "shows_applicable": {
          "type": "array",
          "description": "List of clause_block_refs where this benefit applies",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "metadata": {
      "type": ["object", "null"],
      "description": "Additional information",
      "properties": {
        "source_contract_section": {
          "type": "string",
          "description": "Reference to source contract section"
        },
        "notes_internal": {
          "type": "string",
          "description": "Internal notes for team"
        }
      },
      "additionalProperties": true
    }
  }
}

Part 7: Obligation Clause Schema

json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "ObligationClause",
  "description": "What each party must do or not do (performance, promotion, exclusivity, etc.)",
  "type": "object",
  "required": ["obligation_clause_id", "obligation_clause_name", "obligation_type", "party", "description"],
  "properties": {
    "obligation_clause_id": {
      "type": "string",
      "description": "Unique identifier for this obligation clause",
      "pattern": "^OBL_[A-Z0-9_]+$"
    },
    "obligation_clause_name": {
      "type": "string",
      "description": "Human-readable name for the obligation",
      "maxLength": 200
    },
    "obligation_type": {
      "type": "string",
      "description": "Category of obligation",
      "enum": [
        "performance",
        "promotion",
        "exclusivity",
        "usage",
        "conduct",
        "deliverable",
        "approval",
        "compliance",
        "other"
      ]
    },
    "party": {
      "type": "string",
      "description": "Who has this obligation",
      "enum": ["client", "buyer", "mutual", "third_party"]
    },
    "description": {
      "type": "string",
      "description": "Plain-language description of the obligation"
    },
    "obligation_detail": {
      "type": ["object", "null"],
      "description": "Specific details about what must be done",
      "properties": {
        "actions": {
          "type": "array",
          "description": "List of specific actions required",
          "items": {
            "type": "string"
          }
        },
        "metrics": {
          "type": "object",
          "description": "Measurable requirements",
          "additionalProperties": true
        },
        "approval_required": {
          "type": "boolean",
          "description": "Whether approval is needed"
        },
        "approval_sla_hours": {
          "type": ["integer", "null"],
          "description": "Hours allowed for approval response"
        }
      }
    },
    "timeframe": {
      "type": ["object", "null"],
      "description": "When the obligation applies",
      "properties": {
        "start_date": {
          "type": ["string", "null"],
          "format": "date"
        },
        "end_date": {
          "type": ["string", "null"],
          "format": "date"
        },
        "frequency": {
          "type": "string",
          "description": "How often (e.g., 'monthly', 'per_show', 'one_time')"
        }
      }
    },
    "breach_consequence_summary": {
      "type": ["string", "null"],
      "description": "Plain-language summary of what happens if obligation is not met"
    },
    "related_benefits": {
      "type": "array",
      "description": "IDs of related financial or benefit clauses this obligation supports",
      "items": {
        "type": "string"
      }
    },
    "metadata": {
      "type": ["object", "null"],
      "description": "Additional information",
      "properties": {
        "source_contract_section": {
          "type": "string",
          "description": "Reference to source contract section"
        },
        "notes_internal": {
          "type": "string",
          "description": "Internal notes for team"
        }
      },
      "additionalProperties": true
    }
  }
}

Part 8: Other Clause Schema

json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "OtherClause",
  "description": "Deal mechanics and boilerplate (term, territory, options, rights, etc.)",
  "type": "object",
  "required": ["other_clause_id", "other_clause_name", "other_clause_type", "description"],
  "properties": {
    "other_clause_id": {
      "type": "string",
      "description": "Unique identifier for this clause",
      "pattern": "^OTH_[A-Z0-9_]+$"
    },
    "other_clause_name": {
      "type": "string",
      "description": "Human-readable name for the clause",
      "maxLength": 200
    },
    "other_clause_type": {
      "type": "string",
      "description": "Category of clause",
      "enum": [
        "term",
        "territory",
        "renewal",
        "option",
        "rights",
        "termination",
        "dispute",
        "force_majeure",
        "insurance",
        "confidentiality",
        "other"
      ]
    },
    "description": {
      "type": "string",
      "description": "Plain-language description of the clause"
    },
    "key_terms": {
      "type": ["object", "null"],
      "description": "Structured key terms for this clause",
      "properties": {
        "term": {
          "type": "object",
          "description": "Term-related details",
          "properties": {
            "start_date": {
              "type": ["string", "null"],
              "format": "date"
            },
            "end_date": {
              "type": ["string", "null"],
              "format": "date"
            },
            "auto_renew": {
              "type": "boolean"
            },
            "renewal_notice_deadline_days": {
              "type": ["integer", "null"]
            }
          }
        },
        "territory": {
          "type": "object",
          "description": "Territory-related details",
          "properties": {
            "regions_included": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "regions_excluded": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          }
        }
      },
      "additionalProperties": true
    },
    "business_impact_summary": {
      "type": ["string", "null"],
      "description": "Plain-language summary of business impact"
    },
    "metadata": {
      "type": ["object", "null"],
      "description": "Additional information",
      "properties": {
        "source_contract_section": {
          "type": "string",
          "description": "Reference to source contract section"
        },
        "notes_internal": {
          "type": "string",
          "description": "Internal notes for team"
        }
      },
      "additionalProperties": true
    }
  }
}

Part 9: Template Schema

json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https:///schemas/template.json",
  "title": "Template",
  "description": "Reusable structure definition for creating deals",
  "type": "object",
  "required": ["template_id", "template_name", "deal_type", "variable_definitions", "clause_block_templates"],
  "properties": {
    "template_id": {
      "type": "string",
      "pattern": "^tpl_[a-z0-9_]+$"
    },
    "template_name": {
      "type": "string",
      "maxLength": 200
    },
    "template_version": {
      "type": "string"
    },
    "description": {
      "type": "string"
    },
    "deal_type": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "enum": ["active", "deprecated", "archived"],
      "default": "active"
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "created_by": {
      "type": "string"
    },
    "variable_definitions": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/VariableDefinition"
      }
    },
    "clause_block_templates": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/ClauseBlockTemplate"
      }
    }
  },
  "definitions": {
    "VariableDefinition": {
      "type": "object",
      "required": ["variable_key", "name", "type", "required"],
      "properties": {
        "variable_key": {
          "type": "string",
          "pattern": "^v_[a-z_]+$"
        },
        "name": {
          "type": "string"
        },
        "type": {
          "type": "string",
          "enum": ["number", "string", "boolean"]
        },
        "required": {
          "type": "boolean"
        },
        "default_value": {
          "oneOf": [
            { "type": "number" },
            { "type": "string" },
            { "type": "boolean" },
            { "type": "null" }
          ]
        },
        "description": {
          "type": "string"
        },
        "validation": {
          "type": "object",
          "properties": {
            "min": { "type": ["number", "null"] },
            "max": { "type": ["number", "null"] },
            "pattern": { "type": "string" },
            "enum": { "type": "array" }
          }
        }
      }
    },
    "ClauseBlockTemplate": {
      "type": "object",
      "required": ["clause_block_template_id", "name", "is_required"],
      "properties": {
        "clause_block_template_id": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "description": {
          "type": "string"
        },
        "is_required": {
          "type": "boolean"
        },
        "allow_multiple": {
          "type": "boolean",
          "default": false
        },
        "additional_variables": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/VariableDefinition"
          }
        },
        "state_templates": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/StateTemplate"
          }
        },
        "input_templates": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/InputTemplate"
          }
        },
        "clause_templates": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/ClauseTemplate"
          }
        }
      }
    },    
    "Clause": {
      "type": "object",
      "required": ["clause_id", "name", "amount", "trigger", "calculation"],
      "properties": {
        "clause_id": { "type": "string" },
        "name": { "type": "string" },
        "amount": { "type": "number" },
        "trigger": {
          "type": "string",
          "description": "Expression evaluating to boolean."
        },
        "calculation": {
          "type": "string",
          "description": "Expression evaluating to number."
        },
        "start_date": { "type": "string", "format": "date" },
        "end_date": { "type": "string", "format": "date" },
        "pre_condition": { "type": "string" },
        "calculation_metadata": { "type": "object" }
      }
    },
    "StateTemplate": {
      "type": "object",
      "required": ["state_key", "state_type", "name", "is_required"],
      "properties": {
        "state_key": { "type": "string" },
        "state_type": { "type": "string" },
        "name": { "type": "string" },
        "is_required": { "type": "boolean" },
        "default_status": { "type": "string", "enum": ["D", "F", "C"] },
        "calculation_template": {
          "oneOf": [
            { "type": "string" },
            { "type": "object" }
          ]
        }
      }
    },
    "InputTemplate": {
      "type": "object",
      "required": ["input_key", "input_type", "name", "is_required"],
      "properties": {
        "input_key": { "type": "string" },
        "input_type": { "type": "string" },
        "name": { "type": "string" },
        "is_required": { "type": "boolean" },
        "default_status": { "type": "string", "enum": ["P", "C", "X"] },
        "schema": { "type": "object" }
      }
    },
    "ClauseTemplate": {
      "type": "object",
      "required": ["clause_template_id", "name", "is_required"],
      "properties": {
        "clause_template_id": { "type": "string" },
        "name": { "type": "string" },
        "is_required": { "type": "boolean" },
        "trigger_template": { "type": "string" },
        "calculation_template": { "type": "string" },
        "requires_date_range": { "type": "boolean" }
      }
    }
  }
}

Part 10: Complete Examples

10.1 Flat Guarantee Deal

json

{
  "deal_id": "deal_flat_guarantee_001",
  "deal_type": "flat_guarantee",
  "artist_id": "artist_indie_band_001",
  "promoter_id": "promoter_local_001",
  "name": "Indie Band - The Fonda - Dec 15, 2025",
  "created_at": "2025-11-01T10:00:00Z",
  "created_by": "booking_agent_001",
  "initialized_from_template": "tpl_flat_guarantee_001",
  "version_pointers": {
    "primary": "v_submitted_001"
  },
  "versions": [
    {
      "version_id": "v_submitted_001",
      "status": "submitted",
      "created_from": null,
      "submitted_at": "2025-11-01T10:30:00Z",
      "submitted_by": "booking_agent_001",
      "clause_blocks": [
        {
          "clause_block_id": "cb_show_guarantee_001",
          "clause_block_ref": "CB_SHOW_GUARANTEE",
          "name": "The Fonda Performance",
          "clause_block_type": "show_performance",
          "metadata": {
            "show_id": "show_fonda_dec15",
            "venue": "The Fonda Theatre",
            "city": "Los Angeles",
            "date": "2025-12-15",
            "capacity": 1200
          },
          "static_variables": {
            "v_guarantee": 2500
          },
          "states": [
            {
              "state_key": "SHOW_STATE",
              "state_type": "boolean",
              "name": "Show Played",
              "value": false,
              "status": "F",
              "calculation": "SHOW_DATE_INPUT.value.date < today() && SHOW_DATE_INPUT.value.status == 'confirmed'",
              "calculated_value": null,
              "calculation_error": null,
              "last_calculated_at": "2025-11-01T10:30:00Z"
            }
          ],
          "inputs": [
            {
              "input_key": "SHOW_DATE_INPUT",
              "input_type": "object",
              "name": "Show Confirmation",
              "value": {
                "date": "2025-12-15",
                "status": "unconfirmed"
              },
              "status": "P",
              "source": null
            }
          ],
          "financial_clauses": [
            {
              "clause_id": "clause_guarantee",
              "name": "Guarantee for Show",
              "amount": 0,
              "trigger": "SHOW_STATE.value == true",
              "calculation": "v_guarantee",
              "start_date": "2025-11-01",
              "end_date": "2025-12-25",
              "pre_condition": null,
              "calculation_metadata": {
                "guarantee_component": 2500,
                "winning_path": "guarantee",
                "calculation_summary": "Flat Guarantee of $2,500",
                "last_calculated_at": "2025-11-01T10:30:00Z"
              }
            }
          ]
        }
      ]
    }
  ]
}

10.2 Guarantee vs NBOR with Override

json

{
  "deal_id": "deal_gvn_002",
  "deal_type": "guarantee_vs_percentage_nbor",
  "artist_id": "artist_rock_band_002",
  "promoter_id": "promoter_major_001",
  "name": "Rock Band - The Greek - Dec 20, 2025",
  "created_at": "2025-11-15T14:00:00Z",
  "created_by": "booking_agent_002",
  "initialized_from_template": "tpl_guarantee_vs_nbor_001",
  "version_pointers": {
    "primary": "v_submitted_002",
    "forecast_optimistic": "v_working_abc"
  },
  "versions": [
    {
      "version_id": "v_submitted_002",
      "status": "submitted",
      "created_from": "v_submitted_001",
      "submitted_at": "2025-12-01T16:00:00Z",
      "submitted_by": "finance_user_001",
      "clause_blocks": [
        {
          "clause_block_id": "cb_show_gvn_001",
          "clause_block_ref": "CB_SHOW_GVN",
          "name": "The Greek Performance",
          "clause_block_type": "show_performance",
          "metadata": {
            "show_id": "show_greek_dec20",
            "venue": "The Greek Theatre",
            "city": "Los Angeles",
            "date": "2025-12-20",
            "capacity": 5800
          },
          "static_variables": {
            "v_guarantee": 25000,
            "v_artist_percentage": 85,
            "v_tax_rate": 0.0925
          },
          "states": [
            {
              "state_key": "SHOW_STATE",
              "state_type": "boolean",
              "name": "Show Played",
              "value": true,
              "status": "C",
              "calculation": "SHOW_DATE_INPUT.value.date < today() && SHOW_DATE_INPUT.value.status == 'confirmed'",
              "last_calculated_at": "2025-12-21T10:00:00Z"
            },
            {
              "state_key": "SHOW_SETTLED",
              "state_type": "object",
              "name": "Show Settlement",
              "value": {
                "gross_box_office": 290000,
                "sales_tax_collected": 24551.61,
                "facility_fees": 17400,
                "net_box_office_receipts": 248048.39
              },
              "status": "O",
              "calculation": {
                "type": "aggregate",
                "fields": {
                  "gross_box_office": "TICKET_DETAIL_INPUT.value.total_amount",
                  "sales_tax_collected": "TICKET_DETAIL_INPUT.value.total_amount * v_tax_rate / (1 + v_tax_rate)",
                  "facility_fees": "FACILITY_FEE_INPUT.value.amount_per_ticket * TICKET_DETAIL_INPUT.value.quantity",
                  "net_box_office_receipts": "this.gross_box_office - this.sales_tax_collected - this.facility_fees"
                }
              },
              "calculated_value": {
                "gross_box_office": 287500,
                "sales_tax_collected": 24340.23,
                "facility_fees": 17250,
                "net_box_office_receipts": 245909.77
              },
              "override_active": true,
              "last_calculated_at": "2025-12-21T10:00:00Z"
            }
          ],
          "inputs": [
            {
              "input_key": "SHOW_DATE_INPUT",
              "input_type": "object",
              "name": "Show Confirmation",
              "value": {
                "date": "2025-12-20",
                "status": "confirmed"
              },
              "status": "C",
              "source": null
            },
            {
              "input_key": "TICKET_DETAIL_INPUT",
              "input_type": "object",
              "name": "Ticket Sales Data",
              "value": {
                "tier": "general_admission",
                "quantity": 5750,
                "price_per_ticket": 50.00,
                "total_amount": 287500.00,
                "sales_source": "box_office"
              },
              "status": "C",
              "source": {
                "type": "show",
                "reference": "show_greek_dec20",
                "field_path": "ticket_sales"
              }
            },
            {
              "input_key": "FACILITY_FEE_INPUT",
              "input_type": "object",
              "name": "Facility Fees",
              "value": {
                "amount_per_ticket": 3.00,
                "breakdown": [
                  { "description": "Venue facility fee", "amount_per_ticket": 2.00 },
                  { "description": "Processing fee", "amount_per_ticket": 1.00 }
                ]
              },
              "status": "C",
              "source": null
            }
          ],
          "financial_clauses": [
            {
              "clause_id": "clause_guarantee_vs_nbor",
              "name": "Guarantee vs NBOR for Show",
              "amount": 210841.13,
              "trigger": "SHOW_SETTLED.status == 'C' || SHOW_SETTLED.status == 'F' || SHOW_SETTLED.status == 'O'",
              "calculation": "MAX((SHOW_SETTLED.value.net_box_office_receipts * v_artist_percentage / 100), v_guarantee)",
              "start_date": "2025-11-15",
              "end_date": "2025-12-31",
              "pre_condition": null,
              "calculation_metadata": {
                "guarantee_component": 25000,
                "percentage_component": 210841.13,
                "winning_path": "percentage",
                "calculation_summary": "MAX($25,000, 248,048.39 (NBOR) * 85% = 210,841.13)",
                "last_calculated_at": "2025-12-21T10:00:00Z"
              }
            }
          ]
        }
      ]
    },
    {
      "version_id": "v_working_abc",
      "status": "working",
      "created_from": "v_submitted_002",
      "locked_by": "booking_agent_002",
      "last_auto_save": "2025-12-22T09:30:00Z",
      "clause_blocks": [
        {
          "clause_block_id": "cb_show_gvn_001",
          "clause_block_ref": "CB_SHOW_GVN",
          "name": "The Greek Performance - Optimistic Forecast",
          "static_variables": {
            "v_guarantee": 25000,
            "v_artist_percentage": 85,
            "v_tax_rate": 0.0925
          },
          "states": [
            {
              "state_key": "SHOW_SETTLED",
              "state_type": "object",
              "name": "Show Settlement",
              "value": {
                "gross_box_office": 320000,
                "sales_tax_collected": 27091.24,
                "facility_fees": 17400,
                "net_box_office_receipts": 275508.76
              },
              "status": "F",
              "calculation": "..."
            }
          ],
          "inputs": [
            {
              "input_key": "TICKET_DETAIL_INPUT",
              "input_type": "object",
              "name": "Ticket Sales Data",
              "value": {
                "tier": "general_admission",
                "quantity": 5800,
                "price_per_ticket": 55.17,
                "total_amount": 320000.00,
                "notes": "Optimistic scenario - higher ticket price"
              },
              "status": "F"
            }
          ],
          "financial_clauses": [
            {
              "clause_id": "clause_guarantee_vs_nbor",
              "name": "Guarantee vs NBOR for Show",
              "amount": 234182.45,
              "trigger": "...",
              "calculation": "..."
            }
          ]
        }
      ]
    }
  ]
}

10.3 Multi-Show Tour with Aggregation

json

{
  "deal_id": "deal_spring_tour_2025",
  "deal_type": "guarantee_vs_percentage_nbor",
  "artist_id": "artist_pop_star_001",
  "promoter_id": "promoter_national_001",
  "name": "Pop Star - Spring Tour 2025 - West Coast",
  "version_pointers": {
    "primary": "v_submitted_003"
  },
  "versions": [
    {
      "version_id": "v_submitted_003",
      "status": "submitted",
      "clause_blocks": [
        {
          "clause_block_id": "cb_show_1",
          "clause_block_ref": "CB_SHOW_1",
          "name": "Show 1 - The Fonda",
          "static_variables": { "v_guarantee": 5000, "v_artist_percentage": 85 },
          "states": [
            {
              "state_key": "SHOW_SETTLED",
              "value": { "net_box_office_receipts": 18000 },
              "status": "C"
            }
          ],
          "financial_clauses": [
            {
              "clause_id": "clause_show_1",
              "amount": 15300,
              "trigger": "true"
            }
          ]
        },
        {
          "clause_block_id": "cb_show_2",
          "clause_block_ref": "CB_SHOW_2",
          "name": "Show 2 - The Greek",
          "static_variables": { "v_guarantee": 25000, "v_artist_percentage": 85 },
          "states": [
            {
              "state_key": "SHOW_SETTLED",
              "value": { "net_box_office_receipts": 248000 },
              "status": "C"
            }
          ],
          "financial_clauses": [
            {
              "clause_id": "clause_show_2",
              "amount": 210800,
              "trigger": "true"
            }
          ]
        },
        {
          "clause_block_id": "cb_show_3",
          "clause_block_ref": "CB_SHOW_3",
          "name": "Show 3 - Hollywood Bowl",
          "static_variables": { "v_guarantee": 100000, "v_artist_percentage": 85 },
          "states": [
            {
              "state_key": "SHOW_SETTLED",
              "value": { "net_box_office_receipts": 1250000 },
              "status": "C"
            }
          ],
          "financial_clauses": [
            {
              "clause_id": "clause_show_3",
              "amount": 1062500,
              "trigger": "true"
            }
          ]
        },
        {
          "clause_block_id": "cb_tour_summary",
          "clause_block_ref": "CB_TOUR_SUMMARY",
          "name": "Tour Summary",
          "clause_block_type": "tour_summary",
          "static_variables": {},
          "states": [
            {
              "state_key": "TOTAL_ARTIST_PAYMENT",
              "state_type": "number",
              "name": "Total Artist Payment",
              "value": 1288600,
              "status": "C",
              "calculation": "SUM(cb.financial_clauses[0].amount for cb in [CB_SHOW_1, CB_SHOW_2, CB_SHOW_3] where cb.financial_clauses[0].trigger == true)"
            }
          ],
          "inputs": [],
          "financial_clauses": [
            {
              "clause_id": "clause_tour_total",
              "name": "Tour Total Payment",
              "amount": 1288600,
              "trigger": "true",
              "calculation": "TOTAL_ARTIST_PAYMENT.value"
            }
          ]
        }
      ]
    }
  ]
}

10.4 Endorsement Deal with All Clause Families

This example demonstrates a clause block containing all four clause families: financial, benefit, obligation, and other clauses.

json

{
  "deal_id": "deal_endorsement_001",
  "deal_type": "custom",
  "artist_id": "artist_influencer_001",
  "promoter_id": "brand_beverage_001",
  "name": "Influencer Brand Endorsement - 2026",
  "version_pointers": {
    "primary": "v_submitted_001"
  },
  "versions": [
    {
      "version_id": "v_submitted_001",
      "status": "submitted",
      "clause_blocks": [
        {
          "clause_block_id": "cb_endorsement_main",
          "clause_block_ref": "CB_ENDORSEMENT",
          "name": "Brand Endorsement Agreement",
          "clause_block_type": "custom",
          "static_variables": {
            "v_base_fee": 50000,
            "v_bonus_threshold_posts": 4,
            "v_bonus_amount": 10000
          },
          "states": [
            {
              "state_key": "POSTS_COMPLETED",
              "state_type": "number",
              "name": "Posts Completed This Month",
              "value": 5,
              "status": "C",
              "calculation": "SOCIAL_POSTS_INPUT.value.count"
            }
          ],
          "inputs": [
            {
              "input_key": "SOCIAL_POSTS_INPUT",
              "input_type": "object",
              "name": "Social Media Posts",
              "value": {
                "count": 5,
                "platforms": ["instagram", "tiktok"],
                "month": "2026-01"
              },
              "status": "C"
            }
          ],
          "financial_clauses": [
            {
              "clause_id": "clause_base_fee",
              "name": "Monthly Base Fee",
              "amount": 50000,
              "trigger": "true",
              "calculation": "v_base_fee"
            },
            {
              "clause_id": "clause_performance_bonus",
              "name": "Performance Bonus",
              "amount": 10000,
              "trigger": "POSTS_COMPLETED.value >= v_bonus_threshold_posts",
              "calculation": "v_bonus_amount"
            }
          ],
          "benefit_clauses": [
            {
              "benefit_clause_id": "BEN_PRODUCT_001",
              "benefit_clause_name": "Product Allotment",
              "benefit_type": "goods",
              "benefit_direction": "to_client",
              "description": "Client receives 24 cases of product per month for personal use and gifting",
              "trigger": null,
              "conditions": [
                "Product must be used for personal consumption or gifting only",
                "No resale permitted"
              ],
              "quantitative_terms": {
                "caps": {
                  "cases_per_month": 24
                },
                "units": "cases"
              },
              "applicability": {
                "territory": "US_only",
                "shows_applicable": []
              },
              "metadata": {
                "source_contract_section": "Benefits Schedule §2.1",
                "notes_internal": "Highlight this in sales pitch - significant value add"
              }
            },
            {
              "benefit_clause_id": "BEN_EVENT_ACCESS_001",
              "benefit_clause_name": "VIP Event Access",
              "benefit_type": "access",
              "benefit_direction": "to_client",
              "description": "Client and up to 3 guests receive VIP access to all brand-sponsored events",
              "trigger": null,
              "conditions": [
                "Must RSVP at least 7 days in advance",
                "Subject to venue capacity"
              ],
              "quantitative_terms": {
                "caps": {
                  "guests_per_event": 3
                },
                "units": "guests"
              },
              "applicability": {
                "territory": "worldwide",
                "shows_applicable": []
              },
              "metadata": {
                "source_contract_section": "Benefits Schedule §2.3"
              }
            }
          ],
          "obligation_clauses": [
            {
              "obligation_clause_id": "OBL_SOCIAL_POSTS_001",
              "obligation_clause_name": "Social Media Posts",
              "obligation_type": "promotion",
              "party": "client",
              "description": "Client will post promotional content for the brand 4 times per month on Instagram and TikTok",
              "obligation_detail": {
                "actions": [
                  "Post at least 4 times per calendar month",
                  "At least 2 posts must be video content",
                  "Posts must tag @brand_handle and include #brandcampaign"
                ],
                "metrics": {
                  "min_posts_per_month": 4,
                  "platforms": ["instagram", "tiktok"],
                  "min_video_posts": 2
                },
                "approval_required": true,
                "approval_sla_hours": 72
              },
              "timeframe": {
                "start_date": "2026-01-01",
                "end_date": "2026-12-31",
                "frequency": "monthly"
              },
              "breach_consequence_summary": "Failure to meet posting minimum for 2 consecutive months allows brand to reduce fee by 20% or terminate for cause",
              "related_benefits": ["clause_base_fee", "clause_performance_bonus"],
              "metadata": {
                "source_contract_section": "Endorsement Agreement §4",
                "notes_internal": "Frame as deliverables in kickoff call"
              }
            },
            {
              "obligation_clause_id": "OBL_EXCLUSIVITY_001",
              "obligation_clause_name": "Category Exclusivity",
              "obligation_type": "exclusivity",
              "party": "client",
              "description": "Client may not endorse, promote, or be associated with any competing beverage brands during term",
              "obligation_detail": {
                "actions": [
                  "No endorsement of competing beverage products",
                  "No appearance in competing brand campaigns",
                  "Must disclose any pre-existing beverage brand relationships"
                ],
                "metrics": {
                  "excluded_categories": ["beverages", "energy_drinks", "sports_drinks"]
                },
                "approval_required": false,
                "approval_sla_hours": null
              },
              "timeframe": {
                "start_date": "2026-01-01",
                "end_date": "2026-12-31",
                "frequency": "continuous"
              },
              "breach_consequence_summary": "Material breach allowing immediate termination and return of all fees paid",
              "related_benefits": [],
              "metadata": {
                "source_contract_section": "Exclusivity §5"
              }
            }
          ],
          "other_clauses": [
            {
              "other_clause_id": "OTH_TERM_001",
              "other_clause_name": "Term and Territory",
              "other_clause_type": "term",
              "description": "Agreement runs for 12 months from January 1, 2026 and applies worldwide excluding China",
              "key_terms": {
                "term": {
                  "start_date": "2026-01-01",
                  "end_date": "2026-12-31",
                  "auto_renew": false,
                  "renewal_notice_deadline_days": 30
                },
                "territory": {
                  "regions_included": ["worldwide"],
                  "regions_excluded": ["CN"]
                }
              },
              "business_impact_summary": "Client is locked in for one year; brand cannot extend unless new agreement is signed at least 30 days before expiry",
              "metadata": {
                "source_contract_section": "Master Agreement §2",
                "notes_internal": "CS should remind client of renewal window in Q4"
              }
            },
            {
              "other_clause_id": "OTH_TERMINATION_001",
              "other_clause_name": "Termination Rights",
              "other_clause_type": "termination",
              "description": "Either party may terminate for material breach with 30 days written notice and opportunity to cure",
              "key_terms": {
                "notice_period_days": 30,
                "cure_period_days": 15,
                "termination_for_convenience": false
              },
              "business_impact_summary": "Both parties have protection against breach but cannot exit without cause",
              "metadata": {
                "source_contract_section": "Termination §8"
              }
            }
          ]
        }
      ]
    }
  ]
}

Part 11: Validation Rules Summary

Rule	Applies To	Validation
Unique ID	deal_id, version_id, clause_block_id	Must be unique within scope
Unique Key	state_key, input_key	Must be unique within clause_block
Unique Ref	clause_block_ref	Must be unique within version
Valid Reference	All calculations	Must resolve to existing element
No Cycles	All calculations	Dependency graph must be acyclic
Required Fields	All schemas	Must be present per schema
Status Values	state.status, input.status	Must be valid enum value
Date Format	All dates	Must be valid ISO 8601

Conclusion

These JSON schemas provide a complete, validatable structure for the state machine-based touring deal system. They enable:

Type-safe API contracts
Automated document validation
Code generation for clients and servers
Clear documentation of data structures

The schemas are designed to be strict enough for consistency while flexible enough for the diverse needs of touring deal modeling.

Interfaces

State Machine Proposal

Sample Deals

Touring Deal

Endorsement Deal

Sports Endo Deal

Common Features

State Machine JSON Schemas

Overview

Part 1: Core Deal Schema

1.1 Deal Document

1.2 Version Schema

Part 2: Clause Block Schema

2.1 Clause Block

Part 3: State Schema

Part 4: Input Schema

Part 5: Clause Schema

Part 6: Benefit Clause Schema

Part 7: Obligation Clause Schema

Part 8: Other Clause Schema

Part 9: Template Schema

Part 10: Complete Examples

10.1 Flat Guarantee Deal

10.2 Guarantee vs NBOR with Override

10.3 Multi-Show Tour with Aggregation

10.4 Endorsement Deal with All Clause Families

Part 11: Validation Rules Summary

Conclusion

Sample Deals

Touring Deal

Endorsement Deal

Sports Endo Deal

State Machine JSON Schemas ​

Overview ​

Part 1: Core Deal Schema ​

1.1 Deal Document ​

1.2 Version Schema ​

Part 2: Clause Block Schema ​

2.1 Clause Block ​

Part 3: State Schema ​

Part 4: Input Schema ​

Part 5: Clause Schema ​

Part 6: Benefit Clause Schema ​

Part 7: Obligation Clause Schema ​

Part 8: Other Clause Schema ​

Part 9: Template Schema ​

Part 10: Complete Examples ​

10.1 Flat Guarantee Deal ​

10.2 Guarantee vs NBOR with Override ​

10.3 Multi-Show Tour with Aggregation ​

10.4 Endorsement Deal with All Clause Families ​

Part 11: Validation Rules Summary ​

Conclusion ​

State Machine JSON Schemas

Overview

Part 1: Core Deal Schema

1.1 Deal Document

1.2 Version Schema

Part 2: Clause Block Schema

2.1 Clause Block

Part 3: State Schema

Part 4: Input Schema

Part 5: Clause Schema

Part 6: Benefit Clause Schema

Part 7: Obligation Clause Schema

Part 8: Other Clause Schema

Part 9: Template Schema

Part 10: Complete Examples

10.1 Flat Guarantee Deal

10.2 Guarantee vs NBOR with Override

10.3 Multi-Show Tour with Aggregation

10.4 Endorsement Deal with All Clause Families

Part 11: Validation Rules Summary

Conclusion