Skip to content

Modeling Classes

New to Folio? Start here

Classes

A class, such as Power plant or Company, is a blueprint for its entities. It describes the shape each one is expected to take, its properties, which of them are required and what each may hold, and it is the plan you build each entity against.

Other tools call the same idea an entity type, a record type or a table. It works much like a class in an object-oriented language such as Java or Python: it lists the properties its entities hold, and a subclass inherits them. Unlike an object in those languages, an entity can belong to more than one class, and it can hold properties its classes don't list.

Standards

In Folio, a class is represented using RDFS and SHACL, the standard vocabularies for classes and the shapes their entities take. Semvia's svs: vocabulary adds a few convenience classes and properties on top of them, named to be easier to follow for readers whose background is outside RDF. Each is defined in terms of the standard ones:

  • svs:ClassSchema, a class schema, is an rdfs:Class that is also a sh:NodeShape. It describes a thing and its properties.
  • svs:conformsTo is sh:node.

Nothing in Folio is built against these aliases. Folio works with rdfs:Class and sh:NodeShape, so you're free to skip the class schema and declare a class with rdfs:Class and sh:NodeShape directly.

Examples on this page use these prefixes and the Class Schema profile:

Turtle
@prefix : <https://example.org/my-semantic-package/plants#> .
@prefix dct: <http://purl.org/dc/terms/> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix sh: <http://www.w3.org/ns/shacl#> .
@prefix svs: <https://pkg.semvia.io/semvia/core/meta-schema#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .

<> dct:conformsTo <https://pkg.semvia.io/semvia/core/profiles/class-schema> .

Class

a svs:ClassSchema declares a class.

Turtle
:PowerPlant a svs:ClassSchema ;
  rdfs:label "Power plant"@en ;
  rdfs:comment "A facility that generates electricity for the grid."@en .

svs:ClassSchema is rdfs:subClassOf both rdfs:Class and sh:NodeShape, so under the subclasses rule :PowerPlant is an RDFS class and a SHACL shape at once.

Property

Each sh:property block describes one property: sh:path is the property an entity writes, and sh:name and sh:description are its label and help text on a form.

Turtle
:PowerPlant a svs:ClassSchema ;
  rdfs:comment "A facility that generates electricity for the grid."@en ;
  sh:property [
    sh:path :gridRegion ;
    sh:name "grid region"@en ;
    sh:description "The balancing authority the plant feeds."@en ;
  ] .

Required and cardinality

sh:minCount is the fewest values an entity may give and sh:maxCount the most. sh:minCount 1 makes a property required.

Turtle
:PowerPlant a svs:ClassSchema ;
  rdfs:comment "A facility that generates electricity for the grid."@en ;
  sh:property [
    sh:path :name ;
    sh:name "name"@en ;
    sh:description "The plant's registered name."@en ;
    sh:datatype xsd:string ;
    sh:minCount 1 ;
    sh:maxCount 1 ;
  ] .

The example says every plant has exactly one name.

Value type

A property holds either a literal, such as a date or a number, or another entity. sh:datatype says which kind of literal, and sh:class says which class the entity belongs to.

Datatype

sh:datatype is the kind of literal a property holds.

Turtle
:PowerPlant a svs:ClassSchema ;
  rdfs:comment "A facility that generates electricity for the grid."@en ;
  sh:property [
    sh:path :commissionedOn ;
    sh:name "commissioned on"@en ;
    sh:description "The date the plant entered commercial operation."@en ;
    sh:datatype xsd:date ;
  ] .

The example says a plant's commissioning date is a date, such as "2019-06-14"^^xsd:date.

Class of a value

sh:class says a property's value must be an entity of a given class.

Folio's graph of the file: a PowerPlant node whose operator property has type Company, with an operator edge to a Company node
PowerPlant's operator property points at the Company class.

The example says a plant's operator is a Company.

Allowed values

sh:in lists the only values a property accepts.

Turtle
:PowerPlant a svs:ClassSchema ;
  rdfs:comment "A facility that generates electricity for the grid."@en ;
  sh:property [
    sh:path :gridRegion ;
    sh:name "grid region"@en ;
    sh:description "The balancing authority the plant feeds."@en ;
    sh:in ( "CAISO" "ERCOT" "MISO" "PJM" ) ;
  ] .

The example says a plant feeds one of four grid regions, such as "ERCOT".

Value range

sh:minInclusive and sh:maxInclusive bound a number from below and above. sh:minExclusive and sh:maxExclusive do the same with the bound itself left out.

Turtle
:PowerPlant a svs:ClassSchema ;
  rdfs:comment "A facility that generates electricity for the grid."@en ;
  sh:property [
    sh:path :capacityMW ;
    sh:name "capacity (MW)"@en ;
    sh:description "Nameplate capacity in megawatts."@en ;
    sh:datatype xsd:decimal ;
    sh:minInclusive 0 ;
  ] .

The example says a plant's capacity is never negative.

Pattern

sh:pattern is a regular expression a text value must match. The example describes a plant's code in EIA-860, the U.S. Energy Information Administration's annual survey of power plants, which numbers each plant with one to five digits.

Turtle
:PowerPlant a svs:ClassSchema ;
  rdfs:comment "A facility that generates electricity for the grid."@en ;
  sh:property [
    sh:path :eiaPlantCode ;
    sh:name "EIA plant code"@en ;
    sh:description "The plant's ID in EIA-860, one to five digits."@en ;
    sh:pattern "^[0-9]{1,5}$" ;
  ] .

Default value

sh:defaultValue is the value an entity has for a property it leaves out, under the default-values rule.

Turtle
:PowerPlant a svs:ClassSchema ;
  rdfs:comment "A facility that generates electricity for the grid."@en ;
  sh:property [
    sh:path :operatingStatus ;
    sh:name "operating status"@en ;
    sh:description "Whether the plant is generating, on standby or retired."@en ;
    sh:defaultValue "Operating" ;
  ] .

A plant with no status reads "Operating" in a query. A plant that states "Retired" keeps "Retired".

Label and comment

rdfs:label is a class's name and rdfs:comment its help text. Both take a language tag, so a class can carry one of each per language.

Turtle
:NuclearPlant a svs:ClassSchema ;
  rdfs:label "Nuclear plant"@en ;
  rdfs:comment "A power plant that makes electricity by nuclear fission."@en .

Folio's graph titles the class's node with its label, Nuclear plant, rather than its name in the IRI.

Inheritance

A class inherits properties in two ways, classical and compositional.

Classical (rdfs:subClassOf)

rdfs:subClassOf makes one class a subclass of a broader one, the way a class extends its base class in Java, C# or Python: under the subclasses rule every entity of the narrower class is an entity of the broader one, and under the inherited-properties rule the narrower class inherits the broader class's properties.

Folio's graph of the file: a Nuclear plant node with a subClassOf edge to a Power plant node, and both nodes listing a required name property of type string
NuclearPlant is rdfs:subClassOf PowerPlant, so it inherits the required name.

NuclearPlant declares no properties of its own and inherits PowerPlant's name. Every NuclearPlant is also a PowerPlant, so a query for power plants returns it.

Compositional (svs:conformsTo)

svs:conformsTo gives a class the properties of a shape, a set of properties with no entities of its own, without making the class a kind of that shape, the way a Swift type conforms to a protocol, a Java class implements an interface, or a Rust type implements a trait. svs:conformsTo is declared an equivalent property of sh:node, so the class inherits the shape's properties under the inherited-properties rule.

Folio's graph of the file: a Power plant node with a conformsTo edge to a Metered node, and both nodes listing a required meter ID property of type string
PowerPlant has svs:conformsTo Metered, so it inherits the required meter ID.

Violations

A violation is an entity that breaks its class, the way TypeScript reports an error when code uses a class in a way its declaration doesn't allow. Problems lists each one, such as a plant with no name. A class applies to the entities in a file that follows a profile listing the class's file for role:validation; How profiles work covers how a file gets one.