Nova Json Wrapper Laravel Package

Technical Evaluation

Architecture fit The package is a Nova field composition wrapper: it nests child Nova fields and, instead of persisting each to its own column, serializes their values into a single JSON attribute on the parent model. Architecturally it hooks the Nova Field lifecycle (fill, resolve, hydrate, fillAttributeFromRequest) and proxies the inner fields' state.

• Good fit: cohesive documents that are almost always read/written as a unit — settings blobs, metadata, address blocks, per-entity preferences, third-party payload mirrors.
• Poor fit: any attribute that needs SQL WHERE, ORDER BY, aggregates, unique constraints, foreign keys, or Nova filtering/sorting. Once a field is inside the wrapper it becomes opaque to the query builder and to Nova's searchable/sortable field traits.
• Boundary rule for the team: JSON wrapper is a presentation and storage convenience, not a query surface. If the business will ever report on it, it belongs in a real column.

Integration feasibility

• Mechanically trivial: composer require + register the field in a Nova resource. No service provider gymnastics, no infra change.
• Real gate is the version matrix. Last release is 2021-02-11, which places it in the Nova 3.x era. Nova 4 (2022) and Nova 5 (2024) changed field serialization and asset/script handling. Treat Nova 4/5 support as unproven until spiked, not as a documented capability.
• 0 dependents and 12 stars means essentially zero production evidence. This is a code sample, not a battle-tested dependency. The MIT license is the saving grace: forking is legally and practically cheap.

Technical risk (ranked)

1. Abandonment / upgrade lock — a Nova major bump can hard-fail resource pages with no upstream fix path.
2. Validation semantics — unless the wrapper transparently proxies rules(), required, and sometimes to inner fields, you get a silent validation bypass on writes. This is the highest-severity issue because it fails open.
3. Write path ambiguity — full replacement vs. merge on PATCH. Partial updates can null out sibling keys or clobber concurrent edits.
4. Non-scalar inner fields — file uploads, relationships, and dependsOn conditionals inside the wrapper are where composition wrappers historically break.
5. Query opacity — no native search/filter/sort; every reporting need becomes a generated-column or app-layer workaround.
6. Data migration — backfilling existing columns into JSON is straightforward but one-way-ish; the rollback story needs designing, not assuming.

Key questions to answer before committing

• Which exact Nova and Laravel majors are in the support matrix, and has anyone on the team run the spike?
• Does the wrapper propagate rules()/required/nullable to child fields? Prove it with a failing-request test.
• Is the persist operation a merge or a replace? What happens on two simultaneous editors?
• How are File, BelongsTo, and dependsOn children handled?
• Who owns the JSON schema contract, and is it versioned?
• If upstream is dead, do we fork (MIT permits) into a private namespace, and who staffs that?

Integration Approach

Stack fit Assumes Laravel + a licensed Nova install. It is a pure admin-panel concern — it does not change API shape, model events, or queue behavior, which keeps blast radius small. That is the main argument in its favor: the failure modes are confined to Nova CRUD.

Migration path

1. Add a nullable json column; do not drop legacy columns in the same deploy.
2. Introduce the wrapper field with children mapped to the new attribute, behind a resource-level feature flag or a separate *Beta resource.
3. Backfill with a one-off artisan command (idempotent, chunked, logged) reading legacy columns into the JSON shape.
4. Run dual-write or dual-read verification for one release cycle; diff JSON against legacy columns.
5. Swap reads to JSON, then drop legacy columns in a later migration after a rollback window.

Compatibility

• Pin the package exactly in composer.json; add a CI check that a Nova/Laravel bump cannot silently upgrade it.
• Decide fork-vs-consume up front. Given the release history, the realistic plan is a vendored fork under a private namespace with an internal owner — the license makes this a one-afternoon task, and it converts an unmaintained dependency into owned code.
• Confirm database engine: PostgreSQL jsonb with GIN indexes is materially better than MySQL JSON here, which needs generated columns for any indexed access.

Sequencing (roughly 3–4 weeks, one developer)

• Week 1: spike against the actual Nova version; validation and partial-update tests are the exit criteria, not a demo form that saves.
• Week 2: schema contract + migration/backfill script + feature flag plumbing.
• Week 3: resource swap, dual-read verification, runbook.
• Week 4: rollback rehearsal, docs, decommission legacy columns.

Decision recommendation: adopt only for a bounded, low-cardinality document on a non-critical admin surface, and only with a forked copy. Do not use it for anything the business reports on, and do not use it as a shortcut to avoid schema design — that debt compounds at the reporting layer, not in Nova.

Operational Impact

Maintenance Treat as unmaintained. Last release 2021-02-11, 12 stars, 0 dependents, no evidence of a maintainer response SLA. Plan for: annual review against Nova majors, a named internal owner, and a fork you can patch in hours rather than waiting on upstream. Cost is low but non-zero and permanent — budget it explicitly or the first Nova upgrade becomes an unplanned outage.

Support No vendor, no meaningful community mass, no issue-tracker signal you can rely on. Support is entirely internal: runbook, owner, and a documented fork diff so future maintainers know what was changed and why.

Scaling

• Row-level: JSON blobs inflate row width; keep them small and bounded. Unbounded growth (activity logs, history) does not belong here.
• Query-level: MySQL JSON needs generated columns plus indexes for any filtered path — meaning the "flexible schema" benefit evaporates the moment you need to query it. PostgreSQL jsonb + GIN is the viable path.
• Concurrency: merge-on-write wrappers are read-modify-write and therefore lossy under concurrent editors. If multi-user editing is in scope, you need optimistic locking (updated_at check) or you will silently lose data.

Failure modes to monitor

1. Silent data loss on partial update/merge — add a test that submits a subset of keys.
2. Validation bypass — inner-field rules not enforced; fails open, so test with deliberately invalid payloads.
3. Orphaned file uploads when a File child is removed inside the wrapper.
4. Nova major upgrade → fatal error rendering the resource; error pages, not graceful degradation.
5. JSON shape drift across releases with no schema version key → unreadable records in the Nova UI.
6. Index drift when generated columns fall out of sync with the JSON contract.

Ramp-up Low for anyone fluent in Nova (a few hours to a working field). The genuinely non-obvious part is the field lifecycle and the fork-ownership model — budget 2–3 days for one engineer to become the internal authority, and write it down. Broader team onboarding is a half-day with a working example.

Net TPM read: small blast radius, trivially reversible, but a dead upstream and a validation story that must be proven rather than assumed. Approve as a scoped, forked, feature-flagged experiment on a non-reporting admin surface; reject as a general-purpose schema-shortcut across core entities.