@sanity/workflow-engine 0.13.0 → 0.14.0

package/README.md

@@ -13,6 +13,36 @@ effects for runtimes to drain.
 npm install @sanity/workflow-engine
 ```
 
+## Fields vs Sanity schema fields
+
+A workflow **field** is the engine's state primitive: a typed value a workflow
+instance carries — an assignee, a decision, a due date, a reference to the
+document under review. Fields are declared in `fields: [...]` at workflow,
+stage, or activity scope and live on the workflow **instance** document. They
+are not Sanity schema fields: they never touch your content documents' shape.
+
+The authoring DSL deliberately borrows Sanity's schema idiom, so
+`@sanity/workflow-engine/define` exports its own `defineField`. A Studio file
+that also imports `defineField` from `sanity` should alias one of them:
+
+```ts
+import {defineField as defineWorkflowField} from '@sanity/workflow-engine/define'
+```
+
+The `fields` key itself appears at four nesting levels, meaning something
+different at each — read it by where it sits:
+
+1. **Declared field entries** — on a definition's workflow / stage / activity
+   nodes: the typed state that scope carries.
+2. **Sub-field shapes** — inside an `object`- or `array`-kind field entry:
+   lightweight `{type, name}` shapes for the value's structure, mirroring
+   Sanity's `object.fields` / `array.of`.
+3. **Object value expressions** — a `{type: 'object', fields: {...}}` value
+   expression in an op or `initialValue`: one expression per key of the
+   computed object value.
+4. **Resolved runtime values** — `fields` on a workflow instance document: the
+   declared entries with their current values, written by ops and edits.
+
 ## License
 
 [MIT](./LICENSE)