For example:

d | r | b | m | property | type   | ref     | level | access
datasts/example          |        |         |       |
  | resource1            | sql    |         |       |
  |   |   | Country      |        | name@en | 4     |
  |   |   |   | name@en  | string |         | 4     | open
  |   |   | City         |        | name@en | 4     |
  |   |   |   | name@en  | string |         | 4     | open
  |   |   |   | country  | ref    | Country | 3     | open

Here we use name@en as primary key and as an external key, with level set to 3, that means, we have to use original column values instead of _id.

In this case data for writing and reading of City model should look like this:

{
    "_type": "datasts/example/City",
    "_id": "dcfae257-962d-4204-b483-b03836addf7d",
    "name": {
        "en": "Vilnius"
    },
    "country": {
        "name": {
            "en": "Lithuania"
        }
    }
}

For mapping name@en with _id, via keymap, we have to use "Lithuania" value, not {"en": "Lithuania"}.

For storing data in internal PostgreSQL backend, we should store reference data in country.name@en column of string type, because reference is using string part of text type, not the text type itself, bet a part of it.

There should be a distinction made, that text type is a complex type, while string type is a simple type and can go independently or as part of text type.

For data formats, that support complex types, we use a native format form, for example, if we refer to name@en in JSON we should encode it as {"name": {"en": "Lithuania"}}.

If format does not support complex type, like tabular formats, we use "name@en" as column name.

There might be a slight confusion with implicit and explicit forms of text type. Even if text type is a complex type, it can be expressed in two ways:

• explicit form - {"en": "Lithuania"}
• implicit form - "Lithuania", where language tag is selected using content negotiation

Related

• Add support for text type #204
• Add possibility to reference external model #208