Missing upload still has its string ID in the JSON response

[hdodov]

Link to reproduction

https://github.com/hdodov/payload/tree/bug-missing-media

To Reproduce

1. Create an upload-enabled collection
2. Open the admin
3. Create a new entry in that collection and associate an upload with it
4. Go to the uploads collection and delete the upload
5. The JSON response for the entry will have a string as a value for the upload

Describe the Bug

Services that consume the Payload API expect either an upload to exist or not. In other words, if you have a field associatedMedia, the value for it should either be null or an object — with url, width, etc. You don't really expect it to be a string, unless you specify depth and you set it to 0.

There is also another case where you haven't initially specified a value for the upload, in which case the associatedMedia value is simply not present in the JSON. This could also cause problems.

Basically there are four possibilities for the value of associatedMedia:

• undefined (missing from the JSON) - initially, when the user hasn't specified any value for the field
• object - when an upload is selected by the user and can be successfully populated when a request occurs
• string - when the upload has been deleted from the collection and can no longer be populated
• null - when the user has uploaded and selected a file, then removed it

It's useful to have this difference between undefined and null, and you can catch both of them with a truthy check, but the string situation is unexpected. If Payload attempts to populate a field from an external collection and fails to do so, it should return null as the value, since that resource no longer exists.

Screen.Recording.2023-07-17.at.14.35.46.mov

Payload Version

1.11.2

[DanRibbens]

Hey @hdodov,

Thanks for reporting! I'll add that there is a 2nd situtation where a string is returned and that is if the access control on the related document prevents it from populating.

We have a roadmap item #2938 that will help the usability on the admin side for this situation. I'm going to convert this to a discussion since right now it is working as intended for now.

[hdodov]

I see. Well, my idea is that if nothing prevents Payload from trying to populate, then it tries and fails — it should return null.

If I've set access control on the related document, then at least I'd expect to have to handle some edge cases. But if access control blocks something, I'd still expect some falsy value.

Perhaps you could eliminate all of this with some associated metadata? For example, when everything is alright:

{
	"title": "My Document",
	"associatedMedia": {
		"status": "ok",
		"value": {
			"url": "https://example.com/hello.jpg",
			"width": 640,
			"height": 400
			// ...
		}
	}
}

…when the document couldn't be found:

"associatedMedia": {
	"status": "not_found",
	"value": "64b5278e6dcb9500cab16d82"
}

…or, when the user is blocked, you could even add a reason:

"associatedMedia": {
	"status": "not_allowed",
	"message": "Access control on collection \"media\" does not allow read",
	"value": "64b5278e6dcb9500cab16d82"
}

This way the database remains the single source of truth. Whatever is stored there - that gets returned as the value (only unless Payload populates the document). Meanwhile, users can use this status property to perform sanity checks and even get a bit of an easier time debugging thanks to the message property. This would also free you up to handle future edge cases while remaining backwards compatible simply by adding new statuses.