Home platformOS Logo

Persisting Data With Models

Last edit: Jun 05, 2020

Let's use the example to see exactly what is happening at each stage of Model Schema definition life cycle.

Step 1: Requirements

I want to store my "todo list" in platformOS

Todo list:

Task Priority
Clean the apartment Low
Do the homework High

Step 2: Model Schema File

Create definition file in your project repository that will describe my Model Schema:

touch app/model_schemas/todo.yml

Step 3: Definition of Model Schema

Using the editor of choice, add the definition of Model Schema.

The code below is the description of properties that Model will accept and the name of Model Schema object that is used to identify the object.
For full list of Types that can be used see Property Types

name: todo
- name: task
  type: string
- name: priority
  type: string

Step 4: Sync/Deploy Model Schema definition.

At the moment of deploy pos-cli is asking platformOS if Model Schema object with name todo already exists, if so it will be updated with given definition otherwise new object is created.

You can verify this step with GraphQL query:

  admin_model_schemas {
    results {
      properties {

the result for that query depending on your instance state should be similar to:

  "data": {
    "admin_model_schemas": {
      "results": [
          "name": "todo",
          "properties": [
              "name": "task"
              "name": "priority"

Step 5: Model Creation

In Building Contact Form With Model tutorial you will learn in details how to create Models.

Step 6: Model Schema change

As you know by now Models and Model Schema objects are strictly related as the definition of properties allows for storing the data in platformOS backend systems.
Once you have data persisted within Model you need to be aware of how changes in Model Schema affect your Model objects:

  • Model Schema definition delete - you can only delete your Model Schema object if there is no related Model object. Use models_delete_all mutation to delete all related Model objects.

    If you try to deploy with orphaned Model, you will see the following message:

    Cannot delete record because of dependent model of type: todo
    Use the mutation below to remove dependent objects:
    mutation { models_delete_all(model_schema_name: "todo") { count } }
  • name change - as platformOS detects Model Schema definition by its name, if you change it is equal with adding new Model Schema, please note that Model objects are not automatically migrated and will be treated as orphaned with next deploy attempt, see error message above.

  • add new Model Schema property - adding new properties is a valid change that does not need additional actions, the data remains untouched.

  • delete of Model Schema property - deletion of the property is a valid change, data stored in related Model properties will remain saved but will not be accessible. Use migration to remove the data prior to the change.

  • property edition - is a valid change and is equal to the removal of property with old name and creation of new property, data is not migrated.

Step 7: Mutations

What you have done in steps 2, 3 and 4 can be done with admin_model_schema_create mutation.
In your platformOS instance, the result would be exactly the same, but you can now create CMS system where the user can define their own models with a few clicks in the user interface.
Please note that the same rules apply for Model Schema deletion as when you delete it with pos-cli

Contribute to this page

Github Icon


We are always happy to help with any questions you may have.

contact us