User guide

FieldWeft visualizes field-level data flow. It shows which field in one data source feeds which field in another entity. Entities appear as table-like nodes, with indentation for deeply nested fields.

A typical graph can follow a backend flow from a Kafka event through API and database lookups to an outbound request. The final entity is a selected combination of source fields, not necessarily their superset. Edges record which source fills each destination and whether the value is preserved or transformed.

• Field-to-field mappings connect EntityA.fieldX → EntityB.fieldY. Only leaf field rows have source and destination handles. Containers such as object and object[] are mapped through their leaves. Handle IDs use document-wide stable field IDs, while a path such as address.city is derived from the current tree for display.
• Mapping styles use a solid keep line when a value is preserved and a dotted transform line when it is changed, such as by trimming or formatting.
• Entities are table nodes with a header and field rows. Kinds include event, api, db, and other.
• Process nodes are black boxes that accept inputs and produce outputs. Their left-side input fields only receive values, their right-side output fields only emit values, and no internal mapping is drawn.

• Left sidebar — one graph per page, with actions to add, rename, delete, and switch pages.
• Central canvas — an interactive React Flow canvas for arranging nodes and dragging field handles to create mappings.
• Bottom-left view settings — open View settings to show or hide the Input variants panel, Visibility panel, and Edges between nodes, or turn Snap to grid on or off. The browser remembers these choices separately for each page and read-only sample.
• Edges between nodes — hidden by default. When shown, explicit node relations use long dashed lines with optional labels, while read-only flow derived from field mappings uses denser dashed lines and Field mappings ×N. Both can appear between the same nodes. Only explicit relations can be selected, edited, or saved in JSON; they do not create field mappings or extend field trace. Hiding these edges preserves their data and analysis, and disables Node relation in New edge.
• Snap to grid — on by default. When on, dragging and arrow keys keep node and boundary positions on a 10 px grid; Shift moves 40 px. In an editing page, turning it on or opening the page with it on can realign and autosave positions. This alignment cannot be undone. In a read-only sample it changes only the current view, even after refresh or Reset view. Turning it off restores free dragging and 5 px arrow-key movement, or 20 px with Shift, without moving nodes by itself.
• View setting defaults — View setting defaults at the bottom of the left sidebar, also available from the collapsed rail, sets how new editing pages start. Every page added to this browser, including copies started from a sample, share link, or backup, copies these four values when it is created. Existing pages keep their own settings unless you choose Also apply to existing pages, which replaces them once and does not follow later changes. Read-only samples are not affected.
• Top-right visibility panel — hide or show individual nodes without removing their data or positions.
• Bottom-right actions — create entities, processes, and boundaries, then choose keep, transform, or node relation from New edge.
• Right overview — a collapsed-by-default overlay with the page name, last-saved time, entity, process, relation, mapping, and field counts, input variants, and the Code tool for editing the complete graph as JSON.

Drag from the right source handle of one leaf field to the left destination handle of another. Choose the mapping kind from New edge before drawing.

Select an existing edge to open its context menu. You can edit its label, description, tags, and metadata; switch between keep and transform; or delete it.

Create nodes with the bottom-right entity and process actions. Edit an existing node in a modal from the edit action in its header.

• Add, edit, or remove fields alongside the node's name and kind. Nested object fields can be added or collapsed within the FieldWeft depth limit of 64.
• The shared description, tags, and metadata section starts collapsed. Edit field annotations through each row's annotation action.
• Drag the handle at a row's left edge to reorder it. Reordering is limited to siblings under the same parent.
• Renaming a field preserves mappings and conditions that refer to its stable ID. Removing it or converting it to an object also removes edges attached to that field.
• The two-step delete action at the modal's lower left removes the node and its connected edges.

Entities, processes, boundaries, every field, and mappings can carry the same optional annotations. They supplement names and labels with durable meaning, classification, and external identifiers.

• description is plain text, tags is a list of exact strings, and meta is a shallow map whose values are string | number | boolean | null.
• Use the shared modal section for entities and processes, row actions for fields, the boundary header edit action, and edge context menus for mappings.
• Node and field descriptions appear through ⓘ; tags appear as chips. The node visibility panel searches names, descriptions, and tags, but not metadata values.
• Annotations participate in semantic diff, autosave, backup, code JSON, and share URLs. Do not store per-run timestamps, request IDs, passwords, tokens, or real customer information.

Boundaries group related entities and processes into a domain, system, external integration, or security area. Create an empty boundary, drag free nodes inside, and drop them when the ready indicator appears.

• A 600 ms progress indicator distinguishes an intended drop from a node merely passing across a boundary.
• Moving a boundary moves its members. Moving or editing a member resizes the boundary to fit. The header's · N shows its member count and is hidden when empty.
• With Snap to grid on, automatic boundary fitting expands outward to the nearest grid lines so it never clips its members. Background dots appear every 20 px and mark every other snap point.
• Dragging a member reveals an eject zone at the bottom. Drop it after the ready state or use the member header action to remove it. Deleting a boundary preserves its members and edges.
• Edit the name, fixed color token, kind, description, tags, and metadata from the boundary header. Kind is shown by an icon, description through ⓘ, and color remains independent of kind. Double-click the label for a quick rename.
• Boundary annotations, membership, position, and size are included in autosave, backup, code JSON, and share URLs. Nested boundaries are not supported.

Input variants are an entity-only concept. A discriminator field determines whether other fields in the same entity exist—for example, order details that appear for type=CREATED but not type=CANCELED.

• A discriminator field can define selectable values, and an entity can have several discriminators. JSON uses discriminator: { values: [...] }. Renaming a value updates every when condition that refers to it.
• A field with when exists conditionally. Clauses combine with AND, while values within a clause combine with OR. Condition keys are stable discriminator field IDs in the same entity, not names or paths.
• Choose values in the top-left selector or select a canvas badge to switch variants. Fields absent from the variant remain visible but dimmed.
• Configure variants from the branch action on an entity modal's field row. Processes do not support input variants.

• Collapse objects by selecting an object field. Edges to its hidden descendants roll up to the container as dotted lines and restore when expanded.
• Hover highlighting previews connected edges and fields across process black boxes. It follows the same rules as click tracing and excludes hidden nodes.

Hover provides a temporary preview. Selecting a leaf field, or the descendant-trace action on an object row, keeps analysis results open in the right overlay.

• Upstream shows sources, Downstream shows affected fields and a summary, and Paths shows complete paths with intermediate steps.
• Filter by node name, field path, and maximum distance; Paths also supports direction. Filters change visible and copied results, while the full impact summary and Markdown report keep the original analysis.
• Paths mark keep or transform behavior, transform descriptions, conditional variants, and process traversal. A process black box treats every input as potentially affecting every output, and the internal hop does not add mapping distance.
• Select a result to move to its node and briefly highlight the field. Copy affected fields and paths, or download downstream impact as Markdown with the MD action.
• The node-header impact action analyzes an entity or process using both explicit node relations and mapping-derived flow, with the source identified in results. Field trace never crosses explicit node relations. Hidden nodes are excluded. Close analysis with the panel action, a blank-canvas click, Esc, or by selecting the active field again.

• Autosave writes graph edits to IndexedDB after a debounce and remembers the last-opened page for your next visit. The overview shows the most recent save time.
• URL sharing copies a #g=d1.… fragment URL containing the current page's complete graph using native DEFLATE and base64url. Stable IDs, exact positions, collapsed state, annotations, boundary membership and size, node relations, and field mappings open in a read-only view at /share (or /ko/share for Korean UI). Viewing does not save pages, documents, or view settings. Import as a new page copies the shared original through /app/new in the same locale, preserving existing pages. Older /app/new#g=… links still import directly. Page names, other pages, pan and zoom, selection, filters, trace state, and save history are omitted. A successfully imported fragment is removed only in the app; the read-only view keeps it for reloads and bookmarks. FieldWeft warns when a link is long enough that it may be truncated in transit. Use JSON backup if the link exceeds the publishing limit or compression is unavailable.
• Backup exports every page and page name, unlike a share link's single page. Import can merge or replace and revalidates each document as FieldWeft v1. One invalid page stops the whole import rather than being skipped. Keep a backup for important work and long graphs.

In the read-only view, moving nodes and boundaries, hiding nodes, folding fields, tracing, and choosing input variants are temporary. Reset to original restores the original layout and folds, clears exploration and the right panel, resets all four view settings to factory defaults, and fits the graph to the current canvas. Sample resets continue to keep their saved view settings.

Embed the copied link in a wiki iframe. A sandbox requires allow-same-origin allow-scripts allow-popups allow-popups-to-escape-sandbox: the view must retain its origin to load modules, and importing must open an unrestricted app tab that can save. The view works without browser storage. The wiki must permit these permissions and popups, and its iframe policy and the host proxy’s frame headers must allow embedding. Import as a new page opens a new tab from an iframe. No display options are added to the URL.

Expand the right panel and open Code below the overview to edit the whole graph as JSON. Changes apply only when you select the apply action. Before applying, FieldWeft validates structure, kinds, references, shared annotations, and resource limits and reports each error for correction.

You can also ask an AI model to generate the complete JSON instead of building every node manually. Copy the full rules with Copy spec, paste them into the model, and describe the flow you need. The same specification is available at /code-spec.md. Guidance for safe edits, external-model conversion, and sharing is available in the authoring guide, adapter guide, and sharing guide. These unprefixed contract resources are the normative English editions. Non-normative Korean commentary editions are published separately under /ko and do not replace them.

Top-level format: "fieldweft", version: 1, and all five arrays are required even when empty:

{
  "format": "fieldweft",
  "version": 1,
  "entities": [
    {
      "id": "orderEvent",
      "name": "OrderEvent",
      "kind": "event",
      "description": "주문이 접수됐을 때 발행되는 이벤트",
      "tags": ["critical", "pii"],
      "meta": { "com.example.owner": "orders", "reviewed": true },
      "fields": [
        {
          "id": "order_id_aB3kP9xQ2", "name": "orderId", "type": "string",
          "tags": ["identifier"], "pk": true
        },
        {
          "id": "items_D6fG1hJ4k", "name": "items", "type": "object", "array": true,
          "children": [
            { "id": "product_id_C4mN7rS1v", "name": "productId", "type": "string" }
          ]
        }
      ]
    }
  ],
  "processes": [
    {
      "id": "riskApi", "name": "RiskApi", "kind": "api",
      "inputs": [
        { "id": "risk_order_id_R8tY2uI5o", "name": "orderId", "type": "string" }
      ],
      "outputs": [
        { "id": "risk_score_L3pQ6wE9r", "name": "riskScore", "type": "number" }
      ]
    }
  ],
  "boundaries": [
    {
      "id": "riskZone", "name": "위험도 평가",
      "color": "purple", "kind": "system",
      "description": "위험도 평가 흐름", "members": ["riskApi"]
    }
  ],
  "nodeRelations": [
    {
      "id": "order_to_risk",
      "sourceNodeId": "orderEvent",
      "targetNodeId": "riskApi",
      "label": "위험도 조회",
      "meta": { "com.example.source": "catalog" }
    }
  ],
  "mappings": [
    {
      "id": "p1",
      "sourceFieldId": "order_id_aB3kP9xQ2",
      "targetFieldId": "risk_order_id_R8tY2uI5o"
    }
  ]
}

Keep these rules in mind when writing by hand or reviewing AI output:

• Node id values may contain ASCII letters, numbers, _, and - and must be unique across all nodes. Preserve an ID when changing a name, kind, or position. If an ID changes or a node is removed, update boundary members and node relation endpoints in the same edit.
• Every entity field and process input or output needs a document-wide unique id. New IDs should follow <name slug>_<9-character base64url suffix>. Preserve IDs across rename, reorder, move, and property edits; issue a new ID only for a new field or clone.
• Entities, processes, boundaries, all fields, node relations, and mappings can carry description, tags, and meta directly. Do not use an annotations wrapper. Metadata values are string | number | boolean | null, not nested objects or arrays, and explicit null is preserved.
• String lengths count Unicode code points. IDs, names, and discriminator or when values allow 256 characters; relation and mapping labels 512; descriptions and metadata strings 4,096. Each object allows 32 tags and 32 metadata entries. Tags are 1..64 characters, metadata keys 1..128, and discriminator and when value arrays contain at most 256 values.
• Entity fields can nest through object.children. Process inputs and outputs correspond one-to-one with canvas handles and must remain flat, so they cannot have children.
• Entity and process kind is one of event | api | db | other. Field type is one of uuid | string | number | boolean | timestamp | object | json.
• Boundary color is one of blue | green | purple | rose | slate, and kind is one of domain | system | external | security | other. Members must reference existing entity or process IDs, and a node belongs to at most one boundary.
• nodeRelations express explicit node lineage between entity or process IDs. Boundary endpoints and self-relations are invalid, and a node relation neither replaces nor implies a field mapping.
• sourceFieldId and targetFieldId must reference real leaf-field stable IDs; object containers cannot be mapped. Node and current path are derived from the ID index. Process inputs can only be targets and outputs only sources.
• Input variants are entity-only. Use discriminator: { values: [...] } on a discriminator and when: { "<discriminatorFieldId>": [...] } on a conditional field. The key must be a discriminator stable ID in the same entity. Mappings and process fields cannot carry when.
• collapsed contains only object field IDs from its entity. If a field ID is changed, removed, or cloned, update every reference in when, mappings, and collapsed state together.
• position is optional and omitted nodes are laid out automatically. Boundary size is also optional and adjusts to its members.
• Shared limits are 5,000 nodes and boundaries, 100,000 fields, a field tree depth of 64, and 20,000 combined node relations and mappings. A document with invalid markers, enums, references, or exceeded limits is rejected as a whole. Canonical documents allow 8 MiB UTF-8, raw JSON input 16 MiB, and backup JSON 64 MiB.