Error handling according to fixed set of relations for play-spoken-text

[hsluytergaethje]

In the endpoint /corpora/{corpusname}/plays/{playname}/spoken-text for the parameter relation a fixed set of possible values is indicated in the API documentation. When I pass a parameter that is not in the list an empty string is returned. It would be good to get an error (similar to the gender parameter) in which the possible set of values is indicated.
The same would be good for the parameter role or is this not a fixed set of values?

[cmil]

For roles, I don't think there is a set of fixed values. Correct me if I'm wrong, @lehkost.

For the relation parameter, you are absolutely right that the API should respond with an error since we only accept a fixed list of values. Before changing the API behaviour I would like to wait for the outcome of this discussion: dracor-org/dracor-schema#80, so that end we could reach consistency between API and the DraCor schema.

[lehkost]

Yes, I think roles (so far only used in RomDraCor and GreekDraCor, if I'm not mistaken) will remain the current set of fixed values. Extending the discussion to @juliajbeine, who might shed some more light on this.

[cmil]

This is the list of role values used in RomDraCor:

• Poenus
• adulescens
• advocatus
• ancilla
• anus
• choragus
• cocus
• danista
• deus
• deus prologus
• dux
• eunuchus
• fidicina
• gubernator
• lena
• leno
• libertus
• lorarius
• maritus
• matrona
• medicus
• mercator
• meretrix
• miles
• mulier
• nutrix
• obstetrix
• paedagogus
• parasitus
• piscator
• poeta
• prologus
• puella
• puer
• sacerdos
• senex
• servus
• sycophanta
• trapezita
• uxor
• vilicus
• virgo

It wouldn't seem like a good general purpose classification of roles. Not even for GreekDraCor, which currently hasn't any roles assigned to person elements as far as I can see. (There is something like this though: <editor n="Murray" role="editor">Gilbert Murray</editor>, but that's unrelated.)

[lehkost]

Thanks, we also quantified and visualised roles for RomDraCor in Figure 1 of our recent DH2024 paper "Just the Type" (doi:10.5281/zenodo.13801481), maybe interesting in this regard. But now I'll leave the rest to @juliajbeine. ☺️

[ingoboerner]

An idea regarding the role values: I would suggest that such specific taxonomies must be declared somewhere before used in the encoding and not just put into the TEIs. If corpus editors can agree on a fixed set than they could be declared as a in the in the corpus.xml (I haven't checked the the validity, this is just a quick take). The API could then at least check if the value is part of the taxonomy and if not, return an error. But yes, as Carsten suggested, we should discuss that in the schema/odd issue, if there is one.

[juliajbeine]

The role attribute is relevant to the (tragi-)comedies in RomDraCor, GreekDraCor, and NeoLatDraCor as they feature stock characters. @lehkost and I discussed how to make this information available for digital analyses and came up with the role attribute. The associated commits are:
d3ae74ac87e5876b49c3d08bf9a93993ddeb39cc
70691c6df13f90552b5744772c7b343a60fa04ad
436a6f7927c1295224c1b204176fa9ce116930d4

The roles are based on the information given in the editions themselves.
E.g. for RomDraCor, see https://archive.org/details/comoediaerecens00plaugoog/page/n13/mode/1up?view=theater or https://archive.org/details/comoediaesexwith00tereuoft/page/80/mode/1up?view=theater.

For NeoLatDraCor, see
https://www.let.leidenuniv.nl/Dutch/Ceneton/Facsimiles/MacropediusHecastus1552/source/MacropediusHecastus1552p007.htm

I also included this information in the NeoLatDraCor wiki:
https://github.com/dracor-org/neolatdracor/wiki/FAQs-on-Encoding-Plays-for-the-NeoLatDraCor-in-TEI#how-may-i-encode-stock-characters

The role description may differ between editions. For instance, one may discuss whether puella and virgo are synonyms. My suggestion would be to stick to the information given in the text editions, especially since the NeoLatDraCor is currently built and we do not know all possible values for the role attribute yet. Later, we may discuss whether to revise the values for unification.

Another comment: Mercurius should rather have the role attributes deus AND prologus, so two values. (The same would apply to the god Pan in Menander's Dyskolos. @lehkost and I plan to generally update the TEI files in GreekDraCor, also adding the information on stock characters to Menander's Dyskolos.)

[ingoboerner]

Please create taxonomies for these values, this would be a semantically sound solution for such research-driven markup.

[cmil]

From what @juliajbeine describes as the current state of affairs I think it is clear that a fixed list of role values for all of DraCor is not applicable and the DraCor API should not enforce one.

I opened a ticket to document this current usage. For an alternative of dealing with roles in the future also see dracor-org/dracor-schema#81 (comment).

For the issue at hand here this still leaves the question whether or not the DraCor API should expect a finite choice of values for the relation parameter of the /corpora/{corpusname}/plays/{playname}/spoken-text endpoint. I would argue, in accordance with our current strategy in schema design (see dracor-org/dracor-schema#80 (reply in thread)), we should not limit the choices and thus remove the value list from the OpenAPI document.