1. Supported Formats for Rule Documents
jQAssistant allows you to write your own rules, contraints and concepts, in three different format: XML, YAML, and Asciidoctor. This allows you to choose the document format which fits at best to your project and your environment. XML was the first and orginal document format supported by jQAssistant. Later jQAssistant allowed you embed rules in Asciidoctor documents, because Asciidoctor allows you to document your constraints and concepts and the ideas behind them much better than XML. YAML as document format is the latest addition to the set of supported formats. People how read and write a lot of YAML documents during their daily work might prefer it because of its clear structure.
The following sections provide a guidance how to embedded jQAssistant rules in these formats. How to write rules is described in the manual.
1.1. YAML
YAML is a markup language optimized to be human readable and supported by many editors and programming languages. YAML is basically based on three elements: scalar, sequence, and map. As a sequence and a map can contain any other element. Therefore YAML allows to build tree structures, a feature which allows jQAssistant to embed contraints, concepts, and groups in one document. The structure used for this is very much aligned to the XML Schema used by jQAssistant to embed rules in XML documents.
jQAssistant supports YAML 1.2. To take advantage of all YAML features, it is recommended to read the YAML specification available at https://yaml.org/spec/1.2/spec.html.
YAML 1.2 is a subset of JSON, that means any YAML 1.2 data structure can be represented by an equivalent JSON data structure. This allows to provide and to validate a YAML document against a JSON Schema.
Therefore jQAssistant provides a JSON Schema for rule documents, which can be found in the appendix.
💡
|
This schema can be used in an IDE like IntelliJ IDEA to check the validity of a rule document while writing it. |
1.1.1. Toplevel Structure
A YAML rule document can have three keys: concepts
, constraints
, and
groups
. concepts
and constraints
can take a sequence with valid rule
definitions and groups
can take a sequence with group definitions.
Key | Cardinality | Description |
---|---|---|
|
0..1 |
Sequence of concept definitions |
|
0..1 |
Sequence of constraint definitions. |
|
0..1 |
Sequence of group definitions. |
concepts:
- id: spring-boot:Application
description: >
All types of of a Spring Boot application must be located in the same
package or a sub-package of the application class.
source: |
MATCH
(application:Type:Class)-[:ANNOTATED_BY]->
()-[:OF_TYPE]->(annotationType:Type)
WHERE
annotationType.fqn = "org.springframework.boot.autoconfigure.SpringBootApplication"
SET
application:Spring:Boot:Application:Configuration:Component
RETURN
application AS Application
constraints:
- id: spring-component:ControllerMustOnlyDependOnServicesRepositories
description: >
A Spring controller can only have dependencies to other Spring components
that are services or repositories.
requiredConcepts:
- refId: java:VirtualDependsOn
- refId: spring-component:AnnotatedInjectables
source: |
MATCH
(artifact:Artifact)-[:CONTAINS]->
(controller:Spring:Controller)-[:DEPENDS_ON|VIRTUAL_DEPENDS_ON]->
(other:Spring:Injectable)
WHERE NOT (artifact:Test OR other:Service OR other:Repository )
RETURN
controller AS Controller, collect(other) AS InvalidDependencies
groups:
- id: spring
includedConstraints:
- spring-component:ControllerMustOnlyDependOnServicesRepositories
includedConcepts:
- spring-boot:Application
1.1.2. Concepts and Constraints
Concepts and contraints are used differently by jQAssistant, but they share the same structure. Therefore contraints and concepts are document together. Due to the different usage of concepts and contraints, different default values are used for some of the available options. Since concepts and constraints are both rules, the term rule is used for both in this chapter.
A rule in a YAML rule document is represented as a map of keys. The keynames are the same or very similar to the element and attribute names used in jQAssistants’s XML Schema.
Key | Cardinality | Description |
---|---|---|
|
1 |
Unique id of the rule. |
|
0..1 |
Marks a rule as deprecated. A given text should be used to inform the user of the deprecation and the consequences of the deprecation. |
|
0..1 |
Description of the rule. Intended to be shown to the user in case the verification of the rule failed and to document the rule itself. |
|
0..1 |
Specifies the language the actual rule is written in. If not specified it is assumed that the actual rule is written in Cypher. |
|
0..1 |
Specifies a report which should be generated based on the result of the of rule. See Keys of a map to specify a report for details. |
|
0..1 |
Sequence of rule references to concepts required by the rule. Required conceptswill be executed before the rule itself will be executed. See Keys of a map to specify the required concepts for details. |
|
0..1 |
Sequence of required parameters of the rule. See Keys of a map to specify the required parameters for details. |
|
0..1 |
The serverity of the rule. Must be one of If not specified, the default severity
for a concept is |
|
0..1 |
The verification method of the rule. See Keys of a map to specify the verification method for details. |
|
1 |
The statement representing the rule. |
Key | Cardinality | Description |
---|---|---|
|
1 |
The id of a concept which must be executed before this rule. jQAssistant will ensure the required execution order of all concepts. |
|
0..1 |
The severity to be applied to the referenced rule, overwriting the actual specified severity. |
|
0..1 |
Specifies if a rule is optional or not. Possible values are |
Key | Cardinality | Description |
---|---|---|
|
1 |
The name of the required parameter. |
|
1 |
The data type of the parameter. Must be one of: |
|
0..1 |
The default value for the parameter if not specified. |
Key | Cardinality | Description |
---|---|---|
|
0..1 |
Verification should be performed by aggregating the value of a specific column. See Keys of a map to specify a result verification via aggregation for details. |
|
0..1 |
Verification should be performed by counting the results rows. See Keys of a map to specify a result verification via row counting for details. |
If no verification method has been specified, the default result verification will be performed via rowcounting.
Key | Cardinality | Description |
---|---|---|
|
0..1 |
The column those value will be used to perform the verification. If omitted the first column of the result set will be used for the verification. |
|
0..1 |
The allowed inclusive maximal value for the verification used column. |
|
0..1 |
The allowed inclusive minimal value for the verification used column. |
Key | Cardinality | Description |
---|---|---|
|
0..1 |
Allowed maximal inclusive number of rows in the result set of a rule. For a constraint, the default value is 0, since a constraint may not
have any results. For a concept, |
|
0..1 |
Required minimal inclusive number of rows in the result set of a rule. For a constraint, the default value is 0, since a constraint may not
have any results. For a concept, |
Key | Cardinality | Description |
---|---|---|
|
1 |
Specifies the column of the result set, which will be overhanded as primary column to the plugin generating the report. If not specified the first column of the result set will be taken als primary column. |
|
0..1 |
Map with properties, which will be overhanded to the plugin generating the report. |
|
1 |
Specifies the report to be generated. Which reports are available depends on the used report plugins. |
1.1.3. Groups
A group in a YAML rule document is represented as a map of keys.
Key | Cardinality | Description |
---|---|---|
|
1 |
The unique id for this group. |
|
0..1 |
Severity for all included groups, constraints, and concept, overwriting
the specified severity for those.
Must be one of |
|
0..1 |
Sequence of rule references to concepts to be included in this group. See Keys of a map to specify a rule reference for details |
|
0..1 |
Sequence of rule references to constraints to be included in this group. See Keys of a map to specify a rule reference for details |
|
0..1 |
Sequence of references to other groups to be included in this group. See Keys of a map to specify a rule reference for details |
Key | Cardinality | Description |
---|---|---|
|
1 |
The id of a rule or group which should be included in the containing group. |
|
0..1 |
The severity to be applied to the referenced rule or group, overwriting the actual specified severity. |
|
0..1 |
Specifies if the rule or group is optional or not. Possible values are |
1.1.4. Examples
1.2. XML
1.3. Asciidoctor
2. AsciiDoc Report Plugin
The documentation of this plugin is still only the section Asciidoc Report Plugin of the jQAssistant Manual available.
3. CDI Plugin
The documentation of this plugin is still only the section CDI Plugin of the jQAssistant Manual available.
4. EJB 3 Plugin
The documentation of this plugin is still only the section EJB 3 Plugin of the jQAssistant Manual available.
5. GraphML Plugin
The documentation of this plugin is still only the section GraphML Plugin of the jQAssistant Manual available.
6. GraphQL Plugin
The GraphQL plugin provides scanners for GraphQL schemas provided via
-
SDL files (having the extension
.graphql
or.graphqls
) -
Introspection queries to HTTP endpoints by scanning an URL, e.g.
jqassistant scan -u graphql:schema::https://bahnql.herokuapp.com/graphql
💡
|
For an introduction into GraphQL, its schema and elements refer to http://graphql.org. |
6.1. Features
-
Scanning of
-
SDL files
-
HTTP endpoints by executing an introspection query using scope
graphql:schema
-
-
Supported schema elements
-
Object types including fields and implemented interfaces
-
Input object types including fields
-
Enum types including defined values
-
Scalar types
-
Interface types including fields
-
Union types including the types
-
Directive types
-
-
All supported elements provide additional information
-
The source location (i.e. line and column numbers)
-
Specifed directives and their values
-
6.2. Feature Requests and Bugs
In case of a missing feature or any kind of unexpected or faulty behaviour, please file an issue via Github.
6.3. The Model
Entity | Used Combination of Labels |
---|---|
Schema |
|
Schema File |
|
Schema URL |
|
Type |
|
Value |
|
Scalar Type |
|
Scalar Value |
|
Enum Type |
|
Enum Value |
|
Interface Type |
|
Object Type |
|
Field |
|
Input Object Type |
|
Input Field |
|
Input Value Definition |
|
Union Type |
|
List Type |
|
Directive Type |
|
Directive Value |
|
Directive Location |
|
Argument |
|
6.4. Schema
Represents a GraphQL schema.
Used labels |
|
---|
Relation Name | Target Node | Cardinality | Description |
---|---|---|---|
|
0..n |
References all GraphQL types which are declared in the schema |
|
|
0..n |
References all GraphQL types which are required by the schema (i.e. referenced but not declared) |
6.5. Schema File
A file with the the extension .graphql
or .graphqls
containing a GraphQL Schema.
Used labels |
|
---|
6.6. Schema Url
A URL (i.e. endpoint) providing a GraphQL Schema.
Used labels |
|
---|
Property Name | Existence | Description |
---|---|---|
|
always |
The URL. |
6.7. Type
Represents a GraphQL type.
Used labels |
|
---|
Relation Name | Target Node Type | Cardinality | Description |
---|---|---|---|
|
0..n |
References to the declared directive values |
Property Name | Existence | Description |
---|---|---|
|
always |
The name. |
|
not always |
The optional description as provided in the GraphQL schema. |
|
not always |
The optional line number of the source location within the GraphQL schema. |
|
not always |
The optional column of the source location within the GraphQL schema. |
6.8. Value
Represents a value (e.g. a scalar or enum).
Used labels |
|
---|
6.9. Scalar Type
Represents a GraphQL Scalar Type.
Used labels |
|
---|
6.10. Scalar Value
Represents a GraphQL Scalar value.
Used labels |
|
---|
Property Name | Existence | Description |
---|---|---|
|
always |
The scalar value. |
6.11. Enum Type
Represents a GraphQL Enum Type.
Used labels |
|
---|
Relation Name | Target Node | Cardinality | Description |
---|---|---|---|
|
1..n |
References an enum value declared by the type. |
6.12. Enum Value
Represents a GraphQL Enum value.
Used labels |
|
---|
Relation Name | Target Node | Cardinality | Description |
---|---|---|---|
|
0..n |
References to the declared directive values |
Property Name | Existence | Description |
---|---|---|
|
always |
The name. |
|
not always |
The optional description as provided in the GraphQL schema. |
6.13. Interface Type
Represents a GraphQL Interface Type.
Used labels |
|
---|
Relation Name | Target Node | Cardinality | Description |
---|---|---|---|
|
0..n |
References the declared GraphQL fields |
6.14. Object Type
Represents a GraphQL Object Type.
Used labels |
|
---|
Relation Name | Target Node | Cardinality | Description |
---|---|---|---|
|
0..n |
References the implemented interface types. |
|
|
0..n |
References the declared GraphQL fields |
6.15. Field
Represents a field of an object or interface type.
Used labels |
|
---|
Relation Name | Target Node | Cardinality | Description |
---|---|---|---|
|
1 |
References the field type |
|
|
0..n |
References the declared GraphQL input value definitions |
Property Name | Existence | Description |
---|---|---|
|
always |
The name. |
|
not always |
The optional description as provided in the GraphQL schema. |
6.16. Of Type Relation
References a GraphQL type indicating if this reference is nullable.
Relation Name | Target Node Type |
---|---|
|
Property Name | Existence | Description |
---|---|---|
|
always |
If |
6.17. Input Object Type
Represents a GraphQL Input Object Type.
Used labels |
|
---|
Relation Name | Target Node | Cardinality | Description |
---|---|---|---|
|
1..n |
References the declared input fields. |
6.18. Input Field
Represents a GraphQL Input Field, having similar properties and relations.
Used labels |
|
---|
6.19. Input Value Definition
Defines an input value.
Used labels |
|
---|
Relation Name | Target Node | Cardinality | Description |
---|---|---|---|
|
1 |
The relation to the type. |
|
|
0..1 |
References the default value. |
|
|
0..n |
References to the declared directive values |
Property Name | Existence | Description |
---|---|---|
|
always |
The index number (starting with 0). |
|
always |
The name. |
|
not always |
The optional description as provided in the GraphQL schema. |
|
not always |
The optional line number of the source location within the GraphQL schema. |
|
not always |
The optional column of the source location within the GraphQL schema. |
6.20. Union Type
Represents a GraphQL Union Type.
Used labels |
|
---|
Relation Name | Target Node | Cardinality | Description |
---|---|---|---|
|
1..n |
References the declared GraphQL fields |
6.21. Union Declares Type
References a GraphQL type indicating the index of the relation.
Relation Name | Target Node Type |
---|---|
|
Property Name | Existence | Description |
---|---|---|
|
always |
The index number (starting with 0). |
6.22. List Type
Used labels |
|
---|
Relation Name | Target Node Type | Cardinality | Description |
---|---|---|---|
|
1 |
References the field type |
6.23. Of Element Type Relation
References a GraphQL type indicating if this reference is nullable.
Relation Name | Target Node Type |
---|---|
|
Property Name | Existence | Description |
---|---|---|
|
always |
If |
6.24. Directive Type
Represents a directive Type that is defined within a GraphQL schema.
Used labels |
|
---|
Relation Name | Target Node | Cardinality | Description |
---|---|---|---|
|
1..n |
References the allowed locations the directive can be applied to. |
|
|
0..n |
References the declared GraphQL input value definitions |
6.25. Directive Value
Represents a directive that is present at an element of the GraphQL schema.
Used labels |
|
---|
Relation Name | Target Node | Cardinality | Description |
---|---|---|---|
|
1 |
References the type of the directive |
|
|
0..n |
References arguments of the directive |
6.26. Directive Location
Represents the allowed locations for a directive.
Used labels |
|
---|
Property Name | Existence | Description |
---|---|---|
|
always |
The name. |
6.27. Argument
Represents an argument of a GraphQL directive.
Used labels |
|
---|
Relation Name | Target Node | Cardinality | Description |
---|---|---|---|
|
1 |
References the argument value. |
|
|
1 |
References the input value defined for this argument. |
Property Name | Existence | Description |
---|---|---|
|
always |
The index number (starting with 0). |
7. Java Plugin
The documentation of this plugin is still only the section Java Plugin of the jQAssistant Manual available.
8. Java EE 6 Plugin
The documentation of this plugin is still only the section Java EE 6 Plugin of the jQAssistant Manual available.
9. JAX-RS Plugin
The documentation of this plugin is still only the section JAX-RS Plugin of the jQAssistant Manual available.
10. JPA 2 Plugin
The documentation of this plugin is still only the section JPA 2 Plugin of the jQAssistant Manual available.
11. JSON Plugin
The documentation of this plugin is still only the section JSON Plugin of the jQAssistant Manual available.
12. JUnit Plugin
The documentation of this plugin is still only the section JUnit Plugin of the jQAssistant Manual available.
13. Maven 2 Repository Plugin
The documentation of this plugin is still only the section Maven 2 Repository Plugin of the jQAssistant Manual available.
14. Maven 3 Plugin
The documentation of this plugin is still only the section Maven 3 Plugin of the jQAssistant Manual available.
15. OSGi Plugin
The documentation of this plugin is still only the section OSGi Plugin of the jQAssistant Manual available.
16. RDBMS Plugin
The documentation of this plugin is still only the section RDBMS Plugin of the jQAssistant Manual available.
17. Spring Plugin
The documentation of this plugin is still only the section Spring Plugin of the jQAssistant Manual available.
18. TestNG Plugin
The documentation of this plugin is still only the section TestNG Plugin of the jQAssistant Manual available.
19. Tycho Plugin
The documentation of this plugin is still only the section Tycho Plugin of the jQAssistant Manual available.
20. XML Plugin
The documentation of this plugin is still only the section XML Plugin of the jQAssistant Manual available.
21. YAML Plugin
The documentation of this plugin is still only the section YAML Plugin of the jQAssistant Manual available.
22. YAML II Plugin
The jQAssistant YAML 2 Plugin allows jQAssistant scan YAML documents and to build a graph model out of any valid YAML 1.2 document.
The YAML 2 Plugin is the successor of the jQAssistant YAML Plugin which suffers from a faulty graph model. As soon the YAML 2 Plugin is ready for production, it will replace the YAML Plugin.
💡
|
It is highly recommended to read the YAML 1.2 specification and to become more familiar with the possibilities of YAML. |
Features
-
Support of YAML 1.2 specification
-
Full support for maps, scalars,and sequences
-
Support for aliases and anchors
Feature Requests and Bugs
In case of a missing feature or any kind of unexpected or faulty behaviour, please file an issue via Github.
Configuration
Property | Description | ||
---|---|---|---|
|
A comma separated list of file name patterns, wildcards (?,*) are allowed,
e.g.
|
||
|
A comma separated list of file name patterns, wildcards (?,*) are allowed,
e.g. |
Compatibility with the jQAssistant YAML Plugin
The graph model build by the YAML 2 Plugin is different from the one of the YAML Plugin and not compatible. Therefore, existing constraints and reports, which make use of the graph model generated by the previous plugin must be reworked. == The Model
Entity | Used Combination of Labels |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
22.1. File
A file with the the extension .yaml
or .yml
, which can contain
multiple YAML documents.
Used labels |
|
---|
Relation Name | Target Node | Cardinality | Description |
---|---|---|---|
|
0..n |
References all YAML documents contained in this file |
Property Name | Existence | Description |
---|---|---|
|
always |
Indicates whether or not the item underlying the node was successfully scanned. |
In case the scanner of the YAML 2 plugin is not able to scan all documents
of the YAML file, the file will be marked as not valid by setting
the property valid
of the node representing the YAML file to false
.
This is done on the file level even if only one document of many is not valid.
This behavior is due to the used
SnakeYAML Engine library.
22.2. Document
A single YAML document as specified in the YAML 1.2 specification. A document can contain either a scalar, a sequence or a map.
---
and suffix …
---
# Comments are not handled by jQAssistant
NX-01: Jonathan Archer
NCC-1701-A: James Tiberius Kirk
NCC-1701-D: Jean-Luc Picard
...
Used labels |
|
---|
Relation Name | Target Node Type | Cardinality | Description |
---|---|---|---|
|
0..1 |
Reference to a sequence in the YAML document |
|
|
0..1 |
Reference to a map in the YAML document |
|
|
0..1 |
Reference to a scalar in the YAML document |
22.3. Scalar
A scalar value as described in the YAML 1.2 specification.
Used labels |
|
---|
Property Name | Existence | Description |
---|---|---|
|
not always |
Position of the element in document order in a sequence. |
|
always |
The scalar value itself |
22.4. Sequence
A sequence as specified in the YAML 1.2 specification.
Each item of sequence has an additional label :Item
.
- Humans: Earth
- Hirogen: Delta quadrant
Used labels |
|
---|
Relation Name | Target Node Type | Cardinality | Description |
---|---|---|---|
|
1..n |
Reference to an item in the sequence. The item can be either a scalar, a sequence or a map. |
Property Name | Existence | Description |
---|---|---|
|
not always |
Position of the element in document order in a sequence. |
22.5. Sequence Item
Each item of a sequence is also labeled with :Item
.
Used labels |
|
---|
Label | Existence | Description |
---|---|---|
|
not always |
The last item in a sequence in document order carries also the
label |
|
not always |
The first item in a sequence in document order
carries also the label |
22.6. Map
A map as specified in the YAML 1.2 specification
with a set of key-value pairs. The key of a key-value pair can be
either a simple key or a complex key.
The value of the key-value pair can be an arbitrary YAML structure.
Each value of a map has an additional Value
label.
weight: 91
length: 103
height: 44
Used labels |
|
---|
Relation Name | Target Node Type | Cardinality | Description |
---|---|---|---|
|
1..n |
Reference to key or a compley key in the map |
Property Name | Existence | Description |
---|---|---|
|
not always |
Position of the element in document order in a sequence. |
22.7. Simple Key
A simple key of a key-value pair in a map represented by a scalar value. Beside the simple key there is also the complex key, which can also be used as key for maps. Usage examples can be found in chapter 2.2 of the YAML specification.
simpleKey: "Value for a simple key"
? - complex
- key
: "Value for a complex key"
Used labels |
|
---|
Relation Name | Target Node | Cardinality | Description |
---|---|---|---|
|
0..1 |
Reference to the value of this key-value pair |
Property Name | Existence | Description |
---|---|---|
|
not always |
Position of the element in document order in a sequence. |
|
always |
The name of a key as scalar value |
22.8. Complex Key
A complex key of a key-value pair in a map. A complex key
starts with an ?
and can be any valid YAML structure.
Besides the complex key there is also the
simple key, which is represented by
a single scalar value.
simpleKey: "Value for a simple key"
? - Vulcan
- ShiKahr District
: Spock
? - Earth
- North America
: James T. Kirk
Used labels |
|
---|
Relation Name | Target Node | Cardinality | Description |
---|---|---|---|
|
0..1 |
Reference to the value of this key-value pair |
22.9. Map Value
A value of a key-value pair in a map can be any valid YAML structure.
The YAML 2 Plugin assigns each structure its standard labels, e.g.
:Yaml:Map
for a map used as value or :Yaml:Scalar
to a simple
scalar value like Romulan Star Empire
. Any YAML structure
used as value of a key-value pair is also labeled with :Value
.
Used labels |
|
---|
22.10. Anchor
An anchor as specified in the YAML 1.2 specification, used to mark content in a YAML document for future reuse via an alias in the same document.
"James T. Kirk" : &ufp "United Federation of Planets"
"Hikaru Kato Sulu" : *ufp
"James T. Kirk" : "United Federation of Planets"
"Hikaru Kato Sulu" : "United Federation of Planets"
Used labels |
|
---|
Property Name | Existence | Description |
---|---|---|
|
always |
The name of the anchor |
|
not always |
Position of the element in document order in a sequence. |
22.11. Alias
An alias as specified in the YAML 1.2 specification, used to reuse previously marked content in a document.
"James T. Kirk" : &ufp "United Federation of Planets"
"Hikaru Kato Sulu" : *ufp
Used labels |
|
---|
Relation Name | Target Node Type | Cardinality | Description |
---|---|---|---|
|
1 |
Reference to the anchor of this alias in the YAML document |
Property Name | Existence | Description |
---|---|---|
|
not always |
Position of the element in document order in a sequence. |
Appendix A: JSON Schema for rule documents
1
Unresolved directive in /Users/obf/jqa-release-environment/jqa-manual/target/asciidoc-modules-documentation/com/buschmais/jqassistant/core/rule/yaml-schema.adoc - include::../../../../../META-INF/jsonschema/jqassistant-rule-v1.8.schema.json[]