Skip to content

Tilda JSON Syntax: Objects

Jump to bottom
Laurent Hasson edited this page Nov 23, 2022 · 16 revisions

<-- Main Schema Syntax

Objects

Objects are essentially mapped to database tables for relational systems, but over time, Tilda is expected to support other types of data stores, such as the PostgreSQL big table implementation, and in the future, Hadoop-based data lakes. As such, it was decided to call concrete data store definitions “objects”, which is more generic than “tables”.

Main Outline

Objects are defined as follows:

{ "name":"Organization"
 ,"referenceUrl":"https://build.fhir.org/valueset-encounter-reason.html"
 ,"tag":"Org"
 ,"description": "blah blah"
 ,"descriptionX": [ "blah blah"
                   ,"And more blah blah"
                   ,"And more blah blah again."
                  ]
 ,"cloneAs":[
   ]
 ,"occ":true
 ,"mode":"NORMAL"|"DB_ONLY"|"CODE_ONLY"
 ,"lc":"NORMAL"|"READONLY"|"WORM"
 ,"tenantInit":true|false
 ,"columns":[
   ],
 ,"primary": { "autogen":false, "columns": ["id"] }
 ,"foreign": [
   ]
 ,"indices":[ 
   ]
 ,"queries":[
   ]
 ,"outputMaps":[
   ]
 ,"masks":[
   ]
 ,"history":{
   }
}

The fields are:

  • name: the name of the object, mapping effectively to the name of the Table in the database.
  • referenceUrl: using Tilda to design data warehouses is common. When designing data warehouses, you often have to define multiple dimensions for codesets. We found ourselves copy/pasting URLs to reference material all over the place. With 'referenceUrl', you can define such a link once and then reuse it anywhere the table's description of the description of any of its columns with the placeholder ${REFERENCE_URL}. A proper link will be generated as part of the documentation.
  • tag: similarly to 'referenceUrl', there are often tokens/tags that are reused across the documentation and becomes more useful with cloning capabilities. The value specified here can be used as ${TAG} in any comment for this object.
  • description: HTML-based description field to document the table. This field (or descriptionX) is mandatory: models must be documented in Tilda. Either one of 'description' or 'descriptionX' must be defined but not both.
  • descriptionX: multi-line HTML-based description field to document the table. This field (or description) is mandatory: models must be documented in Tilda. Either one of 'description' or 'descriptionX' must be defined but not both.
  • cloneAs: an optional array describing the names and descriptions of objects which should be cloned from the one currently being defined.
  • occ: optional, true by default, indicates that the table has automated lice-cycle management with columns such as “created”, “lastUpdated” and “deleted” that will be generated automatically.
  • mode: optional, NORMAL by default, indicating how code is generated at the application and database level.
    • NORMAL: generates ALL artifacts, at the database level as well as the application level.
    • DB_ONLY: only generates database-level artifacts (i.e., no application code generated). In some cases, Tilda is used to manage complex schemas and not necessarily to support applications. For that use case, this field can be used to eliminate a lot of code generating, making the project size (i.e., files and final compiled JARs) much lighter.
    • CODE_ONLY: only generates application-level code (i.e., no database-level artifacts are generated). This is useful to customize a complex query where columns are known in advance and reuse JDBC Row handling, queries, JSON formatting etc… on the code-side.
  • lc: optional, ‘NORMAL’ by default, indicating the read/write abilities for the table from an application perspective. This is not enforced in the database itself. The values possible are:
    • NORMAL: expecting to be able to read, write and delete any row.
    • READONLY: the table behaves like a view with read-only capabilities.
    • WORM: Write-Once-Read-Many, the table can be written to, but rows cannot be updated or deleted.
  • tenantInit: optional, false by default, indicating whether initialization logic provided by the application should be run only once (false), or once per tenant (true).
  • columns: a list of column definitions (see next section for details).
  • primary: definition of the primary key, if applicable (see next section for details).
  • foreign: definition of foreign keys if applicable (see next section for details). indices: definition of unique and regular indices (see next section for details).
  • indices: definition of preferred methods of access, usually backed by indices in the database.
  • queries: definition of preferred queries for access.
  • outputMaps: definition of output capabilities such as NVPs, CSV or JSON data formats.
  • masks: definition of field masking logic.
  • history: definition for a history/audit pattern.

🎈 NOTE: All tables must have an identity. That means they must define either a primary key, or at least one unique index.

The meat of an Object's definition is to define columns, identities (PK or unique indices), preferred methods of optimized access (indices), relationships (foreign keys) and export output formats:

Clone this wiki locally