diff --git a/99 Daily/2026-05-15.md b/99 Daily/2026-05-15.md index 499b19d..6308568 100644 --- a/99 Daily/2026-05-15.md +++ b/99 Daily/2026-05-15.md @@ -72,3 +72,4 @@ tags: [daily] - 14:41 — session ended | `Shumiland` - 14:43 — session ended | `Shumiland` - 14:43 — session ended | `Shumiland` +- 15:29 (4min) — session ended | `ai_leed` diff --git a/raw/fields__join.md b/raw/_processed/fields__join.md similarity index 100% rename from raw/fields__join.md rename to raw/_processed/fields__join.md diff --git a/raw/fields__json.md b/raw/_processed/fields__json.md similarity index 100% rename from raw/fields__json.md rename to raw/_processed/fields__json.md diff --git a/wiki/_master-index.md b/wiki/_master-index.md index 348392c..434e164 100644 --- a/wiki/_master-index.md +++ b/wiki/_master-index.md @@ -35,7 +35,7 @@ This 3-hop pattern works for hundreds of articles without vector search. | [[wiki/reports/_index\|reports/]] | Weekly and monthly summaries — generate: `uv run python scripts/report-generator.py --weekly` | 1 | | [[wiki/infrastructure/_index\|infrastructure/]] | Server inventory: all 10 SSH hosts — optical, optical-dev, optical-prod, baic, librechat, modocmms, box-cli, aimpress, pve | 12 | | [[wiki/testing/_index\|testing/]] | Web app testing: functional, performance, security, UI types; TDD/BDD/Agile methodologies; Selenium/Cypress/Playwright/JMeter/OWASP ZAP tools | 1 | -| [[wiki/payloadcms/_index\|payloadcms/]] | Full Payload CMS reference — getting started, config, database (Postgres/MongoDB/SQLite), all 22 field types, access control, hooks, authentication (cookies, JWT, API keys, custom strategies, token data), admin UI, custom components, Lexical rich text, live preview, versions/drafts, Local/REST/GraphQL APIs, queries, plugins, jobs queue, upload, ecommerce, production deploy, TypeScript, migration guides, i18n, localization | 71 | +| [[wiki/payloadcms/_index\|payloadcms/]] | Full Payload CMS reference — getting started, config, database (Postgres/MongoDB/SQLite), all 22 field types, access control, hooks, authentication (cookies, JWT, API keys, custom strategies, token data), admin UI, custom components, Lexical rich text, live preview, versions/drafts, Local/REST/GraphQL APIs, queries, plugins, jobs queue, upload, ecommerce, production deploy, TypeScript, migration guides, i18n, localization | 72 | | [[wiki/shared-patterns/_index\|shared-patterns/]] | Oliver Agency standard library patterns: httpx, structlog, pydantic-settings, alembic — reuse before writing from scratch | 4 | | [[wiki/mistakes/_index\|mistakes/]] | Anti-patterns extracted from sessions — per-stack running lists (fastapi, react, docker, postgres, general) — injected at session start | 5 | diff --git a/wiki/payloadcms/_index.md b/wiki/payloadcms/_index.md index fdda775..aec4558 100644 --- a/wiki/payloadcms/_index.md +++ b/wiki/payloadcms/_index.md @@ -72,3 +72,4 @@ | [[wiki/payloadcms/fields-email\|Email Field]] | Email field with built-in format validation — unique index, saveToJWT, index, placeholder, autoComplete, custom components | raw/fields__email.md | 2026-05-15 | | [[wiki/payloadcms/fields-group\|Group Field]] | Nest fields under a shared property (named) or visually group without nesting (presentational); `localized` covers all nested fields at once | raw/fields__group.md | 2026-05-15 | | [[wiki/payloadcms/fields-join\|Join Field]] | Virtual bi-directional relationship field — zero-overhead reverse lookup, custom junction tables, polymorphic, query options across all APIs | raw/fields__join.md | 2026-05-15 | +| [[wiki/payloadcms/fields-json\|JSON Field]] | Stores native JSON in DB (not string) — jsonSchema validation + Monaco typeahead, local/remote schemas, vs Code Field | raw/fields__json.md | 2026-05-15 | diff --git a/wiki/payloadcms/fields-json.md b/wiki/payloadcms/fields-json.md new file mode 100644 index 0000000..b7036ef --- /dev/null +++ b/wiki/payloadcms/fields-json.md @@ -0,0 +1,126 @@ +--- +title: "JSON Field" +aliases: [payload-json-field, json-field-payload] +tags: [payloadcms, fields, json, validation, monaco] +sources: [raw/fields__json.md] +created: 2026-05-15 +updated: 2026-05-15 +--- + +The JSON Field stores raw JSON (object/array/primitive) directly in the database — unlike the [[wiki/payloadcms/fields-code|Code Field]] which stores a plain string. The Admin Panel shows a Monaco editor with full JSON syntax highlighting. + +## Config + +```ts +import type { Field } from 'payload' + +export const MyJSONField: Field = { + name: 'customerJSON', + type: 'json', + required: true, +} +``` + +## Config Options + +| Option | Description | +|--------|-------------| +| `name` * | DB property name | +| `jsonSchema` | JSON Schema for validation + editor typeahead | +| `label` | Admin Panel label (string or i18n object) | +| `unique` | DB-level unique index | +| `index` | DB index for faster queries | +| `validate` | Custom validation function (client + server) | +| `saveToJWT` | Include in JWT if field is top-level in auth collection | +| `hooks` | Field lifecycle hooks | +| `access` | Field-level access control | +| `hidden` | Hide from all APIs + Admin (still saved to DB) | +| `defaultValue` | Default value | +| `localized` | Enable per-locale content | +| `required` | Make field mandatory | +| `virtual` | Disable DB column (`true`) or link to a relationship (`string path`) | +| `typescriptSchema` | Override generated TS type with JSON schema | +| `admin.editorOptions` | Pass options to Monaco editor | + +## JSON Schema Validation + +Attach a `jsonSchema` to enable: +- **Editor typeahead** — Monaco auto-completes properties and enums in the Admin Panel +- **Save-time validation** — invalid documents cannot be saved + +### Local Schema + +```ts +{ + name: 'customerJSON', + type: 'json', + jsonSchema: { + uri: 'a://b/foo.json', // required (any unique URI) + fileMatch: ['a://b/foo.json'], // required (must match uri) + schema: { + type: 'object', + properties: { + foo: { enum: ['bar', 'foobar'] }, + }, + }, + }, +} +// {"foo": "bar"} ✓ {"foo": "other"} ✗ +``` + +### Remote Schema + +```ts +{ + name: 'customerJSON', + type: 'json', + jsonSchema: { + uri: 'https://example.com/customer.schema.json', + fileMatch: ['https://example.com/customer.schema.json'], + // schema omitted — Payload fetches it from the URL + }, +} +``` + +> **Gotcha:** If the remote URL is not publicly accessible, Payload will fail to fetch the schema. Embed the schema inline or import it from a local file. + +## JSON vs Code Field + +| | JSON Field | [[wiki/payloadcms/fields-code|Code Field]] | +|--|------------|------------| +| DB storage | Native JSON / JSONB | Plain string | +| Editor | Monaco (JSON mode) | Monaco (any language) | +| Validation | JSON Schema supported | Custom `validate` only | +| Use case | Structured data, API configs, metadata | Source code snippets, templates | + +## Custom Components + +Both Server and Client component patterns are supported. Import `JSONField` from `@payloadcms/ui`: + +```tsx +// Server +import { JSONField } from '@payloadcms/ui' +import type { JSONFieldServerComponent } from 'payload' + +export const CustomJSONFieldServer: JSONFieldServerComponent = ({ + clientField, path, schemaPath, permissions, +}) => + +// Client +'use client' +import type { JSONFieldClientComponent } from 'payload' +export const CustomJSONFieldClient: JSONFieldClientComponent = (props) => +``` + +## Key Takeaways + +- `type: 'json'` stores actual JSON in the DB (not a stringified value) — use this when you need to query or index the JSON contents later +- `jsonSchema` unlocks both Monaco typeahead in the Admin Panel and automatic save-time validation — add it for any structured config or metadata field +- For remote schemas: if the URL is not public, embed the schema inline to avoid fetch failures +- `admin.editorOptions` accepts the full Monaco `EditorOptions` object for advanced editor configuration +- Use [[wiki/payloadcms/fields-code|Code Field]] instead when storing source code, templates, or any non-JSON string that just needs syntax highlighting + +## Sources + +- [Payload CMS — JSON Field docs](https://payloadcms.com/docs/fields/json) +- Raw file: `raw/fields__json.md`