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 anrdfs:Classthat is also ash:NodeShape. It describes a thing and its properties.svs:conformsToissh: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:
@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.
: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.
: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.
: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.
: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.
:Company a svs:ClassSchema ; rdfs:label "Company"@en ; rdfs:comment "A business that owns or operates power plants."@en . :PowerPlant a svs:ClassSchema ; rdfs:comment "A facility that generates electricity for the grid."@en ; sh:property [ sh:path :operator ; sh:name "operator"@en ; sh:description "The company that runs the plant day to day."@en ; sh:class :Company ; ] .
The example says a plant's operator is a Company.
Allowed values
sh:in lists the only values a property accepts.
: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.
: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.
: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.
: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.
: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.
:PowerPlant a svs:ClassSchema ; rdfs:label "Power plant"@en ; 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 ; ] . :NuclearPlant a svs:ClassSchema ; rdfs:label "Nuclear plant"@en ; rdfs:comment "A power plant that makes electricity by nuclear fission."@en ; rdfs:subClassOf :PowerPlant .
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.
:Metered a sh:NodeShape ; rdfs:label "Metered"@en ; rdfs:comment "The fields of anything that has a revenue meter."@en ; sh:property [ sh:path :meterId ; sh:name "meter ID"@en ; sh:description "The revenue meter at the point of interconnection."@en ; sh:datatype xsd:string ; sh:minCount 1 ; ] . :PowerPlant a svs:ClassSchema ; rdfs:label "Power plant"@en ; rdfs:comment "A facility that generates electricity for the grid."@en ; svs:conformsTo :Metered .
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.