Cross-entity references: docs say lists, OpenAPI says objects

[arcangelo7]

I think I found a mismatch between the data model html docs (https://skg-if.github.io/interoperability-framework/) and the OpenAPI spec (https://skg-if.github.io/api/openapi/ver/current/skg-if-openapi.yaml) in how entity-to-entity references are typed. When one entity points to another, the docs describe the value as an identifier (a list of strings), while the spec types it as a full nested object.

This affects organisations, grants, topics, venues, data sources and persons.

A possible payload following the docs

"funding": ["grant_789"]

A possible payload following the OpenAPI spec

"funding": [{ "local_identifier": "grant_789", "entity_type": "grant", "titles": {"en": "..."} }]

[rduyme]

Yes at the moment the payload in the OpenAPI is embedded.
This was done on purpose to avoid multiple API calls client side to get sub entities. The OpenAPI currently defines strict embedded structures. But it is confusing.

This is the main important change we want to push for official version 1.0.0

• There is initial PR Fix/schema identifier inconsistencies: allow identifier strings in cross-reference properties #54 , I am on the topic.

[rduyme]

Final PR #64
You can now return both ids or embed
I close

[rduyme]

Discussed in RDA WG meeting. I reopen for @andremann to update the model documentation as well