Required schema specification

TypeScript type: RequiredSchemaSpecification.

Presentation rules may need to be modified as different ECSchemas evolve - new classes and properties may be added and they may require adding additional rules, or, after a major schema release, some classes or properties may even get removed, in which case some rules may need to also be removed or adjusted.

In any case, the rules are not tightly bound to the ECSchema used by an iModel - an application that knows about schema X version 2 will still want to open older iModels that use schema X version 1. This introduces a need to define not only schemas used by the ruleset as a whole, but to define them at rule level, and with ability to specify which version of schema is required for specific rules.

This specification is designed specifically for that purpose. It accepts a list of ECSchema names along with optional minimum required and maximum allowed versions.

Attributes

Attribute: name

Specifies the schema to whom the requirement is being set.

Attribute: minVersion

Minimum required schema version (inclusive). Format: {read version}.{write version}.{minor version}, e.g. 2.1.15.

Attribute: maxVersion

Maximum allowed schema version (exclusive). Format: {read version}.{write version}.{minor version}, e.g. 2.1.15.

Examples

Specifying required schemas for the ruleset

The below ruleset contains a content modifier for Functional.FunctionalElement class - we need to make sure the iModel supports all the ECSchemas that are used in it.

{
  "id": "my-ruleset",
  "requiredSchemas": [{
    "name": "Functional"
  }],
  "rules": [{
    "ruleType": "ContentModifier",
    "class": { "schemaName": "Functional", "className": "FunctionalElement" },
    // ... some overrides for Functional.FunctionalElement
  }]
}

Specifying required schema in a hierarchy rule

// The ruleset has one root node rule that returns `bis.ExternalSourceAspect` instances. The
// ECClass was introduced in BisCore version 1.0.2, so the rule needs a `requiredSchemas` attribute
// to only use the rule if the version meets the requirement.
const ruleset: Ruleset = {
  id: "example",
  rules: [
    {
      ruleType: "RootNodes",
      requiredSchemas: [{ name: "BisCore", minVersion: "1.0.2" }],
      specifications: [
        {
          specType: "InstanceNodesOfSpecificClasses",
          classes: [
            {
              schemaName: "BisCore",
              classNames: ["ExternalSourceAspect"],
            },
          ],
        },
      ],
    },
  ],
};

Specifying required schema in content modifier

// The ruleset has a content rule that returns content of given input instances. There's also
// a content modifier that tells us to load `bis.ExternalSourceAspect` related properties, but the
// ECClass was introduced in BisCore version 1.0.2, so the modifier needs a `requiredSchemas` attribute
// to only use the rule if the version meets the requirement.
const ruleset: Ruleset = {
  id: "example",
  rules: [
    {
      ruleType: "Content",
      specifications: [
        {
          // load content for given input instances
          specType: "SelectedNodeInstances",
        },
      ],
    },
    {
      ruleType: "ContentModifier",
      requiredSchemas: [{ name: "BisCore", minVersion: "1.0.2" }],
      class: { schemaName: "BisCore", className: "ExternalSourceAspect" },
      relatedProperties: [
        {
          // request to include properties of related ExternalSourceAspect instances
          propertiesSource: {
            relationship: { schemaName: "BisCore", className: "ElementOwnsMultiAspects" },
            direction: "Forward",
            targetClass: { schemaName: "BisCore", className: "ExternalSourceAspect" },
          },
        },
      ],
    },
  ],
};

Last Updated: 03 April, 2024