|
1 .. _validation-overview: |
|
2 |
|
3 Validation overview |
|
4 =================== |
|
5 |
|
6 .. note:: |
|
7 This page gives an overview of ConfML and ImplML validation with ConE. |
|
8 For the actual CLI action see :ref:`cli-action-validate` |
|
9 |
|
10 ConE supports validation of the ConfML and ImplML files in configurations |
|
11 projects. This basically means that you can pass a configuration for validation |
|
12 and ConE will spit out a list for *problems*, which can be errors, warnings or |
|
13 informational messages associated with a file and a line number. |
|
14 |
|
15 For example, a list of validation problems might look something like the |
|
16 following: |
|
17 |
|
18 =================================== ====== ====================================== =========== =========================================================================== |
|
19 File Line Type Severity Message |
|
20 =================================== ====== ====================================== =========== =========================================================================== |
|
21 Layer1/confml/broken.confml 1 xml.confml error no element found: line 1, column 0 |
|
22 Layer1/confml/test.confml 11 model.confml.invalid_value.maxlength error Setting ValidationTest.Foo: Maximum number of characters is 3 (value has 6) |
|
23 Layer1/confml/test.confml 12 model.confml.missing_feature_for_data error Feature 'ValidationTest.Bar' not found |
|
24 Layer1/implml/00000002_foo.crml 6 model.implml.crml.invalid_ref error Setting 'Foo.Bar' not found in configuration |
|
25 Layer1/implml/00000003_bar.crml 10 model.implml.crml.duplicate_uid error Duplicate key UID 0x00000001 (duplicate with keys on lines 6, 7 and 8) |
|
26 Layer1/root.confml 7 schema.confml error Element 'foo': This element is not expected. |
|
27 =================================== ====== ====================================== =========== =========================================================================== |
|
28 |
|
29 From a slightly lower-level perspective validation happens on three levels: |
|
30 |
|
31 #. XML level - Files that contain invalid XML data are caught here |
|
32 #. XML Schema level - Things like missing attributes in elements are caught here |
|
33 #. Model level - The rest of possible problems that the other validation levels |
|
34 cannot handle are caught here |
|
35 |
|
36 Problem types and filtering |
|
37 --------------------------- |
|
38 |
|
39 You might have noticed the *type* column in the example above. This is a |
|
40 hierarchical problem type ID that can be used to filter a list of problems to |
|
41 narrow it down to only problems of interest. *Hierarchical* here means that |
|
42 the parts separated by commas are basically sub-IDs, the highest level sub-ID |
|
43 being the leftmost one. For example, suppose that we have a problem whose type |
|
44 is ``model.implml.crml.invalid_ref``. Reading the sub-IDs from left to right |
|
45 we can see that: |
|
46 |
|
47 #. It is a problem caught during model-level validation |
|
48 #. It is an ImplML problem |
|
49 #. The specific ImplML in this case is CRML |
|
50 #. The problem is that a CRML key references a ConfML setting that does not exist |
|
51 |
|
52 Filtering of problems by type happens by specifying a list of *includes* and |
|
53 a list of *excludes*. The output will contain only problems that match any of |
|
54 the includes, but do not match any of the excludes. |
|
55 |
|
56 If we wanted to set up a filter that shows only problems of the type in the |
|
57 example above, we could simply use a single include: ``model.implml.crml.invalid_ref``. |
|
58 However, if we wanted to see all model-level CRML problems *except* that one, |
|
59 we could include ``model.implml.crml`` and exclude ``model.implml.crml.invalid_ref``. |
|
60 Now invalid reference errors would not show up, but duplicate UID errors |
|
61 (type ``model.implml.crml.duplicate_uid``) would. Wildcards are also possible, |
|
62 so including ``*.confml`` would include all ConfML problems: XML-level, |
|
63 schema-level and model-level, or ``model.implml.*.invalid_ref`` would include |
|
64 all ImplML errors for references to non-existent settings. |
|
65 |
|
66 The two first sub-IDs for problem types come from the three validation |
|
67 levels and the fact that ConfML and ImplML can be validated. The following |
|
68 table shows the problem types for all cases: |
|
69 |
|
70 +-------------------+--------------------+-------------------+ |
|
71 | | **ConfML** | **ImplML** | |
|
72 +-------------------+--------------------+-------------------+ |
|
73 | **XML-level** | ``xml.confml`` | ``xml.implml`` | |
|
74 +-------------------+--------------------+-------------------+ |
|
75 | **Schema-level** | ``schema.confml`` | ``schema.implml`` | |
|
76 +-------------------+--------------------+-------------------+ |
|
77 | **Model-level** | ``model.confml`` | ``model.implml`` | |
|
78 +-------------------+--------------------+-------------------+ |
|
79 |
|
80 The sub-IDs after that depend on the context. For example, ImplML validation |
|
81 typically has the implementation language as the next sub-ID: ``model.implml.crml`` |
|
82 or ``schema.implml.genconfml``. |