Now with examples

Author: bbakerman

readme.md

@@ -1,6 +1,6 @@
 # Extended Validation for graphql-java
 
-This library provides extended validation for [graphql-java](https://github.com/graphql-java/graphql-java)
+This library provides extended validation of fields and field arguments for [graphql-java](https://github.com/graphql-java/graphql-java)
 
 
 # Status
@@ -13,16 +13,14 @@ But the project welcomes all feedback and input on code design and validation re
 
 TODO
 
-# SDL @Directive validation
+# SDL @Directive constraints
 
-This library a series of directives that can be applied to field arguments and input type fields which will constrain the values
+This library a series of directives that can be applied to field arguments and input type fields which will constrain their allowable values.
 
 These names and semantics are inspired from the javax.validation annotations
 
 https://javaee.github.io/javaee-spec/javadocs/javax/validation/constraints/package-summary.html
 
-## SDL directives
-
 You can add these onto arguments or input types in your graphql SDL.
 
 For example
@@ -44,113 +42,215 @@ For example
     }
 ```
 
-In the example above, we have a `applications` argument that takes at most 10 applications and within each `Application` input object
+In the example above, we have a `applications` argument that takes at most 10 applications and within each `Application` input object,
 the `name` field must be at least 3 characters long and no more than 100 characters long to be considered valid. 
 
 
-## The library supplied directives
+## The supplied constraints
 
-### AssertFalse
+### @AssertFalse
 
 The boolean value must be false.
 
-- SDL :  `directive @AssertFalse(message : String = "graphql.validation.AssertFalse.message") on ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION`
-- Applies to :  `Boolean`
+- Example : `driver( isDrunk : Boolean @AssertFalse) : DriverDetails`
+
+- Applies to : `Boolean`
+
+- SDL : directive @AssertFalse(message : String = "graphql.validation.AssertFalse.message") on ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION
+
+- Message : `graphql.validation.AssertFalse.message`
+
 
-### AssertTrue
+### @AssertTrue
 
 The boolean value must be true.
 
-- SDL :  `directive @AssertTrue(message : String = "graphql.validation.AssertTrue.message") on ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION`
-- Applies to :  `Boolean`
+- Example : `driver( hasLicence : Boolean @AssertTrue) : DriverDetails`
+
+- Applies to : `Boolean`
+
+- SDL : directive @AssertTrue(message : String = "graphql.validation.AssertTrue.message") on ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION
+
+- Message : `graphql.validation.AssertTrue.message`
+
 
-### DecimalMax
+### @DecimalMax
 
 The element must be a number whose value must be less than or equal to the specified maximum.
 
-- SDL :  `directive @DecimalMax(value : String!, inclusive : Boolean! = true, message : String = "graphql.validation.DecimalMax.message") on ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION`
-- Applies to :  `String`, `Byte`, `Short`, `Int`, `Long`, `BigDecimal`, `BigInteger`, `Float`
+- Example : `driver( bloodAlcoholLevel : Float @DecimalMax(value : "0.05") : DriverDetails`
 
-### DecimalMin
+- Applies to : `String`, `Byte`, `Short`, `Int`, `Long`, `BigDecimal`, `BigInteger`, `Float`
+
+- SDL : directive @DecimalMax(value : String!, inclusive : Boolean! = true, message : String = "graphql.validation.DecimalMax.message") on ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION
+
+- Message : `graphql.validation.DecimalMax.message`
+
+
+### @DecimalMin
 
 The element must be a number whose value must be greater than or equal to the specified minimum.
 
-- SDL :  `directive @DecimalMin(value : String!, inclusive : Boolean! = true, message : String = "graphql.validation.DecimalMin.message") on ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION`
-- Applies to :  `String`, `Byte`, `Short`, `Int`, `Long`, `BigDecimal`, `BigInteger`, `Float`
+- Example : `driver( carHorsePower : Float @DecimalMin(value : "300.50") : DriverDetails`
+
+- Applies to : `String`, `Byte`, `Short`, `Int`, `Long`, `BigDecimal`, `BigInteger`, `Float`
+
+- SDL : directive @DecimalMin(value : String!, inclusive : Boolean! = true, message : String = "graphql.validation.DecimalMin.message") on ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION
+
+- Message : `graphql.validation.DecimalMin.message`
+
 
-### Digits
+### @Digits
 
 The element must be a number inside the specified `integer` and `fraction` range.
 
-- SDL :  `directive @Digits(integer : Int!, fraction : Int!, message : String = "graphql.validation.Digits.message") on ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION`
-- Applies to :  `String`, `Byte`, `Short`, `Int`, `Long`, `BigDecimal`, `BigInteger`, `Float`
+- Example : `driver( carCost : Float @Digits(integer : 5, fraction : 2) : DriverDetails`
 
-### Max
+- Applies to : `String`, `Byte`, `Short`, `Int`, `Long`, `BigDecimal`, `BigInteger`, `Float`
+
+- SDL : directive @Digits(integer : Int!, fraction : Int!, message : String = "graphql.validation.Digits.message") on ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION
+
+- Message : `graphql.validation.Digits.message`
+
+
+### @Max
 
 The element must be a number whose value must be less than or equal to the specified maximum.
 
-- SDL :  `directive @Max(value : Int! = 2147483647, message : String = "graphql.validation.Max.message") on ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION`
-- Applies to :  `Byte`, `Short`, `Int`, `Long`, `BigDecimal`, `BigInteger`, `Float`
+- Example : `driver( horsePower : Float @Max(value : 1000) : DriverDetails`
+
+- Applies to : `Byte`, `Short`, `Int`, `Long`, `BigDecimal`, `BigInteger`, `Float`
 
-### Min
+- SDL : directive @Max(value : Int! = 2147483647, message : String = "graphql.validation.Max.message") on ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION
+
+- Message : `graphql.validation.Max.message`
+
+
+### @Min
 
 The element must be a number whose value must be greater than or equal to the specified minimum.
 
-- SDL :  `directive @Min(value : Int! = 0, message : String = "graphql.validation.Min.message") on ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION`
-- Applies to :  `Byte`, `Short`, `Int`, `Long`, `BigDecimal`, `BigInteger`, `Float`
+- Example : `driver( age : Int @Min(value : 18) : DriverDetails`
+
+- Applies to : `Byte`, `Short`, `Int`, `Long`, `BigDecimal`, `BigInteger`, `Float`
 
-### Negative
+- SDL : directive @Min(value : Int! = 0, message : String = "graphql.validation.Min.message") on ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION
+
+- Message : `graphql.validation.Min.message`
+
+
+### @Negative
 
 The element must be a negative number.
 
-- SDL :  `directive @Negative(message : String = "graphql.validation.Negative.message") on ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION`
-- Applies to :  `Byte`, `Short`, `Int`, `Long`, `BigDecimal`, `BigInteger`, `Float`
+- Example : `driver( licencePoints : Int @Negative) : DriverDetails`
+
+- Applies to : `Byte`, `Short`, `Int`, `Long`, `BigDecimal`, `BigInteger`, `Float`
 
-### NegativeOrZero
+- SDL : directive @Negative(message : String = "graphql.validation.Negative.message") on ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION
+
+- Message : `graphql.validation.Negative.message`
+
+
+### @NegativeOrZero
 
 The element must be a negative number or zero.
 
-- SDL :  `directive @NegativeOrZero(message : String = "graphql.validation.NegativeOrZero.message") on ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION`
-- Applies to :  `Byte`, `Short`, `Int`, `Long`, `BigDecimal`, `BigInteger`, `Float`
+- Example : `driver( licencePoints : Int @NegativeOrZero) : DriverDetails`
+
+- Applies to : `Byte`, `Short`, `Int`, `Long`, `BigDecimal`, `BigInteger`, `Float`
 
-### NotBlank
+- SDL : directive @NegativeOrZero(message : String = "graphql.validation.NegativeOrZero.message") on ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION
+
+- Message : `graphql.validation.NegativeOrZero.message`
+
+
+### @NotBlank
 
 The String must contain at least one non-whitespace character, according to Java's Character.isWhitespace().
 
-- SDL :  `directive @NotBlank(message : String = "graphql.validation.NotBlank.message") on ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION`
-- Applies to :  `String`
+- Example : `updateAccident( accidentNotes : String @NotBlank) : DriverDetails`
+
+- Applies to : `String`
+
+- SDL : directive @NotBlank(message : String = "graphql.validation.NotBlank.message") on ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION
 
-### NotEmpty
+- Message : `graphql.validation.NotBlank.message`
+
+
+### @NotEmpty
 
 The element must have a non zero size.
 
-- SDL :  `directive @NotEmpty(message : String = "graphql.validation.NotEmpty.message") on ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION`
-- Applies to :  `String`, `Lists`, `Input Objects`
+- Example : `updateAccident( accidentNotes : [Notes]! @NotEmpty) : DriverDetails`
+
+- Applies to : `String`, `Lists`, `Input Objects`
+
+- SDL : directive @NotEmpty(message : String = "graphql.validation.NotEmpty.message") on ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION
 
-### Pattern
+- Message : `graphql.validation.NotEmpty.message`
+
+
+### @Pattern
 
 The String must match the specified regular expression, which follows the Java regular expression conventions.
 
-- SDL :  `directive @Pattern(pattern : String! =".*", message : String = "graphql.validation.Pattern.message") on ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION`
-- Applies to :  `String`
+- Example : `updateDriver( licencePlate : String @Patttern(regex : "[A-Z][A-Z][A-Z]-[0-9][0-9][0-9]") : DriverDetails`
+
+- Applies to : `String`
+
+- SDL : directive @Pattern(regexp : String! =".*", message : String = "graphql.validation.Pattern.message") on ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION
 
-### Positive
+- Message : `graphql.validation.Pattern.message`
+
+
+### @Positive
 
 The element must be a positive number.
 
-- SDL :  `directive @Positive(message : String = "graphql.validation.Positive.message") on ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION`
-- Applies to :  `Byte`, `Short`, `Int`, `Long`, `BigDecimal`, `BigInteger`, `Float`
+- Example : `driver( licencePoints : Int @Positive) : DriverDetails`
+
+- Applies to : `Byte`, `Short`, `Int`, `Long`, `BigDecimal`, `BigInteger`, `Float`
+
+- SDL : directive @Positive(message : String = "graphql.validation.Positive.message") on ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION
 
-### PositiveOrZero
+- Message : `graphql.validation.Positive.message`
+
+
+### @PositiveOrZero
 
 The element must be a positive number or zero.
 
-- SDL :  `directive @PositiveOrZero(message : String = "graphql.validation.PositiveOrZero.message") on ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION`
-- Applies to :  `Byte`, `Short`, `Int`, `Long`, `BigDecimal`, `BigInteger`, `Float`
+- Example : `driver( licencePoints : Int @PositiveOrZero) : DriverDetails`
+
+- Applies to : `Byte`, `Short`, `Int`, `Long`, `BigDecimal`, `BigInteger`, `Float`
+
+- SDL : directive @PositiveOrZero(message : String = "graphql.validation.PositiveOrZero.message") on ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION
+
+- Message : `graphql.validation.PositiveOrZero.message`
+
+
+### @Range
+
+The element range must be between the specified `min` and `max` boundaries (inclusive).  It accepts numbers and strings that represent numerical values.
 
-### Size
+- Example : `driver( milesTravelled : Int @Range( min : 1000, max : 100000)) : DriverDetails`
+
+- Applies to : `String`, `Byte`, `Short`, `Int`, `Long`, `BigDecimal`, `BigInteger`, `Float`
+
+- SDL : directive @Range(min : Int = 0, max : Int = 2147483647, message : String = "graphql.validation.Range.message") on ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION
+
+- Message : `graphql.validation.Range.message`
+
+
+### @Size
 
 The element size must be between the specified `min` and `max` boundaries (inclusive).
 
-- SDL :  `directive @Size(min : Int = 0, max : Int = 2147483647, message : String = "graphql.validation.Size.message") on ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION`
-- Applies to :  `String`, `Lists`, `Input Objects`
+- Example : `updateDriver( drivingNote : String @Size( min : 1000, max : 100000)) : DriverDetails`
+
+- Applies to : `String`, `Lists`, `Input Objects`
+
+- SDL : directive @Size(min : Int = 0, max : Int = 2147483647, message : String = "graphql.validation.Size.message") on ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION
+
+- Message : `graphql.validation.Size.message`

src/main/java/graphql/validation/constraints/DirectiveConstraint.java

@@ -13,14 +13,34 @@
 @PublicSpi
 public interface DirectiveConstraint extends ValidationRule {
 
+    /**
+     * @return the name of the constraint
+     */
     String getName();
 
+    /**
+     * @return a description for documentation
+     */
     String getDescription();
 
+    /**
+     * @return a description for documentation
+     */
+    String getExample();
+
+    /**
+     * @return the graphql SDL directive declaration syntax
+     */
     String getDirectiveDeclarationSDL();
 
+    /**
+     * @return the message template name
+     */
     String getMessageTemplate();
 
+    /**
+     * @return a list of the names of applicable types
+     */
     List<String> getApplicableTypeNames();
 
 }

src/main/java/graphql/validation/constraints/standard/AssertFalseConstraint.java

@@ -13,6 +13,11 @@ public String getDirectiveDeclarationSDL() {
                 getMessageTemplate());
     }
 
+    @Override
+    public String getExample() {
+        return "driver( isDrunk : Boolean @AssertFalse) : DriverDetails";
+    }
+
     @Override
     public String getDescription() {
         return "The boolean value must be false.";

src/main/java/graphql/validation/constraints/standard/AssertTrueConstraint.java

@@ -13,6 +13,11 @@ public String getDirectiveDeclarationSDL() {
                 getMessageTemplate());
     }
 
+    @Override
+    public String getExample() {
+        return "driver( hasLicence : Boolean @AssertTrue) : DriverDetails";
+    }
+
     @Override
     public String getDescription() {
         return "The boolean value must be true.";

src/main/java/graphql/validation/constraints/standard/DecimalMaxConstraint.java

@@ -17,6 +17,12 @@ public String getDirectiveDeclarationSDL() {
     public String getDescription() {
         return "The element must be a number whose value must be less than or equal to the specified maximum.";
     }
+
+    @Override
+    public String getExample() {
+        return "driver( bloodAlcoholLevel : Float @DecimalMax(value : \"0.05\") : DriverDetails";
+    }
+
     @Override
     protected boolean isOK(boolean inclusive, int comparisonResult) {
         return inclusive ? comparisonResult <= 0 : comparisonResult < 0;

src/main/java/graphql/validation/constraints/standard/DecimalMinConstraint.java

@@ -18,6 +18,12 @@ public String getDescription() {
         return "The element must be a number whose value must be greater than or equal to the specified minimum.";
     }
 
+    @Override
+    public String getExample() {
+        return "driver( carHorsePower : Float @DecimalMin(value : \"300.50\") : DriverDetails";
+    }
+
+
     @Override
     protected boolean isOK(boolean inclusive, int comparisonResult) {
         return inclusive ? comparisonResult >= 0 : comparisonResult > 0;

src/main/java/graphql/validation/constraints/standard/DigitsConstraint.java

@@ -61,6 +61,12 @@ public String getDescription() {
         return "The element must be a number inside the specified `integer` and `fraction` range.";
     }
 
+    @Override
+    public String getExample() {
+        return "driver( carCost : Float @Digits(integer : 5, fraction : 2) : DriverDetails";
+    }
+
+
     @Override
     public List<GraphQLError> runValidation(ValidationEnvironment validationEnvironment) {
         Object validatedValue = validationEnvironment.getValidatedValue();