Subitems

Unito refers to subitems as a syncable relation of an item. Imagine you could leave notes next to each pokémon, and you'd like these notes to be synchronized alongside other pokémon properties. These notes would be considered as subitems of pokémons.

From a connector standpoint, subitems are defined as relations like any other relation would be.

{
  fields: {
    name: "Pikachu",
  },
  relations: [
    {
      name: "notes",
      label: "Notes",
      path: "/pokedex/1/pokemons/1/notes",
      schema: {
        label: "Note",
        fields: [
          {
            name: "content",
            label: "Content",
            type: FieldValueType.STRING
          }
        ]
      }
    }
  ]
}

But from Unito's standpoint, things are a bit more complicated. You see, as it stands, we don't know that notes exist until we select a given pokémon. Imagine that our pokédex sits empty — how could Unito possibly know that there will be a relation called notes, and that this relation is to be expected on each item of the relation?

Enters RelationSummary. When describing the schema of your items, you can inform Unito that one or more relations are to be expected on each item of that collection. Armed with that knowledge, Unito will then be able to offer that relation as a potential syncable subitem, alongside all other fields.

{
  fields: {
    id: 1,
    name: "John Doe's Pokédex",
  },
  relations: [
    {
      name: "pokemons",
      label: "Pokémons",
      path: "/pokedex/1/pokemons",
      schema: {
        label: "Pokémon",
        fields: [
          {
            name: "name",
            label: "Name",
            type: FieldValueType.STRING
          },
          ...
        ],
        relations: [
          {
            name: "notes",
            label: "Notes",
            schema: {
              label: "Note",
              fields: [
                {
                  name: "content",
                  label: "Content",
                  type: FieldValueType.STRING
                }
              ]
            }
          }
        ]
      }
    }
  ]
}

Summaries are incomplete by nature given how relation properties, like the path, can be dependent on the item owning the relation. The summarized schema might be incomplete too, given how custom fields might also vary from one item to another. They're meant to describe the commonalities one could expect from the relations common to all of the items of that relation.

Optimizing with aggregate paths

Providing a relation summary allows Unito to synchronize subitems, but it can be an expensive operation. Imagine we're synchronizing all the notes of all the pokémons, we'd need to issue N independent API calls to retrieve each pokémon's individual notes.

This operation can be optimized by enhancing the relation summary with an aggregatePath property and making sure there's a PARENT field on all subitems, allowing Unito to retrieve them all in a single API call.

In our pokémon example, this would mean adding an aggregate path on the notes relation summary. This would give Unito a way to retrieve all notes of all the pokémons present in this pokédex, without having to iterate over each one. Not all tools can benefit from this approach, but when they can, it really is an optimization worth doing.

{
  fields: {
    id: 1,
    name: "John Doe's Pokédex",
  },
  relations: [
    {
      name: "pokemons",
      label: "Pokémons",
      path: "/pokedex/1/pokemons",
      schema: {
        label: "Pokémon",
        fields: [
          {
            name: "name",
            label: "Name",
            type: FieldValueType.STRING
          },
          ...
        ],
        relations: [
          {
            name: "notes",
            label: "Notes",
            aggregatePath: "/pokedex/1/notes",
            schema: {
              label: "Note",
              fields: [
                {
                  name: "content",
                  label: "Content",
                  type: FieldValueType.STRING
                },
                {
                  name: "pokemon",
                  label: "Pokémon",
                  type: FieldValueType.REFERENCE,
                  referencePath: "/pokedex/1/pokemons",
                },
              ],
            }
          }
        ]
      }
    }
  ]
}

Relations in item summaries

When relation summaries are defined, Unito can request their paths to be returned on a get collection call, similar to how it can request specific fields. The query parameter relations must be accepted by integrations to be able to fetch the relation paths. For example, on this path /pokedex/1?relations=notes, Unito will expect this result.

{
  info: {},
  data: [
    {
      path: '/pokedex/1/pokemon/1',
      fields: {},
      relations: {
        notes: '/pokedex/1/pokemons/1/notes'
      }
    },
    ...
  ]
}

Sync the parent of an item

When synchronizing subitems, especially through an aggregate path in which subitems from multiple items are present, Unito needs a way to identify to which item a specific subitem belongs. To achieve this, an item must define a field of type reference with the parent semantic.

{
  fields: {
    id: 1,
    name: "John Doe's Pokédex",
  },
  relations: [
    {
      name: "pokemons",
      label: "Pokémons",
      path: "/pokedex/1/pokemons",
      schema: {
        label: "Pokémon",
        fields: [
          {
            name: "name",
            label: "Name",
            type: FieldValueType.STRING
          },
          ...
        ],
        relations: [
          {
            name: "notes",
            label: "Notes",
            schema: {
              label: "Note",
              fields: [
                {
                  name: "content",
                  label: "Content",
                  type: FieldValueType.STRING
                },
                {
                  name: "owner",
                  label: "Owner",
                  type: FieldValueType.REFERENCE,
                  semantic: Semantic.PARENT,
                  reference: {
                    name: 'pokemon',
                    label: 'Pokémon',
                    path: "/pokedex/1/pokemons",
                    schema: {
                      label: 'Pokémon',
                      fields: [
                        {
                          name: 'id',
                          label: 'Id',
                          type: Api.FieldValueType.STRING,
                          semantic: Api.Semantic.DISPLAY_NAME
                        }
                      ]
                    }
                  }
                },
              ],
            }
          }
        ]
      }
    }
  ]
}