Skip to content

Commit 5282209

Browse files
Arnaud RiessCopilot
andcommitted
docs: update README.md with new validation checks for ID length and validity period consistency
Co-authored-by: Copilot <copilot@github.com>
1 parent f2e8bcf commit 5282209

1 file changed

Lines changed: 23 additions & 7 deletions

File tree

src/extensions/score_metamodel/README.md

Lines changed: 23 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -75,11 +75,12 @@ JSON Schema cannot express:
7575
|---|---|---|
7676
| `check_options` | `check_options.py` | Mandatory/optional field presence and patterns (legacy, overlaps with schema validation) |
7777
| `check_extra_options` | `check_options.py` | Warns about fields not defined in the metamodel |
78+
| `check_validity_consistency` | `check_options.py` | Validates that `valid_from` < `valid_until` for `stkh_req` and `feat_req` |
7879
| `check_id_format` | `attributes_format.py` | ID structure (`<type>__<abbrev>__<element>`, part count) |
79-
| `check_for_prohibited_words` | `attributes_format.py` | Forbidden words in titles |
80+
| `check_id_length` | `attributes_format.py` | ID must not exceed 45 characters (62 for IDs containing `example_feature`) |
81+
| `check_for_prohibited_words` | `attributes_format.py` | Forbidden words in titles and content |
8082
| `check_metamodel_graph` | `graph_checks.py` | Cross-need constraints (e.g. ASIL_B needs must link to non-QM requirements) |
81-
| `check_id_contains_feature` | `id_contains_feature.py` | Need IDs must contain the feature abbreviation from the file path |
82-
| `check_standards` | `standards.py` | Standard compliance link validation |
83+
| `id_contains_feature` | `id_contains_feature.py` | Need IDs must contain the feature abbreviation from the file path |
8384

8485
### Coverage comparison
8586

@@ -103,6 +104,8 @@ Schema column: **yes** = implemented, **feasible** = could be added, **--** = no
103104
| Prohibited words | feasible | yes | Negative lookahead regex on `title`; less precise than Python |
104105
| Graph constraints | -- | yes | Cross-need traversals beyond JSON Schema |
105106
| Undefined extra options | -- | yes | `unevaluatedProperties` would reject sphinx-needs internal fields |
107+
| ID length limit (45 chars) | feasible | yes | Can add `maxLength` to per-type ID pattern in schema |
108+
| Validity period consistency (`valid_from` < `valid_until`) | -- | yes | Cross-field comparison beyond JSON Schema |
106109

107110
#### Rule explanations
108111

@@ -164,7 +167,7 @@ same need type with `severity: "info"` that only checks optional link targets.
164167
Same as above, but for regex-based link IDs on optional links (e.g.
165168
`optional_links: { links: ^.*$ }` on `tsf`). Same severity-split approach would work.
166169

167-
**Mixed regex+plain link type** (not possible) --
170+
**Mixed regex+plain link type** (to be analyzed) --
168171
`workproduct` has `optional_links: { complies: std_wp, ^std_req__aspice_40__iic.*$ }`.
169172
A `complies` target is valid if it is either a need of type `std_wp` OR has an ID
170173
matching the regex. The `validate.network` `items` schema applies to ALL linked needs
@@ -178,23 +181,36 @@ These mixed fields are validated only by the Python check.
178181
`__` and counts parts. *Feasible*: generate a per-type regex like
179182
`^feat_req__[^_]+(__[^_]+){1}$` in the schema. However, the Python check also
180183
validates that the ID contains the feature abbreviation from the file path
181-
(`check_id_contains_feature`), which depends on runtime context and cannot be
184+
(`id_contains_feature`), which depends on runtime context and cannot be
182185
expressed in a schema.
183186

187+
**ID length limit (45 chars)** (feasible) --
188+
The Python check (`check_id_length`) rejects IDs longer than 45 characters (IDs
189+
containing `example_feature` get an extra 17 characters to account for the
190+
placeholder being replaced by real feature names). *Feasible*: add `"maxLength": 45`
191+
to the per-type ID pattern in the schema.
192+
193+
**Validity period consistency** (to be analyzed) --
194+
`stkh_req` and `feat_req` may carry `valid_from` and `valid_until` version fields.
195+
The Python check (`check_validity_consistency`) rejects needs where
196+
`valid_from >= valid_until`. This requires comparing two field values against each
197+
other, which JSON Schema cannot do (JSON Schema has no cross-field comparison
198+
operator). Only the Python check can enforce this rule.
199+
184200
**Prohibited words** (feasible) --
185201
The metamodel forbids words like "shall", "must", "will" in need titles (for
186202
requirement types). The Python check splits the title into words and checks each one.
187203
*Feasible*: add a negative lookahead regex on the `title` field, e.g.
188204
`^(?!.*\b(shall|must|will)\b).*$`. This is less precise than the Python check
189205
(which normalizes case, strips punctuation) but catches most violations.
190206

191-
**Graph constraints** (not possible) --
207+
**Graph constraints** (to be analyzed) --
192208
`graph_checks` in the metamodel define rules like "an ASIL_B need must link to at
193209
least one non-QM requirement via `satisfies`". This requires traversing the need
194210
graph across multiple levels, which is fundamentally beyond what JSON Schema can
195211
express. Only the Python check (`check_metamodel_graph`) can do this.
196212

197-
**Undefined extra options** (not possible) --
213+
**Undefined extra options** (to be analyzed) --
198214
The Python check (`check_extra_options`) warns when a need has fields not defined
199215
in the metamodel (e.g. a typo like `saftey` instead of `safety`). In theory,
200216
`unevaluatedProperties: false` could reject unknown fields. In practice, sphinx-needs

0 commit comments

Comments
 (0)