001/*
002 * SPDX-FileCopyrightText: none
003 * SPDX-License-Identifier: CC0-1.0
004 */
005
006package dev.metaschema.databind.model.annotations;
007
008import static java.lang.annotation.ElementType.ANNOTATION_TYPE;
009import static java.lang.annotation.RetentionPolicy.RUNTIME;
010
011import java.lang.annotation.Documented;
012import java.lang.annotation.Retention;
013import java.lang.annotation.Target;
014
015import dev.metaschema.core.model.constraint.IConstraint;
016import dev.metaschema.core.model.constraint.IConstraint.Level;
017import edu.umd.cs.findbugs.annotations.NonNull;
018
019/**
020 * This annotation defines a report condition in the context of the containing
021 * annotation.
022 * <p>
023 * Report constraints generate findings when their test expression evaluates to
024 * {@code true}, which is the opposite of expect constraints.
025 */
026@Documented
027@Retention(RUNTIME)
028@Target(ANNOTATION_TYPE)
029public @interface Report {
030  /**
031   * An optional identifier for the constraint, which must be unique to only this
032   * constraint.
033   *
034   * @return the identifier if provided or an empty string otherwise
035   */
036  @NonNull
037  String id() default "";
038
039  /**
040   * An optional formal name for the constraint.
041   *
042   * @return the formal name if provided or an empty string otherwise
043   */
044  @NonNull
045  String formalName() default "";
046
047  /**
048   * An optional description of the constraint.
049   *
050   * @return the description if provided or an empty string otherwise
051   */
052  @NonNull
053  String description() default "";
054
055  /**
056   * The significance of a violation of this constraint.
057   * <p>
058   * The default level for report constraints is {@link Level#INFORMATIONAL},
059   * which differs from expect constraints that default to {@link Level#ERROR}.
060   *
061   * @return the level
062   */
063  @NonNull
064  Level level() default IConstraint.Level.INFORMATIONAL;
065
066  /**
067   * An optional metapath that points to the target flag or field value that the
068   * constraint applies to. If omitted the target will be ".", which means the
069   * target is the value of the {@link BoundFlag}, {@link BoundField} or
070   * {@link BoundFieldValue} annotation the constraint appears on. In the prior
071   * case, this annotation may only appear on a {@link BoundField} if the field
072   * has no flags, which results in a {@link BoundField} annotation on a field
073   * instance with a scalar, data type value.
074   *
075   * @return the target metapath
076   */
077  @NonNull
078  String target() default ".";
079
080  /**
081   * An optional set of properties associated with this constraint.
082   *
083   * @return the properties or an empty array with no properties
084   */
085  Property[] properties() default {};
086
087  /**
088   * A metapath that is expected to evaluate to {@code true} when a finding should
089   * be reported.
090   * <p>
091   * This is the opposite of expect constraints - report constraints fire when the
092   * test is true.
093   *
094   * @return a metapath expression
095   */
096  @NonNull
097  String test();
098
099  /**
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}