Skip to content

fix: core resource spec drift (evaluation, workflow, credential, data-table, project, variable, folder) - #33

Merged
SomeoneWithOptions merged 7 commits into
mainfrom
fix/core-resources
Oct 22, 2026
Merged

SomeoneWithOptions merged 7 commits into
mainfrom
fix/core-resources

Conversation

@SomeoneWithOptions

Copy link
Copy Markdown
Owner

Spec drift fixes for core resources against n8n Public API 1.1.1 (branch 08 of the spec-drift plan). Each item is its own commit, so the PR can be split (1–2 fix vs 3–6 drift) if review stalls.

Changes

  1. evaluation — evaluation case list failed to decode any numeric executionId (spec: nullable integer; client had *string). Now json.Number, which also accepts numeric strings from older instances.
  2. workflow
    • create keeps description (was filtered and reported as dropped; also lost on workflow copy)
    • parentFolderId: null is sent (null = move to project root)
    • settings with the read-only "DEFAULT" marker are dropped and reported as settings.NAME; null settings is sent as {} instead of failing validation
    • read-only node createdAt/updatedAt stripped and reported
    • new workflow list --include-parent-folder (FOLDER column, parentFolder kept in JSON; stderr note when the instance ignores the parameter)
    • APIError keeps reason, versionId, workflowReviewRequestId; update 403 names the saved draft, update/publish/copy 409 name the blocking review instead of guessing review vs webhook conflict (touches errors.go, after fix(cli): report license denials separately from missing scopes #26)
  3. credential — create accepts description (≤512) and custom id (1–16, [a-zA-Z0-9_-]); update accepts description (null/blank clears); reads keep description and usageScope. No Extra map on purpose: unknown fields stay discarded so an unexpected secret-bearing field cannot reach output.
  4. data-table — json column type refused locally ("use string"); table --sort-by validated against the closed enum; column names (create, add, rename, filters) validated against ^[a-zA-Z][a-zA-Z0-9_]*$, ≤63.
  5. project / variable — Project keeps icon, description, customTelemetryTags, creatorId, timestamps, create's role/scopes, plus Extra (shared by VariableProject and folder homeProject). project create gains --id, --description, --icon TYPE:VALUE, --icon-color, --telemetry-tag KEY=VALUE. Variable key/value/projectId limits validated (create key may not start with a digit; update may). Update help no longer claims omitting --project-id moves to global scope (spec is silent; no --global added).
  6. folder — name ≤128, parentFolderId (create) / transferToFolderId ≤36; help documents --parent-folder-id 0 = move to project root.

New helpers: internal/n8n/nullable.go (Nullable[T] with omitzero for null-vs-omitted fields), internal/n8n/extra.go (unknown-field preservation).

API changes: Client.CreateProject now takes CreateProjectRequest; n8n.DataTableCreateColumnTypes removed (integration test updated).

Spec-derived vs live-verified

  • Live (admin context): workflow list --include-parent-folder — target ignores the parameter (predates it), hence the stderr note; workflow get shape (no parentFolderId, no DEFAULT settings seen); data-table IDs are 16-char alphanumeric.
  • Spec-derived only: evaluation (no test runs on the instance), workflow write normalization and 403/409 details, credentials, data-table validation, projects and variables (403 license on target), folder limits and "0" = root.

Skipped deliberately: data-table ID pattern validation (target agrees, but heavy test churn for little gain); fileId/hasHeaders/csvColumnName on table create (fileId unusable with an API key).

Test plan

  • make docs && make check
  • go test -shuffle=on -count=1 ./internal/n8n ./internal/cli ./internal/coverage with openapi.upstream.yml present
  • client httptest + CLI in-process tests per item; round-trip fixtures for workflow (DEFAULT settings, null parentFolderId), credential (description/id), project read fields

🤖 Generated with Claude Code

SomeoneWithOptions and others added 7 commits October 21, 2026 23:42
The public API types test-case executionId as a nullable integer, but the
client decoded it into *string, so any numeric id failed with an
UnmarshalTypeError. Decode into json.Number, which also accepts the numeric
strings older instances sent.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
- create accepts description; it was filtered out and reported as dropped,
  also losing it on 'workflow copy'
- parentFolderId may be null on write (null = move to the project root)
- settings set to "DEFAULT" (read-only marker) are dropped and reported
  as settings.NAME; a null settings is sent as {} instead of failing
  validation
- read-only node createdAt/updatedAt are stripped and reported
- workflow list --include-parent-folder adds a FOLDER column and keeps
  parentFolder in JSON

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
The API adds reason, versionId and workflowReviewRequestId to the 403 a
republishing update answers and to the 409 a blocked publish answers; the
error decoder dropped them. APIError now keeps them, update names the draft
it saved and the review that blocked republication, and publish/copy name
the review instead of guessing between a review and a webhook conflict.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Create now accepts description (at most 512 characters) and a
caller-chosen id (1-16 of [a-zA-Z0-9_-]), validated locally; update
accepts description, where null or blank clears it. Reads keep
description (absent vs null preserved) and the usageScope delete
returns. Unknown response fields are still discarded rather than kept in
an Extra map, so an unexpected secret-bearing field cannot reach output.

Adds n8n.Nullable for write fields where null differs from omission.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
- column type json is gone from the contract: refuse it locally with a
  message pointing at string, for table and column creation
- table list --sort-by is a closed enum (name|createdAt|updatedAt|size x
  asc|desc); row sort keeps the columnName:asc|desc shape check
- column names (create, add, rename, row filters) must match
  ^[a-zA-Z][a-zA-Z0-9_]*$ and be at most 63 characters

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
- Project gains icon, description, customTelemetryTags, creatorId,
  timestamps, and the role/scopes create returns, plus Extra for unknown
  fields; nullable fields keep absent vs null. VariableProject and folder
  homeProject share it.
- project create sends --id, --description, --icon TYPE:VALUE,
  --icon-color and --telemetry-tag KEY=VALUE; CreateProject takes a
  CreateProjectRequest. Name (255), ID (36), description (512) validated.
- variable key/value/projectId limits validated locally (create key may
  not start with a digit; update allows it). Update help no longer claims
  omitting --project-id moves the variable to global scope: the contract
  does not say.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Folder names are at most 128 characters; parentFolderId on create and
transferToFolderId on delete at most 36. The contract now documents
parentFolderId "0" on update as moving the folder to the project root,
so the help no longer says that is impossible.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@SomeoneWithOptions
SomeoneWithOptions merged commit 2f1b94a into main Oct 22, 2026
4 checks passed
@SomeoneWithOptions
SomeoneWithOptions deleted the fix/core-resources branch October 22, 2026 11:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant