diff --git a/.changeset/getmetaitems-organization-id-describe-precision.md b/.changeset/getmetaitems-organization-id-describe-precision.md new file mode 100644 index 0000000000..e0c3bdf245 --- /dev/null +++ b/.changeset/getmetaitems-organization-id-describe-precision.md @@ -0,0 +1,13 @@ +--- +"@objectstack/spec": patch +--- + +`GetMetaItemsRequestSchema.organizationId` no longer documents itself as always consulted. + +The published `describe()` opened with "Selects the org partition in the ADR-0005 overlay read order" and closed with "Absent = environment-wide read: only env-level overlays apply and no org partition is consulted." Stating only the absent case invites the converse, and an integrator reading it completes it as *present ⇒ consulted* — so a caller who supplies an organization believes it has scoped a read that can in fact be environment-wide. A supplied organization is not consulted on every `getMetaItems` read. + +The corrected text qualifies the promise instead of implying its converse: the parameter selects the org partition **when an org partition applies**, and supplying a value "does not by itself guarantee an org partition is consulted; where none applies, and whenever it is absent, the read is environment-wide and only env-level overlays apply." + +Prose only. No key is added, removed or renamed, no export moves, no accept set changes and no runtime behaviour changes — the schema's shape and validation are byte-for-byte what they were. What ships is the JSON-Schema `description` for the existing `organizationId` key and the matching row in the generated API reference, which is why this is user-visible enough to owe an entry and narrow enough to be a patch. + +The three sibling `organizationId` describes on `GetMetaItemRequestSchema`, `GetMetaItemLayeredRequestSchema` and `GetMetaItemCachedRequestSchema` are deliberately left alone. diff --git a/content/docs/references/api/protocol.mdx b/content/docs/references/api/protocol.mdx index e56387dbd9..ff5005203a 100644 --- a/content/docs/references/api/protocol.mdx +++ b/content/docs/references/api/protocol.mdx @@ -1317,7 +1317,7 @@ Enable package response | :--- | :--- | :--- | :--- | | **type** | `string` | ✅ | Metadata type name (e.g., "object", "plugin") | | **packageId** | `string` | optional | Optional package ID to filter items by | -| **organizationId** | `string` | optional | Organization (tenant) scope for the read. Selects the org partition in the ADR-0005 overlay read order — org overlay wins over env-wide overlay wins over packaged artifact — so it decides which tenant's customization rows are merged into the list. Absent = environment-wide read: only env-level overlays apply and no org partition is consulted. | +| **organizationId** | `string` | optional | Organization (tenant) scope for the read. When an org partition applies, this selects it in the ADR-0005 overlay read order — org overlay wins over env-wide overlay wins over packaged artifact — so it decides which tenant's customization rows are merged into the list. Supplying a value does not by itself guarantee an org partition is consulted; where none applies, and whenever it is absent, the read is environment-wide and only env-level overlays apply. | | **previewDrafts** | `boolean` | optional | Draft-visibility switch (ADR-0033 draft-overlay preview): when true, pending `state='draft'` rows are overlaid on the active list — draft wins on name collision, draft-only items appear, and each overlaid item is tagged `_draft: true` so UIs can badge the preview. Absent/false = published world only. Declaration ≠ authorization: this member only switches which rows are read, and ADR-0106 masking is unaffected — callers without draft-preview authorization are refused upstream (admin-gated), not by this schema. | diff --git a/packages/spec/src/api/protocol.zod.ts b/packages/spec/src/api/protocol.zod.ts index 8c427d73a4..168e08d34d 100644 --- a/packages/spec/src/api/protocol.zod.ts +++ b/packages/spec/src/api/protocol.zod.ts @@ -233,11 +233,13 @@ export const GetMetaItemsRequestSchema = lazySchema(() => z.object({ type: z.string().describe('Metadata type name (e.g., "object", "plugin")'), packageId: z.string().optional().describe('Optional package ID to filter items by'), organizationId: z.string().optional().describe( - 'Organization (tenant) scope for the read. Selects the org partition in the ' - + 'ADR-0005 overlay read order — org overlay wins over env-wide overlay wins ' - + 'over packaged artifact — so it decides which tenant\'s customization rows ' - + 'are merged into the list. Absent = environment-wide read: only env-level ' - + 'overlays apply and no org partition is consulted.', + 'Organization (tenant) scope for the read. When an org partition applies, ' + + 'this selects it in the ADR-0005 overlay read order — org overlay wins ' + + 'over env-wide overlay wins over packaged artifact — so it decides which ' + + 'tenant\'s customization rows are merged into the list. Supplying a value ' + + 'does not by itself guarantee an org partition is consulted; where none ' + + 'applies, and whenever it is absent, the read is environment-wide and ' + + 'only env-level overlays apply.', ), previewDrafts: z.boolean().optional().describe( 'Draft-visibility switch (ADR-0033 draft-overlay preview): when true, '