References

Overview

Relationships between models are defined as references. There are multiple ways on how to specify these relationships depending on your data structure and your application needs.

tip

The main goal of data modelling in dcupl is to make sure your models fit your applications needs. If your attributes are in the correct place (using references, derives, resolves, ...) you can get most out of our SDK.

singleValued reference

A singleValued reference describes a connection where a model points to a single entry of another model.

classDiagram direction LR class Person { key : string passport : Passport -> } class Passport{ key : string country : string } Person --> Passport : a person has a Passport

Model

{
  "key": "Person",
  "references": [
    {
      "key": "passport",
      "model": "Passport",
      "type": "singleValued"
    }
  ]
}

Result

{
  "key": "person_01",
  "passport": {
    "key": "passport_12345"
  }
}

multiValued reference

A multiValued reference points to multiple entries of another model.

classDiagram direction LR class Person { key : string books : Book --> } class Book { key : string } Person --> Book : a person may own many books

Model

{
  "key": "Person",
  "references": [
    {
      "key": "books",
      "model": "Book",
      "type": "multiValued"
    }
  ]
}

Result

{
  "key": "person_01",
  "books": [
    {
      "key": "book_1234"
    },
    {
      "key": "book_5678"
    }
  ]
}

resolving references

Resolving a reference is needed when you want to define a bidirectional connection between models. In the next example our data only tells us, that a specific author wrote a book. But additionally we want to know the other way round from the books perspective. So we have to be the book 🤯.

With a resolve we answer the books question: "Who wrote me?"

To resolve a reference you have to specify the remote model and the reference, where you want to go fishing for a pointer to yourself.

classDiagram direction LR class Author { key : string books : Book --> } class Book { key : string <-- authors : Author } Author --> Book : an author may wrote many books Book --> Author : a book was written by multiple authors

Model

{
  "key": "Author",
  "references": [
    {
      "key": "books",
      "model": "Book",
      "type": "multiValued"
    }
  ]
},


{
  "key": "Book",
  "references": [
    {
      "key": "resolvedAuthors",
      "model": "Author",
      "type": "multiValued",
      "resolve": {
        "model": "Author",
        "reference": "books"
      }
    }
  ]
}

Result

// personList.getItem(...)
{
  "key": "person_01",
  "books": [
    {
      "key": "book_1234"
    },
    {
      "key": "book_5678"
    }
  ]
}

// authorList.getItem(...)
{
  "key": "book_1234",
  "resolvedAuthors": [
    {
      "key": "author_01"
    }
  ]
}

property deriving

Once you have made a connection between two models using a reference you can pull any data from one model to the other. In the example below we derive the property country from the referenced Passport to the Person model.

caution

Deriving properties from multiValued references is currently only supported for strings. The result will be a concatinated string.

classDiagram direction LR class Person { key : string passport : Passport -> passportCountry : string ... } class Passport{ key : string country : string } Person --> Passport : a person has a Passport Passport ..> Person : we derive the country property

Model

{
  "key": "Person",
  "references": [
    {
      "key": "passport",
      "model": "Passport",
      "type": "singleValued"
    }
  ],
  "properties": [
    {
      "key": "passportCountry",
      "type": "string",
      "derive": {
        "localReference": "passport",
        "remoteProperty": "country"
      }
    }
  ]
}

Result

{
  "key": "person_01",
  "passport": {
    "key": "passport_12345"
  },
  "passportCountry": "AUT"
}

reference deriving

Deriving also works with references.
In the example below we derive the reference sex via the passport reference to the Person model.

classDiagram direction LR class Person { key : string passport : Passport -> gender : Gender ... } class Passport{ key : string country : string gender : Gender --> } class Gender{ key : string label : string } Person --> Passport : a person has a passport Passport --> Gender : a passport has a gender defined Passport ..> Person : we derive gender via the passport reference

Model

{
  "key": "Person",
  "references": [
    {
      "key": "passport",
      "model": "Passport",
      "type": "singleValued"
    },
    {
      "key": "passportCountry",
      "model": "Gender",
      "type": "singleValued",
      "derive": {
        "localReference": "passport",
        "remoteReference": "gender"
      }
    }
  ]
}

Result

{
  "key": "person_01",
  "passport": {
    "key": "passport_12345"
  },
  "gender": {
    "key": "M"
  }
}

reference grouping

When you are grouping a reference, you find every data entry of the same model that also points to the reference you are pointing to. As an example we want to find our 👽 clones 👽 - every Person that points to the Passport I claim.

classDiagram direction LR class Person { key : string passport : Passport -> clones: Person } class Passport{ key : string } Person --> Passport : a person has a passport Passport ..> Person : we get every person that points to "my passport"

Model

{
  "key": "Person",
  "references": [
    {
      "key": "passport",
      "model": "Passport",
      "type": "singleValued"
    },
    {
      "key": "clones",
      "model": "Person",
      "type": "multiValued",
      "groupBy": {
        "reference": "passport",
        "includeSelfInGroup": false
      }
    }
  ]
}

Result

{
  "key": "person_01",
  "passport": {
    "key": "passport_12345"
  },
  "clones": [
    {
      "key": "person_01.1"
    },
    {
      "key": "person_01.2"
    }
  ]
}