Consider singular / plural names for API fields

[jduss4]

Currently, it is awkward to iterate over "singular" fields in applications:

@res["person"].each { |person| ... }

At the same time, the alternative is to use plural for things which seem more singular, like API facet requests:

?facet[]=creators.name

Discussion:

• should plural / singular labels be used to indicate whether a field is going to be treated as multivalued or not, respectively, by our API? Therefore as nested fields repeat, "creator" would become "creators" ?
• should nested fields allow multivalued fields in the subdoc? Example:

"person" : [
  {
    "role" : [ "attorney_against", "attorney_for" ],
    "name" : "Chillster Rockstar",
    "id" : "oscys.per1827"
  }
]

Anyway, we have lots of things to think about, and I'm writing them down here for now. Changes we make will affect the data repo, orchid, existing projects based on orchid, and this repo.

[karindalziel]

This is like that rabbit/duck picture my brain keep flipping as to which way to think about it.

[karindalziel]

Is there any reason to indicate whether a field is multivalued in ES?

[jduss4]

Only insofar as it might be nice for us to be able to tell at a glance, but ES itself doesn't care if you send it an array (multivalued) or something singular. it will toggle the field as needed, I believe.

[jduss4]

ES does care if you send it a list or single item for a nested field, though, as I rediscovered during the VRA addition a few days ago

[karindalziel]

So I guess the question is, do WE need the reminder as to what's multivalued? I would tend towards no, as that should be marked in the schema.

Should we nave a name that indicated nested fields?

[jduss4]

Here's a quick survey of the current state of things.

Plural Name -- Not Multivalued

Field	Comments
annotations
rights	generally a single string, but could be multivalued?

Singular Name -- Multivalued

Field	Comments
creator	collection of nested objects (no .role)
contributor	nested, contains multivalued .role
coverage.spatial	nested
person	nested, contains multivalued .role, people field also exists
recipient	nested, contains multivalued .role

Singular Name -- Multivalued

Field	Comments
subject

Already Plural -- Multivalued

Field	Comments
topics
keywords
people
places
works

[jduss4]

Decisions:

Change annotations to annotations_text Change subject to subjects Leave rights since grammatically it makes more sense than right image_id should be implemented (is not currently)

Other fields remain with current naming convention. Plural -- multivalued like "people" are distinct cdrh fields, not modeled on Dublin Core. They should be LISTS and not strings separated by semi-colon.

[jduss4]

Note: creator_sort is specified in the API Schema