[birocorneliu]

Jira: https://digital-science.atlassian.net/browse/FIG-47098

Summary

Documents the v3 contract for ITBM person_list fields (authors, supervisors, custom person lists) introduced by FIG-47085: the GET shape, the write rules enforced by figcore's PersonListProcessor, and the reworked v3 authors endpoints. v3 overlay only; the v2 spec (swagger.json) is unchanged.

Changes

• components/v3.0/inclusions.yaml: new schemas
  • PersonListEntry: GET shape (type, user_id, read-only has_account, merged names/ORCID, masked email, affiliations / is_corresponding for people, name / ror_id / contributors for organizations; empty values left out). It's the write format, so a GET → PUT round trip is a no-op.
  • PersonListEntryCreate: write rules (entries with user_id and overrides; typed entries and exact matching; limits; 422 paths).
  • PersonListAffiliation, PersonListAuthorsCreator.
• components/v3.0/overrides.yaml: the fields descriptions (item and collection, public and private) point person_list fields to PersonListEntry instead of the legacy {id, url_name, is_active, ...} author shape.
• paths/v3.0/inclusions.yaml:
  • /account/items/{item_id}/authors[/{author_id}]: rewritten. The endpoints read and change the item's authors field; POST appends, PUT replaces, DELETE removes the entry for a user_id; 422 with the entry path.
  • /account/collections/{collection_id}/authors[/{author_id}]: the same, as v3 overrides of the v2 paths.
  • /account/authors/search: v3 override, users with an account only (no ghost users, no organizations).
• docs/versions/swagger_v3.0.json: regenerated with make docs.

Testing

• make docs (merge + bundles): only swagger_v3.0.json changes; swagger.json (v2) is identical.
• openapi-spec-validator on swagger_v3.0.json: valid.
• The apiv1 v3 instance with this spec (submodule pointing at this commit): full apiv1 suite (2625 passed) and a local end-to-end run of 89 person_list cases through nginx → apiv1 → figcore → MariaDB, all passing.

Notes

• Merge order: merge this PR first; the apiv1 PR (FIG-47098) bumps the api_docs submodule to it.
• The request schemas declare types and nullable, but no enum / length / readOnly constraints. apiv1 validates requests against this spec, so such constraints would turn figcore's 422 (with the offending path, e.g. authors[0].type) into a generic 400. A wrong JSON type (e.g. is_corresponding: "yes") is still a 400 from request validation, as for every v3 body.

🤖 Generated with Claude Code