Blog · 6 October 2026 · Volodymyr Pavlyshyn

An ontology you can edit by hand, and hand to an RDF tool

A typed vault needs somewhere to say what a Person is, what a Company is, and how they may relate. Typed Graph keeps that in ordinary notes, in YAML short enough to review in a pull request. Version 0.1 of the format is now an open specification, and it exports to and imports from W3C SHACL, so the same ontology can move between your notes and the RDF world.

Where the ontology lives

There is no separate ontology file. The schema is a folder of notes, Types/ by default, and a note directly inside it declares types in its frontmatter. Notes elsewhere in the vault just say type: Person. That keeps the model next to the data, under the same version control, searchable and linkable like everything else.

A note can describe one type, with the body acting as the template for new notes of that type:

---
schema:
  properties:
    name: text
    email: {kind: text, required: true}
    status: {kind: text, values: [active, alumni], default: active}
  edges: {knows: Person, worksAt: Company}
---
## Notes

Or it can describe a whole subsystem. schemas: holds as many types as you like, and edgeTypes: describes the relationships themselves:

---
schemas:
  Person:  {properties: {email: {required: true}}, edges: {worksAt: Company}}
  Company: {uri: schema:Organization, properties: {founded: date}}
edgeTypes:
  worksAt:
    uri: schema:worksFor
    from: Person
    to: Company
    properties:
      since: date
      role: {kind: text, values: [engineer, manager], required: true}
---
How people and organisations relate.

The choice of one note or many is yours. A small vault can keep one note per type. A team that wants one reviewable file for "billing" can put the whole billing model in one note.

What the schema checks

Validation is advisory. Nothing is removed from the graph and no note is rejected, but the status bar and Show diagnostics list what does not fit:

Links to notes that do not exist yet, and notes with no type, are never reported as having the wrong type, so a vault can be typed gradually.

Edge types are the part most note-based schemas leave out. In a property graph the relationship carries data too: since, role, a weight. Declaring those properties once, on the edge type, means every worksAt line in the vault is checked against the same description.

Templates you do not have to write

A new note made from a type takes its body from the first of three places: a note named by the type's template link, the body of the schema note, or a template generated from the schema. The generated one writes a key for every property, with defaults filled in, and an empty relation line for every allowed edge:

---
type: Company
name:
founded:
---

## Notes

## Relations

- employs::

The empty employs:: line has no target, so it creates no edge and no stub node until you fill it in. Adding a property to the schema changes the next template, with nothing else to maintain.

Why SHACL

The Shapes Constraint Language is the W3C standard for saying what data should look like. It is what RDF tools, triple stores and semantic web pipelines already understand. Typed Graph's schema is a small, friendly subset of that idea: shapes for types, properties and relationships. So rather than invent an exchange format, TGS maps onto SHACL directly:

In your notesIn SHACL
A typeA node shape with a target class
email: {required: true}A property shape with sh:datatype xsd:string, sh:minCount 1, sh:maxCount 1
values: [active, alumni]sh:in ( "active" "alumni" )
worksAt: CompanyA property shape with sh:class the Company class
An edge type with propertiesA shape over rdf:subject, rdf:predicate and rdf:object, plus a property shape per edge property
uri: schema:OrganizationThe shape's target class IRI

The edge type row deserves a word. An edge that carries since and role is a statement about a statement. Plain SHACL 1.0 has no direct way to say that, but it can constrain the RDF reification vocabulary, which every RDF toolkit knows. The export uses that, so any SHACL engine can read the result. The things SHACL has no word for, such as a type's visualization or the note it came from, are kept as annotations in a tgs: namespace that engines ignore.

Export, import, and a real run

From the command line, or the two plugin commands Export schemas as SHACL and Import SHACL shapes:

$ tg schema export shapes.ttl --vault example
Exported 6 types and 2 edge types from Types/ to shapes.ttl as SHACL.

$ tg schema import shapes.ttl --vault another-vault
Imported 6 types and 2 edge types from shapes.ttl.
  created Types/Company.md (Company)
  created Types/Engineer.md (Engineer)
  ...
Drop report: everything was imported.

That is the demo vault in the repository: its six type notes and one note of edge types come out as 327 lines of Turtle. Exporting twice gives the same bytes, so the file diffs cleanly in git. Importing it into an empty vault and exporting again also gives the same bytes. That round trip holds when each type goes back into its own note, which is the default. If you ask for --layout single to put everything in one note, the importer tells you which template bodies it could not keep, because a note that declares several types has no single body to be the template.

Importing someone else's shapes is the other direction. Point it at a file that uses schema.org IRIs and it creates types with a uri of schema:Person and properties with schema:email. Anything outside the supported subset, such as sh:pattern, sh:closed, sh:or over datatypes or a property path, is listed in a drop report with the shape it came from, and the rest of that shape is still imported. An import changes only the schema keys of the notes it writes, never deletes a note, and will not touch a note that also declares types missing from the file unless you pass --force.

An open specification

The format is no longer an internal detail. Typed Graph Schema 0.1 is published as a standalone document that defines every key, its default and its meaning, the validation diagnostics and the SHACL mapping, without reference to this plugin's code. It comes with:

The reference implementation runs the same conformance examples in its test suite, so the specification and the code cannot drift apart unnoticed. If you build another reader, say a linter for a different editor, those examples are your test suite.

The spec text is CC BY 4.0, and the JSON Schema and examples are MIT. It is version 0.1, so expect it to grow: inheritance between types and RDF 1.2 reifiers are the first candidates, and neither will break a 0.1 note.

Try it

  1. Create a note in Types/ with the command Create schema note, or copy one of the examples above.
  2. Add a few type: Person notes and a worksAt:: line or two, then open Show diagnostics.
  3. Run tg schema export shapes.ttl and open the result, or load it into any SHACL-aware tool.

The docs cover every key, and the specification is the reference. Questions and corrections are welcome in the issue tracker.