DbIds and Names

From BrAPI-Wiki
Jump to navigation Jump to search


All objects represented in BrAPI have a xxxDbId field. This field represents a primary key which will uniquely identify that object within the database being queried. It is NOT guaranteed to be unique across multiple systems, though it could be. DbIds should primarily be used to link data together within a system.

For example, in a given call, an Observation Unit object is returned with the stduyDbId. In a subsequent call to the same system, you should be able to retrieve the Study Object directly based on the stduyDbId.

DbIds Special Case

There was a special case raised in GitHub Issue #85 where the DbId string was a URL (a DOI url in this specific case, but any url will have the same problem). URLs generally contains the / character which makes them difficult to use as parts of the path in a REST call.

Recommendation: If possible, avoid using URLs as DbIds to avoid this issue. There are other fields available for communicating a variety of URLs to a client, reserve the DbId field for a convenient primary key for linking to other objects.

If you must use a URL as a DbId, you must encode it in some way to hide the slashes. Your system will need to accept the encoded string in a request and un-encode it before querying the database. Likewise, when responding to a request, your system will need to retrieve the URL from the database and encode it before returning. The specific encoding schema doesn't matter, as long as it produces consistent results within your system. GitHub Issue #85 describes a double URL symbol encoding scheme which works. Hexadecimal encoding is another option.


Several BrAPI entities have a xxxPUI field for a Permanent Unique Identifier. This is meant to be a global identifier shared across different data sources. PUIs usually take the form of a URI, with a combination of identifying authority and unique identity value. For example, the Digital Object Identifier (DOI) system is often used to assign PUIs.

Unlike DbIds, PUIs are never used in BrAPI paths, so there is no problem if a PUI contains slashes. In several cases, PUIs can be used as query parameters, so it can be helpful to use the encoding %2F to replace an slash characters in URL query parameters.

External References

Every BrAPI V2 entity has a list of externalReferences. These are meant to record additional identifiers for a data object, usually originating from other tools and systems. This can assist with linking to different systems, without altering the DbIds or PUIs. A particularly important use case for using externalReferences comes from uploading data to a database. When uploading data, the original DbId is not preserved by default because it is assumed that each system will assign a new primary key for new data. The externalReferences allow the originating system to preserve a DbId while uploading. This is often very useful for maintaining links between data.


Most objects represented in BrAPI have a xxxName field. This field is meant to be a short, human readable summary of the object. It is NOT guaranteed to be unique in ANY WAY. Names are a convenient way to interact with users by printing on a screen or searching. Names may be created by a human user or generated automatically by some concatenation of other data points. Name fields should not be used to pass any data other than the intended human readable reference string. For example, the name Field_Trial_abc123 should never be parsed to extract abc123 as a usable DbId or piece of data.