Add and refine OpenAPI Schema annotations for better documentation

tjnelsonfs · tjnelsonfs · commit b1b2e8848bc6 · 2025-02-20T12:30:05.000-07:00
Added new annotations to various classes for improved OpenAPI documentation and updated existing ones with clearer descriptions or additional context. Removed redundant fields and unused annotations for cleaner code.
diff --git a/gedcomx-model/src/main/java/org/gedcomx/Gedcomx.java b/gedcomx-model/src/main/java/org/gedcomx/Gedcomx.java
@@ -92,11 +92,11 @@
 @JsonElementWrapper ( name = "gedcomx" )
 @JsonInclude ( JsonInclude.Include.NON_NULL )
 @XmlType ( name = "Gedcomx", propOrder = {"attribution", "persons", "relationships", "sourceDescriptions", "agents", "events", "places", "documents", "collections", "fields", "recordDescriptors"} )
-@Schema(name = "The GEDCOM X data formats define the serialization formats of the GEDCOM X conceptual model. The canonical documentation is provided by the formal specification documents:\n" +
-    "\n" +
-    "*   [The GEDCOM X Conceptual Model, Version 1.0](https://github.com/FamilySearch/gedcomx/blob/master/specifications/conceptual-model-specification.md)\n" +
-    "*   [The GEDCOM X JSON Format, Version 1.0](https://github.com/FamilySearch/gedcomx/blob/master/specifications/json-format-specification.md)\n" +
-    "*   [The GEDCOM X XML Format, Version 1.0](https://github.com/FamilySearch/gedcomx/blob/master/specifications/xml-format-specification.md)")
+@Schema(name = "The GEDCOM X data formats define the serialization formats of the GEDCOM X conceptual model. The canonical documentation is provided by the formal specification documents:" +
+    " [The GEDCOM X Conceptual Model, Version 1.0](https://github.com/FamilySearch/gedcomx/blob/master/specifications/conceptual-model-specification.md)" +
+    " [The GEDCOM X JSON Format, Version 1.0](https://github.com/FamilySearch/gedcomx/blob/master/specifications/json-format-specification.md)" +
+    " [The GEDCOM X XML Format, Version 1.0](https://github.com/FamilySearch/gedcomx/blob/master/specifications/xml-format-specification.md)" +
+    "This documentation is provided as a non-normative reference guide.")
 public class Gedcomx extends HypermediaEnabledData implements HasFields {
 
   @Schema(description = "The language of this genealogical data set. See http://www.w3.org/International/articles/language-tags/. " +
@@ -133,10 +133,6 @@ public class Gedcomx extends HypermediaEnabledData implements HasFields {
   @Schema(description = "The collections included in this genealogical data set.")
   private List<Collection> collections;
 
-  @Schema(description = "The extracted fields included in this genealogical data set.  Fields that apply to a particular person,\n" +
-      " * relationship or value should be included within that person or value, respectively.\n" +
-      " * Remaining fields that did not have a place within the person or relationship structure can be included here.\n" +
-      " * Also, fields that were extracted but not yet fit into a structure can also be included here.")
   private List<Field> fields;
 
   @Schema(description = "The record descriptors included in this genealogical data set.")
diff --git a/gedcomx-model/src/main/java/org/gedcomx/agent/Address.java b/gedcomx-model/src/main/java/org/gedcomx/agent/Address.java
@@ -28,7 +28,7 @@
  * @author Ryan Heaton
  */
 @XmlType ( name = "Address" )
-@Schema(description = "An address.")
+@Schema(description = "An Address.")
 public class Address extends ExtensibleData {
 
   @Schema(description = "The city.")
diff --git a/gedcomx-model/src/main/java/org/gedcomx/agent/Agent.java b/gedcomx-model/src/main/java/org/gedcomx/agent/Agent.java
@@ -50,8 +50,7 @@
 @XmlType ( name = "Agent" )
 @JsonElementWrapper ( name = "agents" )
 @JsonInclude ( JsonInclude.Include.NON_NULL )
-@Schema(description = "An agent, e.g. person, organization, or group. In genealogical research, an agent often takes the role of a contributor." +
-    "\n@see [foaf:Agent](http://xmlns.com/foaf/spec/#term_Agent)")
+@Schema(description = "An agent, e.g. person, organization, or group. In genealogical research, an agent often takes the role of a contributor.")
 public class Agent extends HypermediaEnabledData {
 
   @Schema(description = "The list of names for the agent.")
diff --git a/gedcomx-model/src/main/java/org/gedcomx/agent/OnlineAccount.java b/gedcomx-model/src/main/java/org/gedcomx/agent/OnlineAccount.java
@@ -33,7 +33,7 @@ public class OnlineAccount extends ExtensibleData {
   @Schema(description = "The homepage of the service that provides this account.")
   private ResourceReference serviceHomepage;
 
-  @Schema(description = "The name associated with this account.")
+  @Schema(description = "The name associated the holder of this account with the account.")
   private String accountName;
 
   public OnlineAccount() {
diff --git a/gedcomx-model/src/main/java/org/gedcomx/common/ExtensibleData.java b/gedcomx-model/src/main/java/org/gedcomx/common/ExtensibleData.java
@@ -38,7 +38,6 @@ public abstract class ExtensibleData implements SupportsExtensionElements, HasTr
   @Schema(description = "Custom extension elements for a conclusion.")
   protected List<Object> extensionElements;
 
-  @Schema(description = "Transient properties that are not to be serialized.")
   protected final Map<String, Object> transientProperties = new TreeMap<String, Object>();
 
   protected ExtensibleData() {
diff --git a/gedcomx-model/src/main/java/org/gedcomx/common/Note.java b/gedcomx-model/src/main/java/org/gedcomx/common/Note.java
@@ -43,7 +43,7 @@
 @Schema(description = "A note about a genealogical resource (e.g. conclusion or source).")
 public class Note extends HypermediaEnabledData implements Attributable, HasText {
 
-  @Schema(description = "The language of the note.")
+  @Schema(description = "The language of the note. See http://www.w3.org/International/articles/language-tags/")
   private String lang;
 
   @Schema(description = "The subject of the note. This is a short title describing the contents of the note text.")
diff --git a/gedcomx-model/src/main/java/org/gedcomx/common/ResourceReference.java b/gedcomx-model/src/main/java/org/gedcomx/common/ResourceReference.java
@@ -40,7 +40,7 @@
 @Schema(description = "A generic reference to a resource.")
 public final class ResourceReference {
 
-  @Schema(description = "The URI to the resource being referenced.")
+  @Schema(description = "The URI to the resource. For more information, see Architecture of the World Wide Web, Volume One, Section 2")
   private URI resource;
 
   @Schema(description = "The resource id of the resource being referenced. Used as an extension attribute when resolving the resource is inconvenient.")
diff --git a/gedcomx-model/src/main/java/org/gedcomx/common/TextValue.java b/gedcomx-model/src/main/java/org/gedcomx/common/TextValue.java
@@ -34,7 +34,7 @@
 @Schema(description = "An element representing a text value that may be in a specific language.")
 public class TextValue {
 
-  @Schema(description = "The language of the text value.")
+  @Schema(description = "The language of the text value. See http://www.w3.org/International/articles/language-tags/")
   private String lang;
 
   @Schema(description = "The text value.")
diff --git a/gedcomx-model/src/main/java/org/gedcomx/conclusion/Date.java b/gedcomx-model/src/main/java/org/gedcomx/conclusion/Date.java
@@ -64,7 +64,6 @@ public class Date extends ExtensibleData implements HasFields {
       "GEDCOM X core, but as extension elements by GEDCOM X RS.")
   private List<TextValue> normalized;
 
-  @Schema(description = "The references to the record fields being used as evidence.")
   private List<Field> fields;
 
   public Date() {
diff --git a/gedcomx-model/src/main/java/org/gedcomx/conclusion/Fact.java b/gedcomx-model/src/main/java/org/gedcomx/conclusion/Fact.java
@@ -67,7 +67,6 @@ public class Fact extends Conclusion implements HasDateAndPlace, HasFields {
   @Schema(description = "The qualifiers associated with this fact.")
   private List<Qualifier> qualifiers;
 
-  @Schema(description = "The references to the record fields being used as evidence.")
   private List<Field> fields;
 
   @Schema(description = "Indicator of whether this fact is the \"primary\" fact of the record from which the subject was extracted. " +
diff --git a/gedcomx-model/src/main/java/org/gedcomx/conclusion/FamilyView.java b/gedcomx-model/src/main/java/org/gedcomx/conclusion/FamilyView.java
@@ -43,19 +43,19 @@
 @JsonElementWrapper( name = "families" )
 @XmlType( name = "FamilyView", propOrder = { "parent1", "parent2", "children"} )
 @JsonInclude ( JsonInclude.Include.NON_NULL )
-@Schema(description = "A family view, meaning up to two parents and a list of children who have those parents in common.\n" +
-    " Relationships carry the canonical information for this view, and the relationships must be used\n" +
-    " to get Facts (lineage types, marriages, etc.) about the relationships covered by a Family.\n" +
-    " The Family data type provides a convenient way to see the typical family views without having to do\n" +
-    " the calculations to derive them. There should only be one family for each unique set of parents,\n" +
+@Schema(description = "A family view, meaning up to two parents and a list of children who have those parents in common." +
+    " Relationships carry the canonical information for this view, and the relationships must be used" +
+    " to get Facts (lineage types, marriages, etc.) about the relationships covered by a Family." +
+    " The Family data type provides a convenient way to see the typical family views without having to do" +
+    " the calculations to derive them. There should only be one family for each unique set of parents," +
     " and only one for each single-parent family with a particular parent.")
 public class FamilyView extends HypermediaEnabledData {
 
-  @Schema(description = "A reference to a parent in the family. The name \"parent1\" is used only to distinguish it from\n" +
+  @Schema(description = "A reference to a parent in the family. The name \"parent1\" is used only to distinguish it from" +
       " the other parent in this family and implies neither order nor role.")
   private ResourceReference parent1; // First parent
 
-  @Schema(description = "A reference to a parent in the family. The name \"parent2\" is used only to distinguish it from\n" +
+  @Schema(description = "A reference to a parent in the family. The name \"parent2\" is used only to distinguish it from" +
       " the other parent in this family and implies neither order nor role.")
   private ResourceReference parent2; // Second parent
 
diff --git a/gedcomx-model/src/main/java/org/gedcomx/conclusion/Gender.java b/gedcomx-model/src/main/java/org/gedcomx/conclusion/Gender.java
@@ -54,10 +54,9 @@
 @Schema(description = "A gender conclusion.")
 public class Gender extends Conclusion implements HasFields {
 
-  @Schema(description = "The type")
+  @Schema(description = "The URI that identifies the type of Gender.")
   private URI type;
 
-  @Schema(description = "The references to the record fields being used as evidence.")
   private List<Field> fields;
 
   /**
diff --git a/gedcomx-model/src/main/java/org/gedcomx/conclusion/NameForm.java b/gedcomx-model/src/main/java/org/gedcomx/conclusion/NameForm.java
@@ -56,7 +56,6 @@ public class NameForm extends ExtensibleData implements HasFields {
   @Schema(description = "The different parts of the name form.")
   private List<NamePart> parts;
 
-  @Schema(description = "The references to the record fields being used as evidence.")
   private List<Field> fields;
 
   public NameForm() {
diff --git a/gedcomx-model/src/main/java/org/gedcomx/conclusion/NamePart.java b/gedcomx-model/src/main/java/org/gedcomx/conclusion/NamePart.java
@@ -63,7 +63,6 @@ public final class NamePart extends ExtensibleData implements HasFields {
   @Schema(description = "The qualifiers associated with this name part.")
   private List<Qualifier> qualifiers;
 
-  @Schema(description = "The references to the record fields being used as evidence.")
   private List<Field> fields;
 
   public NamePart() {
diff --git a/gedcomx-model/src/main/java/org/gedcomx/conclusion/Person.java b/gedcomx-model/src/main/java/org/gedcomx/conclusion/Person.java
@@ -65,22 +65,23 @@ public class Person extends Subject implements HasFacts, HasFields {
   @Schema(description = "Whether this person has been designated for limited distribution or display.")
   private Boolean isPrivate;
 
-  @Schema(description = "Living status of the person as treated by the system. The value of this property is intended to be based on a system-specific calculation and therefore has limited portability. Conclusions about the living status of a person can be modeled with a fact.")
+  @Schema(description = "Living status of the person as treated by the system. The value of this property is intended to be based on a system-specific " +
+      "calculation and therefore has limited portability. Conclusions about the living status of a person can be modeled with a fact.")
   private Boolean living;
 
-  @Schema(description = "Indicator of whether this person is the 'principal' person extracted from the record. Applicable only to extracted persons. The meaning of this flag outside the scope of an extracted person is undefined.")
+  @Schema(description = "Indicator of whether this person is the 'principal' person extracted from the record. Applicable only to extracted persons. " +
+      "The meaning of this flag outside the scope of an extracted person is undefined.")
   private Boolean principal;
 
-  @Schema(description = "The gender of the person")
+  @Schema(description = "The gender conclusion for the person.")
   private Gender gender;
 
-  @Schema(description = "The names of the person.")
+  @Schema(description = "The name conclusions for the person.")
   private List<Name> names;
 
-  @Schema(description = "The facts of the person.")
+  @Schema(description = "The fact conclusions for the person.")
   private List<Fact> facts;
 
-  @Schema(description = "The fields being used as evidence.")
   private List<Field> fields; // person-specific fields, such as used in an extracted historical record.
 
   @Schema(description = "Display properties for the person. Display properties are not specified by GEDCOM X core, but as extension elements by GEDCOM X RS.")
diff --git a/gedcomx-model/src/main/java/org/gedcomx/conclusion/PlaceDescription.java b/gedcomx-model/src/main/java/org/gedcomx/conclusion/PlaceDescription.java
@@ -48,7 +48,7 @@
 public class PlaceDescription extends Subject {
 
   @Schema(description = "An ordered list of standardized (or normalized), fully-qualified (in terms of what is known of the applicable jurisdictional hierarchy) " +
-      "names for this place that are applicable to this description of this place.")
+      "names for this place that are applicable to this description of this place. The list MUST include at least one value. It is RECOMMENDED that instances include a single name and any equivalents from other cultural contexts; name variants should more typically be described in separate PlaceDescription instances. The list is assumed to be given in order of preference, with the most preferred value in the first position in the list.")
   private List<TextValue> names;
 
   @Schema(description = "An implementation-specific uniform resource identifier (URI) used to identify the type of a place (e.g., address, city, county, province, state, country, etc.).")
@@ -57,16 +57,16 @@ public class PlaceDescription extends Subject {
   @Schema(description = "A description of the time period to which this place description is relevant.")
   private Date temporalDescription;
 
-  @Schema(description = "Degrees north or south of the Equator (0.0 degrees).   Values range from −90.0 degrees (south) to 90.0 degrees (north).")
+  @Schema(description = "Degrees north or south of the Equator (0.0 degrees). Values range from −90.0 degrees (south) to 90.0 degrees (north).")
   private Double latitude;
 
-  @Schema(description = "Angular distance in degrees, relative to the Prime Meridian.   Values range from −180.0 degrees (west of the Meridian) to 180.0 degrees (east of the Meridian).")
+  @Schema(description = "Angular distance in degrees, relative to the Prime Meridian. Values range from −180.0 degrees (west of the Meridian) to 180.0 degrees (east of the Meridian).")
   private Double longitude;
 
-  @Schema(description = "A reference to a geospatial description of this place.")
+  @Schema(description = "A reference to the place being described.")
   private ResourceReference place;
 
-  @Schema(description = "A reference to a geospatial description of this place.")
+  @Schema(description = "A reference to a geospatial description of this place. It is RECOMMENDED that this description resolve to a KML document.")
   private ResourceReference spatialDescription;
 
   @Schema(description = "A reference to a description of the jurisdiction this place.")
diff --git a/gedcomx-model/src/main/java/org/gedcomx/conclusion/PlaceReference.java b/gedcomx-model/src/main/java/org/gedcomx/conclusion/PlaceReference.java
@@ -59,7 +59,6 @@ public class PlaceReference extends ExtensibleData implements HasFields {
   @Schema(description = "The level of confidence the contributor has about the data.")
   private URI confidence;
 
-  @Schema(description = "The references to the record fields being used as evidence.")
   private List<Field> fields;
 
   @Schema(description = "The list of normalized values for the place, provided for display purposes by the application. " +
diff --git a/gedcomx-model/src/main/java/org/gedcomx/conclusion/Relationship.java b/gedcomx-model/src/main/java/org/gedcomx/conclusion/Relationship.java
@@ -79,7 +79,6 @@ public class Relationship extends Subject implements HasFacts, HasFields {
   @Schema(description = "The fact conclusions for the relationship.")
   private List<Fact> facts;
 
-  @Schema(description = "The references to the record fields being used as evidence.")
   private List<Field> fields;
 
   public Relationship() {
diff --git a/gedcomx-model/src/main/java/org/gedcomx/conclusion/Subject.java b/gedcomx-model/src/main/java/org/gedcomx/conclusion/Subject.java
@@ -50,7 +50,7 @@
  */
 @XmlType ( name = "Subject", propOrder = { "evidence", "media", "identifiers" })
 @JsonInclude ( JsonInclude.Include.NON_NULL )
-@Schema(description = "The `Subject` data type defines the abstract concept of a genealogical _subject_. A _subject_ is something with a unique and intrinsic identity, e.g., a person, a location on the surface of the earth. We identify that _subject_ in time and space using various supporting _conclusions_, e.g. for a person: things like name, birth date, age, address, etc. We aggregate these supporting _conclusions_ to form an apparently-unique identity by which we can distinguish our _subject_ from all other possible _subjects_")
+@Schema(description = "The `Subject` data type defines the abstract concept of a genealogical _subject_. A _subject_ is something with a unique and intrinsic identity, e.g., a person, a location on the surface of the earth. We identify that _subject_ in time and space using various supporting _conclusions_, e.g. for a person: things like name, birth date, age, address, etc. We aggregate these supporting _conclusions_ to form an apparently-unique identity by which we can distinguish our _subject_ from all other possible _subjects_.")
 public abstract class Subject extends Conclusion implements Attributable {
 
   @Schema(description = "Whether this subject has been identified as 'extracted', meaning it captures information extracted from a single source.")
diff --git a/gedcomx-model/src/main/java/org/gedcomx/links/Link.java b/gedcomx-model/src/main/java/org/gedcomx/links/Link.java
@@ -53,7 +53,7 @@ public class Link implements HasJsonKey {
    */
   public static final Set<String> NON_UNIQUE_RELS = new TreeSet<String>(Arrays.asList("alternate", "bookmark", "related", "item"));
 
-  @Schema(description = "The Relationship.")
+  @Schema(description = "The link relationship.")
   private String rel;
 
   @Schema(description = "The target URI of the link.")
@@ -62,19 +62,23 @@ public class Link implements HasJsonKey {
   @Schema(description = "A URI template per RFC 6570, used to link to a range of URIs, such as for the purpose of linking to a query.")
   private String template;
 
-  @Schema(description = "Metadata about the available media type(s) of the resource being linked to.")
+  @Schema(description = "Metadata about the available media type(s) of the resource being linked to. The value of the \"type\" attribute is as " +
+      "defined by the HTTP specification, RFC 2616, Section 3.7. Note that this attribute can be considered an \"Update Control (CU)\" per Amundsen, M. (2011). Hypermedia APIs with HTML5 and Node. O'Reilly.")
   private String type;
 
-  @Schema(description = "Metadata about the available media type(s) of the resource being linked to.")
+  @Schema(description = "Metadata about the available media type(s) of the resource being linked to update (i.e. change the state of) the resource being " +
+      "linked to. The value of the \"accept\" attribute is as defined by the HTTP specification, RFC 2616, Section 3.7. Note that this attribute can be considered an \"Read Control (CR)\" per Amundsen, M. (2011). Hypermedia APIs with HTML5 and Node. O'Reilly.")
   private String accept;
 
-  @Schema(description = "Metadata about the allowable methods that can be used to transition to the resource being linked.")
+  @Schema(description = "Metadata about the allowable methods that can be used to transition to the resource being linked. The value of the \"allow\" " +
+      "attribute is as defined by the HTTP specification, RFC 2616, Section 14.7. Note that this attribute can be considered an \"Method Control (CM)\" per Amundsen, M. (2011). Hypermedia APIs with HTML5 and Node. O'Reilly.")
   private String allow;
 
-  @Schema(description = "The language of the resource being linked to.")
+  @Schema(description = "The language of the resource being linked to. Note that this attribute can be considered an \"Update Control (CU)\" per Amundsen, " +
+      "M. (2011). Hypermedia APIs with HTML5 and Node. O'Reilly.")
   private String hreflang;
 
-  @Schema(description = "The title for the link.")
+  @Schema(description = "Human-readable information about the link.")
   private String title;
 
   @Schema(description = "The number of elements in the page, if this link refers to a page of resources.")
diff --git a/gedcomx-model/src/main/java/org/gedcomx/source/SourceCitation.java b/gedcomx-model/src/main/java/org/gedcomx/source/SourceCitation.java
@@ -47,7 +47,7 @@ public class SourceCitation extends HypermediaEnabledData {
   @Schema(description = "The language of the citation. See http://www.w3.org/International/articles/language-tags/")
   private String lang;
 
-  @Schema(description = "A rendering (as a string) of a source citation.  This rendering should be the most complete rendering available.")
+  @Schema(description = "A rendering (as a string) of a source citation. This rendering should be the most complete rendering available.")
   private String value;
 
   @Schema(description = "A reference to the citation template for this citation.")
diff --git a/gedcomx-model/src/main/java/org/gedcomx/source/SourceDescription.java b/gedcomx-model/src/main/java/org/gedcomx/source/SourceDescription.java
diff --git a/gedcomx-model/src/main/java/org/gedcomx/vocab/VocabElement.java b/gedcomx-model/src/main/java/org/gedcomx/vocab/VocabElement.java
diff --git a/gedcomx-model/src/main/java/org/gedcomx/vocab/VocabElementList.java b/gedcomx-model/src/main/java/org/gedcomx/vocab/VocabElementList.java
