simp / simp/rubygem-simp-compliance_engine

sce-schema.json applies merged-data rules to individual files, and has no strict variant for merged data

Open
#138 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Ruby
Stars
2
Forks
1
Avg merge
5d 16h
Merged PRs (30d)
2

Description

The shipped schema validates one file, but three of its constraints only make sense once every file has been merged:

  • checks.*: if required: [type] then required: [settings]
  • checks.*.settings: required: [parameter, value]

A single file is entitled to be missing anything but version. Splitting a check so that one file carries type, another carries settings.parameter, and a third carries settings.value is a supported arrangement — it is how map files, checks files, and notes files work together. The schema currently declares each of those files invalid on its own.

Evidence

scelint's test_module_04 is 37 files that exist specifically to cover every legal way of splitting a check. Validating each file against the shipped schema:

violations
as shipped 0
with keys renamed to match patternProperties 25

The 25 break down as 9 × missing required properties: parameter, 8 × missing required properties: settings, 8 × missing required properties: value — against data that is entirely valid.

It reports 0 today only because those fixture keys contain spaces and #136 causes the whole entry to be skipped. That means fixing #136 will turn this into 25 false positives on valid data, so the two need to land together or this needs fixing first.

Proposal

Two variants, because both levels genuinely need checking:

  • Per-file (the default). Drop the if/then required: [settings] conditional and settings.required. Everything except version becomes optional; keep all the type and structure constraints, which are correct at any level.
  • Strict / merged. Adds those required constraints back. This is where "a check with a type must have settings, and settings must have a parameter and a value" is actually true.

Exposed as something like ComplianceEngine.schema(strict: true), or a second ComplianceEngine.strict_schema — whichever fits the API better. Implementation could be two standalone files, or one file with the strict requirements in a $defs block that only the strict variant pulls in; I do not have a strong preference.

One wrinkle for the strict variant: merged data is not a document. A consumer holds merged profiles/ce/checks/controls collections with no version key, so either the strict variant should not require version, or consumers have to synthesize one to validate. Worth deciding explicitly rather than leaving to each caller.

Why it matters

This is exactly the split scelint already implements by hand: Scelint::Lint#check_settings reports a missing parameter as a warning in an individual file and an error in merged data. A two-variant schema would let simp/rubygem-simp-scelint#96 use the permissive schema per file and the strict one on merged data, instead of the current situation where the schema can only be applied per-file and is wrong when it is.

Related: #134 (controlsMap pattern), #135 (missing properties), #136 (patternProperties skip).

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the shipped sce-schema.json and the ComplianceEngine.schema API, then compare behavior against scelint's test_module_04 fixtures and Scelint::Lint#check_settings. Define permissive per-file and strict merged-data variants, including the version-key decision, and verify that split-check fixtures validate per-file while strict validation enforces merged requirements.

Written by the indexing model from the issue text.

Assessment

Tech stack
json, ruby
Domain
tooling
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
52/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.