Beacon specification

[pdl]

Is there a specification for Beacon? If so, where is it?

The only things approaching a specification I can find relating to it is an Avro schema, which is described as a work in progress, doesn't seem to exist in the two tagged versions of that repository, only in the current 'master' branch (although two versions are described here, apparently 0.1 and 0.2), and doesn't describe URL structure requirements or format expectations.

I notice that 19 institutions have apparently implemented Beacon, and some of the implementations are available (e.g. https://github.com/mcupak/beacon-of-beacons) - was there once a specification which has since disappeared or been deprecated?

We were hoping to put up a Beacon implementation but don't want to start unless we know that it's actually achievable at the moment, i.e. that we will be able to verify for ourselves that we have (or haven't) built a compliant implementation, by reference to a specification or a test suite.

Other resources that I've had a look at, to no avail:

• http://genomicsandhealth.org/work-products-demonstration-projects/beacon-project-0
• https://github.com/maximilianh/ucscBeacon
• http://hgwdev.cse.ucsc.edu/~jeltje/build/html/introduction.html

[skeenan]

have a look at

http://mcupak.github.io/beacon-of-beacons/beacons.html http://mcupak.github.io/beacon-of-beacons/beacons.html

On 28 Jul 2015, at 11:15, Daniel Perrett [email protected] wrote:

Is there a specification for Beacon? If so, where is it?

The only things approaching a specification I can find relating to it is an Avro schema https://github.com/ga4gh/schemas/blob/master/src/main/resources/avro/beacon.avdl, which is described as a work in progress http://ga4gh.org/#/schemas, doesn't seem to exist in the two tagged versions of that repository, only in the current 'master' branch (although two versions are described here http://beacon-network.org/#/developers/api/beacon, apparently 0.1 and 0.2), and doesn't describe URL structure requirements or format expectations.

I notice that 19 institutions have apparently implemented Beacon http://ga4gh.org/#/beacon, and some of the implementations are available (e.g. https://github.com/mcupak/beacon-of-beacons https://github.com/mcupak/beacon-of-beacons) - was there once a specification which has since disappeared or been deprecated?

We were hoping to put up a Beacon implementation but don't want to start unless we know that it's actually achievable at the moment, i.e. that we will be able to verify for ourselves that we have (or haven't) built a compliant implementation, by reference to a specification or a test suite.

Other resources that I've had a look at, to no avail:

http://genomicsandhealth.org/work-products-demonstration-projects/beacon-project-0 http://genomicsandhealth.org/work-products-demonstration-projects/beacon-project-0
https://github.com/maximilianh/ucscBeacon https://github.com/maximilianh/ucscBeacon
http://hgwdev.cse.ucsc.edu/~jeltje/build/html/introduction.html http://hgwdev.cse.ucsc.edu/%7Ejeltje/build/html/introduction.html
—
Reply to this email directly or view it on GitHub #1.

[pdl]

@skeenan Yes, I that is one of the implementations I had looked at.

[mcupak]

@pdl The official spec is indeed the Avro schema you listed. As you correctly pointed out, it's work in progress. The fact that it shares the repository with other independently developed schemas makes it difficult to tag it properly, which is why we started doing so on the Beacon Network site. If you're starting to implement a beacon now, the 0.2 version listed there is what you should be implementing.

As for the URL structure, the de facto standard is to provide 2 endpoints returning data in JSON:

• INFO endpoint returning BeaconInformationResource from the Avro file in response to a GET HTTP request, e.g. /info
• QUERY endpoint using the fields from the QueryResource in the Avro file as parameters for a GET HTTP request, e.g. something like /query?chromsome=?&reference=?&position=?&alternateBases=?&referenceBases=?

Several institutions implemented beacons, but due to the lack of standardization at the time, they're using different variations of the API, and often don't conform to 0.1 or 0.2. Beacon Network takes care of the conversions and wraps beacons in a unified API, which can be queried through http://beacon-network.org/.

[Relequestual]

Is it worth adding some of this information to the readme of this repo? I attempted to raise a similar issue (ga4gh/ga4gh-schemas#256 (comment)) but didn't get a response which could resolve the issue.

There needs to be some canonical documentaion.

[maximilianh]

Here is one of the JSON beacon implementation which has a short descriptive text and example requests: http://genome.ucsc.edu/cgi-bin/hgBeacon