Discussion Forum

Approach to Schema Design?

I’m just beginning my exploration of TypeDB. I’m trying to figure out a logical approach to TypeDB schema design. At first blush, based on the product description, entity relationship diagramming would seem to be a reasonable starting point. However, TypeDB schemas go well beyond what Chen defined, especially in its support for subtyping. And TypeDB’s handling of roles is more complex than the simple labeling of edges found in classical ERDs. So I’m left wondering if there are best practices for TypeDB schema design or any other resources that would aid my exploration and adoption of TypeDB.

–Gary Kopp

Hi @geez4,

Very good question, as yet there isn’t any official guidance published. Agreed, typical entity-relationship modelling falls short. I’ve previously written some general guidance here:

The overall theme is to create the most minimal model possible that captures all of the context you need. Rules should be used to compute any facts that are derivable from your model, this guards against introducing contradictions in your data.

As you hint at, roles are powerful. They are the means to indicate the context of a roleplayer within the scope of a relation.

You can find example schemas here:

When it comes to diagramming, please use the de-factor notation for TypeDB/TypeQL as seen on the company homepage. Use that from the start to build up a good intuition for how to use the model. Ideally just write your schema in TypeQL straight away as you draft it (it’s very fast to write, so not a chore) then regularly visualise it by loading the schema into a server and using Workbase. If it’s not what you wanted then delete the database and iterate on it as the fastest workflow to get started.

Lastly, Vaticle runs online webinars called Academy, which run through these concepts. In fact we also run training courses with this kind of content to get teams started with development fast.

You can find the free events via meet-up: https://meetup.com/topics/typedb
Recordings on our youtube: https://www.youtube.com/channel/UCtZKw0RFof3x23KqGtW3yDA

Hope this helps!

Hello James,

Looking at the sample model visualizations on your homepage, they seem to be identical to entity-relationship diagrams (which allow role names to appear as labels on edges, just as in your samples). Am I missing anything?


Typical ER models have no notion of a hyper-relation/N-ary relation as we do in TypeDB, this is the key difference to note right off the bat!

I’m accustomed to seeing ER diagrams much like the variations here where we see only binary relations, where either the relation is a diamond between entities (without role labels) or the relation is represented by an edge between entities with a directional label.

In TypeDB the relations are taken from hypergraph theory, which is a relation which can have N roleplayers (playing any number of different roles in that relation). We represent this hyperrelation as a node with outward-facing edges.

What I should have linked to previously is specifically the TypeDB page where you can see specific examples of N-ary relations, relations relating to other relations, and relations relating to an attribute.

You’ll also see there the type hierarchy using sub, which is present in the Enhanced ER model but not in classic ER.

The last key point to look out for is that attributes are represented as nodes unto themselves, which strongly differentiates the TypeDB model from any other. In fact this is what makes the TypeDB model achieve First Normal Form.

Thanks for your clear explanations and corrected pointer to the sample notation. You’ve hit on all the capabilities of TypeDB schemas that make ER inadequate for TypeDB modeling; I was at least vaguely aware of all of these, but you have stated them with clarity.

This takes me back to my original problem - how to approach TypeDB conceptual design. As a long-time UML devotee I tend to approach design pictorially. I suspect that the TypeDB Schema Designer, if it were available, would allow for visually modeling all of the elements of a TypeDB schema (I guess that’s a true-or-false question). My understanding is that the schema designer is not available in the current version of TypeDB. When will the schema designer be available?

In the absence of the Vaticle schema designer, I’m toying with an idea and would appreciate your comments. The elements of a TypeDB schema could be modeled in UML (in a custom profile) as stereotyped classes and, for roles, as stereotyped UML relationships. I could then use my favorite UML graphical tool, Sparx Systems’ Enterprise Architect, as a TypeDB design platform. Although it certainly wouldn’t be trivial, this could be extended with an MDA facility to generate TypeQL schema definitions from the UML model, and potentially even reverse engineer TypeQL back to a UML model (the main complication there is parsing). Am I crazy?

BTW, another design possibility might be to use ORM for initial TypeDB schema modeling. ORM appears to have all the model elements necessary to capture a TypeDB schema. But tool support is weak - the only option seems to be the NORMA tool running under Microsoft’s Visual Studio. NORMA used to be proprietary, but then was released as open-source.

Thanks again for your valuable guidance.


You’re very welcome!

As of now, mid-2021, the schema designer is not available and won’t be for some time. Not for point-and-click schema creation, the best workflow with Vaticle tools will be driven by writing the schema and then visualising it, for now. I can’t give you a due-date for the re-introduction of the schema designer :frowning:

I don’t think you’re crazy, parsing a custom flavour of UML to TypeQL sounds really rather plausible… which will then be visualisable in Workbase for a visual cross-reference. Parsing it back again would also be fantastic. My input here is that there are plenty of other people on the Vaticle Discord Server who would be very interested in this, or maybe have even attempted it already. It would be great to see you there and maybe we can find potential collaborators/ideas/existing projects.

Totally agree, Object-role modelling is the closest thing around to a TypeDB visual model, but I don’t have any tooling to recommend for it.

Can you point me to an idiot’s guide for the use of Vaticle’s Discord server? I don’t grok its approach :roll_eyes:

Gary, we’re happy to welcome you to the TypeDB Discord community: https://discord.gg/XCdBJh6K

You’ll need to create a quick profile and will then be a member of the server.

You’ll find “channels” on the left-hand side of the window. Navigate down to “TypeDB Community” and you will find topic channels for you to post your questions/comments/requests.

It will be good for you to take a moment to introduce yourself in the “#introduction” channel so our engineers and community members know how best to support you.