Skip to content

Docs: explicitly state that _sharing is not inherited and defaults to private #12

Description

@mitselek

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions