BaryoDev / BaryoDev/barakoCMS

References: many-valued reference fields and typed array items, with include and a has filter

Open
#928 0 comments 0 reactions 0 assignees View on GitHub
core design
Dominant language
C#
Stars
6
Forks
7
Avg merge
4h 42m
Merged PRs (30d)
307

Description

A `reference` field holds one id (`barakoCMS/Core/Validation/FieldTypeRegistry.cs:87`). An `array` field has no item type and accepts any JSON array (`FieldTypeRegistry.cs:204-209`). `include` resolves only single `reference` fields (`barakoCMS/Features/Public/Endpoints.cs:165-176`). So the blueprints model relations as untyped arrays: `Tags` in `barakoCMS/Blueprints/blog.json:20`, `Speakers` in `events.json:22`, `RelatedArticles` in `docs.json:20`, `Gallery` in `portfolio.json:19`. Filtering them uses `contains`, an ILIKE over the value's JSON text (`barakoCMS/Features/Public/DeliveryQuery.cs:248-249`), so a filter for part of an id matches any array holding an id with that substring.

### Why it is too specific

One-to-one covers "a post has an author". A school's class has many students, a clinic visit has several procedures, an event has several speakers. Today those are arrays of ids with no check that the targets exist, no include on delivery, and a filter that can match by accident.

### The general concept

`multiple` on `reference`, the way #820 adds it to `choice`: a list of ids, each checked to exist and to be the declared target type. An item type on `array` (`string`, `url`, `reference` and so on). `include` resolves many-valued references under the same caps. A `has` filter operator for list fields that matches one exact element with a jsonb containment check instead of text.

### Where it lives

Core: field type registry, content validator, delivery query and include.

### Compatibility

Released. `multiple` and an item type are optional, and an `array` field with no item type accepts what it accepts today. `contains` keeps its meaning and `has` is new. Blueprints can switch to typed fields for new applies; types already applied in a tenant are stored data and stay as they are. Additive on the HTTP surface.

### Done when

- A `reference` field with `multiple` refuses a list holding an id of the wrong type, with a test that fails before the change.
- `include=Speakers` returns the referenced entries for a many-valued field.
- `filter[Tags][has]=` matches only entries holding that exact id, tested with an id whose substring would match another entry under `contains`.

Found in the architecture sweep of 15 September 2026.

Contributor guide

Open the contributing guide

Research direction

Read the field definitions in barakoCMS/Core/Validation/FieldTypeRegistry.cs and trace validation, then inspect delivery handling in barakoCMS/Features/Public/Endpoints.cs and DeliveryQuery.cs. Use the existing multiple behavior from #820 as a reference point. Done means typed multiple references validate target types, include resolves every referenced entry, and has matches one exact JSONB array element as specified.

Written by the indexing model from the issue text.

Assessment

Tech stack
csharp, postgresql
Domain
api, backend, databases
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
62/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.