JSON Patch

Overview

All entity updates in Formation use JSON Patch (RFC 6902). The frontend’s buildPatch() function generates patch operations by comparing original and updated entity states.

Patch Operations

A patch document is an array of operations:

[
  { "op": "replace", "path": "/Name", "value": "New Name" },
  { "op": "replace", "path": "/Address/Id", "value": "AD03KwA" }
]

Nested Object Transformation

The backend PatchRewriter automatically transforms nested object references to foreign key updates:

Patch Path	Transformed To
/Address/Id	/AddressId
/CompanyType/CompanyTypeCode	/CompanyTypeId
/DevelopmentStatus/Id	/DevelopmentStatusId

This means the frontend always works with encoded IDs in nested objects, while the backend handles the FK mapping.

Frontend Usage

import { calculateChanges } from '$lib/services/entity-operations.svelte'

const changes = calculateChanges(original, edited, {
  ignore: ['/NavigationProps', '/Collections']
})

// Send to API
await fetch(`/api/Schemes('${id}')`, {
  method: 'PATCH',
  headers: { 'Content-Type': 'application/json-patch+json' },
  body: JSON.stringify(changes)
})

Change Detection

The calculateChanges() function compares two entity snapshots and returns only the fields that differ. Use the ignore option to exclude navigation properties or collections from comparison.