1   /*
2    * SPDX-FileCopyrightText: none
3    * SPDX-License-Identifier: CC0-1.0
4    */
5   
6   package dev.metaschema.databind.model.annotations;
7   
8   import static java.lang.annotation.ElementType.ANNOTATION_TYPE;
9   import static java.lang.annotation.RetentionPolicy.RUNTIME;
10  
11  import java.lang.annotation.Documented;
12  import java.lang.annotation.Retention;
13  import java.lang.annotation.Target;
14  
15  import dev.metaschema.core.model.constraint.IConstraint;
16  import dev.metaschema.core.model.constraint.IConstraint.Level;
17  import edu.umd.cs.findbugs.annotations.NonNull;
18  
19  /**
20   * This annotation defines a report condition in the context of the containing
21   * annotation.
22   * <p>
23   * Report constraints generate findings when their test expression evaluates to
24   * {@code true}, which is the opposite of expect constraints.
25   */
26  @Documented
27  @Retention(RUNTIME)
28  @Target(ANNOTATION_TYPE)
29  public @interface Report {
30    /**
31     * An optional identifier for the constraint, which must be unique to only this
32     * constraint.
33     *
34     * @return the identifier if provided or an empty string otherwise
35     */
36    @NonNull
37    String id() default "";
38  
39    /**
40     * An optional formal name for the constraint.
41     *
42     * @return the formal name if provided or an empty string otherwise
43     */
44    @NonNull
45    String formalName() default "";
46  
47    /**
48     * An optional description of the constraint.
49     *
50     * @return the description if provided or an empty string otherwise
51     */
52    @NonNull
53    String description() default "";
54  
55    /**
56     * The significance of a violation of this constraint.
57     * <p>
58     * The default level for report constraints is {@link Level#INFORMATIONAL},
59     * which differs from expect constraints that default to {@link Level#ERROR}.
60     *
61     * @return the level
62     */
63    @NonNull
64    Level level() default IConstraint.Level.INFORMATIONAL;
65  
66    /**
67     * An optional metapath that points to the target flag or field value that the
68     * constraint applies to. If omitted the target will be ".", which means the
69     * target is the value of the {@link BoundFlag}, {@link BoundField} or
70     * {@link BoundFieldValue} annotation the constraint appears on. In the prior
71     * case, this annotation may only appear on a {@link BoundField} if the field
72     * has no flags, which results in a {@link BoundField} annotation on a field
73     * instance with a scalar, data type value.
74     *
75     * @return the target metapath
76     */
77    @NonNull
78    String target() default ".";
79  
80    /**
81     * An optional set of properties associated with this constraint.
82     *
83     * @return the properties or an empty array with no properties
84     */
85    Property[] properties() default {};
86  
87    /**
88     * A metapath that is expected to evaluate to {@code true} when a finding should
89     * be reported.
90     * <p>
91     * This is the opposite of expect constraints - report constraints fire when the
92     * test is true.
93     *
94     * @return a metapath expression
95     */
96    @NonNull
97    String test();
98  
99    /**
100    * The message to emit when the constraint is violated.
101    *
102    * @return the message or an empty string otherwise
103    */
104   @NonNull
105   String message() default "";
106 
107   /**
108    * Any remarks about the constraint, encoded as an escaped Markdown string.
109    *
110    * @return an encoded markdown string or an empty string if no remarks are
111    *         provided
112    */
113   @NonNull
114   String remarks() default "";
115 }