Skip to main content

​
Understanding Rule Structure

Each rule consists of one or more conditions that work together to validate model elements. Rules use a structured logic system:
ComponentDescription
LogicHow conditions combine: WHERE (filter), AND (additional filter), CHECK (final validation)
Property NameThe object property to check (e.g., category, width, baseline.length)
PredicateThe comparison operation (equal to, greater than, less than, exists, in list, etc.)
ValueThe reference value for comparison
MessageDescription shown in validation results (auto-generated but can be overwritten)
Report SeverityDefines the importance: ERROR, WARNING, or INFO
Important Rule Structure: Every rule must follow this pattern:
  • Start with a WHERE condition to filter objects
  • Add AND conditions to further refine the filter (optional)
  • End with a CHECK condition that performs the validation
Each rule should only have one CHECK condition at the end. If you need multiple checks, create separate rules.

​
Creating Your First Rule

​
Example: Checking Wall Thickness

Let’s create a rule that checks if walls are at least 200 units thick:
  1. WHERE condition: Filter for walls
    • Property: Category
    • Predicate: equal to
    • Value: Walls
  2. CHECK condition: Validate thickness
    • Property: Width
    • Predicate: less than
    • Value: 200
    • Severity: ERROR
    • Message: “Wall thickness must be at least 200” (auto-generated, but can be customized)
This rule will flag any wall thinner than 200 units as an error.

​
Adding Multiple Conditions

You can add multiple AND conditions between WHERE and CHECK to create more complex filters: Example: Check steel beams that are too long
  • WHERE Category = Beams
  • AND Material = Steel
  • CHECK Length > 5000

​
Supported Predicates

Model Checker supports the following predicates for comparing property values:
PredicateDescriptionExample
existsChecks if a property existsheight exists
equal toExact value matchwidth equal to 300
not equal toValue doesn’t matchmaterial not equal to Concrete
identical toExact match (case-sensitive)name identical to Wall-01
less thanValue below thresholdthickness less than 50
greater thanValue exceeds thresholdheight greater than 3000
in rangeValue within boundselevation in range 0,10000
in listValue in allowed settype in list W1,W2,W3
containsProperty contains substringname contains Beam
does not containProperty doesn’t contain substringname does not contain temp
is trueBoolean property is trueis_structural is true
is falseBoolean property is falseis_placeholder is false
is likeLoose text matching (pattern matching)name is like Wall matches “Walls”, “Wall-01”, etc.

​
Rule Types

​
Property Existence

Check whether specific properties exist on model elements. Useful for ensuring required data is present. Example: CHECK acoustic rating exists

​
Pattern Matching

Validate that property values match specific patterns or formats. For example, ensure element names follow a naming convention. Example: Use is like for pattern matching or contains for substring matching.

​
Numeric Comparisons

Compare numeric property values against thresholds or ranges. Check that dimensions, areas, or other measurements meet requirements. Examples:
  • greater than - Values above a threshold
  • less than - Values below a threshold
  • in range - Values between two numbers

​
Value Validation

Verify that properties contain expected values or fall within acceptable ranges. Examples:
  • equal to - Exact match
  • in list - Match any value in a comma-separated list
  • not equal to - Exclude exact matches
  • identical to - Exact match (case-sensitive)

​
Rule Messages

Rule messages are auto-generated to help validate the logic you are testing for. The auto-generated message describes what the rule is checking, making it easier to understand the validation logic. You can overwrite the auto-generated message with a custom message if you want to provide more specific guidance or context.
Auto-generated messages help ensure your rules are clear and understandable. Consider customizing them when you need to provide specific instructions or context for your team.

​
Best Practices

​
Use Specific Property Paths

Use exact property paths for accurate validation. The Model Checker understands properties in Speckle objects regardless of schema:
  • Direct properties: category, name, id
  • Nested properties: baseline.length, parameters.WIDTH.value
  • Revit parameters: Use parameter names like Mark, Width, Assembly Code
If a property like Length exists in multiple locations within an object’s properties, specifying baseline.length ensures the correct value is checked.

​
Set Appropriate Severity Levels

  • ERROR: Critical issues that must be fixed (e.g., “Wall thickness must be at least 200”)
  • WARNING: Moderate concerns that should be reviewed (e.g., “Height should be no more than 3000”)
  • INFO: Informational notifications (e.g., “Material is Concrete”)

​
Write Clear Messages

When customizing messages, make them actionable and specific. Avoid vague terms like “Wall thickness check” and instead say “Wall thickness must be at least 200mm.”

​
Examples of Good vs. Bad Messages

Rule ConditionBad Message ❌Better Message ✅
Width less than 200 and ERROR”Wall thickness check""Wall thickness must be at least 200”
Height greater than 3000 and WARNING”Height check""Height should be no more than 3000”
Material equal to "Concrete" and INFO”Material info""Material is Concrete”

​
Common Rule Patterns

​
Filter by Category

WHERE Category = Walls
CHECK [validation condition]

​
Multiple Filters

WHERE Category = Beams
AND Material = Steel
CHECK Length > 5000

​
Property Existence Check

WHERE Category = Windows
CHECK acoustic rating exists

​
Value Range Check

WHERE Category = Walls
CHECK Width in range 200,400

​
Door Naming Convention

WHERE Category = Doors
CHECK name is like ^D\d{3}$
This rule ensures all doors follow a naming convention (e.g., “D001”, “D123”).

​
Structural Column Height Range

WHERE Category = Columns
AND is_structural is true
CHECK height not in range 2400,4000
This rule checks that structural columns have heights between 2400 and 4000 units.

​
Exporting Rulesets

​
Getting Your Ruleset URL

Once you’ve created a ruleset:
  1. Navigate to your project’s rulesets page
  2. Find the ruleset you want to use
  3. Click Copy Link to get the URL for your ruleset
This URL is a permanent link to your ruleset. When you update your rules in Model Checker, the URL automatically reflects the latest version.
The ruleset URL automatically updates when you modify your rules. You don’t need to regenerate the URL or update your automation configuration.

​
Exporting

Rulesets can also be exported as files for backup or sharing:
  1. Navigate to your project’s rulesets page
  2. Find the ruleset you want to export
  3. Use the export option to download the ruleset
Exported files use the TSV (Tab-Separated Values) format. TSV files can be imported back into Model Checker or shared with other projects or teams.

​
Using Rulesets in Automations

​
Setting Up Model Checker Automation

  1. Copy the ruleset URL from Model Checker
  2. In Speckle Automate, create a new automation
  3. Select the Model Checker function
  4. Paste the ruleset URL into the configuration
  5. Configure which models or projects should be checked
The automation will automatically use the latest version of your rules whenever the URL is accessed.

​
How It Works

When you publish a model to Speckle:
  1. The Model Checker automation is triggered
  2. It fetches your rules from the ruleset URL
  3. It validates the model against all rules in the ruleset
  4. Results are stored and can be viewed in the 3D viewer

​
Importing Rules

If you have existing rules in a file, you can import them into Model Checker:
  1. Navigate to your project’s rulesets page
  2. Click Import
  3. Provide a name and description for the imported ruleset
  4. Upload your file
Imported files should use the TSV (Tab-Separated Values) format. The file should have the following columns:
TSV File Hosting: If you’re creating TSV files manually (outside of the Model Checker UI), the file must be hosted somewhere and served with the MIME-type text/tab-separated-values. The URL to this hosted file can then be used in automation configurations.

​
File Format

The file format should have the following columns:
  • Rule Number - Groups conditions into a single rule
  • Logic - WHERE, AND, or CHECK
  • Property Name - The object property to check
  • Predicate - The comparison operation
  • Value - The reference value for comparison
  • Report Severity - ERROR, WARNING, or INFO
  • Message - Description shown in validation results

​
Example File

Rule Number	Logic	Property Name	Predicate	Value	Report Severity	Message
1	WHERE	Category	equal to	Walls		
1	CHECK	Width	less than	200	ERROR	Wall thickness must be at least 200
2	WHERE	Category	equal to	Beams		
2	AND	Material	equal to	Steel		
2	CHECK	Length	greater than	5000	WARNING	Steel beams should not exceed 5000 in length

​
Managing Multiple Rulesets

You can create multiple rulesets for a single project. This is useful for organizing different types of validation checks:
  • Building Code Compliance - Rules for code requirements
  • Naming Conventions - Rules for element naming standards
  • Material Standards - Rules for material specifications
  • Dimensional Checks - Rules for size and dimension validation
Each ruleset can be used independently in automations, allowing you to run different validation checks on the same models.

​
Updating Rules

When you update rules in Model Checker:
  1. Make changes to your rules in the Model Checker interface
  2. The ruleset URL automatically reflects the latest version
  3. Your automations will use the updated rules without needing to reconfigure
No need to update automation configurations or regenerate URLs.

​
Frequently Asked Questions

Yes, the auto-generated messages are designed to be clear and helpful. You can use them as-is or customize them to provide more specific guidance for your team.
You can add multiple AND conditions between WHERE and CHECK to filter by multiple properties. However, the CHECK condition should validate a single property. If you need to check multiple properties, create separate rules.
Use the exact property path as it appears in your model data. If you’re unsure, you can explore your model’s properties in the 3D viewer or use the property search in Model Checker to find the correct path.
Yes, you can use the same ruleset URL in multiple automations. All automations will use the latest version of your rules whenever they run.
If you delete a ruleset, any automations using that ruleset’s URL will no longer be able to fetch the rules. Make sure to update or remove those automations.
No, the ruleset URL automatically reflects the latest version of your rules. Your automations will use the updated rules without needing to reconfigure.
Yes, exported files can be shared with other teams or imported into other projects. This makes it easy to standardize validation rules across projects.
TSV (Tab-Separated Values) is used instead of CSV (Comma-Separated Values) to cope with commas that may be present in properties or messages. TSV is the same as CSV but uses tabs in place of commas to separate values, preventing issues when property values or messages contain commas.
Yes, you can create TSV files in Excel. When saving, choose “Tab delimited” or “Text (Tab delimited)” as the file format. Make sure to save with the .tsv extension.
IDS (Information Delivery Specification) is designed for IFC model checking, but IDS rules can be applied to all Speckle models regardless of their source format. However, there are important differences:
  • IDS checks for rules that relate to assembly membership - IDS can validate relationships between elements and their assemblies
  • Model Checker is isolated to the data within an element - Model Checker focuses on validating properties and data within individual elements, not relationships between elements
Future updates will include the ability to import IDS files and convert applicable rules to Speckle Model Checker format.

​
Next Steps