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 an expected condition to be met in the context of the
21   * containing annotation.
22   */
23  @Documented
24  @Retention(RUNTIME)
25  @Target(ANNOTATION_TYPE)
26  public @interface Expect {
27    /**
28     * An optional identifier for the constraint, which must be unique to only this
29     * constraint.
30     *
31     * @return the identifier if provided or an empty string otherwise
32     */
33    @NonNull
34    String id() default "";
35  
36    /**
37     * An optional formal name for the constraint.
38     *
39     * @return the formal name if provided or an empty string otherwise
40     */
41    @NonNull
42    String formalName() default "";
43  
44    /**
45     * An optional description of the constraint.
46     *
47     * @return the description if provided or an empty string otherwise
48     */
49    @NonNull
50    String description() default "";
51  
52    /**
53     * The significance of a violation of this constraint.
54     *
55     * @return the level
56     */
57    @NonNull
58    Level level() default IConstraint.Level.ERROR;
59  
60    /**
61     * An optional metapath that points to the target flag or field value that the
62     * constraint applies to. If omitted the target will be ".", which means the
63     * target is the value of the {@link BoundFlag}, {@link BoundField} or
64     * {@link BoundFieldValue} annotation the constraint appears on. In the prior
65     * case, this annotation may only appear on a {@link BoundField} if the field
66     * has no flags, which results in a {@link BoundField} annotation on a field
67     * instance with a scalar, data type value.
68     *
69     * @return the target metapath
70     */
71    @NonNull
72    String target() default ".";
73  
74    /**
75     * An optional set of properties associated with these allowed values.
76     *
77     * @return the properties or an empty array with no properties
78     */
79    Property[] properties() default {};
80  
81    /**
82     * A metapath that is expected to evaluate to {@code true} in this context.
83     *
84     * @return a metapath expression
85     */
86    @NonNull
87    String test();
88  
89    /**
90     * The message to emit when the constraint is violated.
91     *
92     * @return the message or an empty string otherwise
93     */
94    @NonNull
95    String message() default "";
96  
97    /**
98     * Any remarks about the constraint, encoded as an escaped Markdown string.
99     *
100    * @return an encoded markdown string or an empty string if no remarks are
101    *         provided
102    */
103   @NonNull
104   String remarks() default "";
105 }