This section covers the core concepts found in Synth.
The namespace is the top-level abstraction in Synth. Namespaces are the equivalent of traditional schemas in the world of relational databases likes PostgreSQL. References can exist between fields in a given namespace, but never across namespaces.
Namespaces are simply directories from which
synth reads a collection of
schema files. For example, a namespace
blog could have the following
Any file whose extension is
.json in a namespace directory will be opened by
synth generate subcommand and considered part of the
Every namespace has zero or more collections. Collections are addressable by their name and correspond to tables in the world of relational databases. Strictly speaking, collections are a super-set of tables as they are in fact arbitrarily deep JSON document trees.
Collections are represented in a namespace directory as JSON files. The name
of a collection (the way it is referred to by
synth) is its filename
without the extension. For example the file
bank/transactions.json defines a
transactions in a namespace
For a more comprehensive example, let's imagine our namespace
bank has a
transactions and another collection
users. The directory
structure then looks like this:
A field reference is a special kind of fields that is useful for declaring relations between different parts of a collection or different collections in the same namespace.
A field reference can be specified by using the same_as generator type.
The value of the
"ref" field should be the address of the field you want to
refer to. A field address takes the
<collection name>.<level_0>.<level_1>.... For example, say we have a
users.json containing the following schema:
A reference to the
username field would have the
users.content.username. If we want to add a reference to this field
from another collection we would simply add:
The schema is the core data structure that you need to understand to be productive with Synth. The schema represents your data model, it tells Synth exactly how to generate data, which fields we need, what types and so on. This is a little involved so there is a section devoted to just the schema.
Synth can ingest and build schemas on the fly with
synth import command.
To generate data from an existing namespace use
synth generate command.
synth uses a seedable pseudo-random source of entropy. By default,
the seed is set to a constant value of
0 using the
rand::SeedableRng::seed_from_u64 function. This
means that, by default, the data that
synth generates is
deterministic: it is only a function of your schema files.
This behavior can be tuned (and the seed be changed, or randomized) using