You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: doc/walkers.md
+83-28Lines changed: 83 additions & 28 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,14 +2,14 @@
2
2
3
3
There can be use-cases where we need the capability to walk through the given JsonNode allowing functionality beyond validation like collecting information,handling cross cutting concerns like logging or instrumentation. JSON walkers were introduced to complement the validation functionality this library already provides.
4
4
5
-
Currently walking is defined at the validator instance level for all the built-in keywords.
5
+
Currently, walking is defined at the validator instance level for all the built-in keywords.
6
6
7
7
### Walk methods
8
8
9
9
A new interface is introduced into the library that a Walker should implement. It should be noted that this interface also allows the validation based on shouldValidateSchema parameter.
10
10
11
-
```
12
-
public interface JsonWalker {
11
+
```java
12
+
publicinterfaceJsonSchemaWalker {
13
13
/**
14
14
*
15
15
* This method gives the capability to walk through the given JsonNode, allowing
@@ -33,9 +33,9 @@ public interface JsonWalker {
33
33
34
34
```
35
35
36
-
The JSONValidator interface extends this new interface thus allowing all the validator's defined in library to implement this new interface. A default implementation of the walk method is provided in BaseJsonValidator class. In this case the walk method does nothing but validating based on shouldValidateSchema parameter.
36
+
The JSONValidator interface extends this new interface thus allowing all the validator's defined in library to implement this new interface. BaseJsonValidator class provides a default implementation of the walk method. In this case the walk method does nothing but validating based on shouldValidateSchema parameter.
37
37
38
-
```
38
+
```java
39
39
/**
40
40
* This is default implementation of walk method. Its job is to call the
41
41
* validate method if shouldValidateSchema is enabled.
@@ -51,9 +51,9 @@ The JSONValidator interface extends this new interface thus allowing all the val
51
51
52
52
```
53
53
54
-
A new walk method is introduced into JSONSchema class that allows us to walk through the JSONSchema.
54
+
A new walk method added to the JSONSchema class allows us to walk through the JSONSchema.
@@ -97,46 +97,46 @@ ValidationResult result = jsonSchema.walk(data,false);
97
97
98
98
```
99
99
100
-
walk method can be overridden for select validator's based on the use-case. Currently walk method has been overridden in PropertiesValidator,ItemsValidator,AllOfValidator,NotValidator,PatternValidator,RefValidator,AdditionalPropertiesValidator to accommodate the walk logic of the enclosed schema's.
100
+
walk method can be overridden for select validator's based on the use-case. Currently, walk method has been overridden in PropertiesValidator,ItemsValidator,AllOfValidator,NotValidator,PatternValidator,RefValidator,AdditionalPropertiesValidator to accommodate the walk logic of the enclosed schema's.
101
101
102
102
### Walk Listeners
103
103
104
-
Walk listeners allows to execute a custom logic before and after a JsonWalker walk method is called. Walk listeners are modeled by a WalkListener interface.
104
+
Walk listeners allows to execute a custom logic before and after the invocation of a JsonWalker walk method. Walk listeners can be modeled by a WalkListener interface.
105
105
106
-
```
107
-
public interface WalkListener {
106
+
```java
107
+
publicinterfaceJsonSchemaWalkListener {
108
108
109
-
public boolean onWalkStart(WalkEvent walkEvent);
109
+
publicWalkFlowonWalkStart(WalkEventwalkEvent);
110
110
111
-
public void onWalkEnd(WalkEvent walkEvent, Set<ValidationMessage> validationMessages);
There are two kinds of walk listeners, keyword walk listeners and property walk listeners. Keyword walk listeners are called whenever the given keyword is encountered while walking the schema and JSON node data, for example we have added Ref and Property keyword walk listeners in the above example. Property walk listeners are called for every property defined in the JSON node data.
152
+
There are two kinds of walk listeners, keyword walk listeners and property walk listeners. Keyword walk listeners will be called whenever the given keyword is encountered while walking the schema and JSON node data, for example we have added Ref and Property keyword walk listeners in the above example. Property walk listeners are called for every property defined in the JSON node data.
153
153
154
-
Both property walk listeners and keyword walk listener are modeled by using the same WalkListener interface. Following is an example of how to add a property walk listener.
154
+
Both property walk listeners and keyword walk listener can be modeled by using the same WalkListener interface. Following is an example of how to add a property walk listener.
1. onWalkStart and onWalkEnd are the methods defined in the property walk listener
233
+
2.Anywhere during the flow, onWalkStart can return a WalkFlow.SKIP to stop the walk method execution of a particular "property schema".
234
+
3. onWalkEnd will be called even if the onWalkStart returns a WalkFlow.SKIP.
235
+
4.Walking a property will check if the keywords defined in the "property schema" has any keyword listeners, and they will be called in the defined order.
236
+
For example in the above schema when we walk through the "name" property if there are any keyword listeners defined for"type" or "maxlength" , they will be invoked in the defined order.
237
+
5.Since we have a property listener defined, When we are walking through a property that has a "$ref" keyword which might have some more properties defined,
238
+
Our property listener would be invoked for each of the property defined in the "$ref" schema.
239
+
6.As mentioned earlier anywhere during the "Walk Flow", we can return a WalkFlow.SKIP from onWalkStart method to stop the walk method of a particular "property schema" from being called.
240
+
Since the walk method will not be called any property or keyword listeners in the "property schema" will not be invoked.
0 commit comments