The docs describe _sharing defaults and _inheritrights propagation in two separate sections of src/overview/entities/index.md, but neither section explicitly states the combined behaviour:
An entity with no explicit _sharing value defaults to private. _sharing is not propagated via _inheritrights — only _owner, _editor, _expander, and _viewer are inherited.
The pieces are inferrable:
- "Sharing" section:
private is listed as "the default"
- "Rights Inheritance" section: only the four access-rights properties are listed as inherited;
_sharing is not mentioned
But without an explicit statement, integrators naturally assume _sharing inherits from the parent (like the four rights do when _inheritrights: true). We've now seen two independent teams hit this — one assumed deleting a child's _sharing would make it "inherit private from the parent," and designed a bulk-restrict operation around that model. The operation happened to work (absent = default private), but the mental model was wrong, and it would have led to incorrect predictions about future entity creation under parents with non-private _sharing.
Suggested addition
In the "Sharing" section, after the _sharing value table and the existing ::: info block, add:
::: info
`_sharing` is per-entity only — it is **not** propagated to children via `_inheritrights`. An entity with no explicit `_sharing` value defaults to `private`, regardless of its parent's `_sharing`.
:::
This is a one-line clarification that prevents the most common misunderstanding. Happy to send a docs PR if preferred.
The docs describe
_sharingdefaults and_inheritrightspropagation in two separate sections ofsrc/overview/entities/index.md, but neither section explicitly states the combined behaviour:The pieces are inferrable:
privateis listed as "the default"_sharingis not mentionedBut without an explicit statement, integrators naturally assume
_sharinginherits from the parent (like the four rights do when_inheritrights: true). We've now seen two independent teams hit this — one assumed deleting a child's_sharingwould make it "inherit private from the parent," and designed a bulk-restrict operation around that model. The operation happened to work (absent = default private), but the mental model was wrong, and it would have led to incorrect predictions about future entity creation under parents with non-private_sharing.Suggested addition
In the "Sharing" section, after the
_sharingvalue table and the existing::: infoblock, add:This is a one-line clarification that prevents the most common misunderstanding. Happy to send a docs PR if preferred.