Jod Product & Engineering Docs Blog

Ensuring model association shapes throughout the application stack

Wed, 09 Jul 2025 00:00:00 GMT

Intro to Json Shapes

We will consider simple

GET /identities/user/:id

For a simple endpoint like getting a single Identities::User, we would expect the response to be:

Response:

{
  id: ..
  country_id: ..
  email: ..
  first_name: ..
  last_name: ..
  phone_code: ..
  mobile: ..
}

GET /org/user-profiles/:id

We explore the difference cases of considering associations when getting a single Org::UserProfile.

Response if we do not join tables in the backend:

simply rendering the attributes on the model Org::UserProfile

{
  id: ...
  title: ...
}

Response if I join Identities::User in the backend:

Org::UserProfile belongs_to Identities::User

{
  id:  ..
  user: {
    id: ..
    first_name: ..
    last_name: ..
    ...
  }
}

Response if I join all associations of Org::UserProfile in the backend:

Org::UserProfile belongs_to Identities::User
Org::UserProfile belongs_to Company

{
  id:  ..
  user: {
    id: ...
    first_name:
    last_name:
    ...
  },
  company: {
    id: ...
  }
}

Bad response:

This is a badly designed response because there is no database backed model that follows the following format.

{
  id: Org::UserProfile.id,
  first_name: Identities::User.first_name,
  last_name: Identities::User.last_name,
  ...
}

The idea is to maintain the json "shape" to follow the backend models.

Problem Statement

For every careers_job_application, I want to know who posted the careers_job

If I add another relationship to careers_job_applications, do I need to join all the tables?

Since AuthProvider wraps the entire frontend application

AuthProvider stores Identities::User and Careers::UserProfile and Org::UserProfile (depending where the user logs into)
Every page will know who is calling our backend API
This means that the backend doesn't need to join the identities user

However, this only applies for only Career::UserProfile cases.

For an Org::UserProfile, they would need to know names of Careers::UserProfile

For example, for each Careers::JobApplication, we would want to display the person name, which lives in Identities::User

GET /org-user/careers/job_applications

As a org user, I want to see who applied for my job

Looking at the relationship:

The person making this call is an org-user, I need to join the tables to display the name of the user who applied.

I would return the following response:

{
  careers_job_applications: [{
    id:,
    //.. attributes
    career_user_profile: {
      id: ..,
      identities_user: {
        id: ..
        first_name: ..
        last_name: ...
      }
    }
  }]
}

GET /org-user/careers/job_applications/:id (#show)

When showing a single job application:

{
  careers_job_applications: {
    id:,
    //.. attributes
    career_user_profile: {
      id:           ..,
      certificates: [{ .. }],
      experiences:  [{ .. }],
      skills:       [{ .. }],
      identities_user: {
        id:         ..
        first_name: ..
        last_name:  ..
      }
    }
  }
}

How can we reduce joins to improve performance?

Add a json column career_user_profiles.data, every time we save a Career::UserSomething (i.e. skills, experiences, certificates), we update two tables:

Career::UserSomething table
Career::UserProfile.data columns

{
  careers_job_applications: [{
    id:,
    //.. attributes
    career_user_profile: {
      id: ..,
      data: { // new column that pre-computes the "join" of the associated tables
        certificates: { .. },
        experience: { .. },
      }
      identities_user: {
          id: ..
          first_name: ..
          last_name: ...
        }
    }
  }]
}

The downside of this is that we require to update the tables whenever any one of the Career::UserProfile associations change.

then again, it's fairly simple to ensure this by ensuring we call a, for example, Careers::UserProfiles::UpdateDataService in all the places that updates Career::UserProfile associations.

Charlie Question

Imagine we are in a company backend and frontend are two separate teams.

I can see that response will always follow the convention where the payload will be correctly formatted (i.e. following the model "shape")
can frontend user ignore the shape when they are submitting the form?
- I imagine frontend does not have visibility how it is implement in the backend

Backend creates endpoint:

Send the postman doc to Frontend
Frontend would see it and implement their designs
Frontend realise in a particular page UI design, the endpoint provided does not return data from a specific model
Backend say i cannot join tables any more cause the response you got initially is already joining 10 tables
Backend will say, you call this other endpoint to get that model

So what have we established?

The default API Response JSON "shape" should follow the model associations.
Ideally max up to 3 table joins in the backend

How does this "model association json shape" affect forms in the frontend?

Forms should always follow the model it is rendering for.

If want to create a Car, I would have a CarForm that follows the Car attributes.

one form field for each Car attribute.

Likewise, if want to create a Org::UserProfile, I would have a OrgUserProfileForm that follows the Org::UserProfile attributes.

Org::UserProfile Attributes

id
identities_user (association)
company (association)
title
created_at
updated_at

In my , I would need fields for the associations as well.

Scenario 1: Admin

Assume Admin (jod staff) is creating an Org::UserProfile.

Admin can access everything in the system
- they can see all identities_users and companies

<Form>
  <TextInputField name={'title'}>
  <IdentitiesUserSelectField name={'identities_user.id'}>
  <CompanySelectField name={'company'}>
Form>

const IdentitiesUserSelectField = () => {
  // makes an api call to GET /admin-user/identities/users
  // gets a list of identities
  // render the list of identities in a dropdown
  // user select 1 identity from the response
  // update the form OrgUserProfileForm state via react-hook-form
}

When I select a Identities::User and Company from their respective select fields

my form state now has the Identities::User attributes and company attributes.
this means I can nicely render the models int he frontend after the user selects.

Scenario 2: Org User

Assume Org User is creating an Org::UserProfile.

Org User can only access everything associated with their company
They can only see Identities::User and a single Company, which is the company they belong to.

Thinking about the form schema for OrgUserProfileForm

note

In the frontend, form is named as {ModelName}Form

const orgUserProfileSchema = () => {
  title: zod.string()
  // company_id: zod.integer()
  company: {
    id: zod.integer().required()
  }
  identities_user: {
    id: zod.integer()
  }
}

const OrgUserProfileForm = () => {
  return (
    <Form>
      <TextInputField name={'title'}/>
      <TextInputField name={'identities_user.first_name}/>
    <Form/>
  )
}

Yuri Question

Job Application <-- we need to insert this
- User Career Profiles  <-- we don't need to insert anything in this one
   - User Career Experience <-- we need to insert this

note

While the question does not make sense in our domain, consider the same associations in the models.

I want to create a Careers::JobApplication

and at the same time create Career::UserExperience

Looking at the model associations (not the association on the database level)

TL;DR: Yes we follow the format.

// form schema follow "shape"
const jobApplicationSchema = {
  careers_job: {
    id: 1,
  },
  careers_user_profile: {
    id: 1 // we need to know who to create the Careers::UserExperience for
    careers_experience: [{
      job_title: ..
    }]
  },
}

// Alternative form schema which does not consider "model association json-shape"
// While it's not wrong from a technical perspective, this is not our convention.
const jobApplicationSchema = {
  careers_job_id:
  careers_user_profile_id:
  careers_experiences: [{ .. }, ...]
}

Imam Highlight:

Whenever you change any form schema/state shape, ensure you are assigning errors to the correct form field names.

this will ensure that errors are rendered on the correct field in the form

Naming things

July Direction

Week 1 we will make changes to existing MVP based on the technical feedback from ali

naming
api layer should not have async
form schema should follow endpoint structure/shape
endpoint should follow shape of model associations

Week 2

start on the peripheral services
- send email
- simple notification system
- event/analytics
- file upload

Week 3

continue with peripherals
start on product feedback

Week 4

continue on product feedback

Welcome

Thu, 26 Aug 2021 00:00:00 GMT

Docusaurus blogging features are powered by the blog plugin.

Here are a few tips you might find useful.

Simply add Markdown files (or folders) to the blog directory.

Regular blog authors can be added to authors.yml.

The blog post date can be extracted from filenames, such as:

2019-05-30-welcome.md
2019-05-30-welcome/index.md

A blog post folder can be convenient to co-locate blog post images:

The blog supports tags as well!

And if you don't want a blog: just delete this directory, and use blog: false in your Docusaurus config.

MDX Blog Post

Sun, 01 Aug 2021 00:00:00 GMT

Blog posts support Docusaurus Markdown features, such as MDX.

tip

Use the power of React to create interactive blog posts.

For example, use JSX to create an interactive button:

<button onClick={() => alert('button clicked!')}>Click me!</button>

Long Blog Post

Wed, 29 May 2019 00:00:00 GMT

This is the summary of a very long blog post,

Use a comment to limit blog post size in the list view.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet

First Blog Post

Tue, 28 May 2019 00:00:00 GMT

Lorem ipsum dolor sit amet...

...consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet

Jod Product & Engineering Docs Blog

Ensuring model association shapes throughout the application stack

Intro to Json Shapes​

GET /identities/user/:id​

GET /org/user-profiles/:id​

Problem Statement​

GET /org-user/careers/job_applications​

GET /org-user/careers/job_applications/:id (#show)​

How can we reduce joins to improve performance?​

So what have we established?​

How does this "model association json shape" affect forms in the frontend?​

Scenario 1: Admin​

Scenario 2: Org User​

Naming things​

July Direction​