Skip to content

docs: proposal for a public check API - #161

Draft
danyill wants to merge 2 commits into
openscd:mainfrom
danyill:issue-109-check-api-proposal
Draft

danyill wants to merge 2 commits into
openscd:mainfrom
danyill:issue-109-check-api-proposal

Conversation

@danyill

@danyill danyill commented Oct 24, 2026 •

Copy link
Copy Markdown
Collaborator

What this pull request does

Adds one document: docs/proposals/0001-public-check-api.md. No code changes.

The document proposes a public check API for scl-lib: a family of check* functions that answer "can this operation be done, and if not, why". It also proposes one error model, one reason vocabulary and one policy for limits that a file does not declare.

Why

Issue #109 asks how the library should handle a function that fails. Today a caller gets null or [] and cannot tell why. Four element families have a canAdd* check that is not exported, and the two public checks return a bare boolean.

Evidence

The design rests on a study of 716 real SCL files (120 sampled plus the four largest). Section 2 gives the results and Appendix A gives the method and the full table.

  1. 83 of 676 IEDs have no Services element, and 58 of 120 files use a service that they do not declare. A strict default blocks edits in those files.
  2. ConfReportControl@max counts control blocks, not RptEnabled@max instances. The current rule refuses 72 scopes in 24 of 120 files; the block rule refuses 6 in 2.
  3. Real files contain reference faults (lnType, datSet, iedName). The library must report them and must not use them to refuse an unrelated edit.

Shape after the review

  • One result object, discriminated by key, with a finished English sentence in reasonText (D3). No lang parameter.
  • all: true on check* returns every independent reason. No second function (Appendix B).
  • 2.1.0 with new names (D9). check* is added; the old names stay and are deprecated. New names make the addition additive.
  • Three pull requests (D10): the report counting fix with its own review; then the error model and six checks; then the dead-file removal.
  • One declared behaviour change in 2.1: report limits count blocks, for check*, can* and create* (D15). It only removes refusals.
  • limitPolicy defaults to refuse in 2.x and flips to permit in 3.0 (D5). A file that declares no limit becomes editable in 3.0, not before.
  • An example implementation of checkAddDataSet (Appendix F), with the sketch first and a checklist of the rules an author must keep.

How to review

Section 5 has 15 decisions. Each gives the options and our preferred answer. Reply with the decision number and the letter, for example D5: B, or comment on any line of the diff.

Three decisions still need an explicit yes from the reviewers who raised them:

  • D3 text in the library: Stephen and Christian
  • D2 one vocabulary rather than per-family enums: Stephen
  • D15 the counting fix in 2.1: Harald, because it is the one behaviour change

Scope of this pull request

  • Design only. No dependency is added.
  • npm test is unaffected: the change contains no TypeScript and no test.
  • Merging closes Error handling in functions #109. Implementation follows in the three pull requests above.

Changes

  • docs/proposals/0001-public-check-api.md (new, 1127 lines)

Proposes a check function family that returns a structured result:
a reason code, a details object and a policy for undeclared limits.

The proposal answers the questions in openscd#109:

- expected refusals are returned, not thrown
- one reason vocabulary across all element families
- no user text or translation inside the library

The proposal rests on a study of 716 real SCL files.

Closes openscd#109
@danyill

danyill commented Oct 24, 2026

Copy link
Copy Markdown
Collaborator Author

We might never merge this but we could at least use it to comment/discuss

Applies the outcome of the review discussion and restructures the
document:

- One result object, discriminated by key, with a finished English
  sentence in reasonText. No lang parameter.
- all: true on check* returns every independent reason, with collected
  reasons and no second function.
- 2.1.0 with new check* names; the old names stay and are deprecated.
- Three pull requests, so the counting fix has its own review.
- limitPolicy is a shared option of the check function and the create
  function. D5 gives the target default and the release that applies it.
- maxAttributes keeps its type; only its undeclared branch changes.
- checkRemove* takes no force parameter.
- Report limits count blocks, not instances, in 2.1.
- Fixed order of reasons, with a test.
- Appendix D.1 gives the rule for choosing a reason code.
- Appendix F gives a sketch, a checklist and one full implementation.

The evidence section now states what we did, why, what we found and what
each finding changed in the design.

Closes openscd#109
@danyill
danyill force-pushed the issue-109-check-api-proposal branch from 1065e4e to b8a35f0 Compare November 9, 2026 10:04

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Error handling in functions

1 participant