1   /*
2    * SPDX-FileCopyrightText: none
3    * SPDX-License-Identifier: CC0-1.0
4    */
5   
6   package dev.metaschema.core.model;
7   
8   import dev.metaschema.core.datatype.markup.MarkupLine;
9   import edu.umd.cs.findbugs.annotations.Nullable;
10  
11  /**
12   * Represents a model element that has a formal name and description.
13   * <p>
14   * This interface provides access to human-readable documentation properties
15   * that describe the purpose and usage of a model element.
16   */
17  public interface IDescribable {
18    /**
19     * The formal display name.
20     *
21     * @return the formal name or {@code null} if not defined
22     */
23    // from INamedModelElement
24    @Nullable
25    String getFormalName();
26  
27    /**
28     * Get the text that describes the basic use of the element.
29     *
30     * @return a line of markup text or {@code null} if not defined
31     */
32    // from INamedModelElement
33    @Nullable
34    MarkupLine getDescription();
35  
36    /**
37     * The resolved formal display name, which allows an instance to override a
38     * definition's name.
39     *
40     * @return the formal name or {@code null} if not defined
41     */
42    // from INamedModelElement
43    @Nullable
44    default String getEffectiveFormalName() {
45      return getFormalName();
46    }
47  
48    /**
49     * Get the text that describes the basic use of the element, which allows an
50     * instance to override a definition's description.
51     *
52     * @return a line of markup text or {@code null} if not defined
53     */
54    // from INamedModelElement
55    @Nullable
56    default MarkupLine getEffectiveDescription() {
57      return getDescription();
58    }
59  }