Skip to content

Commit

Permalink
Merge pull request #92 from ga4gh-beacon/entry-type-definitions-cleanup
Browse files Browse the repository at this point in the history
Update entryTypeDefinition description
  • Loading branch information
costero-e authored Oct 8, 2024
2 parents 1686220 + 690ee96 commit 7e98b1e
Show file tree
Hide file tree
Showing 2 changed files with 52 additions and 38 deletions.
31 changes: 21 additions & 10 deletions framework/json/configuration/entryTypeDefinition.json
Original file line number Diff line number Diff line change
@@ -1,14 +1,13 @@
{
"$comment": "TO DO: The tagged parts should reference to `common/ontologizedElement.json`. But that configuration fails to validate. Further investigation is required, but should not affect the resulting schema.",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": true,
"description": "Definition of an element or entry type including the Beacon v2 required and suggested attributes. This schema purpose is to describe each type of entities included in a Beacon, hence Beacon clients could have some metadata about such entities.\n\nThe `id` attribute is the key that should be used in other parts of the Beacon Model to allow Beacon clients to identify the different parts (e.g. endpoints, filteringTerms, request parameters, etc.) that fully describe an entry type.",
"description": "Definition of an element or scope of the element, to describe each type of entry type included in a beacon. The `id` attribute is the key that should be used in other parts of the data model to allow Beacon clients to identify the different parts (e.g. endpoints, filtering terms, request parameters, etc.) that are relvant for an entry type.",
"properties": {
"$schema": {
"$ref": "../common/beaconCommonComponents.json#/definitions/$schema"
},
"aCollectionOf": {
"description": "If the entry type is a collection of other entry types, (e.g. a Dataset is a collection of Records), then this attribute must list the entry types that could be included. One collection type could be defined as included more than one entry type (e.g. a Dataset could include Individuals or Genomic Variants), in such cases the entries are alternative, meaning that a given instance of this entry type could be of only one of the types (e.g. a given Dataset contains Individuals, while another Dataset could contain Genomic Variants, but not both at once).",
"description": "If the entry type is a collection of other entities, (e.g. a Dataset is a collection of Records), then this attribute must list the entities that can be included. One _collection_ can include more than one entry type (e.g. a Dataset in teh Beacon cdefault model could include Individuals, Biosamples, GenomicVariations, Analyses amnd Runs). In such cases in each individual response (e.g. `resultSetsResponse` of collections of type \"dataset\") will contain entries of a single entry type (e.g. biosamples) even if a dataset may contain records of multiple types.",
"includedConcepts": {
"$ref": "../common/basicElement.json",
"type": "array"
Expand All @@ -30,13 +29,17 @@
"type": "string"
},
"filteringTerms": {
"$comment": "TO DO: Double-check the proper way of referencing a path or relative path. 'format: uri' is throwing validation errors for relative file paths",
"description": "Reference to the file with the list of filtering terms that could be used to filter this concept in this instance of Beacon. The referenced file could be used to populate the `filteringTerms`endpoint. Having it independently should allow for updating the list of accepted filtering terms when it is necessary.",
"$comment": "TO DO: Evaluate switch this to `url` or a more specific way for allowing URLs and local file paths (is this necessary?).",
"description": "Reference to the list of filtering terms that could be used to filter records of this entry type in this beacon.",
"type": "string"
},
"id": {
"$comments": "++++++ THIS IS THE START OF THE ontologized element ++++++",
"description": "A (unique) identifier of the element.",
"description": "A unique identifier of the element.",
"examples": [
"biosample",
"individual",
"dataset"
],
"type": "string"
},
"name": {
Expand All @@ -47,8 +50,17 @@
"$ref": "../common/beaconCommonComponents.json#/definitions/NonFilteredQueriesAllowed"
},
"ontologyTermForThisType": {
"$comments": "++++++ THIS IS THE END OF THE ontologized element ++++++",
"$ref": "../common/ontologyTerm.json"
"$ref": "../common/ontologyTerm.json",
"examples": [
{
"id": "EFO:0000542",
"label": "individual"
},
{
"id": "OBI:0000747",
"label": "material sample"
}
]
},
"partOfSpecification": {
"description": "This is label to group together entry types that are part of the same specification.",
Expand All @@ -59,7 +71,6 @@
"required": [
"id",
"name",
"ontologyTermForThisType",
"partOfSpecification",
"defaultSchema"
],
Expand Down
59 changes: 31 additions & 28 deletions framework/src/configuration/entryTypeDefinition.yaml
Original file line number Diff line number Diff line change
@@ -1,23 +1,22 @@
$schema: https://json-schema.org/draft/2020-12/schema
title: ''
description: "Definition of an element or entry type including the Beacon v2 required\
\ and suggested attributes. This schema purpose is to describe each type of entities\
\ included in a Beacon, hence Beacon clients could have some metadata about such\
\ entities.\n\nThe `id` attribute is the key that should be used in other parts\
\ of the Beacon Model to allow Beacon clients to identify the different parts (e.g.\
\ endpoints, filteringTerms, request parameters, etc.) that fully describe an entry\
\ type."
description: >-
Definition of an element or scope of the element, to describe each type of entry type included
in a beacon.
The `id` attribute is the key that should be used in other parts of the data model
to allow Beacon clients to identify the different parts (e.g. endpoints, filtering
terms, request parameters, etc.) that are relvant for an entry type.
type: object
$comment: 'TO DO: The tagged parts should reference to `common/ontologizedElement.json`.
But that configuration fails to validate. Further investigation is required, but
should not affect the resulting schema.'
properties:
$schema:
$ref: ../common/beaconCommonComponents.yaml#/definitions/$schema
id:
$comments: ++++++ THIS IS THE START OF THE ontologized element ++++++
type: string
description: A (unique) identifier of the element.
description: A unique identifier of the element.
examples:
- biosample
- individual
- dataset
name:
type: string
description: A distinctive name for the element.
Expand All @@ -26,7 +25,11 @@ properties:
description: A textual description for the element.
ontologyTermForThisType:
$ref: ../common/ontologyTerm.yaml
$comments: ++++++ THIS IS THE END OF THE ontologized element ++++++
examples:
- id: EFO:0000542
label: individual
- id: OBI:0000747
label: material sample
partOfSpecification:
description: This is label to group together entry types that are part of the
same specification.
Expand All @@ -42,31 +45,31 @@ properties:
items:
$ref: ../common/referenceToAnSchema.yaml
aCollectionOf:
description: If the entry type is a collection of other entry types, (e.g. a Dataset
is a collection of Records), then this attribute must list the entry types that
could be included. One collection type could be defined as included more than
one entry type (e.g. a Dataset could include Individuals or Genomic Variants),
in such cases the entries are alternative, meaning that a given instance of
this entry type could be of only one of the types (e.g. a given Dataset contains
Individuals, while another Dataset could contain Genomic Variants, but not both
at once).
description: >-
If the entry type is a collection of other entities, (e.g. a Dataset
is a collection of Records), then this attribute must list the entities that
can be included. One _collection_ can include more than one entry type
(e.g. a Dataset in teh Beacon cdefault model could include Individuals, Biosamples,
GenomicVariations, Analyses amnd Runs). In such cases in each individual
response (e.g. `resultSetsResponse` of collections of type "dataset") will
contain entries of a single entry type (e.g. biosamples) even if a dataset
may contain records of multiple types.
includedConcepts:
type: array
$ref: ../common/basicElement.yaml
filteringTerms:
description: Reference to the file with the list of filtering terms that could
be used to filter this concept in this instance of Beacon. The referenced file
could be used to populate the `filteringTerms`endpoint. Having it independently
should allow for updating the list of accepted filtering terms when it is necessary.
description: >-
Reference to the list of filtering terms that could be used to filter records
of this entry type in this beacon.
type: string
$comment: "TO DO: Double-check the proper way of referencing a path or relative\
\ path. 'format: uri' is throwing validation errors for relative file paths"
$comment: >-
TO DO: Evaluate switch this to `url` or a more specific way for allowing
URLs and local file paths (is this necessary?).
nonFilteredQueriesAllowed:
$ref: ../common/beaconCommonComponents.yaml#/definitions/NonFilteredQueriesAllowed
required:
- id
- name
- ontologyTermForThisType
- partOfSpecification
- defaultSchema
additionalProperties: true

0 comments on commit 7e98b1e

Please sign in to comment.