Can we unify Reference Object and External Resource Object in a single object definition?

[andrea-gioia]

Reference Object and External Resource Object have almost identical definitions.

In Reference Object there is the $ref field while in External Resource Object there is the $href. Both fields anyway point to the desired object/resource using a URI. The field mediaType is not present in Reference Object because it is implicitly assumed to be equal to the media type used for the descriptor document (i.e. JSON or YAML).

So why don't just have one Reference Object with the following fields and use it also to point to external resources?

Field Name	Type	Description
description	string	A description of the target internal or external resource. CommonMark syntax MAY be used for rich text representation.
mediaType	string	The media type of target internal or external resource. It MUST conform to media type format, according to RFC6838.
$ref	string:uri	REQUIRED. The URI of the target internal or external resource. It MUST conform to the URI format, according to RFC3986.

[andrea-gioia]

It's probably better to add the property mediaType to the Reference Object but at the same time keep the External Resource Object.

Adding mediaTypeproperty to the Reference Object will allow to referentiate external objects not encoded in JSON.

Keeping External Resource Object allow to differentiate between reference that point to objects that are part of the specification and so MUST be resolved and validated together with the rest of the descriptor document and reference to objects that are external to the specification and don't need to be resolved and validated.