References: many-valued reference fields and typed array items, with include and a has filter
- 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
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