Types have two main benefits: they define a concrete way to represent a term in the database, this concrete knowledge about the type of a term also allows us to write more complex rules about it. By adding a set of fixed nativeFactTypes and nativeProperties to a type a we gain the possibility to refer to them, and define even more complex rules for any term which has a as its Concept Type.
The SBVR definition for types can be found at balena-io-modules/sbvr-types/Type.sbvr
"The Rest" can be found at: balena-io-modules/sbvr-types/src/types
For a new type you should add a module to the types folder. The module should return a single object, which has the following format:
A types object, which specifies how the type is declared in various systems. This contains:
- postgres/mysql/websql - These can either be a string (which will have the necessity and index appended to it), or a function (necessity, index), which returns the type as a string.
postgres: 'Serial'
mysql: (necessity, index) ->
return 'INTEGER' + necessity + index + ' AUTO_INCREMENT'
websql: (necessity, index) ->
return 'INTEGER' + necessity + index + ' AUTOINCREMENT'- odata - This is an object that must contain a "name" property, which is a string specifying the name of the OData type. It may also contain a "complexType" property, which is a string that specifies an OData ComplexType
odata:
name: 'Edm.Int64'odata:
name: 'Self.Color'
complexType: '''
<ComplexType Name="Color">
<Property Name="r" Nullable="false" Type="Edm.Int8"/>\
<Property Name="g" Nullable="false" Type="Edm.Int8"/>\
<Property Name="b" Nullable="false" Type="Edm.Int8"/>\
<Property Name="a" Nullable="false" Type="Edm.Int8"/>\
</ComplexType>'''- validate - This is a function (value, required, callback(err, data)) that must be provided, and which should validate that incoming data is valid for this type.
valueis the value that has been received as part of the request.requiredspecifies whether this value is required (true: NOT NULL, false: NULL).callbackshould be called with the first parameter as an error explaining why the data is invalid, or if it valid, null, with the second parameter being the valid, processed data.
An example of validating a Color type, we accept either a number that specifies the Color, or an object {'r' or 'red', 'g' or 'green', 'b' or 'blue', 'a' or 'alpha'}, and return an integer that represents the Color.
validate: (value, required, callback) ->
if !_.isObject(value)
processedValue = parseInt(value, 10)
if Number.isNaN(processedValue)
callback('is neither an integer or color object: ' + value)
return
else
processedValue = 0
for own component, componentValue of value
if Number.isNaN(componentValue) or componentValue > 255
callback('has invalid component value of ' + componentValue + ' for component ' + component)
return
switch component.toLowerCase()
when 'r', 'red'
processedValue |= componentValue >> 16
when 'g', 'green'
processedValue |= componentValue >> 8
when 'b', 'blue'
processedValue |= componentValue
when 'a', 'alpha'
processedValue |= componentValue >> 24
else
callback('has an unknown component: ' + component)
return
callback(null, processedValue)- fetchProcessing - This is a function (data, callback(err, data)) that may be specified to process the data after fetching from the database and before sending to the client. If specified this function should call the callback passing either an error message as the first param, or null as the first param and the modified data as the second.
fetchProcessing: (data, callback) ->
callback(null,
r: (data >> 16) & 0xFF
g: (data >> 8) & 0xFF
b: data & 0xFF
a: (data >> 24) & 0xFF
)- nativeProperties - This is an object that may be specified to define "native" properties of the type.
If specified it should match the format:
nativeProperties:
Verb:
Term: (from) -> ...
Term2: (from) -> ...
Verb2:
Term3: (from) -> ...The (from) -> ... function should return a chunk of abstract sql that can be used to fetch the property specified by this fact type, the from parameter is abstract sql that will refer to an instance of the term that is of this type.
Text has Length:
nativeProperties:
'has':
'Length': (from) -> ['CharacterLength', from]For the various properties of Color:
nativeProperties:
'has':
'Red Component': (from) -> ['BitwiseAnd', ['BitwiseShiftRight', from, 16], 255]
'Green Component': (from) -> ['BitwiseAnd', ['BitwiseShiftRight', from, 8], 255]
'Blue Component': (from) -> ['BitwiseShiftRight', from, 255]
'Alpha Component': (from) -> ['BitwiseAnd', ['BitwiseShiftRight', from, 24], 255]- nativeFactTypes - This is an object that may be specified to define "native" fact types of the type. If specified it should match the format:
nativeFactTypes:
'Term':
'Verb1': (from, to) -> ...
'Verb2': (from, to) -> ...
'Term2':
'Verb3': (from, to) -> ...The (from, to) -> ... function should return a chunk of abstract sql that can be used to resolve this fact type.
The from parameter is abstract sql that will refer to an instance of the term that is of this type.
The to parameter is abstract sql that will refer to an instance of the term that is of the type specified by the property name.
Note: The reasoning the ordering of this is SecondTerm -> Verb, rather than Verb -> SecondTerm is that it allows declaring all the links between two terms much easier (as you will see in the examples)
A selection of the the native fact types for Integer (in the actual file much more DRY is practiced):
nativeFactTypes:
'Integer':
'is greater than': (from, to) -> ['GreaterThan', from, to]
'is greater than or equal to': (from, to) -> ['GreaterThanOrEqual', from, to]
'is less than': (from, to) -> ['LessThan', from, to]
'is less than or equal to': (from, to) -> ['LessThanOrEqual', from, to]
'Real':
'is greater than': (from, to) -> ['GreaterThan', from, to]
'is greater than or equal to': (from, to) -> ['GreaterThanOrEqual', from, to]
'is less than': (from, to) -> ['LessThan', from, to]
'is less than or equal to': (from, to) -> ['LessThanOrEqual', from, to]