Defined mechanism for schema extensions

[mbaudis]

It is common for Beacon implementers to add additional parameters in their implementations. Beacon v2 has 2 basic mechanisms for this:

• an info parameter in many different model schemas, with the permissive "an object" definition in the framework (search for Info) and common use to e.g. in response payloads:

Placeholder to allow the Beacon to return any additional information that is necessary or could be of interest in relation to the query or the entry returned. It is recommended to encapsulate additional informations in this attribute instead of directly adding attributes at the same level than the others in order to avoid collision in the names of attributes in future versions of the specification.

• the additionalProperties: true pragma in many schemas

Here it seems prudent to provide a more-specific-but-open mechanism as demonstrated in the VRS v2.n proposal which uses a dedicated Extensions list parameter as wrapper for private/beyond model extensions:

The Extension class provides entities with a means to include additional attributes that are outside of the specified standard but needed by a given content provider or system implementer. These extensions are not expected to be natively understood, but may be used for pre-negotiated exchange of message attributes between systems.

This is pretty much in line with some Beacon schemas such as handovers or references.

Discuss, please...

[redmitry]

The /info schemas are not clear to me...
We have per entry "referenceToSchemaDefinition", so should /info "returnedSchemas" just duplicate this?
EGA ref. returns ("required") empty array :
https://beacon-ri-demo.ega-archive.org/api/info

Note, that providing your own schema it still must comply with the original one. Is there any tool to compare a compatibility between two schemas (A compatible with B)?

Cheers,

D.

[jrambla]

If I'm not mistaken, in the original Beacon v1, Michael's above approach "info different from extensions" was suggested and pushed back as it seemed redundant or already covered by the additionalProperties: true. I should say that this was not my opinion, but...
So, to do this change today, we would need to deprecated the usage of info for schema extensions and create that new extensions section.

I would be in favor of that, just with one big consideration:
if this lets us into making additionalProperties: false and forcing everyone to include an schema of their added properties, I believe that we could be generating more harm than good... hence, worth to explore the options.

In any case, the triggering question for me would be: "which is the problem/issue we want to solve with that change?"

[mbaudis]

@jrambla I would just add it, w/o removing the additionalProperties option (though this should be revisited per schema, in general, as a different issue - I'm not sure we're consistent in its use). The point is more about the info deprecation which however isn't a problem as long as additionalProperties: true exists.