Work with Custom Consistency Check Rules

About Custom Consistency Check Rules

You can create consistency check errors and warnings based on your semantic model’s specific development standards.

Semantic Modeler's Check Consistency provides standard checks that find common modeling issues that prevent you from successfully deploying the model or that cause runtime errors. In cases where your organization has unique modeling requirements or standards, for example when presentation tables must have custom display names, you can create custom consistency checks to help you find and fix such unique issues before you deploy your model. Creating custom consistency checks replaces the manual checks you would otherwise have to perform on the model to find any unique issues.

When you create a custom rule for a model, you specify if you want the check to be an error or warning. You can provide an error number and write a custom error message to display in the custom consistency check results. You can group multiple rules under the same error or warning number.

You can edit the check rules in the SMML editor or the Semantic Modeler user interface.

Semantic Modeler saves custom rules with the model in which you created them. You can share custom rules by copying and pasting content from the SMML editor of one semantic model into the SMML editor of another semantic model.

You use JSONPath to write the custom rule's query. JSONPath is a query language for JSON that allows developers and non-developers to write queries against nested and complex JSON structures. Semantic Modeler ensures the queries you write are valid in the user interface and on the server. See About Using JSONPath to Write Semantic Model Custom Rule Queries.

Semantic Modeler doesn't include your model's custom rules when you run Check Consistency or Advanced Check. The custom rules that you assign to the Error category won't prevent you from running Advanced Check and deploying the model.

For information about Check Consistency, see About Check Consistency.

About Using JSONPath to Write Semantic Model Custom Rule Queries

JSONPath is the query language you use to create custom consistency check rules for your semantic model. JSONPath allows you to create user-defined rules that scan your semantic model's objects for violations of business and data-quality constraints.

You write custom consistency check rules as indefinite queries so they can match zero, one, or many nodes across evolving models, making them ideal for consistency and limiting work flows.

Definite Versus Indefinite Queries

Note these differences between definite and indefinite queries:

Definite paths select at most one node, and implementations typically return a single value or null when using definite paths. This is the “single-target” form.
Indefinite paths can select zero, one, or many nodes and return a collection of matches, often as a list or array. Filters, wildcards, deep-scan, slices, and multi-index selectors make a query indefinite.

Why Custom Consistency Checks Require Indefinite Queries

Custom consistency checks require indefinite queries for these reasons:

Comprehensive scanning - Consistency checks need to find not just one but all offending instances across the model. Therefore queries must be able to return multiple matches in a single evaluation.
Schema and version resilience - As a semantic model evolves, for example, with added properties, reordered arrays, and new nesting, indefinite queries remain valid because they rely on patterns and not fixed positions.
Clean reporting semantics - An indefinite query naturally maps to “N matches = N reported findings”, while zero matches cleanly represent “no issue” without errors or special cases.

Tips and Troubleshooting

Use this information to help you write your JSONPath queries:

When you create a rule, use the Validate button in the Custom Rules dialog to validate your query's syntax. Use a small sample of objects to sanity-check selection and result cardinality.
Be sure to confirm result cardinality. Expect arrays, and if a rule returns a single scalar, adjust to a filter or wildcard to make it indefinite.
For large objects, narrow expensive scans by replacing $.. with subtree roots like $.presentationTable.hierarchies whenever possible.

Resources

Oracle assumes that you're familiar with JSONPath and how to write valid JSONPath queries.

If you're new to JSONPath, use these resources to help you learn how to write your JSONPath queries.

Resource	Description
Official specification (RFC 9535)	The normative IETF standard for JSONPath syntax, selectors, filters, evaluation semantics, and conformance expectations.
Jayway JsonPath (Java) README	A popular implementation with practical syntax, operators, examples, and API usage details.
Hevo Data	A concise tutorial-style overview with examples and filter usage.
REST API Tutorial:	A guide to JSONPath basics and common querying patterns.
JSONPath Online Evaluator	An evaluator for prototyping expressions against sample JSON.
Site24x7 JSON Path Evaluator	An evaluator/validator with an interactive results panel.

JSONPath Custom Consistency Check Query Examples

Use these examples to help you write valid JSONPath custom consistency check queries.

This query selects all permission entries under presentationTable where accessor is “Authenticated User” and access is “NO_ACCESS”.
```
$.presentationTable.permissions[?(@.accessor == "role:AuthenticatedUser" && @.access == "NO_ACCESS")]
```
This query selects presentationTable objects whose name field contains the substring “1”, “2”, or “3”. This query locates duplicate objects.
```
$.presentationTable[?(@.name contains '1'|| @.name contains '2'|| @.name contains '3')]
```
This query selects all logicalColumns of a logicalTable where dataType equals “VARCHAR”.
```
$.logicalTable.logicalColumns[?(@.dataType == 'VARCHAR')]
```
This query like the previous query selects all logicalColumns of a logicalTable where dataType equals “VARCHAR”, but uses different syntax.
```
$..logicalColumns[?(@.dataType == 'VARCHAR')]
```
This query selects all logicalLevels across the document whose name equals “Offices Company”.
```
$..logicalLevels[?(@.name == 'Offices Company')]
```
This query selects all permissions anywhere whose accessor starts with “roleBI:” (requires startsWith support or an approved alternative).
```
$..permissions[?(@.accessor contains "role:BI")]
```
This query selects all physicalMappings across the document where logicalTableSource equals “LTS1 Offices”.
```
$..physicalMappings[?(@.logicalTableSource == "LTS1 Offices")]
```

Create a Custom Consistency Check Rule

You can create custom consistency check rules based on your semantic model’s specific development standards. Creating custom rules saves you the effort of manually checking your model for specific issues.

The custom rules you create are included in the Custom Rules tab in the Semantic Modeler editor, and Semantic Modeler doesn't include custom rules when you run Check Consistency or Advanced Check. The custom rules that you assign to the Error category won't prevent you from running Advanced Check and deploying the model. See About Custom Consistency Check Rules.

Use this information to help you create a rule:

Rule Name - Specifies the name of the rule. This name is for custom rule management purposes only and displays in the Custom Rules tab. It doesn't display in the custom consistency check results.
Error # - Specifies the error number to display in the custom consistency check results. An error number is a string and can contain numbers, letters, and characters. You can assign the same error number to more than one rule. For example, if you want to group rules under one error number.
Category - Specifies if the rule is an error or warning. Error is the default. An error indicates a critical issue that the model developer must fix before deploying the model. A warning indicates an issue that the developer might need to fix. Because Semantic Modeler doesn't include custom consistency checks in Check Consistency or Advanced Check, checks that you label as errors won't prevent you from running an advanced check and deploying the model.
Rule Enabled - Indicates if the rule is included when you run custom consistency check on the model.
Description - Contains the developer's comments and information about the rule and is displayed only in the Custom Rules dialog when the developer modifies the rule.
Message - Specifies the text to display in the Error Description column of the Custom Consistency Check tab when the check finds an instance of the error or warning. This message helps model developers understand the issue and how to fix it.
JSONPATH Query - Contains the query's JSONPath syntax. See About Using JSONPath to Write Semantic Model Custom Rule Queries and JSONPath Custom Consistency Check Query Examples.

On your home page, click Navigator and then click Semantic Models.
In the Semantic Models page, click a semantic model to open it.
In the toolbar, click the down arrow next to Check Consistency and select Custom Rules.
From the Custom Rules tab, click Create Rule.
In the Custom Rules dialog, specify the rule's properties.
In JSONPath Query, write the rule's query. Click Validate.
Click Add.

View Custom Consistency Check Rules

You can view a list of the custom rules that you and other developers created for a model. Use this list for overview information about each rule, and to manage the model's rules, for example delete a rule, edit a rule, or enable or disable a rule.

On your home page, click Navigator and then click Semantic Models.
In the Semantic Models page, click a semantic model to open it.
In the toolbar, click the down arrow next to Check Consistency and select Custom Rules.
Optional: Hover over a rule, click Actions , and select the option that you want to perform for the rule.

Modify a Custom Consistency Check Rule

You can change the properties or JSONPath query for any custom rule that you or other developers added to the model.

For information about the custom rule's properties, see Create a Custom Consistency Check Rule.

On your home page, click Navigator and then click Semantic Models.
In the Semantic Models page, click a semantic model to open it.
In the toolbar, click the down arrow next to Check Consistency and select Custom Rules.
From the Custom Rules tab, hover over the rule you want to modify and click Actions and click Edit.
In the Custom Rules dialog, modify the rule's properties and JSONPath query.
Click Save.

Enable or Disable a Custom Consistency Check Rule

You can enable or disable any of your model's existing custom rules. You can enable a custom rule to test it, or disable it while you develop its query.

For existing rules, you can enable or disable a rule from the Custom Rules tab. When you create or modify a rule, you can enable or disable it from the Custom Rules dialog.

On your home page, click Navigator and then click Semantic Models.
In the Semantic Models page, click a semantic model to open it.
In the toolbar, click the down arrow next to Check Consistency and select Custom Rules.
From the Custom Rules tab, hover over the rule you want to enable or disable and click Actions .
Select Enable to include the rule when you run Check Consistency. Click the Disable field to exclude the rule when you run Check Consistency.

Run Custom Consistency Checks

Use the Custom Consistency Check to identify the errors and warnings custom checks you created based on your semantic model’s specific development standards.

Note the following information:

Custom Consistency Check looks for your custom checks on the whole semantic model. You can't run Custom Consistency Check on individual model objects such as a Physical Table or Initialization Block.
Semantic Modeler doesn't include custom rules when you run Check Consistency or Advanced Check.
The custom rules that you assign to the Error category won't prevent you from running Advanced Check and deploying the model.

On your home page, click Navigator and then click Semantic Models.
In the Semantic Models page, click a semantic model to open it.
In the toolbar, click the down arrow next to Check Consistency and select Custom Rules.
From the Custom Rules tab, click Run custom consistency check .
From the Custom Consistency Check tab, click an object's link to locate and open it.
Fix the object and then click Save to save the semantic model.
Click the Custom Consistency Check tab and click Check to re-run Custom Consistency Check and refresh the results.

Hide Warnings in Custom Consistency Check Results

You can choose the warnings you want to hide or show in your custom check consistency results list. Hiding warnings helps you limit the amount of warnings in your results list so that you can locate and focus on the most critical warnings you need to fix.

On your home page, click Navigator and then click Semantic Models.
In the Semantic Models page, click a semantic model to open it.
In the toolbar, click the down arrow next to Check Consistency and select Custom Rules.
From the Custom Rules tab, click Run custom consistency check .
In the custom consistency check results list, confirm that the Warnings checkbox is selected so that all warnings are displayed.
Locate the warning you want to hide and click its Hide all Warnings icon .

Show Hidden Warnings in Custom Consistence Check

You can select the hidden warnings that you want to show in Custom Check Consistency results.

On your home page, click Navigator and then click Semantic Models.
In the Semantic Models page, click a semantic model to open it.
In the toolbar, click the down arrow next to Check Consistency and select Custom Rules.
From the Custom Rules tab, click Run custom consistency check .
In the consistency check results tab, click Hidden Warnings to display your list of hidden warnings.
Select the warnings that you want to show in the custom check consistency results. Click OK.
In the custom consistency check results list, confirm that the Warnings checkbox is selected so that all warnings are displayed.

Export Custom Consistency Check Rules to a CSV File

After you run Custom Consistency Check you can export the results to a CSV file.

Exporting custom consistency check results exports all results and not only the results displayed in the Custom Consistency Check tab. For example, if you ran Custom Consistency Check on a semantic model for both errors and warnings, and in the Custom Consistency Check tab you click Error to display only error messages, when you click Export to CSV, Oracle Analytics produces a CSV file containing all errors and warnings.

On your home page, click Navigator and then click Semantic Models.
In the Semantic Models page, click a semantic model to open it.
In the toolbar, click the down arrow next to Check Consistency and select Custom Rules.
From the Custom Rules tab, click Run custom consistency check .
In the Custom Check Consistency tab, click Export to CSV .