Data model standards & best practices

Model

Naming conventions

These are the basic rules for a builder while creating a model.

• Model name

  • English
    This makes it understandable for most users what the model is used for.

  • PascalCase
    The model name must be PascalCase and singular. This makes the model names readable and consistent. Examples: Invoice and InvoiceLine.

• Description
  The advice is to add a short description

  • with useful information;

  • about the functionality of the model;

  • with the reason for using the model.

Properties

Models should be light and nimble. If relations could be used, you should use them to create a solid database and to prevent redundant data. Loading times will benefit from this setup.

When adding a lot of properties to a model you might run into a limit. Depending on the types of properties used, this limit lies around 25 properties per model. Please prevent yourself from going anywhere near this limit.

Naming conventions

• Property name

  • English
    This makes it understandable for most users what the model is used for.

  • Capitalize property name
    Save the name capitalized, so always start the name with an uppercase letter and use a space between the separating words.
    ​
    The property name must comply with the following rules:
    - Name must start with a letter.
    - Only use alphanumeric (A to Z) characters or numbers (0 to 9).
    - Use a space ( ) for separating words.
    ​
    ​Example
    Date/Date time properties affix with at, for example, Created at.
    Checkbox properties prefix with is and affix with a question mark, for example
    ​Is valid?.
    All others can only save the name capitalized, for example, First name.

  • Use Snake case for the database name
    The platform will automatically convert any used capitals to lowercase called snake case. By using snake_case the properties remain readable for the human eye.
    ​
    The database must comply with the following rules:
    - Name must start with a letter.
    - Only use alphanumeric (a to z) characters or numbers (0 to 9).
    - Use an underscore ( _ ) for separating words.
    ​
    ​Example
    Date/Date time properties affix with _at, for example, created_at.
    Checkbox properties prefix with is_, for example, is_valid.
    All others can only use snake cases, for example, first_name.

Property types

Choose the type that is best suited for your needs, for example: don’t store a password in a text property but use a password property.

Application memory

• Size of a single public file has a maximum of 10MB

• Applications are allowed to store a total of 1GB of record data in the database.

The assets in applications hosted on the Betty Blocks public cloud have a separate storage, the application asset size has a limit of max 50GB.

Default value

Almost all properties (like CHECKBOX, DATE, EMAIL ADDRESS, LIST, NUMBER, PRICE, and TEXT) and all belong-to relations allow you to set a static or dynamic default value. As soon as a new record is created, and no manual input was set for the concerning property, the default value will be stored.

Format

Properties like DATE, DATETIME, DATE, NUMBER, NUMBER WITH DECIMAL, and PRICE allow you to set a default format.

Validations

These are the basic rules for validation:

• Mark at least one property as required
  By checking this option a record can not be stored in the database unless this information is provided. If you create a new property on a model and make it mandatory by selecting this option, this will affect the currently present records. If you don’t take precautions, the application doesn’t let you update existing records since this info is missing.

• Mark it unique to prevent duplicates
  Use this validation when there should be no duplicates in the database, for example, the property email address of a web user.

If for whatever reason you want to rename a relation that isn’t (widely) used, it is advised to:

• only rename the Name and don’t rename the Database name; or

• remove the wrongly named property and create a new one since

The initially defined name is used in the database and will not change if you rename it. As a Betty Blocks user, this will not have any effect, but if something goes horribly wrong with the applications and changes have to be made in the Betty Blocks database, it will be much harder to debug.

Delete property

Unused properties shouldn’t be in the application. Delete unused properties to prevent yourself and your colleagues from using the wrong properties in the application.

Before deleting a property, you must check the property’s dependencies and all templates. I.E.: If the property is used in an action, this action could return an error after the deletion.

Relations

Models should be light and nimble. By doing so, you create a solid database and reduce loading times.

Naming conventions

• Name

  • English
    This makes it understandable for most users what the model is used for.

  • Capitalize relation name
    Save the name capitalized, so always start the name with an uppercase letter and use a space between the separating words.
    ​
    The relation name must comply with the following rules:
    - Name must start with a letter.
    - Only use alphanumeric (A to Z) characters or numbers (0 to 9).
    - Use a space ( ) for separating words.

  • Use Snake case for database name
    The platform will automatically convert any used capitals to lowercase called snake case. By using snake_case the properties remain readable for the human eye, for example, invoice_lines.
    ​
    The database must comply with the following rules:
    - Name must start with a letter.
    - Only use alphanumeric (a to z) characters or numbers (0 to 9).
    - Use an underscore ( _ ) for separating words.

These are the basic rules for creating a relation:

• Choose the right type of relation;
  Decide which relation type to use and how to name it when creating a relation.

Use singular for “Belongs to” relations

Example:

Invoice >-------------- ( belongs to ) ----------------|-Customer

Always validate the presence of this relation (make it required) unless there are very strong reasons not to do so.

Use plural for “Has many” relations

Example:

Customer-|-------------- ( has many ) ------------------<Invoices

Use plural for “Has and belongs to many” relations

Example:

User>------ (has and belongs to many) -----<Roles

Delete relation

Relations that aren’t used shouldn’t be in the application. Delete unused relations to prevent yourself and your colleagues from using the wrong relations in the application.

Permissions

Permissions determine what a user (based on the given role) is or isn't authorized to do. Every back office user and Data API user needs a role.

Example:

You could have administrators and order pickers. An order picker should only be able to read the invoices and their invoice lines while the administrator cannot only read them but also update and delete them. Set the permissions on the model level to accomplish this.

The role public is a default role that is applied to unauthenticated users in the page builder and Data API. Check the models which can possibly show data in the front end.

Validations

The validations tab displays an overview of the type of validations used on the model’s properties. Existing validations could easily be edited by clicking the tab Properties.

Settings

Model name

You are able to rename existing models. If your model isn’t widely used it is advised to apply the best practice.

Allow import

By enabling the import functionality, you’re able to import data towards Betty Blocks. It could be useful for testing to have data in your application, but it’s time-consuming if you’d add this data by hand. Therefore the import functionality would be useful. By setting this option to TRUE, you’re able to do an import via the grid view of the model.

Allow mass delete

When creating an application it might be useful to mass delete records using the grid view.

Example:

When a developer is creating an application he will be testing if indeed the Invoice and InvoiceLines are created. This could create a lot of test data that you want to delete with one simple click. But, as soon as the developer finishes his job and the app is taken into production, having this option still active is a big risk. Customers could have placed orders that you’ve accidentally deleted in the back office.

Settings model

When enabling the settings model option in your app, all data in this model will be merged through to all sandboxes. This is useful if the data in this model doesn’t have to change a lot and will be used as a setting, for example, roles, countries, and VAT rates. This setting should only be used if the containing record has a meta-purpose.

Think twice before changing an existing model into a settings model. Turning a model into a settings model will transfer all records within the model to the merged-to sandbox on merge. This data will be overwritten on every merge and will be active after the second merge (as protection). It will also overwrite the existing records, including their association with other records (excluding all has and belongs to many relations).

Label property (only for back office usage)

Label properties are set to ID by default. This ID doesn’t give much information to a back office user. Consider changing them to a property that could be of interest to the end-user.

Order property (only for back office usage)

The default order in which data is shown in the back office can be changed by setting the order property.

Log mutations (only for back office usage)

There might be some key features in the app that should be logged. This setting logs every mutation (create/update/delete) in a hashed format with the UUIDs, old value, and new value.

Important note: the log mutation is only untraceable to a specific record when the record has been deleted.

Example:q

You might need to show an IBAN on your site which your customers have to transfer their money. If you’re able to change this IBAN in the app, it’s advised to log by who and when the change was made. By setting this option to TRUE, these changes could be made visible in the grid view.

Delete model

Models that are unused shouldn’t be in the application. Delete unused models to prevent yourself and your colleagues from using the wrong models in the application.

Readable schema overview

The schema overview could be very useful to get an understanding of the application. To make it live up to its potential, you’ll need to organize the overview.