References

The reference field

A reference field stores a UUID pointing to another record. The target schema is configured via targetSchema.

{
  "name": "Author",
  "slug": "author",
  "type": "reference",
  "config": {
    "targetSchema": "person",
    "required": true
  }
}

In the GUI, the editor is a searchable dropdown of records from the target schema.

In the API, the stored value is the target record's UUID. Use the expand query parameter to inline the full record on read:

GET /api/v1/projects/blog/schemas/post/records?expand=author

Returns:

{
  "items": [
    {
      "id": "rec_01...",
      "data": {
        "title": "...",
        "author": {
          "id": "rec_01PERSON...",
          "data": { "name": "Daniela", "avatar": "..." }
        }
      }
    }
  ]
}

One-to-many

A single reference field gives you a one-to-many relationship. One Post points at one Author; an Author can be pointed at by many Posts.

Many-to-many

For many-to-many, use array of reference:

{
  "name": "Tags",
  "slug": "tags",
  "type": "array",
  "config": { "of": { "type": "reference", "config": { "targetSchema": "tag" } } }
}

A Post can have many Tags; a Tag can apply to many Posts.

Bidirectional?

Jaina doesn't enforce inverse relationships. If you want to query "all Posts by this Author," do that on the Post schema with a filter:

GET /api/v1/projects/blog/schemas/post/records?filter[data.author]=rec_01PERSON...

Self-references

A schema can reference itself. Useful for trees (categories with parent categories) or sequences (dialogue lines that point to a next line).

{
  "name": "Next",
  "slug": "next",
  "type": "array",
  "config": { "of": { "type": "reference", "config": { "targetSchema": "dialogue_line" } } }
}

Cascading delete?

By default, deleting a record leaves dangling references in other records. We don't cascade. The trade-off is intentional: cascading deletes are usually a footgun in content systems where editorial mistakes are common.

If you want to clean up dangling references, query for them and decide what to do programmatically.