BaryoDev / BaryoDev/barakoCMS

Site: json fields carry a schema checked on write, and Mode is a choice

Open
#924 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

The site singleton keeps its structured parts (colours, fonts, header links, footer columns and more) in `json` fields, and the API checks only that each holds valid JSON: `docs/site-settings.md:29-32`, and `barakoCMS/Core/Validation/FieldTypeRegistry.cs:77` accepts any object or array. The real shapes live in barakoBrew's Site and Theme screens, and barakoPress drops what it cannot read. PR #860 adds `Mode` as a free `string` field in `barakoCMS/Blueprints/site.json`, so `Holdng` is a valid mode.

### Why it is too specific

The contract holds only while barakoBrew is the writer. A script, the CLI (#345), an MCP tool or an agent setting up a school's site writes `HeaderLinks` in a slightly wrong shape, gets a 200, and the header silently disappears. Every new client repeats barakoBrew's checks or skips them.

### The general concept

A `json` field may carry a JSON Schema on its field definition. The API validates writes against it and names the path that failed. The site blueprint ships schemas for its json fields. `Mode` becomes a `choice` field (#803, #820) with `Live` and `Holding`, so the API refuses a mode it does not know. barakoBrew renders the screens from the schema (BaryoDev/barakoBrew#160).

### Where it lives

Core: the field definition, the json field validator and the site blueprint.

### Compatibility

The site blueprint is released. `Mode` is not merged yet, so making it a choice before #860 ships costs nothing. A schema on a field is optional. Enforcing the blueprint's schemas on existing json fields rejects writes that are accepted today, which tightens request validation: it moves `ApiContract.Version` and is called out in the pull request. Stored values that fail a schema keep reading; only new writes are checked.

### Done when

- Writing `HeaderLinks` as an array of strings is a 400 naming the failing path, with a test that fails before the change.
- `Mode: "Holdng"` is refused, and `Live` and `Holding` are accepted.
- A json field with no schema behaves as today.

Relates BaryoDev/barakoPress#53.

Found in the architecture sweep of 15 September 2026.

Contributor guide

Open the contributing guide

Research direction

Start with the field validation logic in barakoCMS/Core/Validation/FieldTypeRegistry.cs:77 and the site blueprint at barakoCMS/Blueprints/site.json; review the related contract details in docs/site-settings.md:29-32. Trace how JSON field writes are validated and add focused tests for invalid HeaderLinks, the Mode choices, and an unschematized JSON field. Done means invalid paths receive 400 responses while valid values and existing reads remain supported.

Written by the indexing model from the issue text.

Assessment

Tech stack
csharp
Domain
api, backend-api-design
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.