Open specification API (Additional info fields)

[gcornut]

OLD POST: Could we consider generalizing an "additionnalInfo" field for every BrAPI objects?

EDIT: I have renamed this issue because I think we could consider going much farther in BrAPI specification openness.

Allowing any kind of additional fields in the BrAPI response is definitely not a good idea now because it could cause naming conflicts with new fields appearing in new BrAPI versions. But once we have migrated to JSON-LD, each JSON field will have a unique URI identity which would prevent naming conflict/collision.

So, once BrAPI is in JSON-LD, we could consider opening the API specification so that we only enforce required fields and allow any additional field.

Some advantages of this openness:

• Validating a BrAPI v2.3 server on a v2.1 validator would work (IFF no deletion was made between v2.1 and v2.3 but only addition)
• Allow adding new official BrAPI fields in minor version without implementation breaks (no need to rewrite any server/client/validator except if you need that field)
• Allow using standard RDF properties on any BrAPI object (ex: http://schema.org/description as a generic BrAPI object description)

Some disadvantage:

• Force every implementation to allow additional fields (some JSON parser are very strict :frowning_face:)
• Might be confusing for client if the server displays a lot of unofficial BrAPI fields

[guignonv]

I don't think it makes sense. I wonder how would a generic client manage such kind of field? And if you have a specific client that can deal with "your" additionnalInfo field content, how would it behave with others that do not match your patterns? :-S

[BrapiCoordinatorSelby]

BrAPI V2.0 additionalInfo has been standardized and added to all primary BrAPI entities.

@gcornut I feel the additionalInfo gives a clear and obvious separation between data which is part of the BrAPI specification and extra data which is needed to solve specific use cases. That said, as long as you provide documentation for your server, I don't care where you put extra data. If a client application is being built to the BrAPI spec, it will be looking for fields from the BrAPI spec (whether or not you are using JSON-LD). if you have a client being built for a specific purpose against your API implementation, then it will be looking for extra data, and your API documentation should be able to tell the developer where to find it.