# Classes

> Each construct a class schema supports, with a Turtle example of what it says about your domain: class, property, required and cardinality, datatype, class of a value, allowed values, value range, pattern, default value, label and comment, and classical and compositional inheritance.

Source: https://semvia.io/docs/modeling/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](https://www.w3.org/TR/rdf11-schema/) and [SHACL](https://www.w3.org/TR/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](https://semvia.io/docs/modeling/inference#subclasses) `: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.

Graph

Figure: 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.

Turtle

```turtle
: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.

```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](https://www.eia.gov/electricity/data/eia860/), 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](https://semvia.io/docs/modeling/inference#default-values).

```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](https://semvia.io/docs/modeling/inference#subclasses) every entity of the narrower class is an entity of the broader one, and under the [inherited-properties rule](https://semvia.io/docs/modeling/inference#inherited-properties) the narrower class inherits the broader class's properties.

Graph

Figure: 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.

Turtle

```turtle
: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](https://semvia.io/docs/modeling/inference#equivalent-properties) of `sh:node`, so the class inherits the shape's properties under the [inherited-properties rule](https://semvia.io/docs/modeling/inference#inherited-properties).

Graph

Figure: 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.

Turtle

```turtle
: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](https://www.typescriptlang.org/) 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](https://semvia.io/docs/modeling/how-profiles-work) covers how a file gets one.

[Next: Open world and scope](https://semvia.io/docs/modeling/open-world-and-scope): Why every file loads and answers queries, and how datasets and profiles scope what Folio warns about.
