Repository navigation
Conversation
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
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
force-pushed
the
issue-109-check-api-proposal
branch
from
November 9, 2026 10:04
1065e4e to
b8a35f0
Compare
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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
nullor[]and cannot tell why. Four element families have acanAdd*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.
Serviceselement, and 58 of 120 files use a service that they do not declare. A strict default blocks edits in those files.ConfReportControl@maxcounts control blocks, notRptEnabled@maxinstances. The current rule refuses 72 scopes in 24 of 120 files; the block rule refuses 6 in 2.lnType,datSet,iedName). The library must report them and must not use them to refuse an unrelated edit.Shape after the review
key, with a finished English sentence inreasonText(D3). Nolangparameter.all: trueoncheck*returns every independent reason. No second function (Appendix B).check*is added; the old names stay and are deprecated. New names make the addition additive.check*,can*andcreate*(D15). It only removes refusals.limitPolicydefaults torefusein 2.x and flips topermitin 3.0 (D5). A file that declares no limit becomes editable in 3.0, not before.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:
Scope of this pull request
npm testis unaffected: the change contains no TypeScript and no test.Changes
docs/proposals/0001-public-check-api.md(new, 1127 lines)