2_Object Specifications as part of the Common Configurator Framework
An object specification defines a set of allowable values and constraints for the object’s properties. This enables verification of object instances to be performed against the encoded predefined checks – determining if the instance of the object meets the specification and is valid or not. A programmatic definition of a Specification compatible with the Common Configurator Framework (CCF) can be described as follows:
A Specification is given by “some conditions that some objects must respect”.
From this generic definition, it follows that there has to be a way for the Specification to distinguish between the objects that must comply with the given Conditions (rules) and other objects that do not need to comply with those Conditions. In other words, there has to be a way for the Specification to filter the objects that must be verified.
Once we have identified the objects that must be verified, the Filtered Objects, a Condition can be applied to them, and they can be checked against this condition.
Key to both operations, the filtering of relevant objects and the checking of these latter against some rules, are what we call Conditions, explained in detail below.
The Common Object Schema is developed to be language-agnostic. To achieve this, the schema for the Specifications, as well as the schema for the Conditions, is developed under the Json-schema.org standard.
This means that it is possible to author CCF-compatible Specifications and objects from any programming language (not limited to C#), as long as they can be serialised to JSON compatible with the schema.
A specification needs the properties described in its schema, which are:
- A name for the Specification
- An identifier for the Specification
- The FilterConditions
- The CheckConditions
Any Json-schema verification tool can be used to check if JSON data is compatible with the CCF schemas. See some examples here.
A condition is simply a rule. Furthermore, the condition does not specify who is to respect this rule.
By decoupling the target of the rule from the rule itself we gain two key features. First, we maximise the modularity and reusability in the framework, including the ability to very transparently identify and reference individual rules in any specification or indeed have many rules applied to the same singular target.
Second, we can then define who is to respect some rule by using another rule to define this target. This second point is critical to enable the specificity and control of targeted specification authoring and application necessary for use at scale on complex building projects.
As an example of a very simple object specification:
'Columns must be shorter than 3 meters'
By decoupling the rule from the targets of the rule, we can see that this specification can be composed by two conditions: a filter condition that returns the “who” (Columns), followed by a check condition that gives the actual verification rule (shorter than). Constructing in this way we achieve the same result:
'is a Column' 'must be shorter than 3 meters'
Thanks to this structuring, a specification can be applied to any heterogeneous set of objects.
In conclusion, we can say that an Object Specification is defined as:
Object Specification = Filter Conditions + Check Conditions
This effectively can be seen as a sort of “two-step” data validation process.
A condition that filters objects and returns the objects that should be checked as part of a Specification.
It can also be a combined set of filter conditions.
For the Specification:
“Columns must be shorter than 3 meters”
The filter condition is a condition that returns the “who”, i.e. the objects that are Columns.
Conditions that verifies that the objects passed by the Filter Conditions respect some clause.
For the Specification:
“Columns must be shorter than 3 meters”
The check condition here is a process that verifies that Column objects - as passed by the FilterCondition - are "shorter than 3 meters".
The repository includes some schemas for specific Conditions that can be used with the CCF.
This Condition checks the value associated with a certain property of an object, which can be found under a certain property name.
See its Json-schema.
See the corresponding BHoM's C# implementation.
Condition that is made by the combination of several conditions. Each condition is combined to the others using a Boolean Operator (AND/OR/NOT/etc). E.g. If AND is used, then the LogicalCondition will be considering a pass only if the an object satisfies all the given Conditions.
See its Json-schema.
See the corresponding BHoM's C# implementation.
Condition that verifies if the value of a Property of the object is within a certain domain (range).
See its Json-schema.