Clearly document all media properties

[obulat]

Start Date	Project Lead	Actual Ship Date
2023-03-01	@dhruvkb	TBD

Description

All the details we collect and store for each media type should be clearly documented, and should be consistent across the stack (Catalog, API and Frontend).

Due to historic reasons during the development of the project, not all properties that are deemed required are available in the data. As a pre-requisite to making the data more consistent, we need to document all the media properties and whether they are available (should be available in the future) in the database or are added by the API/ingestion server/elasticsearch/frontend.

Also, we need to document whether the properties are nullable, and what their constraints are. Although we have the database constraints, some of them are not reliable.

Documents

• Project Proposal: Document all media properties #855

Implementation Plans

• Implementation Plan: Clearly document all media properties in the catalog #1995
• Implementation Plan: Clearly document all media properties in catalog in API & Frontend #1996

Issues

Prior Art

• Excellent table for image fields by @rwidom : https://docs.google.com/spreadsheets/d/1gaVsvFnsYby2iwzRm0Ta9IPhvNixCpQdHByGLo1r_pg/edit?usp=sharing ("image table ddl" tab)
• Related analysis was attempted in the Data normalization issue Normalize data models #244

[obulat]

Update 2023-04-26

The project proposal has been finalized, and the PR with the Catalog implementation plan (#1904) opened.
The migration to drf-spectacular that creates OpenAPI 3 spec in the API is also the foundation work for the API and frontend parts of this project.

Blockers

None.

[openverse-bot]

Hi @obulat, this project has not received an update comment in 14 days. Please leave an update comment as soon as you can. See the documentation on project updates for more information.

[openverse-bot]

Hi @obulat, this project has not received an update comment in 14 days. Please leave an update comment as soon as you can. See the documentation on project updates for more information.

[dhruvkb]

Update 2024-04-03:

Both implementation plans for the project have been approved and merged. Both implementation plans also have implementation PRs.

IP request	IP PR	IP impl request	IP impl PR
#1995	#1904	#2186	#3620
#1996	#3965	#4023	#3966

When both implementation scripts are merged, we will move this project to "Shipped" where it will stay while manual field documentation is being written. That is covered by these issues:

• Create the media properties description file #2187
• Write docstrings to document API fields #4024
• Write TSDoc to document frontend fields #4025

[openverse-bot]

Hi @dhruvkb, this project has not received an update comment in 14 days. Please leave an update comment as soon as you can. See the documentation on project updates for more information.

[openverse-bot]

Hi @dhruvkb, this project has not received an update comment in 14 days. Please leave an update comment as soon as you can. See the documentation on project updates for more information.

[dhruvkb]

This project has been shipped, efforts are underway to describe the properties manually across catalog, API and frontend, after which it can be considered successful.

[zackkrida]

I've begun work on #4025 and should have a PR out in the next 1-2 days.

[openverse-bot]

Hi @dhruvkb, this project has not received an update comment in 14 days. Please leave an update comment as soon as you can. See the documentation on project updates for more information.

[dhruvkb]

#4366 is the final PR which will close #2187 and also this project.