[Enhancement]: Add optional email(s) and phone number(s) variables to stakeholder object

[arthur-clara]

Description of Enhancement :

Add optional Email(s) field to the stakeholder object.

Why is this Needed?

Right now, the only way to add an email and/or phone number to a stakeholder object is through the primary contact type in the stakeholder object and the primary contact type requires name, phone and email.

Primary contact makes sense as is for Institutional stakeholders but less sense of individual stakeholders. Having optional emails & phone numbers fields directly for individual stakeholders makes more logically sense.

Anything else we need to know?

An alternative is to use the primary contact type but not make both phone and email required. Or if required only means you need the variable and can input an empty array, then it is less of an issue.

[JSIV]

Thoughts, @jacobyavis or @pjohnmeyer ?

[Jake Yavis - Shareworks]

I think it would make sense to use a oneOf keyword to denote that EITHER phone OR email is required for a given ContactInfo object.
This way it's more flexible, but disallows one from creating an empty ContactInfo object

[JSIV]

TWG Notes:

Let's confirm whether oneOf would work here. Another option is an array of oneOf. We need to be careful that a new design pattern doesn't break the doc generator.

Also check out that there is some duplication across Stakeholder and Primary Contact. May be possible to split the stakeholder type between humans and orgs.

[arthur-clara]

@JSv4 I reviewed this and it looks like it should work without breaking changes if we replace line 30:
"required": ["name", "phone_numbers", "emails"],
with:
"anyOf": [{"required": ["phone_numbers"]},{"required": ["emails"]}],

This statement validates the type as long as there is either a phone_numbers array, a emails array or both.

Note: I have suggested removed the requirement for the name object since for individual stakeholders this seems redundant but it can easily be added into the anyOf statement.

Let me know if you want me to send a PR for this change.

[JSIV]

Per call on 2/28, let's explore two contact info types and see about using JSON schema rules to require different types depending on the stakeholder type.

[arthur-clara]

Potential changes to accommodate two contact info types for stakeholders:

Changes to schema/objects/Stakeholder.schema.json: Update description of "primary_contact" and add "contact_info" property

    "primary_contact": {
      "description": "The primary contact info for an institutional stakeholder",
      "$ref": "https://raw.githubusercontent.com/Open-Cap-Table-Coalition/Open-Cap-Format-OCF/main/schema/types/ContactInfo.schema.json"
    },
    "contact_info": {
      "description": "The contact info for an individual stakeholder",
      "$ref": "https://raw.githubusercontent.com/Open-Cap-Table-Coalition/Open-Cap-Format-OCF/main/schema/types/ContactInfoWithoutName.schema.json"
    },

Changes to schema/types/ContactInfo.schema.json: Replace required property with:

  "anyOf": [
    {
    	"required": ["name","phone_numbers"]
    },
    {
      "required": ["name","emails"]
    }
  ],

Add new type to schema/types/ : ContactInfoWithoutName.schema.json

{
  "$schema": "http://json-schema.org/draft-07/schema",
  "$id": "https://raw.githubusercontent.com/Open-Cap-Table-Coalition/Open-Cap-Format-OCF/main/schema/types/ContactInfoWithoutName.schema.json",
  "title": "Type - Contact Info Without Name",
  "description": "Type representation of the contact info for an individual stakeholder",
  "type": "object",
  "properties": {
    "phone_numbers": {
      "title": "Contact Info - Phone Number Array",
      "description": "Phone numbers to reach the contact at",
      "type": "array",
      "items": {
        "$ref": "https://raw.githubusercontent.com/Open-Cap-Table-Coalition/Open-Cap-Format-OCF/main/schema/types/Phone.schema.json"
      }
    },
    "emails": {
      "title": "Contact Info - Email Address Array",
      "description": "Emails to reach the contact at",
      "type": "array",
      "items": {
        "$ref": "https://raw.githubusercontent.com/Open-Cap-Table-Coalition/Open-Cap-Format-OCF/main/schema/types/Email.schema.json"
      }
    }
  },
  "additionalProperties": false,
  "anyOf": [
    {
    	"required": ["phone_numbers"]
    },
    {
      "required": ["emails"]
    }
  ],
  "$comment": "Copyright © 2023 Open Cap Table Coalition (https://opencaptablecoalition.com) / Original File: https://github.com/Open-Cap-Table-Coalition/Open-Cap-Format-OCF/tree/main/schema/types/ContactInfoWithoutNameSchema.schema.json"
}