Change roles from dictionary keys to a key named 'role'.

[pvretano]

Change the role dictionary key to a key named role. Thus something like this:

"phones": {
   "home": "+1-416-555-5555",
   "office": "+1-416-555-5554"
}

changes to something like this:

"phones": [
  { "value": "+1-416-555-5555", "role": "home" },
  { "value": "+1-416-555-5554", "role": "office" }
]

Closes #243

[pvretano]

@m-mohr for some reason you don't show up in the reviews list so I am adding this comment to ping you to review.

[m-mohr]

I think I'd prefer "roles" as array, aligned with the contacts / providers. It tackles the use case where users have the same work and private addresses (as I have it as a self-employed individual, for example). I think that would be more versatile. But if others prefer the string strongly, I'll not block it.

[tomkralidis]

Since we use a roles array elsewhere (contact role), +1 to have a roles array here as well for consistency.

[pvretano]

@m-mohr @tomkralidis just to make sure, you want it to look like this ... yes?

"phones": [
  { "value": "+1-416-555-5555", "roles": [{"name": "home"}] },
  { "value": "+1-416-555-5554", "roles": [{"name": "office"}] }
]

Works for me, just verify this is what you have in mind and I'll update the PR.

[m-mohr]

I thought like this:

"phones": [
  { "value": "+1-416-555-5555", "roles": ["home"] },
  { "value": "+1-416-555-5554", "roles": ["office"] }
]

[pvretano]

@m-mohr ah OK. I thought @tomkralidis was implying the reuse of the role.yaml schema in the master branch. No worries. I can make it an array of string ... works for me.

[tomkralidis]

Roles as defined in contact objects proper are consistent with the following:

"phones": [
  { "value": "+1-416-555-5555", "roles": [{"name": "home"}] },
  { "value": "+1-416-555-5554", "roles": [{"name": "office"}] }
]

Having said this, no objections to moving roles to an array, however we should be consistent with contact roles as well (changing role.yaml so that it can be used in contact.roles and contact.phones, etc. I would also tighten roles to have minItems: 1 so that if someone specifies roles, that it should not be empty.

[m-mohr]

Oh, I thought the roles in OAR were the same as the roles in STAC (assets + providers). Do you have any reason why you are not just using an array of strings in general, also for contact roles? I'm also just aiming for consistency here, but were caught in my STAC world ;-)

[tomkralidis]

I think the idea of having a role (for contacts) as an object is being able to qualify (with a codelist) to provide further meaning to the value. Different metadata standards have different vocabularies for roles, and in OARec we do not constrain which (contact) roles are put forth; we do provide an annex with known vocabularies (including ISO, DCAT, STAC, for example) in case users do not have one in place.

If it's important to keep consistent the structure with contact.roles, then we should keep with roles as an object.

Having said this, what about:

{
  "phones": [
    {
      "value": "+1-416-555-5555",
      "type": "home"
    },
    {
      "value": "+1-905-555-5555",
      "type": "office"
    }
  ]
}

I know this introduces the possibility of having to duplicate a phone number, email, or address if we want to express multiple roles, but I'm not sure how often we will see the same contact type with multiple phone numbers/emails/addresses. As well, given the OGC API - Records "Record" building is meant to provide a baseline, perhaps the above is enough?

[pvretano]

@tomkralidis @m-mohr if we use role then I think its structure should be consistent which means that role is an object with name and authority members. If we use one structure in one place and another in another place you know someone is going to make a comment about that! So, changing role to type seems OK to me. Assuming we make that change then the only outstanding issue is whether type is a string or an array. Personally, I'm easy either way but lean towards any approach that results in greater STAC alignment.

[m-mohr]

Generally, I feel like roles with codelists seem overengineered to me and should not be in core. If at all, it feels more like an extension. I must admit I've not realized until this came up here that the roles in contacts were so complex. I guess type is fine (although why not "types" as an array then?), but then I still need to resolve the issue that roles != roles in STAC (contacts vs. providers and assets). I don't like that roles in contacts is much more complex than roles in providers and assets.

[pvretano]

@m-mohr no problem with renaming roles to types and making it an array of strings. I'll make that change here.

As for roles in general -- not sure how the others feel -- but I would prefer alignment with STAC in this area. That would mean making all roles members arrays of strings rather than objects.

If organizations or communities of interests want the role values to be from some authoritative list then they can create a standard or best practice or guideline indiciating this requirement. Even more. Say there is a community of interest like WMO. They develop and publish guidelines about how to use OGC API Records. In those guidelines they can indicate that the value of the roles member(s) must come from some authoritative code list. Hopefully in those guidelines they also define a conformsTo URL so that clients that recognize that URL will know that the record conforms to their guidelines and will thus also know that the value(s) of the roles member are taken from the specific, authoritative code list in the ~WMS~ WMO guidelines. You get the idea. I can even add a recommendation to this effect if we decide to make this change.

If the others (@tomkralidis, @kalxas) are OK with this approach I can add those changes to this PR.

[m-mohr]

What you'd do in STAC for the authoritive roles, is probably either what @pvretano proposes or to just re-use themes in contacts or providers. We have this notion of "common metadata" where you can use fields in many different places.

If we align roles with STAC, we don't need to rename to types though...

[tomkralidis]

@pvretano in WMO, this is exactly what we are doing (having a specific conformsTo). No strong objections on aligning with STAC. To summarize, then:

• contact.roles becomes an array
• contact.phone / contact.emails / contact.addresses have a property named roles which is an array
• add text to the definition of conformsTo to mention that conformsTo can also help qualifying values or articulating controlled vocabularies
  • https://github.com/opengeospatial/ogcapi-records/blob/master/core/standard/clause_7_record.adoc#record-extensions
  • https://github.com/opengeospatial/ogcapi-records/blob/master/core/openapi/schemas/common/confClasses.yaml

Does the above seem reasonable?

[m-mohr]

Just to clarify: "becomes an array" means "becomes an array of strings", right? Sounds reasonable to me.

[tomkralidis]

Correct, yes.

[pvretano]

Question ... what is the difference between the postitionName and a role in the contacts strcuture?

[tomkralidis]

Example:

• positionName: Grand Poobah
• role: distributor # controlled vocabulary

[m-mohr]

With my STAC bias I'd say:

positionName: e.g. Senior Scientist roles: e.g. "producer"

or

positionName: e.g. IT Specialist roles: e.g. "host"

or

positionName: e.g. Contracts lawyer roles: e.g. "licensor"

[pvretano]

So is it fair to say that the position name is a named role taken from the organization's organizational hierarchy/chart while a role is a function, duty or permission assigned by the organization?

[m-mohr]

Yes, although the role might be something else depending on what an external "vocabulary" defines.

[tomkralidis]

from 19115:

• positionName: role or position of the responsible person
• role: function performed by the responsible party

[pvretano]

@m-mohr @tomkralidis please review latest changes and let me know if they are satisfactory.