Skip to content

Learn More About Conventions & Schema Annotations

Jump to bottom
Jarrod edited this page Mar 25, 2021 · 1 revision

Conventions & Schema Annotations

Per the documentation "Datomic Schema is stored as data, you can and should annotate your schema elements with useful information". Those useful annotations can enable many things. This particular application uses annotations to build a visualization of the structure and relationships between schema elements.

By creating attrs that are designated as a entity or enumeration grouping. We can provide documentation related to the intended usage and attributes of the group that have :db/ident's which share the same namespace. This information can be leveraged to create a very traditional feeling relational data like visualization of the schema.

The annotations used by the application are:

(def annotation-schema-tx [{:db/ident :cartographer/entity
                            :db/valueType :db.type/keyword
                            :db/unique :db.unique/identity
                            :db/cardinality :db.cardinality/one
                            :db/doc "Creating an entity with this attr will cause its value to be considered an entity-grouping namespace in the application."}
                           {:db/ident :cartographer/enumeration
                            :db/valueType :db.type/keyword
                            :db/unique :db.unique/identity
                            :db/cardinality :db.cardinality/one
                            :db/doc "Creating an entity with this attr will cause its value to be considered an enumeration-grouping namespace in the application."}
                           {:db/ident :cartographer/deprecated?
                            :db/valueType :db.type/boolean
                            :db/cardinality :db.cardinality/one
                            :db/doc "Boolean flag indicating the field has been deprecated."}
                           {:db/ident :cartographer/replaced-by
                            :db/valueType :db.type/ref
                            :db/cardinality :db.cardinality/many
                            :db/doc "Used to document when a deprecated field is replaced by other."}
                           {:db/ident :cartographer/references-namespaces
                            :db/valueType :db.type/ref
                            :db/cardinality :db.cardinality/many
                            :db/doc "Used to indicate which specific :cartographer/entity or :cartographer/enumeration are intended to be referenced by :db.type/ref"}
                           {:db/ident :cartographer/validates-namespace
                            :db/valueType :db.type/ref
                            :db/cardinality :db.cardinality/one
                            :db/doc "Used to indicate which specific :cartographer/entity is intended to be validated by :db.type/ref"}])

Basic Example

Defining An Entity

By adhering to a convention of creating a :cartographer/entity with a value of :store. We can then conclude all attrs with a :db/ident having a keyword with the namespace store will be grouped together in the application.

;; == Create a 'grouping' of 'store'
{:cartographer/entity :store
 :db/doc              "An entity representing an individual ice cream store"}
;; == The following elements all have idents with a keyword namespace of 'store' and will be grouped together
{:db/ident       :store/id
 :db/valueType   :db.type/uuid
 :db/cardinality :db.cardinality/one
 :db/unique      :db.unique/identity
 :db/doc         "Unique id assigned to each store"}
{:db/ident       :store/address
 :db/valueType   :db.type/string
 :db/cardinality :db.cardinality/one
 :db/doc         "Street address of a specific store location"}
{:db/ident       :store/employees
 :db/valueType   :db.type/ref
 :db/cardinality :db.cardinality/many
 :db/doc         "Employees who may work at a given store"
 :cartographer/references-namespaces ["employee"]} ;; Specifies a specific entity that is referenced

Defining An Enumeration

By adhering to a convention of creating a :cartographer/enumeration with a value of :ice-cream-flavor. We can then conclude all attrs with a :db/ident having a keyword with the namespace ice-cream-flavor will be grouped together in the application.

;; == Create a 'grouping' of 'ice-cream-flavor'
{:cartographer/enumeration :ice-cream-flavor
 :db/doc   "Ice cream flavor options, currently available in store."}
;; == The following enumerations all have idents with a keyword namespace of 'ice-cream-flavor' and will be grouped together
{:db/ident :ice-cream-flavor/strawberry}
{:db/ident :ice-cream-flavor/chocolate}
{:db/ident :ice-cream-flavor/vanilla}

Complete Example Schema

Create a connection to a new Datomic database and transact the following example schema. This will provide a complete fully annotated schema suitable to experiment with the application and for use as a reference.

Clone this wiki locally