/media/v3/preview_url response spec should include more properties

[cperrin88]

Link to problem area:

matrix-spec/data/api/client-server/content-repo.yaml

Lines 774 to 783 in 0b43b5a

	properties:
	matrix:image:size:
	type: integer
	format: int64
	description: The byte-size of the image. Omitted if there is no image attached.
	og:image:
	type: string
	format: uri
	description: An [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris) to
	the image. Omitted if there is no image.

Issue
The /media/v3/preview_url endpoint spec includes only the matrix:image:size and the og:image properties. This means that clients that are based purely on the OpenAPI export, don't expose other OpenGraph properties beyond the image.

Expected behaviour
The spec should contain at least the following properties as optional:

• og:title
• og:type
• og:url
• og:description

With these properties it is possible to create a useful preview with more than just the image.

OpenGraph: https://ogp.me/

[richvdh]

@cperrin88 is this causing a problem in the rendered output? If so, please could you link to the part of the spec that is incorrect? Or is the effect limited to the OpenAPI data?

[cperrin88]

I'd say that's up for discussion. I think that the addtional fields might be helpful in the docs as a reference for what might be returned. The more important part for me is the OpenAPI spec. Any client that is created from this spec will not be able to display anything apart from the image data unless manually modified.

[richvdh]

Without a link to the spec doc, I'll be honest that it's unlikely to get much attention.

If you have strong opinions, feel free to open a PR which we can use as a basis for discussion.

[cperrin88]

What do mean with a link? I thought I had linked all the relevant things.

I'd be willing to open a PR. Where would be the best place to ask questions since I am not familiar with the repo?

[clokep]

The rendered link: https://spec.matrix.org/v1.10/client-server-api/#get_matrixmediav3preview_url

[richvdh]

I'd be willing to open a PR. Where would be the best place to ask questions since I am not familiar with the repo?

Thanks! The Matrix Spec & Docs Authoring room is the best place to discuss updates to the matrix-spec repo.