Extending Brick
Contents
Extending Brick#
This page documents best practices for extending Brick. Extending Brick may include adding new classes, new relationships, new entity properties, new documentation or ontology rules.
Whenever possible, it is recommended to submit extensions to Brick as a pull request on the GitHub repository so that they can be made available to the broader community. The CONTRIBUTING.md document in the root of the repository contains detailed instructions and guidelines for how to achieve this.
However, in some cases, it may make sense to develop a proprietary or internal extension to Brick which defines classes/relationships that (a) refer to company-specific products or features, (b) refer to internal classes not exposed to customers or users, or (c) are being developed and will be released at a later date.
Proprietary Extensions#
Proprietary extensions should be distributed as an independent RDF file (using a .ttl
, .n3
or .xml
extension) containing the definitions of the new classes/relationships in the extension, and their relationship to existing Brick definitions. Relating proprietary extensions to existing Brick definitions is crucial for the correct interpretation/discovery of those classes for any consumers of the extension. This allows, for example, a proprietary definition of a special kind of equipment to be understood as a more specific type of an existing Brick equipment class.
Namespace#
Proprietary extension classes and relationships should be placed in their own namespace. A namespace is a URI prefix which groups the names of the classes, relationships and definitions in a graph; it does not need to be resolvable, but it is generally best practice if an HTTP GET on the namespace URI returns the definition of the extension 1. Once published, a namespace should change rarely, if ever. For a hypothetical “Example Corporation” developing its extensions to Brick, possible namespaces might be: https://example.com/schema/BrickExtension#
, https://example.com/brick/extension/
and so on. It is helpful, but not strictly necessary, for the namespace to end in a #
or /
.
Adding Classes and Relationships#
The names of the classes and relationships in the extension are suffixed to the namespace chosen above, resulting in a URI which uniquely identifies that class or relationship. For example, to add a ice-making machine class in the “Example Corporation” extension, the class name IceMachine
may be chosen. Prefixing this with the namespace results in the URI https://example.com/schema/BrickExtension#IceMachine
.
New classes should have several properties attached to them (see the example below):
a owl:Class
: classes should be annotated as instances of OWL classesskos:definition "definition goes here"
: classes should have textual definitions of what they are and how they are intended to be usedrdfs:subClassOf <Brick class>
: classes should be related to existing Brick classes through therdfs:subClassOf
relationship. A extension’s class can subclass multiple Brick classes, and those classes can be as generic or specific as required. Some classes, such asIceMachine
, may have no obvious parent classes in Brick other thanbrick:Equipment
. Other classes, such as a specific kind of VFD, may havebrick:VFD
as a parent class instead.
New relationships or properties have similar requirements:
a owl:ObjectProperty
: if the relationship has other entities/URIs as values,ObjectProperty
should be used. If the relationship will have scalar values such as integers, floats or strings, thenowl:DatatypeProperty
is more appropriateskos:definition "definition goes here"
: relationships should have textual definitions of what they are and how they are intended to be usedrdfs:domain <class>
: where appropriate, relationships should be annotated with the types of entities that will have the relationshiprdfs:range <class>
: where appropriate, relationships should be annotated with the types of entities that will be the object of the relationship (or the datatype of the relationship)rdfs:subPropertyOf <Brick relationship>
: if the extension’s relationship is a specialization of an existing Brick relationship, then the extension should indicate which relationship is being specialized.
Example#
Below develops a simple extension defining:
an
IceMachine
equipment which produces ice,a
SnowConeMaker
equipment which recieves ice from anIceMachine
and makes snow cones, anda
feedsIce
relationship to indicate which snow cones receive ice from which ice machines. This is a subproperty of thebrick:feeds
relationship
Notice that the ext
prefix is used in the Turtle file below; the choice of prefix is arbitrary and can be anything convenient. It is recommended to choose a prefix that clearly identifies the extension.
@prefix brick: <https://brickschema.org/schema/Brick#> .
@prefix ext: <https://example.com/schema/BrickExtension#> .
ext:IceMachine a owl:Class ;
rdfs:subClassOf brick:Equipment ;
skos:definition "A machine made by Example Corp. that produces ice" .
ext:SnowConeMaker a owl:Class ;
rdfs:subClassOf brick:Equipment ;
skos:definition "A machine made by Example Corp. that uses ice to make snow cones" .
ext:feedsIce a owl:ObjectProperty ;
rdfs:subPropertyOf brick:feeds ;
skos:definition "The subject feeds ice to the object" ;
rdfs:domain ext:IceMachine ;
rdfs:range ext:SnowConeMaker .
Creating Extensions#
There are two supported ways to create and maintain Brick extensions.
Direct/Manual Maintenance#
One way of extending Brick is to manually maintain an RDF graph file, e.g. serialized in a Turtle (.ttl
) file.
This can be done by editing the file directly, or using an external ontology
tool like Protege. This is the most flexible option, though maintaining RDF
ontologies “by hand” can be tricky to manage.
The occupancy extension is one example of how this can be done.
Python-based Extensions#
The other way to extend Brick is to create a Python extension file and compile it with Brick. The demo_extension folder in the Brick repository contains an example of this.
To compile Brick with this extension, provide the Python import path to the extension’s .py
file when invoking generate_brick.py
:
$ python generate_brick.py demo_extension.new_sensors
The advantage of this method is that you can use the same Python constructs to implement Brick features like Entity Properties.
Example demo extension file
import rdflib
from datetime import datetime
from bricksrc.namespaces import BRICK, SKOS, SH, XSD, RDFS, DCTERMS, RDF, SDO, OWL
# define the namespace to hold all of our terms, classes, properties, etc
DEMO = rdflib.Namespace("urn:demo_extension#")
# this is the ontology metadata dictionary. It MUST be named 'ontology_definition'
ontology_definition = {
# required 'namespace' key for ontology declaration
"namespace": DEMO,
# optional list of creators (individuals)
DCTERMS.creator: [
{
RDF.type: SDO.Person,
SDO.email: rdflib.Literal("gtfierro@mines.edu"),
SDO.name: rdflib.Literal("Gabe Fierro"),
},
],
# first date of release of extension/ontology
DCTERMS.issued: rdflib.Literal("2023-07-13"),
# keep this to ensure the 'modified' date matches when this was last ran
DCTERMS.modified: rdflib.Literal(datetime.now().strftime("%Y-%m-%d")),
# a version number for the ontology
OWL.versionInfo: rdflib.Literal("0.0.1"),
# a human-readable label for the extension/ontology
RDFS.label: rdflib.Literal("Demo Extension"),
# metadata on the publisher of the extension/ontology
DCTERMS.publisher: {
# see schema.org for other types, e.g. Consortium or Person
RDF.type: SDO.Organization,
SDO.legalName: rdflib.Literal("Not a real org"),
SDO.sameAs: rdflib.Literal("http://my fake organization website.org"),
},
# key-value pairs of prefix to URI of ontology being imported. This will
# add owl:imports statements to the generated extension
"imports": {
"shacl": "http://www.w3.org/ns/shacl#",
},
# namespace declarations for any SHACL rules
"decls": {
"rdf": RDF,
"rdfs": RDFS,
"brick": BRICK,
"owl": OWL,
"sh": SH,
"demo": DEMO,
}
}
# optional
# the *first* level of this dictionary should have Brick (or otherwise existing)
# classes as keys, and class definition dictionaries as values. Anything further
# nested can follow the normal class dictionary construction.
# This dictionary MUST be named 'classes'
classes = {
BRICK.Equipment: {
DEMO["Sensor_Platform"]: {},
DEMO["PurpleAir_Weather_Station"]: {
"parents": [BRICK.Weather_Station],
},
},
}
# optional
# this dictionary MUST be named 'entity_properties'
entity_properties = {
DEMO.manufacturer: {
SKOS.definition: rdflib.Literal("the manufacturer"),
SH.datatype: XSD.string,
RDFS.label: rdflib.Literal("manufacturer"),
"property_of": BRICK.Equipment,
},
DEMO.version: {
SKOS.definition: rdflib.Literal("a MAJOR.MINOR.PATCH version number"),
SH.node: DEMO.VersionShape,
RDFS.label: rdflib.Literal("version"),
"property_of": BRICK.Equipment,
},
}
# optional
# this dictionary MUST be named 'property_value_shapes'
property_value_shapes = {
DEMO.VersionShape: {
"properties": {
DEMO.versionMajor: {
SKOS.definition: rdflib.Literal("Major version"),
"datatype": XSD.integer,
},
DEMO.versionMinor: {
SKOS.definition: rdflib.Literal("Minor version"),
"datatype": XSD.integer,
},
DEMO.versionPatch: {
SKOS.definition: rdflib.Literal("Patch version"),
"datatype": XSD.integer,
},
},
},
}
Using Extensions#
Extensions may be distributed in a downloadable file containing the contents of the extension. This extension can be loaded into a graph in the same manner that the Brick ontology definitions can.
Consider the following code snippet which loads the above extension (serialized into a example_extension.ttl
file) into a graph using the brickschema Python package:
import brickschema
g = brickschema.Graph()
g.load_file("Brick.ttl")
g.load_file("example_extension.ttl")
g.load_file("my_building_graph.ttl")
In the Brick model file, my_building_graph.ttl
, the extension classes and relationships can be used with Brick classes and relationships.
@prefix brick: <https://brickschema.org/schema/Brick#> .
@prefix ext: <https://example.com/schema/BrickExtension#> .
@prefix bldg: <urn:snow_cone_factory#> .
bldg:factory a brick:Building ;
brick:buildingPrimaryFunction [ brick:value "Manufacturing/Industrial Plant" ] .
bldg:ice_machine_1 a ext:IceMachine ;
brick:hasLocation bldg:factory ;
ext:feedsIce bldg:snow_cone_maker_1 .
bldg:snow_cone_maker_1 a ext:SnowConeMaker ;
brick:hasLocation bldg:factory .
Integrating Extensions into Brick#
It may come to pass that a proprietary extension is developed and used internally, but then an equivalent classes/relationships are developed in Brick, or the extension is offered for inclusion in a future release of Brick. In these cases, it is likely that there will be “old” models using the extension’s version of the class and “new” models using the Brick version of the same class. These two definitions can be reconciled in a few different ways.
<brick class> owl:equivalentClass <proprietary class>
: this statement can be added to the proprietary extension file to mark the two classes as being equivalent. After applying a reasoner, both classes will be assigned to all instances of either class.<brick class> rdfs:subClassOf <proprietary class>
: this statement can be added to the proprietary extension file to mark the Brick class as being more specific. This means that instances of the Brick class are implied to be instances of the proprietary class, but not vice-versa<proprietary class> rdfs:subClassOf <brick class>
: this statement can be added to the proprietary extension file to mark the proprietary class as being more specific. This means that instances of the proprietary class are implied to be instances of the Brick class, but not vice-versa
- 1
Visiting the Brick namespace in the browser will download the latest release of Brick! Try it: https://brickschema.org/schema/Brick