openapi: 3.1.0 info: version: 1.0.0 title: SKG-IF OpenAPI - compatible with SKG-IF Data Model 1.1.0 termsOfService: 'https://skg-if.github.io/interoperability-framework/' contact: url: 'https://github.com/skg-if' license: name: CC-BY url: 'http://creativecommons.org/licenses/by/4.0/' x-logo: url: 'https://www.rd-alliance.org/wp-content/uploads/2024/04/RDA_Logotype_CMYK.png' description: | OpenAPI end points specifications for [SKG-IF](https://skg-if.github.io/interoperability-framework/) Last version of the SKG-IF OpenAPI is available at : https://skg-if.github.io/api/ # Note for implementers : - Please refer to the [SKG-IF OpenAPI Implementer documentation](https://docs.google.com/document/d/1t7b7h28UTtM56Sda4NGJIp0hnQfGbcVVGn12fny9wfI/edit?usp=sharing) - [RDA SKG-IF WG](https://skg-if.github.io/) does not provide any official implementation of the current specification. - Recommended OpenAPI viewer : - StopLight/Elements Viewer [Current/last SKG-IF OpenAPI version](https://elements-demo.stoplight.io/?spec=https://w3id.org/skg-if/api/skg-if-openapi.yaml). - Swagger : [Current/last SKG-IF OpenAPI version](https://editor.swagger.io/?url=https://w3id.org/skg-if/api/skg-if-openapi.yaml) externalDocs: description: SKG-IF url: 'https://skg-if.github.io/interoperability-framework/' tags: # upper case name - name: Product description: product operations - name: Person description: person operations. - name: Organisation description: organisation operations. - name: Venue description: venue operations. - name: Grant description: grant operations. - name: Data Source description: grant operations. - name: Topic description: topic operations. - name: Echo description: test operations. - name: Pagination description: Pagination description (can use markdown syntax) x-traitTag: true servers: - url: '{protocol}://{server}:{port}/{skg_if_api_path}' variables: protocol: enum: - "https" - "http" default: "https" description: service provider protocol. server: default: example.com description: service provider server. port: default: "8443" description: service provider port. skg_if_api_path: default: skg-if/api description: service provider skg-if api path paths: '/products/{local_identifier}': get: tags: - Product summary: Get product by id description: | Get single `product`. See definition in SKG-IF [Research product](https://skg-if.github.io/interoperability-framework/docs/research-product.html) ( entity_type:product ). operationId: getProductById parameters: - $ref : '#/components/parameters/localIdPathParam' responses: '200': description: | Success. content: # not 'application/json-ld' to be compatible with StopLight PRISM tool application/json: schema: required: ['@context','@graph'] properties: "@context": type: array description: JSON-LD context # not displayed in Stoplight elements minItems: 3 # http://../skg-if.json, http://../skg-if-api.json and @base uniqueItems: true items: anyOf: - $ref: '#/components/schemas/JsonLdCtxDataModel' - $ref: '#/components/schemas/JsonLdCtxSearch' - $ref: '#/components/schemas/JsonLdCtxBaseOrMore' examples: - ["https://w3id.org/skg-if/context/1.1.0/skg-if.json", "https://w3id.org/skg-if/context/1.0.0/skg-if-api.json", {"@base" : "https://w3id.org/skg-if/sandbox/acme/"}] meta: type: object $ref: '#/components/schemas/MetaSingleEntity' "@graph": type: array minItems: 1 maxItems: 1 items: $ref: "#/components/schemas/Product" examples: JournalArticleEx01: summary: "Journal article - FAIR Guiding Principles" value : "@context": [ "https://w3id.org/skg-if/context/1.1.0/skg-if.json", "https://w3id.org/skg-if/context/1.0.0/skg-if-api.json", {"@base" : "https://w3id.org/skg-if/sandbox/acme/"} ] "meta" : local_identifier: https://example.com/skg-if/api/products/product-1-fgp entity_type: single_entity api_items: - local_identifier: person-5-mw urls: - entity_type: "link" rel: "self" href: "https://example.com/skg-if/api/persons/person-5-mw" - local_identifier: affiliation-organisation-1 urls: - entity_type: "link" rel: "self" href: "https://example.com/skg-if/api/organisations/affiliation-organisation-1" - local_identifier: datasource-1-aa urls: - entity_type: "link" rel: "self" href: "https://example.com/skg-if/api/datasources/datasource-1-aa" - local_identifier: venue-5-sd urls: - entity_type: "link" rel: "self" href: "https://example.com/skg-if/api/venues/venue-5-sd" "@graph" : - local_identifier: "product-1-fgp" entity_type: "product" product_type: literature titles : "en": ["The FAIR Guiding Principles for scientific data management and stewardship"] abstracts : "en": ["There is an urgent need to improve the infrastructure supporting the reuse of scholarly data. A diverse set of stakeholders—representing academia, industry, funding agencies, and scholarly publishers—have come together to design and jointly endorse a concise and measureable set of principles that we refer to as the FAIR Data Principles"] identifiers: - value: "10.1038/sdata.2016.18" scheme: "doi" - value: "26978244" scheme: "pmid" contributions: - contribution_types: - "writing – original draft" - "conceptualization" role: "author" rank: 1 by: name: "Mark Wilkinson" given_name: "Mark" family_name: "Wilkinson" identifiers: - value: "0000-0001-6960-357X" scheme: "orcid" local_identifier: person-5-mw entity_type: "person" declared_affiliations: - name: "Center for Plant Biotechnology and Genomics, Universidad Politécnica de Madrid, Madrid, 28223, Spain" local_identifier: affiliation-organisation-1 entity_type: "organisation" country: "ES" manifestations: - type: labels: en: localtypey defined_in: http://www.example.com/types/onto class: http://www.example.com/types/onto/localtypemethodology biblio: hosting_data_source: local_identifier: datasource-1-aa entity_type: datasource name: "An Archive" in: name: "Scientific Data" acronym: "Sci Data" identifiers: - "value": "2052-4463" "scheme": "issn" local_identifier: venue-5-sd entity_type: "venue" dates: # http://api.crossref.org/works/10.1038/sdata.2016.18 publication: - "2016-03-15" collected: - "2013" - "2014" deposit: - "2023-01-04" related_products: cites: - local_identifier: product-10 entity_type: "product" DatasetEx02: summary: "Dataset - OpenAIRE Graph dataset new collected projects" value : "@context": [ "https://w3id.org/skg-if/context/1.1.0/skg-if.json", "https://w3id.org/skg-if/context/1.0.0/skg-if-api.json", {"@base" : "https://w3id.org/skg-if/sandbox/acme/"} ] "meta" : local_identifier: https://example.com/skg-if/api/products/product-2-ogd entity_type: single_entity "@graph" : - local_identifier: product-2-ogd entity_type: product product_type: research data titles : "en": ["OpenAIRE Graph dataset - new collected projects"] abstracts : "en": ["The dataset includes metadata about projects grants collected by OpenAIRE since October 2024."] identifiers: - value: "10.5281/zenodo.14622592" scheme: "doi" - value: "W4393781519" scheme: "openalex" '404': description: | Error if entity does not exists '/products': get: tags: - Product summary: Get list of product operationId: getProducts description: | Get a list of `product`. See definition in SKG-IF [Research product](https://skg-if.github.io/interoperability-framework/docs/research-product.html) ( entity_type:product ). __Attribute filters__ \ You can filter using these attributes of the `product` object. Exact match. | Filter key | Attribute filter example | | -------- | -------- | | product_type | `product_type:literature` | | identifiers.id | `identifiers.id:10.1038/sdata.2016.18`, see also : [search filter format for identifiers](https://skg-if.github.io/api/#search-filter-formats)| | identifiers.scheme | `identifiers.scheme:doi` | | contributions.by. local_identifier | `contributions.by. local_identifier:https://example.com/skg-if/api/products/prod_c66c6-38be-4d5f-85db-d44c9f869881` | | contributions.by. identifiers.id | `contributions.by. identifiers.id:0000-0002-1825-0097` | | contributions.by. identifiers.scheme | `contributions.by. identifiers.scheme:orcid` | | contributions.by. family_name | `contributions.by. family_name:smith` | | contributions.by. given_name | `contributions.by. given_name:john` | | contributions.by. name | `contributions.by. name:john smith` | | contributions.declared_affiliations. local_identifier | `contributions.declared_affiliations. local_identifier:https://example.com/skg-if/api/organisations/org_c66c6-38be-4d5f-85db-d44c9f869881` | | contributions.declared_affiliations. identifiers.id | `contributions.declared_affiliations. identifiers.id:05gq02987` | | contributions.declared_affiliations. identifiers.scheme | `contributions.declared_affiliations. identifiers.scheme:ror` | | contributions.declared_affiliations. name | `contributions.declared_affiliations. name:brown university` | | contributions.declared_affiliations. short_name | `contributions.declared_affiliations. short_name:BU` | | funding. local_identifier | `funding. local_identifier:grant_1` | | funding. grant_number | `funding. grant_number:101095129` | | funding. identifiers.id | `funding. identifiers.id:10.3030/101095129` | | funding. identifiers.scheme | `funding. identifiers.scheme:doi` | __Convenience filters__ \ These filters (`cf.*`) aren't attributes of the `product` object, but they're handy for solving some common use cases. | Filter key | Filter value | List returned | Attribute filter example | | -------- | -------- | ------- | ------- | | cf.search.title | a string | `product` with title containing the filter value | `cf.search.title:ocean` | | cf.search.title_abstract | a string | `product` with title or abstract containing the filter value | `cf.search.title_abstract:ocean` | | cf.contributions_orcid | a string | `product` with contributor with orcid value | `cf.contributions_orcid:0000-0002-1825-0097` | | cf.contributions_aff_ror | a string | `product` with contributor with declared_affiliations ror value | `cf.contributions_aff_ror:05gq02987` | | cf.contributions_aff_country | a string | `product` with contributor with declared_affiliations country value | `cf.contributions_aff_country:us` | | cf.cites | a local_identifier | `product` citing the `product` having local_identifier filter value | `cf.cites:prod_1` | | cf.cited_by | a local_identifier | `product` cited by the `product` having local_identifier filter value | `cf.cited_by:prod_1` | | cf.cites_doi | a doi | `product` citing the `product` having doi filter value | `cf.cites_doi:10.1038/sdata.2016.18` | | cf.cited_by_doi | a doi | `product` cited by the `product` having doi filter value | `cf.cited_by_doi:10.1038/sdata.2016.18` | __Query parameter syntax examples__ \ * `/products?filter=product_type:literature,identifiers.id:10.1038/sdata.2016.18` * `/products?filter=cf.search.title:ocean` * `/products?filter=cf.contributions_orcid:0000-0002-1825-0097` * `/products?filter=cf.search.title:ocean&page=1&page_size=5` > #### Filter error > Each filter implementation is optional. > If the endpoint does not implement one of the requested filters it must return an HTTP 422 response. parameters: - name: filter in: query description: | Search filter. Format : Coma separated filter_name:filter_value elements ( filter_name_1:filter_value_1,filter_name_2:filter_value_2,filter_name_3:filter_value_3... ). Server side operator used is _AND_. schema: type: string pattern: '^(,?.+:.+)*$' examples : # note example with parameter $ref. OK on Redoc, KO on stoplight product_type_lit_ex : value: product_type:literature summary : Get all product with type 'literature' id_orcid_ex: value: contributions.person.identifiers.id:0000-0002-1825-0097 summary : Get all product with author with identifier id '0000-0002-1825-0097' id_orcid_scheme_ex: value: contributions.person.identifiers.id:0000-0002-1825-0097,contributions.person.identifiers.scheme:orcid summary : Get all product with author with identifier scheme 'orcid' and id '0000-0002-1825-0097' title_ex : value: cf.search.title:ocean summary : search product which title contains 'ocean' - $ref : '#/components/parameters/pageQueryParam' - $ref : '#/components/parameters/pageSizeQueryParam' responses: '200': description: | Success. content: application/json: schema: properties: "@context": type: array description: JSON-LD context # not displayed in Stoplight elements minItems: 3 # http://../skg-if.json, http://../skg-if-api.json and @base uniqueItems: true items: anyOf: - $ref: '#/components/schemas/JsonLdCtxDataModel' - $ref: '#/components/schemas/JsonLdCtxSearch' - $ref: '#/components/schemas/JsonLdCtxBaseOrMore' examples: - ["https://w3id.org/skg-if/context/1.1.0/skg-if.json", "https://w3id.org/skg-if/context/1.0.0/skg-if-api.json", {"@base" : "https://w3id.org/skg-if/sandbox/acme/"}] meta: type: object $ref: '#/components/schemas/MetaSearch' "@graph": type: array items: oneOf: - $ref: '#/components/schemas/Product' - $ref: '#/components/schemas/LocalIdentifierRef' required: [ "@context", "meta", "@graph" ] examples: JournalArticleListEx01: summary: A list of journal articles value : "@context": - "https://w3id.org/skg-if/context/1.1.0/skg-if.json" - "https://w3id.org/skg-if/context/1.0.0/skg-if-api.json" - "@base" : "https://w3id.org/skg-if/sandbox/acme/" meta: local_identifier: https://example.com/skg-if/api/products?filter=product_type:literature&page=1 entity_type: search_result_page next_page: local_identifier: https://example.com/skg-if/api/products?filter=product_type:literature&page=2 entity_type: search_result_page part_of: local_identifier: https://example.com/skg-if/api/products?filter=product_type:literature entity_type: search_result total_items: 54231 api_items: - local_identifier: product-500 urls: - entity_type: "link" rel: "self" href: "https://example.com/skg-if/api/products/product-500" - local_identifier: product-501 urls: - entity_type: "link" rel: "self" href: "https://example.com/skg-if/api/products/product-501" "@graph": - local_identifier: product-500 entity_type: product product_type: literature - local_identifier: product-501 entity_type: product product_type: research data DatasetListEx02: summary: A list of datasets value : "@context": - "https://w3id.org/skg-if/context/1.1.0/skg-if.json" - "https://w3id.org/skg-if/context/1.0.0/skg-if-api.json" - "@base" : "https://w3id.org/skg-if/sandbox/acme/" meta: local_identifier: http://example.com/skg-if/api/products?filter=product_type:research%20data&page=1 entity_type: search_result_page next_page: local_identifier: http://example.com/skg-if/api/products?filter=product_type:research%20data&page=2 entity_type: search_result_page part_of: local_identifier: http://example.com/skg-if/api/products?filter=product_type:research%20data entity_type: search_result total_items: 13202 api_items: - local_identifier: product-500 urls: - entity_type: "link" rel: "self" href: "https://example.com/skg-if/api/products/product-1000-ds" - local_identifier: product-501 urls: - entity_type: "link" rel: "self" href: "https://example.com/skg-if/api/products/product-1001-ds" "@graph": - local_identifier: product-1000-ds entity_type: product product_type: research data - local_identifier: product-1001-ds entity_type: product product_type: research data '422': description: Not implemented or invalid filter error. Conform to format [RFC7807](https://datatracker.ietf.org/doc/html/rfc7807) content: application/json: schema: $ref: '#/components/schemas/Error' examples: ErrorInvalidFilter01: summary: Invalid filter. value : type: 'https://skg-if.github.io/api/errors#INVALID_FILTER' title: 'INVALID_FILTER' status: '422' detail: 'The filter b is not supported by this implementation, valid filters are x, y, z' occurence: 'http://my-api/products?filter=b:foo,x:bar' '/persons/{local_identifier}': get: tags: - Person summary: Get person by id description: | Get `person` by id. See definition in SKG-IF [Agent](https://skg-if.github.io/interoperability-framework/docs/agent.html) ( entity_type:person ) .\ operationId: getPersonById parameters: - $ref : '#/components/parameters/localIdPathParam' responses: '200': description: Success content: application/json: schema: required: ['@context','@graph'] properties: "@context": type: array description: JSON-LD context # not displayed in Stoplight elements minItems: 3 # http://../skg-if.json, http://../skg-if-api.json and @base uniqueItems: true items: anyOf: - $ref: '#/components/schemas/JsonLdCtxDataModel' - $ref: '#/components/schemas/JsonLdCtxSearch' - $ref: '#/components/schemas/JsonLdCtxBaseOrMore' examples: - ["https://w3id.org/skg-if/context/1.1.0/skg-if.json", "https://w3id.org/skg-if/context/1.0.0/skg-if-api.json", {"@base" : "https://w3id.org/skg-if/sandbox/acme/"}] meta: type: object $ref: '#/components/schemas/MetaSingleEntity' "@graph": type: array minItems: 1 maxItems: 1 items: $ref: "#/components/schemas/Person" examples: PersonEx01: summary: Josiah Carberry person value : "@context": [ "https://w3id.org/skg-if/context/1.1.0/skg-if.json", "https://w3id.org/skg-if/context/1.0.0/skg-if-api.json", {"@base" : "http://example.com/"} ] "@graph" : - local_identifier: person-1-jc entity_type: "person" identifiers: - scheme: orcid value: 0000-0002-1825-0097 given_name: "Josiah" family_name: "Carberry" name: "Josiah Carberry" PersonEx02: summary: John Doe person on-the-fly id value : "@context": [ "https://w3id.org/skg-if/context/1.1.0/skg-if.json", "https://w3id.org/skg-if/context/1.0.0/skg-if-api.json", {"@base" : "http://example.com/"} ] "@graph" : - local_identifier: person-2-jd entity_type: "person" name: "John Doe" '404': description: | Error if entity does not exists '/persons': get: tags: - Person summary: Get list of person operationId: getPersons description: | Get a list of `person`. See definition in SKG-IF [Agent](https://skg-if.github.io/interoperability-framework/docs/agent.html) ( entity_type:person ) . __Attribute filters__ \ You can filter using these attributes of the `person` object | Filter key| Attribute filter example | | -------- | -------- | | identifiers.id | `identifiers.id:0000-0002-1825-0097` | | identifiers.scheme | `identifiers.scheme:orcid` | | given_name | `given_name:Josiah` | | family_name | `family_name:Carberry` | | name | `name:Josiah Carberro` | | affiliations.affiliation.local_identifier | `affiliations.affiliation.local_identifier:http://example.com/skg-if/api/organisations/org-c66c6-38be-4d5f-85db-d44c9f869333` | | affiliations.affiliation.name | `affiliations.affiliation.name:Brown University` | | affiliations.affiliation.short_name | `affiliations.affiliation.short_name:BU` | | affiliations.role | `affiliations.role:affiliate` | __Convenience filters__ \ These filters (`cf.*`) aren't attributes of the `person` object, but they're handy for solving some common use cases. | Filter key | Filter value | List returned | Attribute filter example | | -------- | -------- | ------- | ------- | | cf.search.family_name | a string | `person` with family_name containing the filter value | `cf.search.family_name:Carberry` | | cf.search.given_name | a string | `person` with given_name containing the filter value | `cf.search.given_name:Jos` | | cf.search.name | a string | `person` with name containing the filter value | `cf.search.name:Carberry` | __Query parameter syntax examples__ \ * `/persons?filter=identifiers.scheme:orcid,identifiers.id:0000-0002-1825-0097` * `/persons?filter=cf.search.family_name:Carberry,cf.search.given_name:Jos` * `/persons?filter=cf.search.family_name:Carberry` * `/persons?filter=cf.search.family_name:Carberry&page=1&page_size=5` parameters: - name: filter in: query description: | Search filter. Format : Coma separated filter_name:filter_value elements ( filter_name_1:filter_value_1,filter_name_2:filter_value_2,filter_name_3:filter_value_3... ). Server side operator used is _AND_. schema: type: string pattern: '^(,?.+:.+)*$' examples : orcid_ex: value: identifiers.scheme:orcid,identifiers.id:0000-0002-1825-0097 summary: Get all person with identifier scheme 'orcid' and id '0000-0002-1825-0097' - $ref : '#/components/parameters/pageQueryParam' - $ref : '#/components/parameters/pageSizeQueryParam' responses: '200': description: Success content: application/json: schema: properties: "@context": type: array description: JSON-LD context # not displayed in Stoplight elements minItems: 3 # http://../skg-if.json, http://../skg-if-api.json and @base uniqueItems: true items: anyOf: - $ref: '#/components/schemas/JsonLdCtxDataModel' - $ref: '#/components/schemas/JsonLdCtxSearch' - $ref: '#/components/schemas/JsonLdCtxBaseOrMore' examples: - ["https://w3id.org/skg-if/context/1.1.0/skg-if.json", "https://w3id.org/skg-if/context/1.0.0/skg-if-api.json", {"@base" : "https://w3id.org/skg-if/sandbox/acme/"}] meta: type: object $ref: '#/components/schemas/MetaSearch' "@graph": type: array items: oneOf: - $ref: '#/components/schemas/Person' - $ref: '#/components/schemas/LocalIdentifierRef' required: [ "@context", "meta", "@graph" ] examples: PersonEx01: summary: a list of persons value : "@context": - "https://w3id.org/skg-if/context/1.1.0/skg-if.json" - "https://w3id.org/skg-if/context/1.0.0/skg-if-api.json" - "@base" : "https://w3id.org/skg-if/sandbox/acme/" meta: local_identifier: https://example.com/skg-if/api/persons?filter=family_name:Carberry&page=1 entity_type: search_result_page next_page: local_identifier: https://example.com/skg-if/api/persons?filter=family_name:Carberry&page=2 entity_type: search_result_page part_of: local_identifier: https://example.com/skg-if/api/persons?filter=family_name:Carberry entity_type: search_result total_items: 4 api_items: - local_identifier: person-1-jc urls: - entity_type: "link" rel: "self" href: "https://example.com/skg-if/api/persons/person-1-jc" - local_identifier: person-2-gc urls: - entity_type: "link" rel: "self" href: "https://example.com/skg-if/api/persons/person-2-gc" "@graph": - local_identifier: person-1-jc entity_type: "person" identifiers: - scheme: orcid value: 0000-0002-1825-0097 given_name: "Josiah" family_name: "Carberry" name: "Josiah Carberry" - local_identifier: person-2-gc entity_type: "person" given_name: "Gerard" family_name: "Carberry" name: "Gerard Carberry" #PersonEx02: # commented KO on StopLight UI, OK on Redoc UI, Not used in PRISM # summary: "a list of persons - external URL" # externalValue: "https://raw.githubusercontent.com/skg-if/examples/refs/heads/main/OpenCitations/oc_1.json" links: address: operationId: getPersonById parameters: local_identifier: $response.body#/@graph/local_identifier '/organisations/{local_identifier}': get: tags: - Organisation summary: Get organisation by id description: | Get `organisation` by id. See definition in SKG-IF [Agent](https://skg-if.github.io/interoperability-framework/docs/agent.html) ( entity_type:organisation) .\ operationId: getOrganisationById parameters: - $ref : '#/components/parameters/localIdPathParam' responses: '200': description: Success content: # not 'application/json-ld' to be compatible with StopLight PRISM tool application/json: schema: required: ['@context','@graph'] properties: "@context": type: array description: JSON-LD context # not displayed in Stoplight elements minItems: 3 # http://../skg-if.json, http://../skg-if-api.json and @base uniqueItems: true items: anyOf: - $ref: '#/components/schemas/JsonLdCtxDataModel' - $ref: '#/components/schemas/JsonLdCtxSearch' - $ref: '#/components/schemas/JsonLdCtxBaseOrMore' examples: - ["https://w3id.org/skg-if/context/1.1.0/skg-if.json", "https://w3id.org/skg-if/context/1.0.0/skg-if-api.json", {"@base" : "https://w3id.org/skg-if/sandbox/acme/"}] meta: type: object $ref: '#/components/schemas/MetaSingleEntity' "@graph": type: array minItems: 1 maxItems: 1 items: $ref: "#/components/schemas/Organisation" examples: OrgBrownUniversity: summary: "Brown University" value : "@context": - "https://w3id.org/skg-if/context/1.1.0/skg-if.json" - "https://w3id.org/skg-if/context/1.0.0/skg-if-api.json" - "@base" : "https://w3id.org/skg-if/sandbox/acme/" "@graph": - local_identifier: organisation-2-bu entity_type: 'organisation' identifiers: - scheme: ror value: https://ror.org/05gq02987 name: Brown University. short_name: BU country: US types: - education OrgJohnCarterBrownLibrary: summary: "John Carter Brown Library - Brown University" value : "@context": - "https://w3id.org/skg-if/context/1.1.0/skg-if.json" - "https://w3id.org/skg-if/context/1.0.0/skg-if-api.json" - "@base" : "https://w3id.org/skg-if/sandbox/acme/" "@graph": - local_identifier: organisation-3-jcbl entity_type: 'organisation' identifiers: - scheme: ror value: https://ror.org/05gq02987 - scheme: ror value: https://ror.org/0274ane14 name: John Carter Brown Library, Brown University, Providence RI, US short_name: BU country: US types: - archive OrgLabScienceNoRor: summary: "Lab of science" value : "@context": - "https://w3id.org/skg-if/context/1.1.0/skg-if.json" - "https://w3id.org/skg-if/context/1.0.0/skg-if-api.json" - "@base" : "https://w3id.org/skg-if/sandbox/acme/" "@graph": - local_identifier: organisation-5-lsa entity_type: 'organisation' name: Lab of science, unknown University, Antarctica OrgEuropeanCommission: summary: "European Commission Funder" value : "@context": - "https://w3id.org/skg-if/context/1.1.0/skg-if.json" - "https://w3id.org/skg-if/context/1.0.0/skg-if-api.json" - "@base" : "https://w3id.org/skg-if/sandbox/acme/" "@graph": - local_identifier: organisation-6-eu entity_type: 'organisation' identifiers: - scheme: ror value: https://ror.org/00k4n6c32 name: "European Commission" short_name: EU types: - funder '404': description: | Error if entity does not exists '/organisations': get: tags: - Organisation summary: Get list of organisation. operationId: getOrganisations description: | Get a list of `organisation`. See definition in SKG-IF [Agent](https://skg-if.github.io/interoperability-framework/docs/agent.html) ( entity_type:organisation) . __Attribute filters__ \ You can filter using these attributes of the `organisation` object | Filter key| Attribute filter example | | -------- | -------- | | identifiers.id | `identifiers.id:05gq02987` | | identifiers.scheme | `identifiers.scheme:ror` | | name | `name:Brown University` | | short_name | `short_name:BU` | | website | `website:https://www.brown.edu` | | country | `country:US` | __Convenience filters__ \ These filters (`cf.*`) aren't attributes of the `organization` object, but they're handy for solving some common use cases. | Filter key | Filter value | List returned | Attribute filter example | | -------- | -------- | ------- | ------- | | cf.search.name | a string | `organisation` with name containing the filter value | `cf.search.name:Brown` | __Query parameter syntax examples__ \ * `/organisations?filter=identifiers.scheme:ror,identifiers.id:05gq02987` * `/organisations?filter=cf.search.name:Brown` * `/organisations?filter=cf.search.name:Brown&page=1&page_size=5` parameters: - name: filter in: query description: filter. Coma separated filter_name:filter_value elements ( filter_name_1:filter_value_1,filter_name_2:filter_value_2,filter_name_3:filter_value_3... ). Server side operator used is _AND_. examples : rorid_ex: value: identifiers.scheme:ror,identifiers.id:05gq02987 summary : Get all organisation with identifier scheme 'ror' and id '05gq02987' name_ex: value: cf.search.name:Brown summary : Get all organisation with name containing 'Brown' schema: type: string pattern: '^(,?.+:.+)*$' - $ref : '#/components/parameters/pageQueryParam' - $ref : '#/components/parameters/pageSizeQueryParam' responses: '200': description: Success content: application/json: schema: properties: "@context": type: array description: JSON-LD context # not displayed in Stoplight elements minItems: 3 # http://../skg-if.json, http://../skg-if-api.json and @base uniqueItems: true items: anyOf: - $ref: '#/components/schemas/JsonLdCtxDataModel' - $ref: '#/components/schemas/JsonLdCtxSearch' - $ref: '#/components/schemas/JsonLdCtxBaseOrMore' examples: - ["https://w3id.org/skg-if/context/1.1.0/skg-if.json", "https://w3id.org/skg-if/context/1.0.0/skg-if-api.json", {"@base" : "https://w3id.org/skg-if/sandbox/acme/"}] meta: type: object $ref: '#/components/schemas/MetaSearch' "@graph": type: array items: oneOf: - $ref: '#/components/schemas/Organisation' - $ref: '#/components/schemas/LocalIdentifierRef' required: [ "@context", "meta", "@graph" ] '/grants/{local_identifier}': get: tags: - Grant summary: Get grant by id description: | Get single `grant`. See definition in SKG-IF [Grant](https://skg-if.github.io/interoperability-framework/docs/grant.html) ( entity_type:grant ). operationId: getGrantById parameters: - $ref : '#/components/parameters/localIdPathParam' responses: '200': description: Success content: # not 'application/json-ld' to be compatible with StopLight PRISM tool application/json: schema: required: ['@context','@graph'] properties: "@context": type: array description: JSON-LD context # not displayed in Stoplight elements minItems: 3 # http://../skg-if.json, http://../skg-if-api.json and @base uniqueItems: true items: anyOf: - $ref: '#/components/schemas/JsonLdCtxDataModel' - $ref: '#/components/schemas/JsonLdCtxSearch' - $ref: '#/components/schemas/JsonLdCtxBaseOrMore' examples: - ["https://w3id.org/skg-if/context/1.1.0/skg-if.json", "https://w3id.org/skg-if/context/1.0.0/skg-if-api.json", {"@base" : "https://w3id.org/skg-if/sandbox/acme/"}] meta: type: object $ref: '#/components/schemas/MetaSingleEntity' "@graph": type: array minItems: 1 maxItems: 1 items: $ref: "#/components/schemas/Grant" examples: GrantEx01: summary: GraspOS grant value : "@context": [ "https://w3id.org/skg-if/context/1.1.0/skg-if.json", "https://w3id.org/skg-if/context/1.0.0/skg-if-api.json", {"@base" : "https://w3id.org/skg-if/sandbox/acme/"} ] "meta" : local_identifier: https://example.com/skg-if/api/grants/grant-1-go entity_type: "single_entity" api_items: - local_identifier: person-1-jc urls: - entity_type: "link" rel: "self" href: "https://example.com/skg-if/api/persons/person-1-jc" - local_identifier: person-2-gc urls: - entity_type: "link" rel: "self" href: "https://example.com/skg-if/api/persons/person-2-gc" - local_identifier: organisation-2-bu urls: - entity_type: "link" rel: "self" href: "https://example.com/skg-if/api/organisations/organisation-2-bu" "@graph" : - local_identifier: grant-1-go entity_type: "grant" identifiers: - scheme: "doi" value: "https://doi.org/10.3030/101095129" grant_number: "101095129" titles: "en": "GraspOS: next Generation Research Assessment to Promote Open Science" abstracts: { "en": "GraspOS aims to build and operate a data infrastructure to support the policy reforms..." } acronym: "GraspOS" funding_agency: local_identifier: organisation-2-bu entity_type: "organisation" identifiers: - scheme: "ror" value: "https://ror.org/05gq02987" name: "Brown University" short_name: "BU" country: "US" website: "https://www.brown.edu/" funding_stream: "Horizon Europe" currency: "EUR" funded_amount: 50000 duration: start: "2023-01-01T00:00:00Z" end: "2025-12-31T23:59:59Z" website: "https://graspos.eu" beneficiaries: - local_identifier: organisation-2-bu entity_type: "organisation" identifiers: - scheme: "ror" value: "https://ror.org/05gq02987" name: "Brown University" short_name: "BU" country: "US" website: "https://www.brown.edu/" contributions: - by: local_identifier: person-1-jc entity_type: "person" identifiers: - scheme: "orcid" value: "0000-0002-1825-0097" given_name: "Josiah" family_name: "Carberry" name: "Josiah Carberro" declared_affiliations: - local_identifier": "organisation-2-bu" entity_type": "organisation" identifiers: - scheme: "ror" value: "https://ror.org/05gq02987" name: "Brown University" short_name: "BU" country: "US" website: "https://www.brown.edu/" roles: - "co-applicant" '404': description: | Error if entity does not exists '/grants': get: tags: - Grant summary: Get list of grant operationId: getGrants description: | Get a list of `grant`. See definition in SKG-IF [Grant](https://skg-if.github.io/interoperability-framework/docs/grant.html) ( entity_type:grant ) __Attribute filters__ \ You can filter using these attributes of the `grant` object. Exact match. | Filter key | Attribute filter example | | -------- | -------- | | identifiers.scheme | `identifiers.scheme:doi` | | identifiers.value | `identifiers.value:10.3030/101095129` | | acronym | `acronym:CIKM` | | currency | `currency:EUR` | | website | `website:https://ostrails.eu/` | | beneficiaries.identifiers.scheme | `beneficiaries.identifiers.scheme:ror` | | beneficiaries.identifiers.value | `beneficiaries.identifiers.value:https://ror.org/05gq02987` | | beneficiaries.name | `beneficiaries.name:Brown University` | | beneficiaries.short_name | `beneficiaries.short_name:BU` | | beneficiaries.website | `beneficiaries.website:https://www.brown.edu` | | beneficiaries.country | `beneficiaries.country:US` | | contributions.by.local_identifier | `contributions.by.local_identifier:http://example.com/skg-if/api/persons/yyy` | | contributions.by.identifiers.scheme | `contributions.by.identifiers.scheme:orcid` | | contributions.by.identifiers.value | `contributions.by.identifiers.value:0000-0002-1825-0097` | | contributions.by.given_name | `contributions.by.given_name:Josiah` | | contributions.by.family_name | `contributions.by.family_name:Carberry` | | contributions.by.name | `contributions.by.name:Josiah Carberro` | | contributions.declared_affiliations.local_identifier | `contributions.declared_affiliations.local_identifier:http://example.com/skg-if/api/organisations/ooo` | | contributions.declared_affiliations.identifiers.scheme | `contributions.declared_affiliations.identifiers.scheme:ror` | | contributions.declared_affiliations.identifiers.value | `contributions.declared_affiliations.identifiers.value:https://ror.org/05gq02987` | | contributions.declared_affiliations.name | `contributions.declared_affiliations.name:Brown University` | | contributions.declared_affiliations.short_name | `contributions.declared_affiliations.short_name:BU` | | contributions.declared_affiliations.website | `contributions.declared_affiliations.website:https://www.brown.edu` | | contributions.declared_affiliations.country | `contributions.declared_affiliations.country:US` | | contributions.role | `contributions.role:project manager` | | identifiers.scheme | `identifiers.scheme:doi` | | identifiers.value | `identifiers.value:10.3030/101095129` | | grant_number | `grant_number:101095129` | | acronym | `acronym:GraspOS` | | funding_agency.identifiers.scheme | `funding_agency.identifiers.scheme:ror` | | funding_agency.identifiers.value | `funding_agency.identifiers.value:https://ror.org/05gq02987` | | funding_agency.name | `funding_agency.name:Brown University` | | funding_agency.short_name | `funding_agency.short_name:BU` | | funding_agency.website | `funding_agency.website:https://www.brown.edu` | | funding_agency.country | `funding_agency.country:US` | | funding_stream | `funding_stream:Horizon Europe` | __Convenience filters__ \ These filters (`cf.*`) aren't attributes of the `grant` object, but they're handy for solving some common use cases. | Filter key | Filter value | List returned | Attribute filter example | | -------- | -------- | ------- | ------- | | cf.search.title | a string | `grant` with the `title` property containing the specified value | `cf.search.title:GraspOS` | | cf.search.title_abstract | a string | `grant` with the `title` or `abstract` property containing the specified value | `cf.search.title_abstract:GraspOS` | | cf.funded_amount.from | a number | `grant` with a funded amount greater than or equal to the specified value. | `cf.funded_amount.from:1000000` | | cf.funded_amount.to | a number | `grant` with a funded amount less than or equal to the specified value. | `cf.funded_amount.to:2000000` | | cf.duration.start.from | a ISO 8601 datetime string | `grant` with a start date on or after the specified date.| `cf.funded_amount.from:2023-01-01` | | cf.duration.start.to | a ISO 8601 datetime string | `grant` with start date on or before the specified date. | `cf.duration.start.to:2023-01-01` | | cf.duration.end.from | a ISO 8601 datetime string | `grant` with an end date on or after the specified date. | `cf.duration.end.from:2025-12-31` | __Query parameter syntax examples__ \ * `/grants?filter=cf.search.title:GraspOS` * `/grants?filter=cf.search.title:GraspOS&page=1&page_size=5` parameters: - name: filter in: query description: | Search filter. Format :Coma separated filter_name:filter_value elements ( filter_name_1:filter_value_1,filter_name_2:filter_value_2,filter_name_3:filter_value_3... ). Server side operator used is _AND_. schema: type: string pattern: '^(,?.+:.+)*$' examples : # note example with parameter $ref. OK on Redoc, KO on stoplight grant_title_ex : value: cf.search.title:GraspOS summary: Get all grants with title containing `GraspOS` - $ref : '#/components/parameters/pageQueryParam' - $ref : '#/components/parameters/pageSizeQueryParam' responses: '200': description: Success content: application/json: schema: properties: "@context": type: array description: JSON-LD context # not displayed in Stoplight elements minItems: 3 # http://../skg-if.json, http://../skg-if-api.json and @base uniqueItems: true items: anyOf: - $ref: '#/components/schemas/JsonLdCtxDataModel' - $ref: '#/components/schemas/JsonLdCtxSearch' - $ref: '#/components/schemas/JsonLdCtxBaseOrMore' examples: - ["https://w3id.org/skg-if/context/1.1.0/skg-if.json", "https://w3id.org/skg-if/context/1.0.0/skg-if-api.json", {"@base" : "https://w3id.org/skg-if/sandbox/acme/"}] meta: type: object $ref: '#/components/schemas/MetaSearch' "@graph": type: array items: oneOf: - $ref: '#/components/schemas/Grant' - $ref: '#/components/schemas/LocalIdentifierRef' required: [ "@context", "meta", "@graph" ] '/venues/{local_identifier}': get: tags: - Venue summary: Get venue by id description: | Get single `venue`. See definition in SKG-IF [Venue](https://skg-if.github.io/interoperability-framework/docs/venue.html) ( entity_type:venue ). operationId: getVenueById parameters: - $ref : '#/components/parameters/localIdPathParam' responses: '200': description: Success content: # not 'application/json-ld' to be compatible with StopLight PRISM tool application/json: schema: required: ['@context','@graph'] properties: "@context": type: array description: JSON-LD context # not displayed in Stoplight elements minItems: 3 # http://../skg-if.json, http://../skg-if-api.json and @base uniqueItems: true items: anyOf: - $ref: '#/components/schemas/JsonLdCtxDataModel' - $ref: '#/components/schemas/JsonLdCtxSearch' - $ref: '#/components/schemas/JsonLdCtxBaseOrMore' examples: - ["https://w3id.org/skg-if/context/1.1.0/skg-if.json", "https://w3id.org/skg-if/context/1.0.0/skg-if-api.json", {"@base" : "https://w3id.org/skg-if/sandbox/acme/"}] meta: type: object $ref: '#/components/schemas/MetaSingleEntity' "@graph": type: array minItems: 1 maxItems: 1 items: $ref: "#/components/schemas/Venue" examples: VenueEx01: summary: Journal of Psychoceramics venue value : "@context": [ "https://w3id.org/skg-if/context/1.1.0/skg-if.json", "https://w3id.org/skg-if/context/1.0.0/skg-if-api.json", {"@base" : "https://w3id.org/skg-if/sandbox/acme/"} ] "meta" : local_identifier: https://example.com/skg-if/api/venues/venue-1-jp entity_type: "single_entity" "@graph" : - local_identifier: venue-1-jp entity_type: "venue" identifiers: - scheme: issn value: 0264-3561 name: Journal of Psychoceramics acronym: JPC type: journal '404': description: | Error if entity does not exists '/venues': get: tags: - Venue summary: Get list of venue operationId: getVenues description: | Get a list of `venue`. See definition in SKG-IF [Venue](https://skg-if.github.io/interoperability-framework/docs/venue.html) ( entity_type:venue ). __Attribute filters__ \ You can filter using these attributes of the `venue` object. Exact match. | Filter key | Attribute filter example | | -------- | -------- | | acronym | `acronym:JPC` | | type | `type:journal` | | identifiers.scheme | `identifiers.scheme:issn` | | identifiers.value | `identifiers.value:0264-3561` | | name | `name:Journal of Psychoceramics` | __Convenience filters__ \ These filters (`cf.*`) aren't attributes of the `venue` object, but they're handy for solving some common use cases. | Filter key | Filter value | List returned | Attribute filter example | | -------- | -------- | ------- | ------- | | cf.search.name | a string | `venue` with name containing the filter value | `cf.search.name:Psychoceramics` | parameters: - name: filter in: query description: | Search filter. Format : Coma separated filter_name:filter_value elements ( filter_name_1:filter_value_1,filter_name_2:filter_value_2,filter_name_3:filter_value_3... ). Server side operator used is _AND_. schema: type: string pattern: '^(,?.+:.+)*$' examples : # note example with parameter $ref. OK on Redoc, KO on stoplight topic_label_ex: value: cf.search.name:Psychoceramics summary: Get all venues with name containing 'Psychoceramics' - $ref : '#/components/parameters/pageQueryParam' - $ref : '#/components/parameters/pageSizeQueryParam' responses: '200': description: Success content: application/json: schema: properties: "@context": type: array description: JSON-LD context # not displayed in Stoplight elements minItems: 3 # http://../skg-if.json, http://../skg-if-api.json and @base uniqueItems: true items: anyOf: - $ref: '#/components/schemas/JsonLdCtxDataModel' - $ref: '#/components/schemas/JsonLdCtxSearch' - $ref: '#/components/schemas/JsonLdCtxBaseOrMore' examples: - ["https://w3id.org/skg-if/context/1.1.0/skg-if.json", "https://w3id.org/skg-if/context/1.0.0/skg-if-api.json", {"@base" : "https://w3id.org/skg-if/sandbox/acme/"}] meta: type: object $ref: '#/components/schemas/MetaSearch' "@graph": type: array items: oneOf: - $ref: '#/components/schemas/Venue' - $ref: '#/components/schemas/LocalIdentifierRef' required: [ "@context", "meta", "@graph" ] '/topics/{local_identifier}': get: tags: - Topic summary: Get topic by id description: | Get single `topic`. See definition in SKG-IF [Topic](https://skg-if.github.io/interoperability-framework/docs/topic.html) ( entity_type:topic ). operationId: getTopicById parameters: - $ref : '#/components/parameters/localIdPathParam' responses: '200': description: Success content: # not 'application/json-ld' to be compatible with StopLight PRISM tool application/json: schema: required: ['@context','@graph'] properties: "@context": type: array description: JSON-LD context # not displayed in Stoplight elements minItems: 3 # http://../skg-if.json, http://../skg-if-api.json and @base uniqueItems: true items: anyOf: - $ref: '#/components/schemas/JsonLdCtxDataModel' - $ref: '#/components/schemas/JsonLdCtxSearch' - $ref: '#/components/schemas/JsonLdCtxBaseOrMore' examples: - ["https://w3id.org/skg-if/context/1.1.0/skg-if.json", "https://w3id.org/skg-if/context/1.0.0/skg-if-api.json", {"@base" : "https://w3id.org/skg-if/sandbox/acme/"}] meta: type: object $ref: '#/components/schemas/MetaSingleEntity' "@graph": type: array minItems: 1 maxItems: 1 items: $ref: "#/components/schemas/Topic" examples: TopicEx01: summary: Computer Science topic value : "@context": [ "https://w3id.org/skg-if/context/1.1.0/skg-if.json", "https://w3id.org/skg-if/context/1.0.0/skg-if-api.json", {"@base" : "https://w3id.org/skg-if/sandbox/acme/"} ] "meta" : local_identifier: https://example.com/skg-if/api/topics/topc-1-cs entity_type: "single_entity" "@graph" : - local_identifier: topic-1-cs entity_type: "topic" identifiers: - scheme: wikidata value: https://www.wikidata.org/wiki/Q21198 labels: en: "Computer Science" it: "Informatica" '404': description: | Error if entity does not exists '/topics': get: tags: - Topic summary: Get list of topic operationId: getTopics description: | Get a list of `topic`. See definition in SKG-IF [Topic](https://skg-if.github.io/interoperability-framework/docs/topic.html) ( entity_type:topic ). __Attribute filters__ \ You can filter using these attributes of the `topic` object. Exact match. | Filter key | Attribute filter example | | -------- | -------- | | identifiers.scheme | `identifiers.scheme:wikidata` | | identifiers.value | `identifiers.value:https://www.wikidata.org/wiki/Q42` | __Convenience filters__ \ These filters (`cf.*`) aren't attributes of the `topic` object, but they're handy for solving some common use cases. | Filter key | Filter value | List returned | Attribute filter example | | -------- | -------- | ------- | ------- | | cf.search.labels | a string | `topic` with label containing the filter value | `cf.search.labels:Solar` | | cf.search.language | a string | `topic` with language key equals to the filter value | `cf.search.language:en` | __Query parameter syntax examples__ \ * `/topics?filter=cf.search.labels:Solar,identifiers.scheme:myvocabulary` * `/topics?filter=cf.search.labels:Solar` * `/topics?filter=cf.search.labels:Solar,cf.search.language:en` * `/topics?filter=cf.search.labels:Solar,cf.search.language:en&page=1&page_size=5` parameters: - name: filter in: query description: | Search filter. Format : Coma separated filter_name:filter_value elements ( filter_name_1:filter_value_1,filter_name_2:filter_value_2,filter_name_3:filter_value_3... ). Server side operator used is _AND_. schema: type: string pattern: '^(,?.+:.+)*$' examples : # note example with parameter $ref. OK on Redoc, KO on stoplight topic_label_ex: value: cf.search.labels:Solar summary: Get all topics with label containing 'Solar' topic_label_lang_ex: value: cf.search.labels:Solar,cf.search.language:en summary: Get all topics with label containing 'Solar' and english topic_label_vocab_ex: value: cf.search.labels:Solar,identifiers.scheme:myvocabulary summary: Get all topics with label containing 'Solar' in the scheme 'myvocabulary' - $ref : '#/components/parameters/pageQueryParam' - $ref : '#/components/parameters/pageSizeQueryParam' responses: '200': description: Success content: application/json: schema: properties: "@context": type: array description: JSON-LD context # not displayed in Stoplight elements minItems: 3 # http://../skg-if.json, http://../skg-if-api.json and @base uniqueItems: true items: anyOf: - $ref: '#/components/schemas/JsonLdCtxDataModel' - $ref: '#/components/schemas/JsonLdCtxSearch' - $ref: '#/components/schemas/JsonLdCtxBaseOrMore' examples: - ["https://w3id.org/skg-if/context/1.1.0/skg-if.json", "https://w3id.org/skg-if/context/1.0.0/skg-if-api.json", {"@base" : "https://w3id.org/skg-if/sandbox/acme/"}] meta: type: object $ref: '#/components/schemas/MetaSearch' "@graph": type: array items: oneOf: - $ref: '#/components/schemas/Topic' - $ref: '#/components/schemas/LocalIdentifierRef' required: [ "@context", "meta", "@graph" ] '/datasources/{local_identifier}': get: tags: - Data Source summary: Get datasource by id description: | Get single `datasource`. See definition in SKG-IF [Data Source](https://skg-if.github.io/interoperability-framework/docs/data-source.html) ( entity_type:datasource ). operationId: getDataSourceById parameters: - $ref : '#/components/parameters/localIdPathParam' responses: '200': description: Success content: # not 'application/json-ld' to be compatible with StopLight PRISM tool application/json: schema: required: ['@context','@graph'] properties: "@context": type: array description: JSON-LD context # not displayed in Stoplight elements minItems: 3 # http://../skg-if.json, http://../skg-if-api.json and @base uniqueItems: true items: anyOf: - $ref: '#/components/schemas/JsonLdCtxDataModel' - $ref: '#/components/schemas/JsonLdCtxSearch' - $ref: '#/components/schemas/JsonLdCtxBaseOrMore' examples: - ["https://w3id.org/skg-if/context/1.1.0/skg-if.json", "https://w3id.org/skg-if/context/1.0.0/skg-if-api.json", {"@base" : "https://w3id.org/skg-if/sandbox/acme/"}] meta: type: object $ref: '#/components/schemas/MetaSingleEntity' "@graph": type: array minItems: 1 maxItems: 1 items: $ref: "#/components/schemas/DataSource" examples: DatasourceEx01: summary: Oxford University Research Archive datasource value : "@context": [ "https://w3id.org/skg-if/context/1.1.0/skg-if.json", "https://w3id.org/skg-if/context/1.0.0/skg-if-api.json", {"@base" : "https://w3id.org/skg-if/sandbox/acme/"} ] "meta" : local_identifier: https://example.com/skg-if/api/venues/datasource-1-oura entity_type: "single_entity" "@graph" : - local_identifier: datasource-1-oura entity_type: "datasource" identifiers: - scheme: doi value: 10.25504/FAIRsharing.rkwr6y name: "Oxford University Research Archive" data_source_classification: "repository" research_product_types: - "research data" - "literature" '404': description: | Error if entity does not exists '/datasources': get: tags: - Data Source summary: Get list of datasource operationId: getDataSources description: | Get a list of `datasource`. See definition in SKG-IF [Data Source](https://skg-if.github.io/interoperability-framework/docs/data-source.html) ( entity_type:datasource ). __Attribute filters__ \ You can filter using these attributes of the `datasource` object. Exact match. | Filter key | Attribute filter example | | -------- | -------- | | data_source_classification | `data_source_classification:repository` | | research_product_type | `research_product_type:metadata` | | identifiers.scheme | `identifiers.scheme:doi` | | identifiers.value | `identifiers.value:10.3030/101095129` | | acronym | `acronym:CIKM` | __Convenience filters__ \ These filters (`cf.*`) aren't attributes of the `datasource` object, but they're handy for solving some common use cases. | Filter key | Filter value | List returned | Attribute filter example | | -------- | -------- | ------- | ------- | | cf.search.name | a string | `datasource` with name containing the filter value | `cf.search.name:Management` | parameters: - name: filter in: query description: | Search filter. Format : Coma separated filter_name:filter_value elements ( filter_name_1:filter_value_1,filter_name_2:filter_value_2,filter_name_3:filter_value_3... ). Server side operator used is _AND_. schema: type: string pattern: '^(,?.+:.+)*$' examples : # note example with parameter $ref. OK on Redoc, KO on stoplight datasource_name_ex: value: cf.search.name:Oxford summary: Get all datasources with name containing `Oxford` - $ref : '#/components/parameters/pageQueryParam' - $ref : '#/components/parameters/pageSizeQueryParam' responses: '200': description: Success content: application/json: schema: properties: "@context": type: array description: JSON-LD context # not displayed in Stoplight elements minItems: 3 # http://../skg-if.json, http://../skg-if-api.json and @base uniqueItems: true items: anyOf: - $ref: '#/components/schemas/JsonLdCtxDataModel' - $ref: '#/components/schemas/JsonLdCtxSearch' - $ref: '#/components/schemas/JsonLdCtxBaseOrMore' examples: - ["https://w3id.org/skg-if/context/1.1.0/skg-if.json", "https://w3id.org/skg-if/context/1.0.0/skg-if-api.json", {"@base" : "https://w3id.org/skg-if/sandbox/acme/"}] meta: type: object $ref: '#/components/schemas/MetaSearch' "@graph": type: array items: oneOf: - $ref: '#/components/schemas/DataSource' - $ref: '#/components/schemas/LocalIdentifierRef' required: [ "@context", "meta", "@graph" ] components: securitySchemes: main_auth: type: oauth2 flows: implicit: authorizationUrl: 'http://example.com/api/oauth/dialog' scopes: 'read:users': read users info 'write:users': modify or remove users api_key: type: apiKey in: header name: api_key basic_auth: type: http scheme: basic parameters: localIdPathParam: name: local_identifier in: path description: | Entity id. - Example entity id with as URL : `http://skg-base-domain.com/prod-c66c6-38be-4d5f-85db-d44c9`. To define your SKG base domain ( `@base` ), please refer to the [SKG-IF API doc](https://skg-if.github.io/api/) - Example entity id without its SKG base domain : `prod-c66c6-38be-4d5f-85db-d44c9` The entity endpoint MUST resolve ids as full URL and SHOULD resolve ids without SKG base domain. required: true schema: type: string # filterQueryParam: # filterQueryParam duplicated in each search endpoint ( only way to add distinct examples for each endpoint ) # name: filter # in: query # description: | # Search filter. Format : Coma separated filter_name:filter_value elements ( filter_name_1:filter_value_1,filter_name_2:filter_value_2,filter_name_3:filter_value_3... ). Server side operator used is _AND_. # schema: # type: string # pattern: '^(,?.+:.+)*$' pageQueryParam: name: page in: query description: | Search page reference (page number or search iteration token).\ Note: As a client application you should build your iterating logic using the `meta.next_page.local_identifier` and `meta.prev_page.local_identifier` URLs schema: type: string pageSizeQueryParam: name: page_size in: query description: | Search page size. limit search result size. schema: type: integer schemas: LocalIdentifierRef: type: string description: | A local identifier reference. You can pass a local identifier as a string and not a full object entity structure, but it is not recommended. ex: ``` "foo":"product-1" ``` This feature is included in the current SKG-IF OpenAPI specifications to remain compatible with SKG-IF model documentation and raw exports. This approach creates important limitations for the client applications explained below. Instead, we recommend to pass one of the object structure entities compatible with this property, and also fill its properties. One additional benefit of object structure is to limit the client API calls to resolve entities and sub-entities. ex: ``` "foo": { "local_identifier":"product-1", "entity_type:product", "title":"xxx", ... "contributions" : [ { "by": { "local_identifier":"person-1", "entity_type:person", "name":"John Doe", ... } } ] } ``` This is also very useful for client using your API for autocomplete features. A typical autocomplete use case is : search products by term and get a list of products with the contributors names in a single API call. ApiItem: type: object title: 'Link' description: | Result element required: [ "local_identifier" ] properties: local_identifier: type: string description: | Unique local identifier as URL examples: - http://w3id.org/skg-if/sandbox/acme/product-1 - http://w3id.org/skg-if/sandbox/acme/person-1 urls: type: [array, "null"] description: | List of API URLs to access to the entity metadata items: $ref: '#/components/schemas/Link' Link: type: object title: 'Link' description: | Link to resource (API, web...\ The main expected link on entities, is a `self` relation with `href` link pointing to the SKG-IF API endpoint for this entity.\ ex: `https://example.com/skg-if/api/products/product-1`. Note: as a client you should not expect to have an HTTP 200 response on a `self` API link on entities with an `otf` `local_identifier` properties: entity_type: default: "link" type: [string, "null"] x-faker: helpers.arrayElement: [["link"]] rel: default: "self" description: | Link relation. Use `self` value for SKG-IF API only. You can also use values defined in [IANA](https://www.iana.org/assignments/link-relations/link-relations.xhtml). You can use `describedBy`, combined with the `media_type` property, to link to other API and representation of the entity. type: [string, "null"] x-faker: helpers.arrayElement: [["self"]] href: type: [string, "null"] description: "a URL. For `rel:self`should be SKG-IF endpoint" x-faker: fake : ['https://example.com/skg-if/api/products/product-{{random.alphaNumeric(8)}}'] media_type: default: "link" type: [string, "null"] description: "Media type. Leave empty for `rel:self`" x-faker: helpers.arrayElement: [["text/xml"]] Product: type: object title: 'Product' description: "`product` object. See definition in SKG-IF [Research product](https://skg-if.github.io/interoperability-framework/docs/research-product.html) ( entity_type:product )." allOf: - $ref: "#/components/schemas/Entity" - type: object required: [ "local_identifier","entity_type","product_type" ] properties: entity_type: default: "product" type: string x-faker: helpers.arrayElement: [["product"]] identifiers: type: [array, "null"] items: properties: scheme: type: string x-faker: helpers.arrayElement: [["url"]] value: type: string x-faker: fake : ['{{internet.url}}/record/{{random.alphaNumeric(8)}}'] product_type: type: string description: see 4 types definition in [SKG-IF Research product](https://skg-if.github.io/interoperability-framework/docs/research-product.html) enum: - "literature" - "research data" - "research software" - "other" titles: type: [object, "null"] description: | The titles of a `product` (multiple for multilinguism).\ The object is a dictionary, the keys represent language codes following [ISO 639-1](https://en.wikipedia.org/wiki/ISO_639-1).\ The special key `none` is reserved whenever the information about the language is not available or cannot be shared. # Warn patternProperties, display does not work with vscode-openapi-viewer vscode extension, but compatible in stoplight.io web viewer. patternProperties: "^([a-z]{2}|none)$": type: array items: type: string x-faker: random.words: [ 5 ] abstracts: type: [object, "null"] description: | The abstracts of a `product` (multiple for multilinguism).\ The object is a dictionary, the keys represent language codes following [ISO 639-1](https://en.wikipedia.org/wiki/ISO_639-1).\ The special key `none` is reserved whenever the information about the language is not available or cannot be shared. patternProperties: "^([a-z]{2}|none)$": type: array items: type: string x-faker: random.words: [ 20 ] topics: type: [array, "null"] description: List of `topic` covered by the `product` items: required: [ "term" ] properties: term: oneOf: - $ref: '#/components/schemas/Topic' - $ref: '#/components/schemas/LocalIdentifierRef' # TODO provenance ? contributions: type: [array, "null"] description: List of objects describing a `person` or `organisation`, its role, contribution, rank, when working on the `product`. items: $ref: '#/components/schemas/ProductContribution' manifestations: type: [array, "null"] description: List of objects representing multiple manifestations of the same `product` (e.g., a preprint, a postprint, etc.). items: $ref: '#/components/schemas/ProductManifestation' relevant_organisations: type: [array, "null"] description: List of relevant Organisation associated with the `product`, in case the individual affiliations of a `person` are not available. items: oneOf: - $ref: '#/components/schemas/Organisation' - $ref: '#/components/schemas/LocalIdentifierRef' funding: type: [array, "null"] description: List of `grant` associated with the `product` items: oneOf: - $ref: '#/components/schemas/GrantLite' - $ref: '#/components/schemas/LocalIdentifierRef' related_products: anyOf: - $ref: '#/components/schemas/ProductsRelated' - type: "null" examples: - local_identifier: product-1-fgp entity_type: product product_type: literature titles : "en": ["The FAIR Guiding Principles for scientific data management and stewardship"] abstracts : "en": ["There is an urgent need to improve the infrastructure supporting the reuse of scholarly data. A diverse set of stakeholders—representing academia, industry, funding agencies, and scholarly publishers—have come together to design and jointly endorse a concise and measureable set of principles that we refer to as the FAIR Data Principles"] identifiers: - value: "10.1038/sdata.2016.18" scheme: "doi" - value: "26978244" scheme: "pmid" contributions: - contribution_types: - "writing – original draft" role: "author" rank: 1 by: name: "Mark Wilkinson" given_name: "Mark" family_name: "Wilkinson" identifiers: - value: "0000-0001-6960-357X" scheme: "orcid" local_identifier: person-5-mw entity_type: "person" declared_affiliations: - name: "Center for Plant Biotechnology and Genomics, Universidad Politécnica de Madrid, Madrid, 28223, Spain" local_identifier: affiliation-organisation-1 entity_type: "organisation" country: "ES" manifestations: - type: labels: en: localtypey defined_in: http://www.example.com/types/onto class: http://www.example.com/types/onto/localtypemethodology biblio: hosting_data_source: local_identifier: datasource-1-aa entity_type: datasource name: "An Archive" in: name: "Scientific Data" acronym: "Sci Data" identifiers: - "value": "2052-4463" "scheme": "issn" local_identifier: venue-5-sd entity_type: "venue" dates: # http://api.crossref.org/works/10.1038/sdata.2016.18 publication: - "2016-03-15" collected: - "2013" - "2014" deposit: - "2023-01-04" funding: - local_identifier: grant-7-zz entity_type: "grant" titles: - en: "EU grant ZZ" related_products: { cites: [ "614a6575-5d6c-416c-a8e1-f49a5d589bf8" ] } ProductContribution: type: object title: 'ProductContribution' description: 'Product contribution. Describes a `person` or `organisation`, its role, contribution, rank, when working on a `product`. See definition in SKG-IF [Research product](https://skg-if.github.io/interoperability-framework/docs/research-product.html#contributions)' required: [ "by" ] properties: by: description: The identifier of a `person` or `organisation` contributing to a `product`. oneOf: - $ref: '#/components/schemas/PersonLite' - $ref: '#/components/schemas/Organisation' - $ref: '#/components/schemas/Agent' - $ref: '#/components/schemas/LocalIdentifierRef' discriminator: propertyName: entity_type mapping: person: '#/components/schemas/PersonLite' organisation: '#/components/schemas/Organisation' agent: '#/components/schemas/Agent' declared_affiliations: description: List of `organisation` that reflect the declared affiliations of a `person` contributing to a `product`. type: [array, "null"] items: oneOf: - $ref: '#/components/schemas/Organisation' - $ref: '#/components/schemas/LocalIdentifierRef' rank: type: [integer, "null"] x-faker: helpers.regexpStyleStringParse: ['[0-10]'] role: type: [string, "null"] enum: - "author" - "editor" - "publisher" contribution_types: description: | The contributions of `person` or `organisation` had in a `product`.\ Each element in the list is a String compliant with the [CRediT](https://credit.niso.org/) taxonomy. type: [array, "null"] items: type: string enum: - "conceptualization" - "data curation" - "formal analysis" - "funding acquisition" - "investigation" - "methodology" - "project administration" - "resources" - "software" - "supervision" - "validation" - "visualization" - "writing – original draft" - "writing – review & editing" ProductManifestation: type: object title: 'ProductManifestation' description: 'Product manifestation, represents a specific manifestation of a `product` (e.g., a preprint, a postprint, etc.). See definition in SKG-IF [Research product](https://skg-if.github.io/interoperability-framework/docs/research-product.html#manifestations)' properties: type: description: 'The type of the manifestation (e.g., preprint).' type: [object, "null"] properties: class: type: [string, "null"] description: The URL of the class identifying the entity (e.g., in an ontology) describing that type. x-faker: fake : ['http://www.example.com/types/onto/localtype{{random.words(1)}}'] examples: - "http://purl.org/spar/fabio/Preprint" defined_in: type: [string, "null"] description: the URL of the schema of the manifestation type, e.g., a link to the vocabulary of allowed product types. x-faker: fake : ['http://www.example.com/types/onto'] examples: - "http://purl.org/spar/fabio" labels: type: [object, "null"] description: | the labels describing the type (multiple for multilinguism)\ The object is a dictionary, the keys represent language codes following [ISO 639-1](https://en.wikipedia.org/wiki/ISO_639-1).\ The special key `none` is reserved whenever the information about the language is not available or cannot be shared. # Warn patternProperties, display does not work with vscode-openapi-viewer vscode extension, but compatible in stoplight.io web viewer. patternProperties: "^([a-z]{2}|none)$": type: string x-faker: helpers.arrayElement: [["localtypez", "localtypex", "localtypey"]] examples: - preprint dates: type: [object, "null"] description: 'Manifestation dates, for each date type (acceptance, publication, embargo...) you can define an array of dates. Format [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) compliant string ( "2024-10-01", "2024-10", "2024", "2024-10-01T10:42:14Z" ).' properties: acceptance: type: [array, string, "null"] items: type: string examples: - "2024-10-01" - "2024-10" - "2024" - "2024-10-01T10:42:14Z" access: type: [array, string, "null"] items: type: string collected: type: [array, string, "null"] items: type: string copyright: type: [array, string, "null"] items: type: string correction: type: [array, string, "null"] items: type: string creation: type: [array, string, "null"] items: type: string decision: type: [array, string, "null"] items: type: string deposit: type: [array, string, "null"] items: type: string distribution: type: [array, string, "null"] items: type: string embargo: type: [array, string, "null"] items: type: string modified: type: [array, string, "null"] items: type: string publication: type: [array, string, "null"] items: type: string received: type: [array, string, "null"] items: type: string request: type: [string, "null"] retraction: type: [array, string, "null"] items: type: string validity: type: [array, string, "null"] items: type: string peer_review: description: 'Whether the manifestation has undergone a peer review. It must be specify only if information about peer reviewing exists' type: [object, "null"] properties: status: type: [string, "null"] description: describe if the manifestation peer review status. enum: - "peer reviewed" - "under review" - null description : type: [string, "null"] description: describe the type of peer review that applies. enum: - "single-blind peer review" - "double-blind peer review" - "open peer review" access_rights: description: 'The access right for the specific materialisation' type: [object, "null"] properties: status: type: [string, "null"] description: describe if the manifestation accessrights status. enum: - "open" - "closed" - "embargoed" - "restricted" - "unavailable" description : type: [string, "null"] description: describe and qualify the specific status selected. licence: type: [string, "null"] description: The URL of the licence specific to the manifestation x-faker: fake: ['https://creativecommons.org/licenses/by/4.0/'] examples: - https://creativecommons.org/licenses/by/4.0/ version: type: [string, "null"] description: The version for a software or research data product examples: - "2.3.6" biblio: type: [object, "null"] properties: issue: type : [string, "null"] description: Issue number. x-faker: fake : ['{{datatype.number(5)}}'] pages: type : [object, "null"] description: the pages where the manifestation in defined (within its Venue). required: [ "first", "last" ] properties : first: type : string description: The starting page. x-faker: fake : ['{{datatype.number(20)}}'] last: type : string description: The ending page. x-faker: fake : ['{{datatype.number(20)}}'] volume: type : [string, "null"] description: Volume number (for journals, books, conferences). x-faker: fake : ['{{datatype.number(50)}}'] edition: type : [string, "null"] description: The edition (for journals and books). number: type : [string, "null"] description: a number of the manifestation within the Venue (e.g., chapter number). x-faker: fake : ['{{datatype.number(5)}}'] in: oneOf: - $ref: '#/components/schemas/VenueLite' - $ref: '#/components/schemas/LocalIdentifierRef' - type: "null" hosting_data_source : oneOf: - $ref: '#/components/schemas/DataSourceLite' - $ref: '#/components/schemas/LocalIdentifierRef' - type: "null" ProductsRelatedItem: type: object description: "Reference to a `product` object" allOf: - $ref: "#/components/schemas/Entity" - type: object required: [ "local_identifier","entity_type" ] properties: entity_type: default: "product" type: string x-faker: helpers.arrayElement: [["product"]] ProductsRelated: type: object description : A dictionary of objects representing related `product`, where the semantics of such relationships is specified as a key. properties : cites: type: [array, "null"] items: oneOf : - $ref: '#/components/schemas/ProductsRelatedItem' - $ref: '#/components/schemas/LocalIdentifierRef' is_supplemented_by: type: [array, "null"] items: oneOf : - $ref: '#/components/schemas/ProductsRelatedItem' - $ref: '#/components/schemas/LocalIdentifierRef' is_documented_by: type: [array, "null"] items: oneOf: - $ref: '#/components/schemas/ProductsRelatedItem' - $ref: '#/components/schemas/LocalIdentifierRef' is_new_version_of: type: [array, "null"] items: oneOf : - $ref: '#/components/schemas/ProductsRelatedItem' - $ref: '#/components/schemas/LocalIdentifierRef' is_part_of: type: [array, "null"] items: oneOf : - $ref: '#/components/schemas/ProductsRelatedItem' - $ref: '#/components/schemas/LocalIdentifierRef' Agent: type: object title: "Agent" description: "`agent` object. You may use `agent` if your system does not make the difference between `person` and `organisation` See definition in SKG-IF [Agent](https://skg-if.github.io/interoperability-framework/docs/agent.html) ( entity_type:agent )." allOf: - $ref: "#/components/schemas/Entity" - type: object required: [ "local_identifier","entity_type" ] properties : entity_type: enum: - "agent" type: string x-faker: fake: ["agent"] identifiers: description: Objects representing external identifiers for the entity. See [Agent](https://skg-if.github.io/interoperability-framework/docs/agent.html#identifiers) documentation for supported schemes type: [array, "null"] items: required: [ "scheme", "value" ] properties: scheme: type: string description: The scheme for the external identifier. x-faker: fake: ["ror"] examples: - 'ror' value: type: string description: "The external identifier." x-faker: fake : ['{{random.alphaNumeric(10)}}'] examples: - "https://ror.org/05gq02987" name: type: [string, "null"] x-faker: company.companyName examples: - "Brown University" Organisation: type: object title: "Organisation" description: "`organisation` object. See definition in SKG-IF [Agent](https://skg-if.github.io/interoperability-framework/docs/agent.html) ( entity_type:organisation )." allOf: - $ref: "#/components/schemas/Entity" - type: object required: [ "local_identifier","entity_type" ] properties : entity_type: enum: - "organisation" type: string x-faker: fake: ["organisation"] identifiers: description: Objects representing external identifiers for the entity. See [Agent](https://skg-if.github.io/interoperability-framework/docs/agent.html#identifiers) documentation for supported schemes type: [array, "null"] items: required: [ "scheme", "value" ] properties: scheme: description: The scheme for the external identifier. type: string x-faker: fake: ["ror"] examples: - 'ror' value: type: string description: "The external identifier." x-faker: fake : ['{{random.alphaNumeric(10)}}'] examples: - "https://ror.org/05gq02987" name: type: [string, "null"] x-faker: company.companyName examples: - "Brown University" other_names: description: "Other names, perhaps in different languages, identifying an `organisation`." type: [array, "null"] items: type: string examples : - ["Brownie"] short_name: type: [string, "null"] #x-faker: company.bsAdjective x-faker: random.alpha: [{count: 4, upcase: true}] examples: - "BU" website: type: [string, "null"] description: The website URL for an Organisation examples: - "https://www.brown.edu/" country: type: [string, "null"] description: The country code expressed as [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). pattern: '^[A-Z]{2}$' examples: - "US" types: description: "The types of an `organisation`." type: [array, "null"] items: type: string enum: - archive - company - education - facility - government - healthcare - nonprofit - funder - research - unspecified examples: - local_identifier: 'organisation-2-bu' entity_type: 'organisation' identifiers: - "scheme": ror "value": https://ror.org/05gq02987 name: "Brown University" short_name: BU country: US types: - education - local_identifier: organisation-3-jcbl entity_type: 'organisation' identifiers: - scheme: ror value: https://ror.org/05gq02987 - scheme: ror value: https://ror.org/0274ane14 name: John Carter Brown Library, Brown University, Providence RI, US short_name: BU country: US types: - archive - local_identifier: organisation-5-lsa entity_type: 'organisation' name: Lab of science, unknown University, Antarctica - local_identifier: organisation-6-eu entity_type: 'organisation' identifiers: - scheme: ror value: https://ror.org/00k4n6c32 name: "European Commission" short_name: EU types: - funder Person: type: object title: "Person" description: "`person` object. See definition in SKG-IF [Agent](https://skg-if.github.io/interoperability-framework/docs/agent.html) ( entity_type:person )" allOf: - $ref: "#/components/schemas/PersonLite" - type: object required: [ "local_identifier","entity_type" ] properties : affiliations: description : "All the affiliations of a `person`. (curriculum vitae list )" type: [array, "null"] items: required: [ "affiliation"] properties: affiliation: description : "`organisation` a `person` is affiliated with" $ref: "#/components/schemas/Organisation" role : type: [string, "null"] default: "affiliate" x-faker: fake : ['affiliate'] period : type: [object, "null"] description : "The time period where the Person was affiliated with an Organisation" properties : start: type: [string, "null"] description: start date. Format [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) compliant string ( "2024-10-01", "2024-10", "2024" ).' end: type: [string, "null"] description: end date. Format [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) compliant string ( "2024-10-01", "2024-10", "2024" ).' examples: - local_identifier: person-1-jc entity_type: 'person' identifiers: - scheme: orcid value: 0000-0002-1825-0097 given_name: Josiah family_name: Carberry name: Josiah Carberry affiliations: role: affiliate period: start: "2010-08-24" end: "2020-08-24" affiliation: local_identifier: organisation-2-bu entity_type: 'organisation' identifiers: - scheme: ror value: https://ror.org/05gq02987 name: Brown University short_name: BU country: US PersonLite: type: object title: "PersonLite" description: "`person` object containing a limited set of fields. See definition in SKG-IF [Agent](https://skg-if.github.io/interoperability-framework/docs/agent.html) ( entity_type:person )." allOf: - $ref: "#/components/schemas/Entity" - type: object required: [ "local_identifier","entity_type" ] properties : entity_type: type: string enum: - "person" x-faker: fake: ["person"] identifiers: description: Objects representing external identifiers for the entity. See [Agent](https://skg-if.github.io/interoperability-framework/docs/agent.html#identifiers) documentation for supported schemes type: [array, "null"] items: required: [ "scheme", "value" ] properties: scheme: type: string description: The scheme for the external identifier. x-faker: fake: ["orcid"] examples : - orcid value: type: string description: "The external identifier." x-faker: helpers.regexpStyleStringParse: ['[1000-9999]-[1000-9999]-[1000-9999]-[1000-9999]'] examples : - "0000-0002-1825-0097" given_name: type: [string, "null"] x-faker: name.firstName examples : - Josiah family_name: type: [string, "null"] x-faker: name.lastName examples : - Carberry name: type: [string, "null"] x-faker: name.findName examples : - Josiah Carberro examples: - local_identifier: person-1-jc entity_type: 'person' identifiers: - scheme: orcid value: 0000-0002-1825-0097 given_name: Josiah family_name: Josiah name: Josiah Carberry Topic: allOf: - $ref: "#/components/schemas/Entity" - type: object required: [ "local_identifier","entity_type" ] title: 'Topic' description: "`topic` object containing a limited set of fields. See definition in SKG-IF [Topic](https://skg-if.github.io/interoperability-framework/docs/topic.html) ( entity_type:topic )." properties : entity_type: type: string enum: - "topic" x-faker: fake: ["topic"] identifiers: description: Objects representing external identifiers for the entity. See [Topic](https://skg-if.github.io/interoperability-framework/docs/topic.html#identifiers) documentation for supported schemes type: [array, "null"] items: required: [ "scheme", "value" ] properties: scheme: description: The scheme for the external identifier. type: string #TODO regexp no space examples: - wikidata - dbpedia x-faker: helpers.arrayElement: [["wikidata", "dbpedia", "computer_science_ontology"]] value: type: string examples: - https://www.wikidata.org/wiki/Q21198 x-faker: fake : ['{{internet.url}}/topic_{{random.alphaNumeric(6)}}'] labels: type: [object, "null"] description: The labels describing a Topic (multiple for multilingualism). The object is a dictionary, the keys represent language codes following ISO 639-1 (`en`, `es`, `it`, `fr`...). The special key `none` is reserved whenever the information about the language is not available or cannot be shared. patternProperties: "^([a-z]{2}|none)$": type: string x-faker: random.words: [1] example: # 'object' type only supports single value 'example' ( not 'examples' ) https://swagger.io/docs/specification/v3_0/adding-examples/ en: "Computer Science" it: "Informatica" Grant: type: object title: 'Grant' description: "`grant` object. See SKG-IF definition [Grant](https://skg-if.github.io/interoperability-framework/docs/grant.html) ( entity_type:grant )." allOf: - $ref: "#/components/schemas/GrantLite" - type: object required: [ "local_identifier","entity_type" ] properties : currency: description: "Currency of the funded amount, following [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217)." type: [string, "null"] examples : - EUR - USD x-faker: helpers.arrayElement: [["EUR", "USD"]] funded_amount: type: [integer, "null"] description: "Amount funded for the `grant`" keywords: description: "keywords for the `grant`" type: [array, "null"] items: type: string duration : type: [object, "null"] description : "The duration of the `grant`" required: [ "start"] properties : start: type: string description: The start date of the Grant. Format [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) compliant string ( "2024-10-01", "2024-10", "2024" ). examples: - "2023-01-01" end: type: [string, "null"] description: The end date of the Grant. Format [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) compliant string ( "2024-10-01", "2024-10", "2024" ). examples: - "2025-12-31" website: type: [string, "null"] description: The website URL for the `grant` examples: - "https://graspos.eu" beneficiaries: description: "List of `organisation` funded by the `grant`" type: [array, "null"] items: oneOf: - $ref: '#/components/schemas/Organisation' - $ref: '#/components/schemas/LocalIdentifierRef' contributions: type: [array, "null"] description: List of objects describing a `person` or `organisation`, its role, contribution, rank, when working on the `grant`. items: oneOf: - $ref: '#/components/schemas/GrantContribution' - $ref: '#/components/schemas/LocalIdentifierRef' GrantContribution: type: object title: 'GrantContribution' description: 'Grant contribution. Describes a `person` or `organisation`, its role, contribution, rank, when working on a `grant`. See SKG-IF definition [Grant contribution](https://skg-if.github.io/interoperability-framework/docs/grant.html#contributions) ( entity_type:grant ).' properties: by: description: The identifier of a `person` or `organisation` contributing to a `grant`. oneOf: - $ref: '#/components/schemas/PersonLite' - $ref: '#/components/schemas/Organisation' - $ref: '#/components/schemas/LocalIdentifierRef' - type: "null" discriminator: propertyName: entity_type mapping: person: '#/components/schemas/PersonLite' organisation: '#/components/schemas/Organisation' declared_affiliations: description: List of `organisation` that reflect the declared affiliations of a `person` contributing to a `grant`. type: [array, "null"] items: oneOf: - $ref: '#/components/schemas/Organisation' - $ref: '#/components/schemas/LocalIdentifierRef' roles: description: | The roles that a `person` or `organisation` had in a `grant`.\ Each element in the list is a String compliant with the [SCoRO](https://sparontologies.github.io/scoro/current/scoro.html#http://purl.org/spar/scoro/ProjectRole) taxonomy. type: [array, "null"] items: type: string enum: - "co-applicant" - "lead applicant" - "project leader" - "project manager" - "project member" - "workpackage leader" GrantLite: type: object title: 'GrantLite' description: "`grant` object containing a limited set of fields. See SKG-IF definition [Grant](https://skg-if.github.io/interoperability-framework/docs/grant.html) ( entity_type:grant )." allOf: - $ref: "#/components/schemas/Entity" - type: object required: [ "local_identifier","entity_type" ] properties : entity_type: type: string enum: - "grant" x-faker: fake: ["grant"] identifiers: description: Objects representing external identifiers for the entity. See [Grant](https://skg-if.github.io/interoperability-framework/docs/grant.html#identifiers) documentation for supported schemes type: [array, "null"] items: required: [ "scheme", "value" ] properties: scheme: description: The scheme for the external identifier. type: string x-faker: fake: ["doi"] examples: - "doi" value: description: "The external identifier." type: string x-faker: fake : ['{{internet.url}}/grant/{{random.alphaNumeric(8)}}'] examples: - "https://doi.org/10.3030/101095129" grant_number: type: [string, "null"] x-faker: fake : ['{{internet.url}}/grant/{{random.alphaNumeric(8)}}'] examples: - "101095129" titles: type: [object, "null"] description: | The titles of a `grant` (multiple for multilinguism).\ The object is a dictionary, the keys represent language codes following [ISO 639-1](https://en.wikipedia.org/wiki/ISO_639-1).\ The special key `none` is reserved whenever the information about the language is not available or cannot be shared. patternProperties: "^([a-z]{2}|none)$": type: string x-faker: random.words: [ 5 ] examples: - "en": "GraspOS: next Generation Research Assessment to Promote Open Science" abstracts: type: [object, "null"] description: | The abstracts of a `grant` (multiple for multilinguism).\ The object is a dictionary, the keys represent language codes following [ISO 639-1](https://en.wikipedia.org/wiki/ISO_639-1).\ The special key `none` is reserved whenever the information about the language is not available or cannot be shared. patternProperties: "^([a-z]{2}|none)$": type: string x-faker: random.words: [ 5 ] examples: - "en": "GraspOS aims to build and operate a data infrastructure to support the policy reforms and pave the way towards a responsible research assessment system." acronym: type: [string, "null"] x-faker: random.alpha: [{count: 8, upcase: true}] examples: - "GraspOS" funding_agency: description : "`organisation` funding the `grant`." anyOf: - $ref: "#/components/schemas/Organisation" - type: "null" funding_stream: description : "funding stream of the `grant`" type: [string, "null"] examples : - "Horizon Europe" Venue: type: object title: 'Venue' description: "`venue` object. See definition in SKG-IF [Venue](https://skg-if.github.io/interoperability-framework/docs/venue.html) ( entity_type:venue )." allOf: - $ref: "#/components/schemas/VenueLite" - type: object required: [ "local_identifier","entity_type" ] properties: acronym: type: [string, "null"] x-faker: random.alpha: [{count: 8, upcase: true}] examples: - "JPC" type: type: [string, "null"] enum: [journal, conference, book, repository, other, unknown] VenueLite: type: object title: 'VenueLite' description: "`venue` object containing a limited set of fields. See definition in SKG-IF [Venue](https://skg-if.github.io/interoperability-framework/docs/venue.html) ( entity_type:venue )." allOf: - $ref: "#/components/schemas/Entity" - type: object required: [ "local_identifier","entity_type" ] properties : entity_type: default: "venue" type: string x-faker: fake: ["venue"] identifiers: description: Objects representing external identifiers for the entity. See [Venue](https://skg-if.github.io/interoperability-framework/docs/venue.html#identifiers) documentation for supported schemes type: [array, "null"] items: required: [ "scheme", "value" ] properties: scheme: description: "The scheme for the external identifier." type: string x-faker: fake: ["issn"] examples: - "issn" - "isbn" - "lissn" - "doi" - "handle" - "url" value: description: "The external identifier." type: string x-faker: helpers.regexpStyleStringParse: ['[1000-9999]-[1000-9999]'] examples: - "0264-3561" name: type: [string, "null"] x-faker: fake : ['{{random.words(5)}} {{helpers.arrayElement(["Journal", "Catalog"])}}'] examples: - "Journal of Psychoceramics" acronym: type: [string, "null"] x-faker: random.alpha: [{count: 8, upcase: true}] examples: - "JPC" DataSource: type: object title: 'DataSource' description: "`datasource` object. See definition in SKG-IF [Data Source](https://skg-if.github.io/interoperability-framework/docs/data-source.html) ( entity_type:datasource )." allOf: - $ref: "#/components/schemas/DataSourceLite" - type: object required: [ "local_identifier","entity_type" ] properties: #TODO persistent_identity_systems #TODO audience data_source_classification: type : [string, "null"] description: "The specific type of a Data source, based on the vocabulary Data source Classification. It can be chosen among the following values" enum : [repository, aggregator, scientific database, journal archive, publisher archive, cris system] research_product_types: type: [array, "null"] description: "The types of entities managed by a Data source. Each item in the list should be compliant with the following terms" items: type: string enum : [metadata, research data, literature , software , any] #TODO disciplines #TODO policies #TODO targets DataSourceLite: type: object title: 'DataSourceLite' description: "`datasource` object containing a limited set of fields. See definition in SKG-IF [Data Source](https://skg-if.github.io/interoperability-framework/docs/data-source.html) ( entity_type:datasource )." allOf: - $ref: "#/components/schemas/Entity" - type: object required: [ "local_identifier","entity_type" ] properties : entity_type: type: string enum: - "datasource" x-faker: fake: ["datasource"] identifiers: description: Objects representing external identifiers for the entity. See [Data Source](https://skg-if.github.io/interoperability-framework/docs/data-source.html#identifiers) documentation for supported schemes type: [array, "null"] required: [ "scheme", "value" ] items: properties: scheme: type: string description: The scheme for the external identifier. examples: - doi x-faker: helpers.arrayElement: [["url"]] value: type: string description: "The external identifier." examples: - "10.25504/FAIRsharing.rkwr6y" x-faker: fake : ['{{internet.url}}/datasource/{{random.alphaNumeric(8)}}'] name: type: [string, "null"] examples: - "Oxford University Research Archive" x-faker: fake : ['{{random.words(4)}} {{helpers.arrayElement(["Archive", "Repository", "Database"])}}'] Entity: type: object description: "Entity common fields used for entities : `product`,`person`,`organisation`,`grant`,`venue`,`datasource`" properties: local_identifier: type: string description: | Unique local identifier as URL. format : `https://[your-@base-url]/{identifier string}` example: `https://w3id.org/skg-if/sandbox/acme/prod-1` The local identifier value can contain only the `{identifier string}` part only if the `@base` is present in the `@context` output. \ The local identifier value can also be an URL reference not included in your `@base` domain. This can be useful for entities identified in your system by their external PID only (RoR, DOI...) If the entity does not have any stable identifier, an on-the-fly identifier is returned : `otf______`. - `otf` stands for on-the-fly to explicitly clarify the local identifiers it has been created for the purpose of creating this SKG-IF document; - `` is a string portion that enables the source to uniquely identifier the session in which such SKG-IF document has been created - e.g. it could be the current time of the software run to create the SKG expressed in milliseconds; - `` is a string portion that identifies the particular entity in consideration. For instance, a possible example of such a local identifier would be : `otf___1730027051396___person-1`. An on-the-fly may not resolve with its `self` API link URL ex: `https://example.com/skg-if/api/persons/otf___1730027051396___person-1`. on-the-fly means that this local identifier cannot be resolved outside the session context. x-faker: fake : ['{{random.uuid}}'] examples: - http://w3id.org/skg-if/sandbox/acme/product-1 - http://w3id.org/skg-if/sandbox/acme/person-1 - http://w3id.org/skg-if/sandbox/acme/otf___1730027051396___person-1 - http://w3id.org/skg-if/sandbox/acme/otf___1730027051396___product-1 identifiers: type: [array, "null"] items: required: [ "scheme", "value" ] properties: scheme: type: string # alias list in https://skg-if.github.io/context/ver/current/skg-if.json # enum: ["doi","pmid","pmcid","arxiv","url","omid","crossref","openalex","orcid","viaf","ror": ,"issn": , "eissn":, "lissn","isbn","opendoar","re3data.org","fairsharing","handle"] value: type: string entity_type: type: string MetaSingleEntity: type: object required: [ "local_identifier", "entity_type" ] properties: local_identifier: type: string description: Entity API URL. local_identifier can be expressed with ot without full domain. Full domain, including your @base, MUST also resolve examples: - https://example.com/skg-if/api/products/product-1 - https://example.com/skg-if/api/persons/person-1 - https://acme.com/skg-if/api/products/https://w3id.org/skg-if/sandbox/acme/prod-1 - https://acme.com/skg-if/api/persons/https://w3id.org/skg-if/sandbox/acme/person-1 entity_type: type: string description: single entity enum: - single_entity api_items: type: [array, "null"] items: $ref: '#/components/schemas/ApiItem' MetaSearch: type: object required: [ "local_identifier", "entity_type" ] properties: local_identifier: type: string description: search result page id as SKG-IF API URL examples: - https://example.com/skg-if/api/products?filter=xxx&page=y - https://example.com/skg-if/api/persons?filter=xxx&page=y entity_type: type: string description: search result page type enum: - search_result_page prev_page: description: Previous page reference anyOf: - $ref: '#/components/schemas/SearchResultPage' - type: "null" next_page: description: Next page reference anyOf: - $ref: '#/components/schemas/SearchResultPage' - type: "null" part_of: description: Reference for the search result as a whole (all pages) type: [object, "null"] required: [ "local_identifier", "entity_type" ] properties: local_identifier: type: string description: search result id as SKG-IF API URL examples: - https://example.com/skg-if/api/products?filter=xxx - https://example.com/skg-if/api/persons?filter=xxx entity_type: type: string description: search type. Value must be `search_result` enum: - search_result total_items: description: total number of item entities for the search type: [integer, "null"] x-faker: datatype.number: [{min: 10, max: 100}] first_page: description: First page reference of the search anyOf: - $ref: '#/components/schemas/SearchResultPage' - type: "null" last_page: description: Last page reference of the search anyOf: - $ref: '#/components/schemas/SearchResultPage' - type: "null" api_items: type: [array, "null"] items: $ref: '#/components/schemas/ApiItem' SearchResultPage: type: object properties: local_identifier: type: [string, "null"] description: search result page id as SKG-IF API URL examples: - https://example.com/skg-if/api/products?filter=xxx&page=y - https://example.com/skg-if/api/persons?filter=xxx&page=y entity_type: type: [string, "null"] description: search result page type. Value must be `search_result_page` enum: - search_result_page Error: type: object properties: # from https://datatracker.ietf.org/doc/html/rfc7807 "type": type: [string, "null"] description: A URI reference that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML). When this member is not present, its value is assumed to be "about:blank" "title": type: [string, "null"] description: A short, human-readable summary of the problem type. It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization (e.g., using proactive content negotiation). "status": type: [string, "null"] description: The HTTP status code generated by the origin server for this occurrence of the problem. "detail" : type: [string, "null"] description: A human-readable explanation specific to this occurrence of the problem. "instance": type: [string, "null"] description: A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. JsonLdCtxDataModel: type: string description: "URL to SKG-IF data model context supported by the current OpenAPI `https://w3id.org/skg-if/context/1.1.0/skg-if.json`" enum: - https://w3id.org/skg-if/context/1.1.0/skg-if.json x-faker: fake: ['https://w3id.org/skg-if/context/1.1.0/skg-if.json'] JsonLdCtxSearch: type: string description: "URL to SKG-IF API context (meta section) supported by the current OpenAPI `https://w3id.org/skg-if/context/1.0.0/skg-if-api.json`" enum: - https://w3id.org/skg-if/context/1.0.0/skg-if-api.json x-faker: fake: ['https://w3id.org/skg-if/context/1.0.0/skg-if-api.json'] JsonLdCtxBaseOrMore: description : 'Additional context mappings ex: `{ "@base":"https://w3id.org/skg-if/sandbox/acme" }`' properties: "@base": type: [string, "null"] description : | Default root URL of the JSON-LD context. \ To define your `@base`, please refer to the [SKG-IF API doc](https://skg-if.github.io/api/) \ Your `@base` should end with a `/` \ common formats : \ - `https://acme.com/skg/` \ - `https://w3id.org/acme/` \ - `https://w3id.org/skg-if/sandbox/acme/`\ x-faker: fake: ['https://w3id.org/skg-if/sandbox/{{random.alpha(5)}}/'] examples: - "https://acme.com/skg/" - "https://acme.com/graph/" - "https://w3id.org/acme/" - "https://w3id.org/skg-if/sandbox/acme/" additionalProperties: type: string description: "context URL of extension entities" x-faker: fake : ['http://www.example.com/skg/{{random.alpha(3)}}']