30-second answer
basis declares what kind of authority a rule has. It is the field that keeps
a broken product limit and a departure from a recommendation out of the same
list of problems.
The five types
| Type | What it means |
|---|---|
requirement | Something that must hold |
documented-limit | A limit the vendor publishes. Exceeding it breaks |
documented-guidance | The vendor's recommendation. Departing from it is a decision |
convention | A practice, not a published position |
opinion | Held by whoever wrote the rule, and labelled as such |
What each type has to carry
The schema enforces the difference rather than trusting the author.
The documented types require at least one source. A source is an object
with url (which must be https://), title, publisher and checked_at as
an ISO date. A rule claiming documented-limit with nothing to point at does
not validate.
documented-limit carries a limit object: value, unit, and a
statement of at least 20 characters. The statement is the vendor's sentence,
quoted. From SPO-LIST-002:
basis:
type: documented-limit
limit:
value: 50000
unit: unique permission scopes
statement: >
"The supported limit of unique permissions for items in a list or
library is 50,000. However, the recommended general limit is 5,000."rationale is at least 40 characters, and it is where the author explains
why this basis and not another. The same rule's rationale is worth reading as a
model: the number is enforced by the product rather than recommended by it, and
the second source is cited because it makes the count reproducible by a reader.
Why this is the most important field
Two findings can look identical in a report and mean opposite things. A list past 50,000 unique scopes will refuse the next sharing operation. A site whose default link is Anyone is configured in a way Microsoft advises against, and an organisation may have decided that on purpose.
Presenting both as "problems" is how a governance report loses an argument it
should win. basis is printed in list-rules for exactly this reason.
Where it is visible
ID VERSION BASIS SEVERITY APPLIES TO TITLE
SPO-LIST-002 v1.0 documented-limit high list ...
SPO-SHARE-002 v1.0 documented-guidance medium site ...