{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "definitions": {
        "$schema": {
            "$comment": "TO REVIEW: adding a `format` or `regex` attribute that validates correctly against a file path (relative).",
            "description": "Refers to the JSON Schema which describes the set of valid attributes for this particular document type. This attribute is mostly used in schemas that should be tested in Beacon implementations.",
            "type": "string"
        },
        "ApiVersion": {
            "description": "Version of API, e.g. in request or response. Beacon uses a Github-style, \"v\"-prefixed semantic versioning format.",
            "examples": [
                "v2.0.1",
                "v0.3"
            ],
            "type": "string"
        },
        "BeaconError": {
            "description": "Beacon-specific error.",
            "properties": {
                "errorCode": {
                    "description": "Entry not found",
                    "examples": [
                        "404"
                    ],
                    "format": "int32",
                    "type": "integer"
                },
                "errorMessage": {
                    "examples": [
                        "The provided parameters are incomplete: `start` is missing."
                    ],
                    "type": "string"
                }
            },
            "required": [
                "errorCode"
            ],
            "type": "object"
        },
        "BeaconId": {
            "description": "The Id of a Beacon. Usually a reversed domain string, but any URI is acceptable. The purpose of this attribute is, in the context of a Beacon network, to disambiguate responses coming from different Beacons.",
            "examples": [
                "org.example.beacon.v2",
                "org.progenetix.beacon"
            ],
            "type": "string"
        },
        "CURIE": {
            "description": "Definition of an identifier in the CURIE `prefix:local-part` format which is the default type of e.g. ontology term `id` values (used e.g. for filters or external identifiers).",
            "examples": [
                "ga4gh:GA.01234abcde",
                "DUO:0000004",
                "orcid:0000-0003-3463-0775",
                "PMID:15254584"
            ],
            "pattern": "^\\w[^:]+:.+$",
            "type": "string"
        },
        "Exists": {
            "description": "Indicator of whether any record was observed in any of the collections queried. This should be non-null.",
            "examples": [
                true
            ],
            "type": "boolean"
        },
        "Filters": {
            "description": "Ontology based filters. A CURIE syntax is encouraged to be used.",
            "example": [
                "BTO:0000199",
                "PATO:0000383"
            ],
            "items": {
                "type": "string"
            },
            "type": "array"
        },
        "Granularity": {
            "default": "boolean",
            "description": "Level of detail of the response:\n* `boolean`: returns true/false' responses * `count`: adds the total number of positive results found * `aggregated`: returns summary, aggregated or distribution like responses * `record`: returns details for every row. In cases where a Beacon prefers to return records with fewer than allattributes, different strategies have to be considered w/o adding them to the current design, e.g.:\n    - keeping non-mandatory attributes empty\n    - Beacon to provide a minimal record definition",
            "enum": [
                "boolean",
                "count",
                "aggregated",
                "record"
            ],
            "type": "string"
        },
        "Handover": {
            "description": "A handover is a typed link for attaching actionable links to results, non purely informational, requests. The goal of the handovers is to list the different actions available, e.g.:\n* a link to a request access page * linking to a file for download, e.g. a VCF file\nAnother common scenario is to provide a fast summary response (e.g. BeconCountResponse) and to provide access to different endpoints for the entities matched by the query using temporary access tokens in the handover URLs.",
            "properties": {
                "handoverType": {
                    "$ref": "#/definitions/HandoverType"
                },
                "note": {
                    "description": "An optional text including considerations on the handover link provided.",
                    "example": "This handover link provides access to a summarized VCF.",
                    "type": "string"
                },
                "url": {
                    "description": "URL endpoint to where the handover process could progress, in RFC3986 format",
                    "example": "https://api.mygenomeservice.org/Handover/9dcc48d7-fc88-11e8-9110-b0c592dbf8c0/",
                    "format": "uri",
                    "type": "string"
                }
            },
            "required": [
                "handoverType",
                "url"
            ],
            "type": "object"
        },
        "HandoverType": {
            "$ref": "./ontologyTerm.json",
            "description": "Handover type, as an Ontology_term object with CURIE syntax for the `id` value. Use `CUSTOM` for the `id` when no ontology is available.",
            "examples": [
                {
                    "id": "EFO:0004157",
                    "label": "BAM format"
                },
                {
                    "id": "CUSTOM",
                    "label": "download genomic variants in .pgxseg file format"
                }
            ]
        },
        "IncludeResultsetResponses": {
            "default": "HIT",
            "description": "Indicator of whether responses from every Resultset should be included in the response to this request or just the ones with positive, negative results or no details at all. If null (not specified), the default value of 'HIT' is assumed. This parameter allows for returning boolean/counting results although the Beacon instance is capable to return record level details.",
            "enum": [
                "ALL",
                "HIT",
                "MISS",
                "NONE"
            ],
            "examples": [
                "ALL",
                "HIT",
                "MISS",
                "NONE"
            ],
            "type": "string"
        },
        "Info": {
            "description": "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.",
            "type": "object"
        },
        "Limit": {
            "default": 10,
            "description": "Size of the page. Use `0` to return all the results or the maximum allowed by the Beacon, if there is any.",
            "example": 10,
            "minimum": 0,
            "type": "integer"
        },
        "ListOfHandovers": {
            "description": "Set of handovers to be added in one section the response.",
            "items": {
                "$ref": "#/definitions/Handover",
                "description": "Requested schema to be used for individuals in the response."
            },
            "type": "array"
        },
        "ListOfSchemas": {
            "description": "Set of schemas to be used in the response to a request.",
            "items": {
                "$ref": "#/definitions/SchemasPerEntity"
            },
            "type": "array"
        },
        "NonFilteredQueriesAllowed": {
            "default": true,
            "description": "Switch that declares if this Beacon instance, for a given entry type, admits queries that does not include any element that restrict returning all the results, like filters, parameters, ids, etc. The default value is 'true' for backward compatibility and for clarity in the request-response dialog.",
            "type": "boolean"
        },
        "NumTotalResults": {
            "description": "Total number of results. NOT the number of results returned in this batch (after pagination) but the total obtained by the query.",
            "examples": [
                123
            ],
            "minimum": 0,
            "type": "integer"
        },
        "PageToken": {
            "description": "A hash or similar that allows the server to retrieve a \"page\", e.g. (a subset of) a query response.",
            "example": "ab0sc&fe1dd",
            "type": "string"
        },
        "Pagination": {
            "description": "Pagination to apply or that has been applied on the results.",
            "properties": {
                "currentPage": {
                    "$ref": "#/definitions/PageToken",
                    "description": "Token of the returned page. To be used only in the response to allow the client to check if the returned page is the one requested."
                },
                "limit": {
                    "$ref": "#/definitions/Limit"
                },
                "nextPage": {
                    "$ref": "#/definitions/PageToken",
                    "description": "Token of the next page. Used to navigate forward. If empty, it is assumed that no more pages are available"
                },
                "previousPage": {
                    "$ref": "#/definitions/PageToken",
                    "description": "Token of the previous page. Used to navigate backwards. If empty, it is assumed that the current page is the first one."
                },
                "skip": {
                    "$ref": "#/definitions/Skip"
                }
            },
            "type": "object"
        },
        "SchemasPerEntity": {
            "description": "Schema to be used for the requested entry type in the response.",
            "properties": {
                "entityType": {
                    "$comment": "TO REVIEW: Should that refer to a concept definition? Or would that include an undesired dependency to the configuration?",
                    "example": "Individual",
                    "type": "string"
                },
                "schema": {
                    "$comment": "TO DO: Add the correct format as 'uri' or 'regex'",
                    "examples": [
                        "./ga4gh-beacon-dataset-v2.0.0",
                        "https://www.example.org/schemas/ga4gh-beacon-dataset-v2.0.0.json"
                    ],
                    "type": "string"
                }
            },
            "type": "object"
        },
        "Skip": {
            "default": 0,
            "description": "* In the request: number of pages to skip * In the response: number of pages that has been skipped",
            "example": 0,
            "minimum": 0,
            "type": "integer"
        },
        "TestMode": {
            "default": false,
            "description": "Used for indicating that a request or response is done in a test context e.g. for compliance testing i.e. to evaluate the acceptance/understanding of a request and the structure of the returned response by the Beacon instance. A TRUE `testMode` parameter DOES NOT require that the Beacon instance is a test instance, but that this specific request-response cycle is a testing one. When `true` the Beacon instance MUST respond the request but it SHOULD use virtual or non-sensitive data. Here, what is being evaluated is the acceptance/understanding of a request and the structure of the returned response by the Beacon instance.",
            "type": "boolean"
        }
    },
    "description": "Definition of relatively simple components used in different points of the Beacon specification, both in requests and responses, therefore not associated exclusively with one or the other. Separate schema documents are provided for complex components.",
    "title": "Beacon Common Components",
    "type": "object"
}