Airtable naming convention [clean-base system part 1]

Why do you need a naming convention ?

The goal is to be able to build faster, cleaner, and in a more flexible way.

Having a naming convention will allow you to build a robust and lean app with no duplicate fields and no error when pointing to the data.

Furthermore, you will build much faster as you will never search for a field again in airtable and you will link to data in your app in a blink.

In SOFTR, you can have very long dropdowns of 30+ fields sorted alphabetically. With the naming convention, you find what you need in seconds.

*softr dropdown to select airtable fields*

A naming convention is also indispensable for flexibility. If you decide to move from SOFTR to another frontend, if you need to add new data, if you decide to remove a set of data… all these scenarios will be much easier if your base is built as suggested in this guide.

Furthermore, complex apps can easily become a burden to manage. Having clearly named views, tables and fields will allow you to easily manage the dozens of fields you need to create. Having the same clarity on the SOFTR side will let you easily manage your robots.txt, find pages, link to pages, and overall organize a complex app.

But most importantly, people who don’t know (or forgot about) your app will be onboard very easily as they will immediately know what the data relates to.

It’s incredibly useful to your future self but also if you have a third-party developer coming in to help you fix something. He will be faster, you’ll pay less.

Naming bases

I'd recommend giving the base the name of your domain name. You often start with one project and end up with ten ideas.

Domains are a common denominator. Your base and your app should be named using the domain.

But why does naming bases matter?

It might seem basic but the unlock-softr.com base was named "test" for quite some time.

Why ? Because it was just supposed to be a personal base to test softr features, then it was because renaming in softr breaks stuff and I was too lazy to change all my blocks.

Your "main project" base will probably not be your main project forever, or even just your project. So, yes, even the bases should be properly named.

Naming tables

For naming tables, you should simply use the type of Record in lowercase and plural.

This might seem obvious to most of you, but from experience, it's far from being applied everywhere.

Don’t	Do
`List of jobs`	`jobs`
`Company`	`companies`
`App's Users`	`users`

But why does naming tables matter?

As discussed above, a naming convention has many advantages.

On top of that, clean table names will match your app pages and if you come back to a page after a year, you'll know exactly where to find your data.

As you’ll see, we’ll use these clearly named tables when naming relational views and fields (linked records and lookup fields).

Naming views

💡

Views are used for quickly finding the information you're looking for. However, with SOFTR, it's also a powerful way to filter records on a SOFTR page rather than the native conditional filter function. I'd recommend using the conditional filter function only for when you need to filter data according to the current page or the logged in user. We'll talk more about that later.

Record views

The first set of views you have will be related to the Records contained in the table itself.

You won’t show all the fields at once (except if you have a very simple dataset). As such, you will need to name a broad category of fields that will be held in that view. On most tables though, you’ll have one view with basic information on each of the listings, I just name that dataset information.

The naming structure for views directly relating to Records contained in the table should be:

✅

{current table} - {dataset} 👉 jobs - status

Sometimes you want a view to see a specific set of data. The worst you can do is not let people (including your future self) know that the view only contains part of the dataset. So the naming of the view shall include that filter.

And if you need a filter on that data:

✅

{current table} - {dataset} - {filter} 👉 jobs - status - rejected

Relation views

For related data, we need to quickly identify where the data comes from and why it’s here.

So the structure to apply when showing linked records as well as lookups and roll-ups needs to be:

✅

{origin table} - {relation} 👉 users - applying

Same as above, sometimes you need to filter the data but you now know never to forget to warn the table viewer that the view is partial.

So if you need a filter on that related data view, apply the following structure:

✅

{origin table} - {relation} - {filter} 👉 users - applying - France

Technical views

You are working with softr (or not, it still applies) and will have a ton of columns that are here just for functional purposes.

SEO view

✅

technical - seo

This is where you will store all the SEO and Open Graph columns (i.e. Social:Title, Social:Description, etc.)

General workflow view

✅

technical - workflow

This is where you will store all the columns only developers need to see except someone building the app or an automation (url behind an airtable button, a counter in text instead of just the number, etc.)

Specific workflow view

If you have a specific workflow that requires more than 2 columns, I recommend you isolate that workflow using the following naming convention:

✅

technical - workflow - {general action} 👉 technical - workflow - applying

Naming fields

This is the most important part of the naming convention. On top of the general advantages explained in the first part of this guide, several aspects are to be considered:

You will need to have other users intervene in your base. People are not in your head and must understand what the columns hold.

Depending on the syntax used in JavaScript, it might break if spaces are used in the name of the field.

SOFTR lets you search fields and it sorts them in alphabetical order. Your naming will drastically improve the speed at which you build.

Record data

This is the simplest level of data. If the data is related to the Records held in that table, simply use one word in lowercase.

Let's keep going with the job board example. For example, your jobs table could have the following Records field:

title

summary

description

url

If one word is really not possible, use “-” instead of spaces:

magic-link

Where it gets interesting is when you need to have granular data.

I recommend using an underscore in two cases:

when you want to show data in a different way/format:

created_date 👉 2022-08-23 03:00PM
created_timeframe 👉 two days ago

when you want to show data relating to another field:

description_excerpt
url_button If you followed the guide until here, you know that the URL_button field has to relate directly to the Record in the table and it has to be useful to the airtable user. Indeed, this is the button to quickly open a listing page from airtable as we’ll see in the airtable structure section of the clean-base system. It’s not the code for a button in SOFTR, Otherwise the field would be in the technical - workflow view.

⛔

What you should never do: I’ve noticed that many users tend to repeat the name of the table. That is a very common mistake leading to a lot of redundancy and lookup fields impossible to name.

If you’re working in the jobs table, never name your field job-title. You are in the jobs table, if a field is named title, it’s necessarily the job’s title.

Otherwise, if you need to have a lookup field to that field in another table, you’ll end up with job_job-title instead of the clear name you should have : job_title.

Relation data

If the data is relational, meaning it relates to data contained in other tables, you will need to make it clear by (i) using a prefix with the exact name of the table holding that linked data and (ii) adding the relation identifying the reason for this link:

✅

{name of the table holding the linked data}_{relation to the current table}

In our job board example, the linked records field could be: company-hiring 👉 12 (reference being the primary key value) user-hiring 👉 doe@gmail.com user-applying 👉 smith@gmail.com

Then, when you start adding lookup fields, roll-up fields, and formula fields based on such fields, you will have no difficulty as the naming will be smooth and clear. You will simply follow the naming convention for data relating to another field:

{name of the table holding the linked data}-{relation to the current table}_{data}

In our job board example, the lookups, roll-ups and formulas fields could be:

✅

company_hiring_name 👉 Acme Corp. company_hiring_website 👉 acme.com user_hiring_name 👉 John Doe

It will greatly help when you start naming formulas:

✅

user_applying_count 👉 13 user_applying_counter 👉 13 applicants company_hiring_page 👉 [open page]

Action fields

If you start building something complex, you'll start having webhooks urls to make.com, to n8n, or to appspan.

For this, I recommend prefixing the columns with "webhook_" followed by the name of the event (or trigger). The format will be:

✅

webhook_{name of the event} 👉 webhook_created

You will notice that we did not name these fields webhook_job-created. Why? Because it's the jobs table. There is no reason to add that.

For naming webhooks affecting linked records from the linking table (and not the linked table), you should name the webhook accordingly.

For example, if you are managing an applicant from the job table side (you could also do it from the user table side), you would name the fields:

✅

webhook_relation_{name of the event} 👉 webhook_user_applied

➡️

Go to the next part of the clean-base system

Airtable naming convention [clean-base system part 1]

Why do you need a naming convention ?