Merge pull request #116 from FamilySearch/gedcomx-schema-updates

Gedcomx schema updates for OpenAPI

Author: tjnelsonfs

gedcomx-model/src/main/java/org/gedcomx/Gedcomx.java

@@ -43,6 +43,8 @@
 import org.gedcomx.types.ResourceType;
 
 import javax.xml.XMLConstants;
+
+import io.swagger.v3.oas.annotations.media.Schema;
 import jakarta.xml.bind.annotation.*;
 import java.text.DateFormat;
 import java.util.ArrayList;
@@ -90,20 +92,50 @@
 @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:" +
+    " [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/. " +
+      "Note that some language-enabled elements MAY override the language.")
   private String lang;
+
+  @Schema(description = "A reference to a description of this data set.")
   private URI descriptionRef;
+
+  @Schema(description = "The attribution of this genealogical data.")
   private Attribution attribution;
+
+  @Schema(description = "The persons included in this genealogical data set.")
   private List<Person> persons;
+
+  @Schema(description = "The relationships included in this genealogical data set.")
   private List<Relationship> relationships;
+
+  @Schema(description = "The descriptions of sources included in this genealogical data set.")
   private List<SourceDescription> sourceDescriptions;
+
+  @Schema(description = "The agents included in this genealogical data set.")
   private List<Agent> agents;
+
+  @Schema(description = "The events included in this genealogical data set.")
   private List<Event> events;
+
+  @Schema(description = "The places included in this genealogical data set.")
   private List<PlaceDescription> places;
+
+  @Schema(description = "The documents included in this genealogical data set.")
   private List<Document> documents;
+
+  @Schema(description = "The collections included in this genealogical data set.")
   private List<Collection> collections;
+
   private List<Field> fields;
+
+  @Schema(description = "The record descriptors included in this genealogical data set.")
   private List<RecordDescriptor> recordDescriptors;
 
   public Gedcomx() {

gedcomx-model/src/main/java/org/gedcomx/agent/Address.java

@@ -15,6 +15,8 @@
  */
 package org.gedcomx.agent;
 
+import io.swagger.v3.oas.annotations.media.Schema;
+
 import org.gedcomx.common.ExtensibleData;
 
 import jakarta.xml.bind.annotation.XmlType;
@@ -26,18 +28,40 @@
  * @author Ryan Heaton
  */
 @XmlType ( name = "Address" )
+@Schema(description = "An Address.")
 public class Address extends ExtensibleData {
 
+  @Schema(description = "The city.")
   private String city;
+
+  @Schema(description = "The country.")
   private String country;
+
+  @Schema(description = "The postal code.")
   private String postalCode;
+
+  @Schema(description = "The state or province.")
   private String stateOrProvince;
+
+  @Schema(description = "The street.")
   private String street;
+
+  @Schema(description = "Additional street information.")
   private String street2;
+
+  @Schema(description = "Additional street information.")
   private String street3;
+
+  @Schema(description = "Additional street information.")
   private String street4;
+
+  @Schema(description = "Additional street information.")
   private String street5;
+
+  @Schema(description = "Additional street information.")
   private String street6;
+
+  @Schema(description = "The value of the property, if it can be expressed as a string.")
   private String value;
 
   public Address() {

gedcomx-model/src/main/java/org/gedcomx/agent/Agent.java

@@ -19,6 +19,7 @@
 import com.fasterxml.jackson.annotation.JsonInclude;
 import com.fasterxml.jackson.annotation.JsonProperty;
 import com.webcohesion.enunciate.metadata.rs.TypeHint;
+import io.swagger.v3.oas.annotations.media.Schema;
 import org.gedcomx.common.ResourceReference;
 import org.gedcomx.common.TextValue;
 import org.gedcomx.common.URI;
@@ -34,7 +35,6 @@
 import jakarta.xml.bind.annotation.XmlTransient;
 import jakarta.xml.bind.annotation.XmlType;
 
-import java.sql.Array;
 import java.util.ArrayList;
 import java.util.List;
 
@@ -50,16 +50,34 @@
 @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.")
 public class Agent extends HypermediaEnabledData {
 
+  @Schema(description = "The list of names for the agent.")
   private List<TextValue> names;
+
+  @Schema(description = "The list of identifiers for the agent.")
   private List<Identifier> identifiers;
+
+  @Schema(description = "The homepage of the person or organization. Note this is different from the homepage of the service where the person or organization has an account.")
   private ResourceReference homepage;
+
+  @Schema(description = "The openid of the person or organization.")
   private ResourceReference openid;
+
+  @Schema(description = "The accounts that belong to this person or organization.")
   private List<OnlineAccount> accounts;
+
+  @Schema(description = "The emails that belong to this person or organization.")
   private List<ResourceReference> emails;
+
+  @Schema(description = "The phones that belong to this person or organization.")
   private List<ResourceReference> phones;
+
+  @Schema(description = "The addresses that belong to this person or organization.")
   private List<Address> addresses;
+
+  @Schema(description = "The person that describes this agent.")
   private ResourceReference person;
 
   public Agent() {

gedcomx-model/src/main/java/org/gedcomx/agent/OnlineAccount.java

@@ -15,6 +15,7 @@
  */
 package org.gedcomx.agent;
 
+import io.swagger.v3.oas.annotations.media.Schema;
 import org.gedcomx.common.ExtensibleData;
 import org.gedcomx.common.ResourceReference;
 
@@ -26,9 +27,13 @@
  * @author Ryan Heaton
  */
 @XmlType( name = "OnlineAccount" )
+@Schema(description = "An online account for a web application.")
 public class OnlineAccount extends ExtensibleData {
 
+  @Schema(description = "The homepage of the service that provides this account.")
   private ResourceReference serviceHomepage;
+
+  @Schema(description = "The name associated the holder of this account with the account.")
   private String accountName;
 
   public OnlineAccount() {

gedcomx-model/src/main/java/org/gedcomx/common/Attribution.java

@@ -17,6 +17,8 @@
 
 import com.fasterxml.jackson.annotation.JsonInclude;
 import com.webcohesion.enunciate.metadata.Facet;
+import io.swagger.v3.oas.annotations.media.Schema;
+
 import org.gedcomx.agent.Agent;
 import org.gedcomx.rt.GedcomxConstants;
 import org.gedcomx.rt.RDFRange;
@@ -38,13 +40,25 @@
 @XmlType ( name = "Attribution", propOrder = { "contributor", "modified", "changeMessage", "changeMessageResource", "creator", "created" } )
 @JsonInclude ( JsonInclude.Include.NON_NULL )
 @SuppressWarnings("gedcomx:no_id")
+@Schema(description = "Attribution for genealogical information. Attribution is used to model who is contributing/modifying information, when they contributed it, and why they are making the contribution/modification.")
 public class Attribution extends ExtensibleData {
 
+  @Schema(description = "Reference to the contributor of the attributed data.")
   private ResourceReference contributor;
+
+  @Schema(description = "Reference to the creator of the attributed data. The creator might be different from the contributor if the attributed data has been modified since it was created.")
   private ResourceReference creator;
+
+  @Schema(description = "The modified timestamp for the attributed data.")
   private Date modified;
+
+  @Schema(description = "The created timestamp for the attributed data.")
   private Date created;
+
+  @Schema(description = "The \"change message\" for the attributed data provided by the contributor.")
   private String changeMessage;
+
+  @Schema(description = "A reference to the change message for the attributed data provided by the contributor.")
   private URI changeMessageResource;
 
   public Attribution() {

gedcomx-model/src/main/java/org/gedcomx/common/EvidenceReference.java

@@ -17,6 +17,7 @@
 
 import com.fasterxml.jackson.annotation.JsonInclude;
 import com.webcohesion.enunciate.metadata.Facet;
+import io.swagger.v3.oas.annotations.media.Schema;
 import org.gedcomx.links.HypermediaEnabledData;
 import org.gedcomx.links.Link;
 import org.gedcomx.rt.GedcomxConstants;
@@ -38,10 +39,16 @@
 @XmlType ( name = "EvidenceReference" )
 @JsonElementWrapper ( name = "evidence" )
 @JsonInclude ( JsonInclude.Include.NON_NULL )
+@Schema(description = "A reference to a resource that is being used as evidence.")
 public final class EvidenceReference extends HypermediaEnabledData implements Attributable {
 
+  @Schema(description = "The URI to the resource being referenced as evidence.")
   private URI resource;
+
+  @Schema(description = "The resource id of the resource being referenced. Used as an extension attribute when resolving the resource is inconvenient.")
   private String resourceId;
+
+  @Schema(description = "Attribution metadata for evidence reference.")
   private Attribution attribution;
 
   public EvidenceReference() {

gedcomx-model/src/main/java/org/gedcomx/common/ExtensibleData.java

@@ -16,6 +16,7 @@
 package org.gedcomx.common;
 
 import com.fasterxml.jackson.annotation.JsonIgnore;
+import io.swagger.v3.oas.annotations.media.Schema;
 import org.gedcomx.rt.SupportsExtensionElements;
 
 import jakarta.xml.bind.JAXBElement;
@@ -28,10 +29,15 @@
  * @author Ryan Heaton
  */
 @XmlType( name = "ExtensibleData" )
+@Schema(description = "A set of data that supports extension elements.")
 public abstract class ExtensibleData implements SupportsExtensionElements, HasTransientProperties {
 
+  @Schema(description = "A local, context-specific id for the data.")
   private String id;
+
+  @Schema(description = "Custom extension elements for a conclusion.")
   protected List<Object> extensionElements;
+
   protected final Map<String, Object> transientProperties = new TreeMap<String, Object>();
 
   protected ExtensibleData() {

gedcomx-model/src/main/java/org/gedcomx/common/Note.java

@@ -17,6 +17,7 @@
 
 import com.fasterxml.jackson.annotation.JsonInclude;
 import com.webcohesion.enunciate.metadata.Facet;
+import io.swagger.v3.oas.annotations.media.Schema;
 import org.gedcomx.links.HypermediaEnabledData;
 import org.gedcomx.links.Link;
 import org.gedcomx.rt.GedcomxConstants;
@@ -39,11 +40,19 @@
 @JsonElementWrapper ( name = "notes" )
 @XmlType ( name = "Note", propOrder = {"subject", "text", "attribution"} )
 @JsonInclude ( JsonInclude.Include.NON_NULL )
+@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. 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.")
   private String subject;
+
+  @Schema(description = "The text of the note.")
   private String text;
+
+  @Schema(description = "Attribution metadata for a note.")
   private Attribution attribution;
 
   public Note() {

gedcomx-model/src/main/java/org/gedcomx/common/Qualifier.java

@@ -23,6 +23,7 @@
 import org.gedcomx.rt.ControlledVocabulary;
 import org.gedcomx.rt.json.JsonElementWrapper;
 
+import io.swagger.v3.oas.annotations.media.Schema;
 import jakarta.xml.bind.annotation.XmlAttribute;
 import jakarta.xml.bind.annotation.XmlRootElement;
 import jakarta.xml.bind.annotation.XmlTransient;
@@ -38,9 +39,13 @@
 @JsonElementWrapper(name = "qualifiers")
 @XmlType( name = "Qualifier" )
 @JsonInclude ( JsonInclude.Include.NON_NULL )
+@Schema(description = "A data qualifier. Qualifiers are used to \"qualify\" certain data elements to provide additional context, information, or details.")
 public final class Qualifier {
 
+  @Schema(description = "The name of the qualifier. The name should be an element of a constrained vocabulary and is used to determine meaning of the qualifier.")
   private URI name;
+
+  @Schema(description = "The value of the qualifier. Some qualifiers may not have values, indicating that the qualifier is to be treated more like a \"tag\".")
   private String value;
 
   public Qualifier() {

gedcomx-model/src/main/java/org/gedcomx/common/ResourceReference.java

@@ -18,6 +18,7 @@
 import com.fasterxml.jackson.annotation.JsonInclude;
 import com.webcohesion.enunciate.metadata.Facet;
 import com.webcohesion.enunciate.metadata.Facets;
+import io.swagger.v3.oas.annotations.media.Schema;
 import org.gedcomx.rt.GedcomxConstants;
 import org.gedcomx.rt.json.JsonElementWrapper;
 
@@ -36,9 +37,13 @@
 @XmlType ( name = "ResourceReference" )
 @JsonElementWrapper ( name = "resourceReference" )
 @JsonInclude ( JsonInclude.Include.NON_NULL )
+@Schema(description = "A generic reference to a resource.")
 public final class ResourceReference {
 
+  @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.")
   private String resourceId;
 
   public ResourceReference() {