How Remote builds onboarding for 60+ countries

Remote allows employers to hire employees all across the globe, and each country is different regarding the details and documents needed to hire. These details are not only specific to each country, but are also constantly changing due to new country-specific laws and other factors.

When Remote started, we used simple forms on the frontend, where a part of the input validation process happened. The other part happened in the backend. This became a problem for us, as the backend had different validations and input fields defined for each country. This problem was happening due to the nature of our business: country laws change often, and we need to adapt to those changes quickly.

With the launch of the Remote API, it was clear that we needed to build something both robust and simple to change to make all our services share the same requirements for every country.

Remote’s use of the JSON Schema

We decided to use JSON Schema to address the challenge. JSON Schema allows for forms definition and data validation in the frontend and backend services, creating a single source of truth. This is defined (as the name implies) in JSON, so it can be read and updated by anyone. JSON Schema also has good documentation, so even a new joiner can make any necessary changes.

These JSON Schemas are then parsed, and a form is rendered on the frontend according to the definition. On top of standard JSON Schema fields (such as “type," "title," "maxLength," etc.), we added metadata to each field to make the form render as we intended. One example is the “presentation" object, which contains fields like “position" that define where the position a certain field is displayed on the form. Another example is the “options” field: useful when the input type is a radio button or a selection from a dropdown, allowing us to define a label and a value (where the value must match one of the values defined in the “enum” array).

The following code block shows an example of a JSON Schema containing a single property (the number of accepted values was reduced to make the example shorter):

1{
2   "additionalProperties":false,
3   "properties":{
4      "marital_status":{
5         "description":"Select your marital status from the dropdown",
6         "enum":[
7            "married",
8            "single",
9            "civil_partnership"
10         ],
11         "presentation":{
12            "inputType":"select",
13            "options":[
14               {
15                  "label":"Married",
16                  "value":"married"
17               },
18               {
19                  "label":"Single",
20                  "value":"single"
21               },
22               {
23                  "label":"Civil Partnership",
24                  "value":"civil_partnership"
25               }
26            ],
27            "position":0
28         },
29         "title":"Marital status"
30      }
31   },
32   "required":[
33      "marital_status"
34   ],
35   "type":"object"
36}

The previous example renders a simple form, but JSON Schemas allow for much more complex definitions, such as having fields that depend on the value of some other field using “if,” “then,” and “else” keywords.

Engineers at Remote are working on adopting JSON Schemas for every country we support, resulting in a much smoother user experience, speeding up our onboarding times and reducing onboarding questions from users all around the globe.

For Remote API partners, we plan to launch an SDK that customers can embed on their websites to make the integration process with Remote much faster for their development teams. We will also be publishing two more interesting articles to go into detail about how we build and use JSON Schemas on our frontend and backend services.

If you have any questions, feel free to reach out to me on Twitter @csilva_antonio. I'm always happy to help!