docs(api): TRA-789 BB67 — Errors catalog correction + q parameter docs#183
Merged
Conversation
added 6 commits
May 18, 2026 18:08
… catalog correction
read_only field list trimmed to truly server-managed fields and asset
location_* (scan-derived). external_key, tags, and parent_external_key
no longer appear: external_key and tags PATCH divergence emits
code: invalid_context per the BB63 split; parent_external_key is fully
writable on PATCH /locations/{id} for re-parenting.
invalid_context entry expanded with the second semantic category
(field handed off to a dedicated write subresource on PATCH), listing
external_key (via /rename) and tags (via /tags POST + DELETE).
…ites section code split "Validator behavior on writes" section previously claimed a uniform code: read_only across all non-settable PATCH fields, listed parent_external_key among them, and pointed the rename/tags-subresource hints at the read_only code. All three drift items: code is now split (read_only for server-managed + asset location_*; invalid_context for external_key + tags); parent_external_key called out as fully writable on PATCH for re-parenting.
…ion code split PATCH content-type section claimed a uniform code: read_only with /rename and /tags hints, and lumped parent_external_key into the natural-key reference enumeration. Split the code per BB63 (read_only for server-managed and asset location_*; invalid_context for external_key + tags). Call out parent_external_key as fully writable on PATCH for re-parenting.
…otes light-touch code split resource-identifiers.md (UpdateLocationRequest / UpdateAssetRequest bullets): replace stale 400 read_only mentions with the BB63 code split on external_key + tags (invalid_context) vs scan-derived asset location_* (read_only). design-notes.md (updated_at concurrency token): clarify the accept-if-matches rule covers fields not directly settable on PATCH (rather than "read-only fields"), with a parenthetical pointing at the code split.
…alue semantics Existing substring-search section had the per-endpoint matched-fields matrix but didn't call out the reports asymmetry (no description, no location fields — searches asset's identifying fields only) or the single-value runtime behavior (only first ?q= wins; multi-value not supported by the spec).
|
🚀 Preview Deployment Update ✅ This PR has been successfully merged into the preview branch. The preview environment will update shortly at: https://docs.preview.trakrf.id |
Deploying docs with
|
| Latest commit: |
5003eab
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://7d810bf2.docs-4n7.pages.dev |
| Branch Preview URL: | https://preview.docs-4n7.pages.dev |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Docs-only fixes from the BB67 multi-org parallel triage. No platform PR — the committed customer-facing spec already encodes the post-BB63 / BB66 contract; only the prose is being aligned.
docs/api/errors.mdread_onlycatalog entry no longer claimsexternal_keyandtagsPATCH divergence emitscode: read_only(they emitcode: invalid_contextper the BB63 split).invalid_contextentry expanded to document the second semantic category (field handed off to a dedicated write subresource onPATCH).parent_external_keyremoved from the read-only field list on the Errors page (it is fully writable onPATCH /locations/{id}for re-parenting). Cross-reference added.docs/api/pagination-filtering-sorting.mdqparameter section gains an explicit asymmetry callout (reports endpoint matches asset-side identifying fields only — nodescription, no location fields) and a single-value semantics note (only the first?q=is honored).Audit sweep
Per F1's "audit sibling pages for the same drift" verification step, additional sites carrying the same outdated
read_onlyclaim orparent_external_key-as-read-only listing have been corrected:docs/api/pagination-filtering-sorting.md— "Validator behavior on writes" section.docs/api/http-method-coverage.md— PATCH content-type section.docs/api/resource-identifiers.md—UpdateLocationRequest/UpdateAssetRequestparagraphs (lines 300–301).docs/api/design-notes.md—updated_atoptimistic-concurrency note (light-touch parenthetical for the code split).No changelog
None of F1/F2/F3 is a runtime behavior change. The wire contract is what it has been since BB63 / BB66; only the prose is being aligned. No changelog entry needed (matches the ticket).
Test plan
pnpm buildsucceeds with no broken links/docs/api/errorsread_onlylist contains exactly:id,created_at,updated_at,deleted_at, assetlocation_id, assetlocation_external_key/docs/api/errorsinvalid_contextentry has both semantic categories/docs/api/pagination-filtering-sortingqsection has asymmetry callout + single-value noteparent_external_keyas read-only or claimscode: read_onlyforexternal_key/tagsdivergence🤖 Generated with Claude Code