diff --git a/src/main/proto/ga4gh/beacon.proto b/src/main/proto/ga4gh/beacon.proto new file mode 100644 index 00000000..36c166ec --- /dev/null +++ b/src/main/proto/ga4gh/beacon.proto @@ -0,0 +1,268 @@ +syntax = "proto3"; + +package ga4gh; + +// A Beacon is a web service for genetic data sharing that can be queried for +// information about specific alleles. +// Query for information about a specific allele. Based on ga4gh variant. +message BeaconAlleleRequest { + // Reference name (chromosome). + // + // Accepted values: 1-22, X, Y. + // Required. + string reference_name = 1; + + // Position, genomic locus (0-based). This is represented as a list with + // 1..2 elements. + // For the querying of variants with known exact position and composition, + // the use of a single start position value is sufficient. + // For querying imprecise positions (e.g. identifying all structural variants + // starting in a genomic region), 2 values indicating start and end of this + // region are required. + // + // Accepted values: 1 or 2 non-negative integers smaller than reference length. + // Required. + repeated int64 start = 2; + + // Position of the end of avariant as genomic locus (0-based). This is + // represented as a list with of 0..2 elements. + // A query against variants with known exact position and composition (e.g. + // single base SNP), no "end" parameters have to be specified. + // For the query against e.g. a structural variant with known exact end + // position, the use of a single end value is possible. + // For querying imprecise positions (e.g. identifying all structural variants + // starting in a genomic region), 2 values indicating start and end of the + // assumed end are required. + // + // Accepted values: 0, 1 or 2 non-negative integers smaller or equal to the + // reference length. + // Optional. + repeated int64 end = 3; + + // Reference bases for this variant (starting from `start`). + // + // Accepted values: see the REF field in VCF 4.2 specification + // (https://samtools.github.io/hts-specs/VCFv4.2.pdf). + // Optional. + string reference_bases = 4; + + // The bases that appear instead of the reference bases. + // + // Accepted values: see the ALT field in VCF 4.2 specification + // (https://samtools.github.io/hts-specs/VCFv4.2.pdf). + // Optional (either "alternate_bases" or "variant_type" is required) + string alternate_bases = 5; + + // The "variant_type" is used to denote e.g. structural variants. + // Examples: + // DUP : duplication of sequence following "start"; not necessarily in situ + // DEL : deletion of sequence following "start" + // Optional (either "alternate_bases" or "variant_type" is required) + string variant_type = 6; + + // Assembly identifier (GRC notation, e.g. `GRCh37`). + string assembly_id = 6; + + // Identifiers of datasets, as defined in `BeaconDataset`. + // + // If this field is null/not specified, all datasets should be queried. + // Optional. + repeated string dataset_ids = 7; + + // Indicator of whether responses for individual datasets + // (`datasetAlleleResponses`) should be included (not null) in the response + // (`BeaconAlleleResponse`) to this request. + // + // If null (not specified), the default value of false is assumed. + // Optional. + bool include_dataset_responses = 8; +} + +// Dataset of a beacon. +message BeaconDataset { + // Unique identifier of the dataset. + string id = 1; + + // Name of the dataset. + string name = 2; + + // Description of the dataset. + string description = 3; + + // Assembly identifier (GRC notation, e.g. `GRCh37`). + string assembly_id = 4; + + // The time the dataset was created (ISO 8601 format). + string create_date_time = 5; + + // The time the dataset was updated in (ISO 8601 format). + string update_date_time = 6; + + // Version of the dataset. + string version = 7; + + // Total number of variants in the dataset. + int64 variant_count = 8; + + // Total number of calls in the dataset. + int64 call_count = 9; + + // Total number of samples in the dataset. + int64 sample_count = 10; + + // URL to an external system providing more dataset information (RFC 3986 format). + string external_url = 11; + + // A map of additional information. + map info = 12; +} + +// Organization owning a beacon. +message BeaconOrganization { + // Unique identifier of the organization. + string id = 1; + + // Name of the organization. + string name = 2; + + // Description of the organization. + string description = 3; + + // Address of the organization. + string address = 4; + + // URL of the website of the organization (RFC 3986 format). + string welcome_url = 5; + + // URL with the contact for the beacon operator/maintainer, e.g. link to + // a contact form (RFC 3986 format) or an email (RFC 2368 format). + string contact_url = 6; + + // URL to the logo (PNG/JPG format) of the organization (RFC 3986 format). + string logoUrl = 7; + + // A map of additional information. + map info = 12; +} + +// Beacon. +message Beacon { + // Unique identifier of the beacon. + string id = 1; + + // Name of the beacon. + string name = 2; + + // Version of the API provided by the beacon. + string api_version = 3; + + // Organization owning the beacon. + BeaconOrganization organization = 4; + + // Description of the beacon. + string description = 5; + + // Version of the beacon. + string version = 6; + + // URL to the welcome page for this beacon (RFC 3986 format). + string welcome_url = 7; + + // Alternative URL to the API, e.g. a restricted version of this beacon + // (RFC 3986 format). + string alternative_url = 8; + + // The time the beacon was created (ISO 8601 format). + string create_date_time = 9; + + // The time the beacon was updated in (ISO 8601 format). + string update_date_time = 10; + + // Datasets served by the beacon. Any beacon should specify at least one + // dataset. + repeated BeaconDataset datasets = 11; + + // Examples of interesting queries, e.g. a few queries demonstrating different + // responses. + repeated BeaconAlleleRequest sample_allele_requests = 12; + + // A map of additional information. + map info = 13; +} + +// Beacon-specific error representing an unexpected problem. +message BeaconError { + // Numeric error code. + int32 error_code = 1; + + // Error message. + string message = 2; +} + +// Dataset's response to a query for information about a specific allele. +message BeaconDatasetAlleleResponse { + // Identifier of the dataset, as defined in `BeaconDataset`. + string dataset_id = 1; + + // Indicator of whether the given allele was observed in the dataset. + // + // This should be non-null, unless there was an error, in which case + // `error` has to be non-null. + bool exists = 2; + + // Dataset-specific error. + // + // This should be non-null in exceptional situations only, in which case + // `exists` has to be null. + BeaconError error = 3; + + // Frequency of this allele in the dataset. Between 0 and 1, inclusive. + double frequency = 4; + + // Number of variants matching the allele request in the dataset. + int64 variant_count = 5; + + // Number of calls matching the allele request in the dataset. + int64 call_count = 6; + + // Number of samples matching the allele request in the dataset. + int64 sample_count = 7; + + // Additional note or description of the response. + string note = 8; + + // URL to an external system, such as a secured beacon or a system providing + // more information about a given allele (RFC 3986 format). + string external_url = 9; + + // A map of additional information. + map info = 13; +} + +// Beacon's response to a query for information about a specific allele. +message BeaconAlleleResponse { + // Identifier of the beacon, as defined in `Beacon`. + string beacon_id = 1; + + // Indicator of whether the given allele was observed in any of the datasets + // queried. + // + // This should be non-null, unless there was an error, in which case + // `error` has to be non-null. + bool exists = 2; + + // Beacon-specific error. + // + // This should be non-null in exceptional situations only, in which case + // `exists` has to be null. + BeaconError error = 3; + + // Allele request as interpreted by the beacon. + BeaconAlleleRequest allele_request = 4; + + // Indicator of whether the given allele was observed in individual datasets. + // + // This should be non-null if `includeDatasetResponses` in the corresponding + // `BeaconAlleleRequest` is true, and null otherwise. + repeated BeaconDatasetAlleleResponse dataset_allele_responses = 5; +} diff --git a/src/main/proto/ga4gh/beacon_service.proto b/src/main/proto/ga4gh/beacon_service.proto new file mode 100644 index 00000000..e4d19efa --- /dev/null +++ b/src/main/proto/ga4gh/beacon_service.proto @@ -0,0 +1,43 @@ +syntax = "proto3"; + +package ga4gh; + +import "ga4gh/beacon.proto"; +import "google/protobuf/empty.proto"; + +service BeaconService { + + // + // Gets beacon information. + // `GET /` (root of the beacon API) returns a representation of `Beacon`. + rpc GetBeacon(google.protobuf.Empty) + returns (Beacon); + + // Gets response to a beacon query for allele information. + // + // GET and POST HTTP verbs must be supported. `GET /query` accepts fields of + // `BeaconAlleleRequest` as URL parameters and returns a JSON representation of + // `BeaconAlleleResponse`. `POST /query` accepts a JSON representation of + // `BeaconAlleleRequest` as the request body and returns a JSON representation + // of `BeaconAlleleResponse`. + // + // Examples: + // GET /query?referenceName=1&start=1000&referenceBases=A&alternateBases=C + // &assemblyId=GRCh37&datasetIds=d1&datasetIds=d2 + // + // POST /query + // { + // "referenceName": "1", + // "start": 1000, + // "referenceBases": "A", + // "alternateBases": "C", + // "assemblyId": "GRCh37", + // "datasetIds": [ + // "d1", + // "d2" + // ] + // } + rpc GetBeaconAlleleResponse(BeaconAlleleRequest) + returns(BeaconAlleleResponse); + +} \ No newline at end of file diff --git a/src/main/resources/avro/beacon.avdl b/src/main/resources/avro/beacon.avdl deleted file mode 100644 index 0fbee28c..00000000 --- a/src/main/resources/avro/beacon.avdl +++ /dev/null @@ -1,276 +0,0 @@ -@namespace("org.ga4gh.beacon") - -/** -A Beacon is a web service for genetic data sharing that can be queried for -information about specific alleles. -*/ -protocol Beacons { - -/** -Query for information about a specific allele. - -Based on `org.ga4gh.models.Variant`. -*/ -record BeaconAlleleRequest { - /** - Reference name (chromosome). - - Accepted values: 1-22, X, Y. - */ - string referenceName; - - /** - Position, allele locus (0-based). - - Accepted values: non-negative integers smaller than reference length. - */ - long start; - - /** - Reference bases for this variant (starting from `start`). - - Accepted values: see the REF field in VCF 4.2 specification - (https://samtools.github.io/hts-specs/VCFv4.2.pdf). - */ - string referenceBases; - - /** - The bases that appear instead of the reference bases. - - Accepted values: see the ALT field in VCF 4.2 specification - (https://samtools.github.io/hts-specs/VCFv4.2.pdf). - */ - string alternateBases; - - /** Assembly identifier (GRC notation, e.g. `GRCh37`). */ - string assemblyId; - - /** - Identifiers of datasets, as defined in `BeaconDataset`. - - If this field is null/not specified, all datasets should be queried. - */ - union{ null, array } datasetIds = null; - - /** - Indicator of whether responses for individual datasets - (`datasetAlleleResponses`) should be included (not null) in the response - (`BeaconAlleleResponse`) to this request. - - If null (not specified), the default value of false is assumed. - */ - union{ null, boolean } includeDatasetResponses = null; -} - -/** Dataset of a beacon. */ -record BeaconDataset { - /** Unique identifier of the dataset. */ - string id; - - /** Name of the dataset. */ - string name; - - /** Description of the dataset. */ - union{ null, string } description = null; - - /** Assembly identifier (GRC notation, e.g. `GRCh37`). */ - string assemblyId; - - /** The time the dataset was created (ISO 8601 format). */ - string createDateTime; - - /** The time the dataset was updated in (ISO 8601 format). */ - string updateDateTime; - - /** Version of the dataset. */ - union{ null, string } version = null; - - /** Total number of variants in the dataset. */ - union{ null, long } variantCount = null; - - /** Total number of calls in the dataset. */ - union{ null, long } callCount = null; - - /** Total number of samples in the dataset. */ - union{ null, long } sampleCount = null; - - /** URL to an external system providing more dataset information (RFC 3986 format). */ - union{ null, string } externalUrl = null; - - /** Additional structured metadata, key-value pairs. */ - union{ null, map } info = null; -} - -/** Organization owning a beacon. */ -record BeaconOrganization { - /** Unique identifier of the organization. */ - string id; - - /** Name of the organization. */ - string name; - - /** Description of the organization. */ - union{ null, string } description = null; - - /** Address of the organization. */ - union{ null, string } address = null; - - /** URL of the website of the organization (RFC 3986 format). */ - union{ null, string } welcomeUrl = null; - - /** - URL with the contact for the beacon operator/maintainer, e.g. link to - a contact form (RFC 3986 format) or an email (RFC 2368 format). - */ - union{ null, string } contactUrl = null; - - /** - URL to the logo (PNG/JPG format) of the organization (RFC 3986 format). - */ - union{ null, string } logoUrl = null; - - /** Additional structured metadata, key-value pairs. */ - union{ null, map } info = null; -} - -/** Beacon. */ -record Beacon { - /** Unique identifier of the beacon. */ - string id; - - /** Name of the beacon. */ - string name; - - /** Version of the API provided by the beacon. */ - string apiVersion; - - /** Organization owning the beacon. */ - BeaconOrganization organization; - - /** Description of the beacon. */ - union{ null, string } description = null; - - /** Version of the beacon. */ - union{ null, string } version = null; - - /** URL to the welcome page for this beacon (RFC 3986 format). */ - union{ null, string } welcomeUrl = null; - - /** - Alternative URL to the API, e.g. a restricted version of this beacon - (RFC 3986 format). - */ - union{ null, string } alternativeUrl = null; - - /** The time the beacon was created (ISO 8601 format). */ - union{ null, string } createDateTime; - - /** The time the beacon was updated in (ISO 8601 format). */ - union{ null, string } updateDateTime; - - /** - Datasets served by the beacon. Any beacon should specify at least one - dataset. - */ - array datasets = []; - - /** - Examples of interesting queries, e.g. a few queries demonstrating different - responses. - */ - union{ null, array } sampleAlleleRequests = null; - - /** Additional structured metadata, key-value pairs. */ - union{ null, map } info = null; -} - -/** Beacon-specific error representing an unexpected problem. */ -record BeaconError { - /** Numeric error code. */ - int errorCode; - - /** Error message. */ - union{ null, string } message = null; -} - -/** Dataset's response to a query for information about a specific allele. */ -record BeaconDatasetAlleleResponse { - /** Identifier of the dataset, as defined in `BeaconDataset`. */ - string datasetId; - - /** - Indicator of whether the given allele was observed in the dataset. - - This should be non-null, unless there was an error, in which case - `error` has to be non-null. - */ - union{ null, boolean } exists; - - /** - Dataset-specific error. - - This should be non-null in exceptional situations only, in which case - `exists` has to be null. - */ - union{ null, BeaconError } `error` = null; - - /** Frequency of this allele in the dataset. Between 0 and 1, inclusive. */ - union{ null, double } frequency = null; - - /** Number of variants matching the allele request in the dataset. */ - union{ null, long } variantCount = null; - - /** Number of calls matching the allele request in the dataset. */ - union{ null, long } callCount = null; - - /** Number of samples matching the allele request in the dataset. */ - union{ null, long } sampleCount = null; - - /** Additional note or description of the response. */ - union{ null, string } note = null; - - /** - URL to an external system, such as a secured beacon or a system providing - more information about a given allele (RFC 3986 format). - */ - union{ null, string } externalUrl = null; - - /** Additional structured metadata, key-value pairs. */ - union{ null, map } info = null; -} - -/** Beacon's response to a query for information about a specific allele. */ -record BeaconAlleleResponse { - /** Identifier of the beacon, as defined in `Beacon`. */ - string beaconId; - - /** - Indicator of whether the given allele was observed in any of the datasets - queried. - - This should be non-null, unless there was an error, in which case - `error` has to be non-null. - */ - union{ null, boolean } exists; - - /** - Beacon-specific error. - - This should be non-null in exceptional situations only, in which case - `exists` has to be null. - */ - union{ null, BeaconError } `error` = null; - - /** Allele request as interpreted by the beacon. */ - union{ null, BeaconAlleleRequest } alleleRequest; - - /** - Indicator of whether the given allele was observed in individual datasets. - - This should be non-null if `includeDatasetResponses` in the corresponding - `BeaconAlleleRequest` is true, and null otherwise. - */ - union{ null, array } datasetAlleleResponses = null; -} - -} diff --git a/src/main/resources/avro/beaconmethods.avdl b/src/main/resources/avro/beaconmethods.avdl deleted file mode 100644 index af434aae..00000000 --- a/src/main/resources/avro/beaconmethods.avdl +++ /dev/null @@ -1,45 +0,0 @@ -@namespace("org.ga4gh.beacon") - -protocol BeaconMethods { - -import idl "beacon.avdl"; - -/**************** / *******************/ -/** -Gets beacon information. - -`GET /` (root of the beacon API) returns a representation of `Beacon`. -*/ -Beacon getBeacon(); - -/**************** /query *******************/ -/** -Gets response to a beacon query for allele information. - -GET and POST HTTP verbs must be supported. `GET /query` accepts fields of -`BeaconAlleleRequest` as URL parameters and returns a JSON representation of -`BeaconAlleleResponse`. `POST /query` accepts a JSON representation of -`BeaconAlleleRequest` as the request body and returns a JSON representation -of `BeaconAlleleResponse`. - -Examples: -GET /query?referenceName=1&start=1000&referenceBases=A&alternateBases=C -&assemblyId=GRCh37&datasetIds=d1&datasetIds=d2 - -POST /query -{ - "referenceName": "1", - "start": 1000, - "referenceBases": "A", - "alternateBases": "C", - "assemblyId": "GRCh37", - "datasetIds": [ - "d1", - "d2" - ] -} -*/ -BeaconAlleleResponse getBeaconAlleleResponse( - BeaconAlleleRequest beaconAlleleRequest); - -}