jQAssistant Reference

1. Supported Documat Formats

Note	This chapter has not been written yet.

1.1. YAML

Note	This chapter has not been written yet.

1.2. XML

Note	This chapter has not been written yet.

1.3. Asciidoctor

Note	This chapter has not been written yet.

2. 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.

2.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

2.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.

2.3. The Model

Entity Used Combination of Labels

Entity	Used Combination of Labels
Schema	`:GraphQL:Schema`
Schema File	`:GraphQL:Schema:File`
Schema URL	`:GraphQL:Schema:URL`
Type	`:GraphQL:Type`
Value	`:GraphQL:Value`
Scalar Type	`:GraphQL:Scalar:Type`
Scalar Value	`:GraphQL:Scalar:Value`
Enum Type	`:GraphQL:Enum:Type`
Enum Value	`:GraphQL:Enum:Value`
Interface Type	`:GraphQL:Interface:Type`
Object Type	`:GraphQL:Object:Type`
Field	`:GraphQL:Field`
Input Object Type	`:GraphQL:Input:Object:Type`
Input Field	`:GraphQL:Input:Field`
Input Value Definition	`:GraphQL:Input:ValueDefinition`
Union Type	`:GraphQL:Union:Type`
List Type	`:GraphQL:List:Type`
Directive Type	`:GraphQL:Directive:Type`
Directive Value	`:GraphQL:Directive:Value`
Directive Location	`:GraphQL:Directive:Location`
Argument	`:GraphQL:Argument`

Schema

:GraphQL:Schema

Schema File

:GraphQL:Schema:File

Schema URL

:GraphQL:Schema:URL

Type

:GraphQL:Type

Value

:GraphQL:Value

Scalar Type

:GraphQL:Scalar:Type

Scalar Value

:GraphQL:Scalar:Value

Enum Type

:GraphQL:Enum:Type

Enum Value

:GraphQL:Enum:Value

Interface Type

:GraphQL:Interface:Type

Object Type

:GraphQL:Object:Type

Field

:GraphQL:Field

Input Object Type

:GraphQL:Input:Object:Type

Input Field

:GraphQL:Input:Field

Input Value Definition

:GraphQL:Input:ValueDefinition

Union Type

:GraphQL:Union:Type

List Type

:GraphQL:List:Type

Directive Type

:GraphQL:Directive:Type

Directive Value

:GraphQL:Directive:Value

Directive Location

:GraphQL:Directive:Location

Argument

:GraphQL:Argument

2.4. Schema

Represents a GraphQL schema.

Table 1. Used Combination of Labels
Used labels	`:GraphQL:Schema`

Table 2. Relations of a GraphQL Schema
Relation Name	Target Node	Cardinality	Description
`DECLARES_TYPE`	Type	0..n	References all GraphQL types which are declared in the schema
`REQUIRES_TYPE`	Type	0..n	References all GraphQL types which are required by the schema (i.e. referenced but not declared)

2.5. Schema File

A file with the the extension .graphql or .graphqls containing a GraphQL Schema.

Table 3. Used Combination of Labels
Used labels	`:GraphQL:Schema:File`

2.6. Schema Url

A URL (i.e. endpoint) providing a GraphQL Schema.

Table 4. Used Combination of Labels
Used labels	`:GraphQL:Schema:URL`

Table 5. Properties of :GraphQL:Schema:URL
Property Name	Existence	Description
`url`	always	The URL.

2.7. Type

Represents a GraphQL type.

Table 6. Used Combination of Labels
Used labels	`:GraphQL:Type`

Table 7. Relations of a GraphQL Type
Relation Name	Target Node Type	Cardinality	Description
`DECLARES_DIRECTIVE`	Directive Value	0..n	References to the declared directive values

Table 8. Properties of :GraphQL:Type
Property Name	Existence	Description
`name`	always	The name.
`description`	not always	The optional description as provided in the GraphQL schema.
`line`	not always	The optional line number of the source location within the GraphQL schema.
`column`	not always	The optional column of the source location within the GraphQL schema.

2.8. Value

Represents a value (e.g. a scalar or enum).

Table 9. Used Combination of Labels
Used labels	`:GraphQL:Value`

2.9. Scalar Type

Represents a GraphQL Scalar Type.

Table 10. Used Combination of Labels
Used labels	`:GraphQL:Scalar:Type`

2.10. Scalar Value

Represents a GraphQL Scalar value.

Table 11. Used Combination of Labels
Used labels	`:GraphQL:Scalar:Value`

Table 12. Properties of :GraphQL:Scalar:Value
Property Name	Existence	Description
`value`	always	The scalar value.

2.11. Enum Type

Represents a GraphQL Enum Type.

Table 13. Used Combination of Labels
Used labels	`:GraphQL:Enum:Type`

Table 14. Relations of an Enum Type
Relation Name	Target Node	Cardinality	Description
`DECLARES_VALUE`	Enum Value	1..n	References an enum value declared by the type.

2.12. Enum Value

Represents a GraphQL Enum value.

Table 15. Used Combination of Labels
Used labels	`:GraphQL:Enum:Value`

Table 16. Relations of an Enum Value
Relation Name	Target Node	Cardinality	Description
`DECLARES_DIRECTIVE`	Directive Value	0..n	References to the declared directive values

Table 17. Properties of :GraphQL:Enum:Value
Property Name	Existence	Description
`name`	always	The name.
`description`	not always	The optional description as provided in the GraphQL schema.

2.13. Interface Type

Represents a GraphQL Interface Type.

Table 18. Used Combination of Labels
Used labels	`:GraphQL:Interface:Type`

Table 19. Relations of an Interface Type
Relation Name	Target Node	Cardinality	Description
`DECLARES_FIELD`	Field	0..n	References the declared GraphQL fields

2.14. Object Type

Represents a GraphQL Object Type.

Table 20. Used Combination of Labels
Used labels	`:GraphQL:Object:Type`

Table 21. Relations of an Object Type
Relation Name	Target Node	Cardinality	Description
`IMPLEMENTS`	Interface Type	0..n	References the implemented interface types.
`DECLARES_FIELD`	Field	0..n	References the declared GraphQL fields

2.15. Field

Represents a field of an object or interface type.

Table 22. Used Combination of Labels
Used labels	`:GraphQL:Field`

Table 23. Relations of a Field
Relation Name	Target Node	Cardinality	Description
`OF_TYPE`	Of Type (Relation)	1	References the field type
`DEFINES_INPUT_VALUE`	Input Value Definition	0..n	References the declared GraphQL input value definitions

Table 24. Properties of :GraphQL:Field
Property Name	Existence	Description
`name`	always	The name.
`description`	not always	The optional description as provided in the GraphQL schema.

2.16. Of Type Relation

References a GraphQL type indicating if this reference is nullable.

Table 25. Relation to a GraphQL Type
Relation Name	Target Node Type
`OF_TYPE`	Type

Table 26. Properties of :OF_TYPE
Property Name	Existence	Description
`nonNull`	always	If `true` the reference is not nullable.

2.17. Input Object Type

Represents a GraphQL Input Object Type.

Table 27. Used Combination of Labels
Used labels	`:GraphQL:Input:Object:Type`

Table 28. Relations of an Input Object Type
Relation Name	Target Node	Cardinality	Description
`DECLARES_FIELD`	Input Field	1..n	References the declared input fields.

2.18. Input Field

Represents a GraphQL Input Field, having similar properties and relations.

Table 29. Used Combination of Labels
Used labels	`:GraphQL:Input:Field`

2.19. Input Value Definition

Defines an input value.

Table 30. Used Combination of Labels
Used labels	`:GraphQL:Input:ValueDefinition`

Table 31. Relations of an Input Value Definition
Relation Name	Target Node	Cardinality	Description
`OF_TYPE`	Of Type (Relation)	1	The relation to the type.
`HAS_DEFAULT_VALUE`	Value	0..1	References the default value.
`DECLARES_DIRECTIVE`	Directive Value	0..n	References to the declared directive values

Table 32. Properties of :GraphQL:Input:ValueDefinition
Property Name	Existence	Description
`index`	always	The index number (starting with 0).
`name`	always	The name.
`description`	not always	The optional description as provided in the GraphQL schema.
`line`	not always	The optional line number of the source location within the GraphQL schema.
`column`	not always	The optional column of the source location within the GraphQL schema.

2.20. Union Type

Represents a GraphQL Union Type.

Table 33. Used Combination of Labels
Used labels	`:GraphQL:Union:Type`

Table 34. Relations of an Union Type
Relation Name	Target Node	Cardinality	Description
`DECLARES_TYPE`	Union Declares Type	1..n	References the declared GraphQL fields

2.21. Union Declares Type

References a GraphQL type indicating the index of the relation.

Table 35. Relation to a GraphQL Type
Relation Name	Target Node Type
`DECLARES_TYPE`	Type

Table 36. Properties of :DECLARES_TYPE
Property Name	Existence	Description
`index`	always	The index number (starting with 0).

2.22. List Type

Represents a GraphQL list Type that declares an element Type.

Table 37. Used Combination of Labels
Used labels	`:GraphQL:List:Type`

Table 38. Relations of a GraphQL List Type
Relation Name	Target Node Type	Cardinality	Description
`OF_ELEMENT_TYPE`	Of Type (Relation)	1	References the field type

2.23. Of Element Type Relation

References a GraphQL type indicating if this reference is nullable.

Table 39. Relation to a GraphQL Type
Relation Name	Target Node Type
`OF_ELEMENT_TYPE`	Type

Table 40. Properties of :OF_TYPE
Property Name	Existence	Description
`nonNull`	always	If `true` the reference is not nullable.

2.24. Directive Type

Represents a directive Type that is defined within a GraphQL schema.

Table 41. Used Combination of Labels
Used labels	`:GraphQL:Directive:Type`

Table 42. Relations of a GraphQL Directive Type
Relation Name	Target Node	Cardinality	Description
`DECLARES_LOCATION`	Directive Location	1..n	References the allowed locations the directive can be applied to.
`DEFINES_INPUT_VALUE`	Input Value Definition	0..n	References the declared GraphQL input value definitions

2.25. Directive Value

Represents a directive that is present at an element of the GraphQL schema.

Table 43. Used Combination of Labels
Used labels	`:GraphQL:Directive:Value`

Table 44. Relations of a GraphQL Directive Value
Relation Name	Target Node	Cardinality	Description
`OF_TYPE`	Directive Type	1	References the type of the directive
`HAS_ARGUMENT`	Argument	0..n	References arguments of the directive

2.26. Directive Location

Represents the allowed locations for a directive.

Table 45. Used Combination of Labels
Used labels	`:GraphQL:Directive:Location`

Table 46. Properties of :GraphQL:Directive:Location
Property Name	Existence	Description
`name`	always	The name.

2.27. Argument

Represents an argument of a GraphQL directive.

Table 47. Used Combination of Labels
Used labels	`:GraphQL:Argument`

Table 48. Relations of a GraphQL Argument
Relation Name	Target Node	Cardinality	Description
`HAS_VALUE`	Value	1	References the argument value.
`OF_INPUT_VALUE`	Input Value Definition	1	References the input value defined for this argument.

Table 49. Properties of :GraphQL:Argument
Property Name	Existence	Description
`index`	always	The index number (starting with 0).

3. 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 of 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.

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.

3.1. The Model

Entity Used Combination of Labels

YAML Document

:Yaml:Document

YAML File (.yaml or .yml extension)

:Yaml:File

YAML Map

:Yaml:Key:Simple

Complex Key

:Yaml:Key:Complex

YAML Map

:Yaml:Map

:Yaml:Value

:Yaml:Sequence

:Yaml:Item

:Yaml:Alias

:Yaml:Anchor

3.2. A YAML File

A file with the the extension .yaml or .yml, which can contain multiple YAML documents.

Table 50. Used Combination of Labels
Used labels	`:Yaml:File`

Table 51. Relations of a YAML file
Relation Name	Target Node	Cardinality	Description
`HAS_DOCUMENT`	Document	0..n	References all YAML documents contained in this file

Table 52. Properties of a YAML File
Property Name	Existence	Description
`valid`	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.

3.3. A YAML 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.

A YAML document with document prefix --- and suffix …

---
# Comments are not handled by jQAssistant
NX-01: Jonathan Archer
NCC-1701-A: James Tiberius Kirk
NCC-1701-D: Jean-Luc Picard
...

Table 53. Used Combination of Labels
Used labels	`:Yaml:Document`

Table 54. Relations of :Yaml:Document
Relation Name	Target Node Type	Cardinality	Description
`HAS_SEQUENCE`	Sequence	0..1	Reference to a sequence in the YAML document
`HAS_MAP`	Map	0..1	Reference to a map in the YAML document
`HAS_SCALAR`	Scalar	0..1	Reference to a scalar in the YAML document

3.4. A Scalar

A scalar value as described in the YAML 1.2 specification.

Table 55. Used Combination of Labels
Used labels	`:Yaml:Scalar`

Table 56. Properties of :Yaml:Map
Property Name	Existence	Description
`index`	not always	Position of the element in document order in a sequence. The `index` property is only a available if this element is an item in a sequence.
`value`	always	The scalar value itself

3.5. A Sequence

A sequence as specified in the YAML 1.2 specification. Each item of sequence has an additional label :Item.

A Sequence with two maps as items

- Humans: Earth
- Hirogen: Delta quadrant

Table 57. Used Combination of Labels
Used labels	`:Yaml:Sequence`

Table 58. Relations of a Sequence
Relation Name	Target Node Type	Cardinality	Description
`HAS_ITEM`	Scalar, Sequence or Map	1..n	Reference to an item in the sequence. The item can be either a scalar, a sequence or a map.

Table 59. Properties of :Yaml:Sequence
Property Name	Existence	Description
`index`	not always	Position of the element in document order in a sequence. The `index` property is only a available if this element is an item in a sequence.

3.6. An Item in a Sequence

Each item of a sequence is also labled with :Item.

Table 60. Used Combination of Labels
Used labels	`:Yaml:Item`

Table 61. Additional Labels of an Item
Label	Existence	Description
`:Yaml:Last`	not always	The last item in a sequence in document order carries also the label `:Last`
`:Yaml:First`	not always	The first item in a sequence in document order carries also the label `:First`

3.7. A 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.

A map in a YAML document with three key-value-pairs

weight: 91
length: 103
height: 44

Table 62. Used Combination of Labels
Used labels	`:Yaml:Map`

Table 63. Relations of a map
Relation Name	Target Node Type	Cardinality	Description
`HAS_KEY`	Simple key or complex key	1..n	Reference to key or a compley key in the map

Table 64. Properties of a Map
Property Name	Existence	Description
`index`	not always	Position of the element in document order in a sequence. The `index` property is only a available if this element is an item in a sequence.

3.8. 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.

A map with a simple key and a complex key in the same map

simpleKey: "Value for a simple key"
? - combined
  - key
: "Value for a complex key"

Table 65. Used Combination of Labels
Used labels	`:Yaml:Key:Simple`

Table 66. Relations of a simple key
Relation Name	Target Node	Cardinality	Description
`HAS_VALUE`	Map, Sequence or Scalar	0..1	Reference to the value of this key-value pair

Table 67. Properties of simple key
Property Name	Existence	Description
`index`	not always	Position of the element in document order in a sequence. The `index` property is only a available if this element is an item in a sequence.
`name`	always	The name of a key as scalar value

3.9. 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.

A map with two complex keys

simpleKey: "Value for a simple key"
? - Vulcan
  - ShiKahr District
: Spock
? - Earth
  - North America
: James T. Kirk

Table 68. Used Combination of Labels
Used labels	`:Yaml:Key:Complex`

Table 69. Relations of a complex key
Relation Name	Target Node	Cardinality	Description
`HAS_VALUE`	Map, Sequence or Scalar	0..1	Reference to the value of this key-value pair

3.10. A value in a map

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 labled with :Value.

Table 70. Used Combination of Labels
Used labels	`:Yaml:Value`

3.11. An Anchor

An anchor as specified in the YAML 1.2 specification, used to mark content in a YAML document for future reuse in the same document.

A Map with reused Content

"James T. Kirk" : &ufp "United Federation of Planets"
"Hikaru Kato Sulu" : *ufp

The resulting Map after processing all Anchors and Aliases

"James T. Kirk" : "United Federation of Planets"
"Hikaru Kato Sulu" : "United Federation of Planets"

Table 71. Used Combination of Labels
Used labels	`:Yaml:Anchor`

Table 72. Properties of an Anchor
Property Name	Existence	Description
`anchorName`	always	The name of the anchor
`index`	not always	Position of the element in document order in a sequence. The `index` property is only a available if this element is an item in a sequence.

3.12. An Alias

An alias as specified in the YAML 1.2 specification, used to reuse previously marked content in a document.

A Map with reused Content

"James T. Kirk" : &ufp "United Federation of Planets"
"Hikaru Kato Sulu" : *ufp

Table 73. Used Combination of Labels
Used labels	`:Yaml:Alias`

Table 74. Relations of an Alias
Relation Name	Target Node Type	Cardinality	Description
`IS_ALIAS_FOR`	Anchor	1	Reference to the anchor of this alias in the YAML document

Table 75. Properties of an Alias
Property Name	Existence	Description
`index`	not always	Position of the element in document order in a sequence. The `index` property is only a available if this element is an item in a sequence.