From e10f99e005af36411f368cee617bebf626d436e7 Mon Sep 17 00:00:00 2001 From: rduyme Date: Sat, 21 Mar 2026 16:40:43 +0100 Subject: [PATCH 1/7] Add Link relation and support for loca_identifier external urls --- openapi/ver/1.0.0/context/skg-if-api.json | 13 +- openapi/ver/current/skg-if-openapi.yaml | 571 ++++++++++++++++------ 2 files changed, 436 insertions(+), 148 deletions(-) diff --git a/openapi/ver/1.0.0/context/skg-if-api.json b/openapi/ver/1.0.0/context/skg-if-api.json index e59988e..702afc6 100644 --- a/openapi/ver/1.0.0/context/skg-if-api.json +++ b/openapi/ver/1.0.0/context/skg-if-api.json @@ -27,6 +27,17 @@ "prev_page": { "@id": "as:prev" }, - "meta": "@nest" + "meta": "@nest", + "_links":"as:url", + "link":"as:Link", + "rel":{ + "@id": "as:rel" + }, + "media_type":{ + "@id": "as:mediaType" + }, + "href": { + "@id": "as:href" + } } } \ No newline at end of file diff --git a/openapi/ver/current/skg-if-openapi.yaml b/openapi/ver/current/skg-if-openapi.yaml index acfe2fa..9a3dbd9 100644 --- a/openapi/ver/current/skg-if-openapi.yaml +++ b/openapi/ver/current/skg-if-openapi.yaml @@ -16,7 +16,7 @@ info: Last version of the SKG-IF OpenAPI is available at : https://skg-if.github.io/api/ # Note for implementers : - - Please refer to [SKG-IF OpenAPI Implementer documentation](https://docs.google.com/document/d/1t7b7h28UTtM56Sda4NGJIp0hnQfGbcVVGn12fny9wfI/edit?usp=sharing) + - 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). @@ -64,7 +64,7 @@ servers: default: skg-if/api description: service provider skg-if api path paths: - '/products/{short_local_identifier}': + '/products/{local_identifier}': get: tags: - Product @@ -73,7 +73,7 @@ paths: 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/shortLocalIdPathParam' + - $ref : '#/components/parameters/localIdPathParam' responses: '200': description: | @@ -95,7 +95,7 @@ paths: - $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/my-skg-acronym/"}] + - ["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": type: array minItems: 1 @@ -109,11 +109,15 @@ paths: "@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/my-skg-acronym/"} + {"@base" : "https://w3id.org/skg-if/sandbox/acme/"} ] "@graph" : - - local_identifier: http://example.com/skg-if/api/products/prd-c66c6-38be-4d5f-85db-d44c9f869333 - entity_type: product + - local_identifier: "product-1-fgp" + entity_type: "product" + _links: + - entity_type: "link" + rel: "self" + href: "https://example.com/skg-if/api/products/product-1-fgp" product_type: literature titles : "en": ["The FAIR Guiding Principles for scientific data management and stewardship"] @@ -137,12 +141,20 @@ paths: identifiers: - value: "0000-0001-6960-357X" scheme: "orcid" - local_identifier: http://example.com/skg-if/api/persons/otf___1730027051396___person-1 + local_identifier: person-5-mw entity_type: "person" + _links: + - entity_type: "link" + rel: "self" + href: "https://example.com/skg-if/api/persons/person-5-mw" declared_affiliations: - name: "Center for Plant Biotechnology and Genomics, Universidad Politécnica de Madrid, Madrid, 28223, Spain" - local_identifier: http://example.com/skg-if/api/otf___1730027051396___person-1-aff-1 + local_identifier: affiliation-organisation-1 entity_type: "organisation" + _links: + - entity_type: "link" + rel: "self" + href: "https://example.com/skg-if/api/organisations/affiliation-organisation-1" country: "ES" manifestations: - type: @@ -152,17 +164,25 @@ paths: class: http://www.example.com/types/onto/localtypemethodology biblio: hosting_data_source: - local_identifier: http://example.com/skg-if/api/arch-6f368a3a-b1cf-498f-b2de-27135d1e0075 + local_identifier: datasource-1-aa entity_type: datasource name: "An Archive" + _links: + - entity_type: "link" + rel: "self" + href: "https://example.com/skg-if/api/datasources/datasource-1-aa" in: name: "Scientific Data" acronym: "Sci Data" identifiers: - "value": "2052-4463" "scheme": "issn" - local_identifier: http://example.com/skg-if/api/venues/journal-46bc1-00f8-42dd-8221-ac4deb52fb25 + local_identifier: venue-5-sd entity_type: "venue" + _links: + - entity_type: "link" + rel: "self" + href: "https://example.com/skg-if/api/venues/venue-5-sd" dates: # http://api.crossref.org/works/10.1038/sdata.2016.18 publication: - "2016-03-15" @@ -173,19 +193,28 @@ paths: - "2023-01-04" related_products: cites: - - "614a6575-5d6c-416c-a8e1-f49a5d589bf8" - + - local_identifier: product-10 + entity_type: "product" + _links: + - entity_type: "link" + rel: "self" + href: "https://example.com/skg-if/api/products/product-10" + 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/my-skg-acronym/"} + {"@base" : "https://w3id.org/skg-if/sandbox/acme/"} ] "@graph" : - - local_identifier: http://example.com/skg-if/api/products/prd-c66c6-38be-4d5f-85db-d44c9f869555 + - local_identifier: product-2-ogd entity_type: product + _links: + - entity_type: "link" + rel: "self" + href: "https://example.com/skg-if/api/products/product-2-ogd" product_type: research data titles : "en": ["OpenAIRE Graph dataset - new collected projects"] @@ -299,14 +328,16 @@ paths: - $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/my-skg-acronym/"}] + - ["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/Meta' "@graph": type: array items: - $ref: '#/components/schemas/Product' + anyOf: + - $ref: '#/components/schemas/Product' + - $ref: '#/components/schemas/LocalIdentifierRef' required: [ "@context", "meta", "@graph" ] examples: JournalArticleListEx01: @@ -315,7 +346,7 @@ paths: "@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/my-skg-acronym/" + - "@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 @@ -327,19 +358,27 @@ paths: entity_type: search_result total_items: 54231 "@graph": - - local_identifier: http://example.com/skg-if/api/products/prd-c66c6-38be-4d5f-85db-d44c9f869333 + - local_identifier: product-500 entity_type: product product_type: literature - - local_identifier: http://example.com/skg-if/api/products/prd-c66c6-38be-4d5f-85db-d44c9f869999 + _links: + - entity_type: "link" + rel: "self" + href: "https://example.com/skg-if/api/products/product-500" + - local_identifier: prd-c66c6-38be-4d5f-85db-d44c9f869999 entity_type: product product_type: research data + _links: + - entity_type: "link" + rel: "self" + href: "https://example.com/skg-if/api/products/product-501" 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/my-skg-acronym/" + - "@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 @@ -351,12 +390,20 @@ paths: entity_type: search_result total_items: 13202 "@graph": - - local_identifier: http://example.com/skg-if/api/products/prd-c66c6-38be-4d5f-85db-d44c9f869888 + - local_identifier: product-1000-ds entity_type: product product_type: research data - - local_identifier: http://example.com/skg-if/api/products/prd-c66c6-38be-4d5f-85db-d44c9f869881 + _links: + - entity_type: "link" + rel: "self" + href: "https://example.com/skg-if/api/products/product-1000-ds" + - local_identifier: product-1001-ds entity_type: product product_type: research data + _links: + - entity_type: "link" + rel: "self" + href: "https://example.com/skg-if/api/products/product-1001-ds" '422': description: Not implemented or invalid filter error. Conform to format [RFC7807](https://datatracker.ietf.org/doc/html/rfc7807) content: @@ -372,7 +419,7 @@ paths: 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/{short_local_identifier}': + '/persons/{local_identifier}': get: tags: - Person @@ -381,7 +428,7 @@ paths: 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/shortLocalIdPathParam' + - $ref : '#/components/parameters/localIdPathParam' responses: '200': description: Success @@ -401,7 +448,7 @@ paths: - $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/my-skg-acronym/"}] + - ["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": type: array minItems: 1 @@ -418,8 +465,12 @@ paths: {"@base" : "http://example.com/"} ] "@graph" : - - local_identifier: http://example.com/skg-if/api/persons/pers-c66c6-38be-4d5f-85db-d44c9f869333 + - local_identifier: person-1-jc entity_type: "person" + _links: + - entity_type: "link" + rel: "self" + href: "https://example.com/skg-if/api/persons/person-1-jc" identifiers: - scheme: orcid value: 0000-0002-1825-0097 @@ -435,9 +486,14 @@ paths: {"@base" : "http://example.com/"} ] "@graph" : - - local_identifier: http://example.com/skg-if/api/persons/otf_126848135_prod-1-pers-1 + - local_identifier: person-2-jd entity_type: "person" name: "John Doe" + _links: + - entity_type: "link" + rel: "self" + href: "https://example.com/skg-if/api/persons/person-2-jd" + '404': description: | Error if entity does not exists @@ -512,14 +568,16 @@ paths: - $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/my-skg-acronym/"}] + - ["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/Meta' "@graph": type: array items: - $ref: '#/components/schemas/Person' + anyOf: + - $ref: '#/components/schemas/Person' + - $ref: '#/components/schemas/LocalIdentifierRef' required: [ "@context", "meta", "@graph" ] examples: PersonEx01: @@ -528,7 +586,7 @@ paths: "@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/my-skg-acronym/" + - "@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 @@ -540,16 +598,24 @@ paths: entity_type: search_result total_items: 4 "@graph": - - local_identifier: http://example.com/skg-if/api/persons/pers-c66c6-38be-4d5f-85db-d44c9f869333 + - local_identifier: person-1-jc entity_type: "person" + _links: + - entity_type: "link" + rel: "self" + href: "https://example.com/skg-if/api/persons/person-1-jc" identifiers: - scheme: orcid value: 0000-0002-1825-0097 given_name: "Josiah" family_name: "Carberry" name: "Josiah Carberry" - - local_identifier: http://example.com/skg-if/api/persons/pers-c66c6-38be-4d5f-85db-d44c9f869888 + - local_identifier: person-2-gc entity_type: "person" + _links: + - entity_type: "link" + rel: "self" + href: "https://example.com/skg-if/api/persons/person-2-gc" given_name: "Gerard" family_name: "Carberry" name: "Gerard Carberry" @@ -561,7 +627,7 @@ paths: operationId: getPersonById parameters: local_identifier: $response.body#/@graph/local_identifier - '/organisations/{short_local_identifier}': + '/organisations/{local_identifier}': get: tags: - Organisation @@ -570,7 +636,7 @@ paths: 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/shortLocalIdPathParam' + - $ref : '#/components/parameters/localIdPathParam' responses: '200': description: Success @@ -591,7 +657,7 @@ paths: - $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/my-skg-acronym/"}] + - ["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": type: array minItems: 1 @@ -605,10 +671,14 @@ paths: "@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/my-skg-acronym/" + - "@base" : "https://w3id.org/skg-if/sandbox/acme/" "@graph": - - local_identifier: http://example.com/skg-if/api/organisations/otf_session12324_org_1124 + - local_identifier: organisation-2-bu entity_type: 'organisation' + _links: + - entity_type: "link" + rel: "self" + href: "https://example.com/skg-if/api/persons/organisation-2-bu" identifiers: - scheme: ror value: https://ror.org/05gq02987 @@ -623,10 +693,14 @@ paths: "@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/my-skg-acronym/" + - "@base" : "https://w3id.org/skg-if/sandbox/acme/" "@graph": - - local_identifier: http://example.com/skg-if/api/organisations/otf_session12325_org_1125 + - local_identifier: organisation-3-jcbl entity_type: 'organisation' + _links: + - entity_type: "link" + rel: "self" + href: "https://example.com/skg-if/api/organisations/organisation-3-jcbl" identifiers: - scheme: ror value: https://ror.org/05gq02987 @@ -637,16 +711,20 @@ paths: country: US types: - archive - OrgLabScienceNoId: + 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/my-skg-acronym/" + - "@base" : "https://w3id.org/skg-if/sandbox/acme/" "@graph": - - local_identifier: http://example.com/skg-if/api/organisations/otf_session12325_org_1126 + - local_identifier: organisation-5-lsa entity_type: 'organisation' + _links: + - entity_type: "link" + rel: "self" + href: "https://example.com/skg-if/api/organisations/organisation-5-lsa" name: Lab of science, unknown University, Antarctica OrgEuropeanCommission: summary: "European Commission Funder" @@ -654,10 +732,14 @@ paths: "@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/my-skg-acronym/" + - "@base" : "https://w3id.org/skg-if/sandbox/acme/" "@graph": - - local_identifier: http://example.com/skg-if/api/organisations/otf_session12324_org_1127 + - local_identifier: organisation-6-eu entity_type: 'organisation' + _links: + - entity_type: "link" + rel: "self" + href: "https://example.com/skg-if/api/perorganisationssons/organisation-6-eu" identifiers: - scheme: ror value: https://ror.org/00k4n6c32 @@ -735,16 +817,18 @@ paths: - $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/my-skg-acronym/"}] + - ["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/Meta' "@graph": type: array items: - $ref: '#/components/schemas/Organisation' + anyOf: + - $ref: '#/components/schemas/Organisation' + - $ref: '#/components/schemas/LocalIdentifierRef' required: [ "@context", "meta", "@graph" ] - '/grants/{short_local_identifier}': + '/grants/{local_identifier}': get: tags: - Grant @@ -753,7 +837,7 @@ paths: 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/shortLocalIdPathParam' + - $ref : '#/components/parameters/localIdPathParam' responses: '200': description: Success @@ -774,13 +858,15 @@ paths: - $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/my-skg-acronym/"}] + - ["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": type: array minItems: 1 maxItems: 1 items: - $ref: "#/components/schemas/Grant" + anyOf: + - $ref: "#/components/schemas/Grant" + - $ref: '#/components/schemas/LocalIdentifierRef' examples: GrantEx01: summary: GraspOS grant @@ -788,11 +874,15 @@ paths: "@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/my-skg-acronym/"} + {"@base" : "https://w3id.org/skg-if/sandbox/acme/"} ] "@graph" : - - local_identifier: http://example.com/skg-if/api/grants/grant-c66c6-38be-4d5f-85db-d44c9f869333 + - local_identifier: grant-1-go entity_type: "grant" + _links: + - entity_type: "link" + rel: "self" + href: "https://example.com/skg-if/api/organisations/grant-1-go" identifiers: - scheme: "doi" value: "https://doi.org/10.3030/101095129" @@ -804,8 +894,12 @@ paths: } acronym: "GraspOS" funding_agency: - local_identifier: http://example.com/skg-if/api/grants/otf___1730027051396___org-1 + local_identifier: organisation-2-bu entity_type: "organisation" + _links: + - entity_type: "link" + rel: "self" + href: "https://example.com/skg-if/api/organisations/organisation-2-bu" identifiers: - scheme: "ror" value: "https://ror.org/05gq02987" @@ -821,8 +915,12 @@ paths: end: "2025-12-31T23:59:59Z" website: "https://graspos.eu" beneficiaries: - - local_identifier: http://example.com/skg-if/api/organisations/otf___1730027051396___org-2 + - local_identifier: organisation-2-bu entity_type: "organisation" + _links: + - entity_type: "link" + rel: "self" + href: "https://example.com/skg-if/api/organisations/organisation-2-bu" identifiers: - scheme: "ror" value: "https://ror.org/05gq02987" @@ -832,8 +930,12 @@ paths: website: "https://www.brown.edu/" contributions: - by: - local_identifier: http://example.com/skg-if/api/persons/otf___1730027051396___pers-1 + local_identifier: person-1-jc entity_type: "person" + _links: + - entity_type: "link" + rel: "self" + href: "https://example.com/skg-if/api/persons/person-1-jc" identifiers: - scheme: "orcid" value: "0000-0002-1825-0097" @@ -841,8 +943,12 @@ paths: family_name: "Carberry" name: "Josiah Carberro" declared_affiliations: - - local_identifier": "otf___1730027051396___org-2" + - local_identifier": "affiliation-organisation-2" entity_type": "organisation" + _links: + - entity_type: "link" + rel: "self" + href: "https://example.com/skg-if/api/organisations/affiliation-organisation-2" identifiers: - scheme: "ror" value: "https://ror.org/05gq02987" @@ -958,16 +1064,18 @@ paths: - $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/my-skg-acronym/"}] + - ["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/Meta' "@graph": type: array items: - $ref: '#/components/schemas/Grant' + anyOf: + - $ref: '#/components/schemas/Grant' + - $ref: '#/components/schemas/LocalIdentifierRef' required: [ "@context", "meta", "@graph" ] - '/venues/{short_local_identifier}': + '/venues/{local_identifier}': get: tags: - Venue @@ -976,7 +1084,7 @@ paths: 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/shortLocalIdPathParam' + - $ref : '#/components/parameters/localIdPathParam' responses: '200': description: Success @@ -997,7 +1105,7 @@ paths: - $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/my-skg-acronym/"}] + - ["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": type: array minItems: 1 @@ -1011,11 +1119,15 @@ paths: "@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/my-skg-acronym/"} + {"@base" : "https://w3id.org/skg-if/sandbox/acme/"} ] "@graph" : - - local_identifier: http://example.com/skg-if/api/venues/venue-c66c6-38be-4d5f-85db-d44c9f869333 + - local_identifier: venue-1-jp entity_type: "venue" + _links: + - entity_type: "link" + rel: "self" + href: "https://example.com/skg-if/api/venues/venue-1-jp" identifiers: - scheme: issn value: 0264-3561 @@ -1084,16 +1196,18 @@ paths: - $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/my-skg-acronym/"}] + - ["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/Meta' "@graph": type: array items: - $ref: '#/components/schemas/Venue' + anyOf: + - $ref: '#/components/schemas/Venue' + - $ref: '#/components/schemas/LocalIdentifierRef' required: [ "@context", "meta", "@graph" ] - '/topics/{short_local_identifier}': + '/topics/{local_identifier}': get: tags: - Topic @@ -1102,7 +1216,7 @@ paths: 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/shortLocalIdPathParam' + - $ref : '#/components/parameters/localIdPathParam' responses: '200': description: Success @@ -1123,13 +1237,15 @@ paths: - $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/my-skg-acronym/"}] + - ["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": type: array minItems: 1 maxItems: 1 items: - $ref: "#/components/schemas/Topic" + anyOf: + - $ref: "#/components/schemas/Topic" + - $ref: '#/components/schemas/LocalIdentifierRef' examples: TopicEx01: summary: Computer Science topic @@ -1137,11 +1253,15 @@ paths: "@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/my-skg-acronym/"} + {"@base" : "https://w3id.org/skg-if/sandbox/acme/"} ] "@graph" : - - local_identifier: http://example.com/skg-if/api/topics/topic-c66c6-38be-4d5f-85db-d44c9f869333 + - local_identifier: topic-1-cs entity_type: "topic" + _links: + - entity_type: "link" + rel: "self" + href: "https://example.com/skg-if/api/topics/topic-1-cs" identifiers: - scheme: wikidata value: https://www.wikidata.org/wiki/Q21198 @@ -1221,16 +1341,18 @@ paths: - $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/my-skg-acronym/"}] + - ["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/Meta' "@graph": type: array items: - $ref: '#/components/schemas/Topic' + anyOf: + - $ref: '#/components/schemas/Topic' + - $ref: '#/components/schemas/LocalIdentifierRef' required: [ "@context", "meta", "@graph" ] - '/datasources/{short_local_identifier}': + '/datasources/{local_identifier}': get: tags: - Data Source @@ -1239,7 +1361,7 @@ paths: 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/shortLocalIdPathParam' + - $ref : '#/components/parameters/localIdPathParam' responses: '200': description: Success @@ -1260,13 +1382,15 @@ paths: - $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/my-skg-acronym/"}] + - ["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": type: array minItems: 1 maxItems: 1 items: - $ref: "#/components/schemas/DataSource" + anyOf: + - $ref: "#/components/schemas/DataSource" + - $ref: '#/components/schemas/LocalIdentifierRef' examples: DatasourceEx01: summary: Oxford University Research Archive datasource @@ -1274,11 +1398,15 @@ paths: "@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/my-skg-acronym/"} + {"@base" : "https://w3id.org/skg-if/sandbox/acme/"} ] "@graph" : - - local_identifier: http://example.com/skg-if/api/datasources/datasrc-c66c6-38be-4d5f-85db-d44c9f869333 + - local_identifier: datasource-1-oura entity_type: "datasource" + _links: + - entity_type: "link" + rel: "self" + href: "https://example.com/skg-if/api/datasources/datasource-1-oura" identifiers: - scheme: doi value: 10.25504/FAIRsharing.rkwr6y @@ -1349,14 +1477,16 @@ paths: - $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/my-skg-acronym/"}] + - ["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/Meta' "@graph": type: array items: - $ref: '#/components/schemas/DataSource' + anyOf: + - $ref: '#/components/schemas/DataSource' + - $ref: '#/components/schemas/LocalIdentifierRef' required: [ "@context", "meta", "@graph" ] components: securitySchemes: @@ -1376,13 +1506,12 @@ components: type: http scheme: basic parameters: - shortLocalIdPathParam: - name: short_local_identifier + localIdPathParam: + name: local_identifier in: path description: | - entity id. URL suffix used in OpenAPI get by id operations. \ - `https://[your-server-root-skg-if-url]/[products|persons|organisations|datasources|venues|topics]/{short_local_identifier}` \ - example `http://example.com/skg-if/api/products/c66c6-38be-4d5f-85db-d44c9` + entity id. URL. \ + example `http://skgbase.example.com/prod-c66c6-38be-4d5f-85db-d44c9` required: true schema: type: string @@ -1410,6 +1539,52 @@ components: schema: type: integer schemas: + LocalIdentifierRef: + type: string + title: 'local_identifier' + description: "a local_identifier.\ + You can pass a local_identifier string and not a full object entity structure, but it is not recommnended.\ + When you pass a local_identifier string as reference for a linked entity, you cannot pass the `_links` field. The `_links` allows entity API linking for the client API.\ + We recommend to pass one of the object structure entities compatible with this property, and also fill its properties and `_links`.\ + One additional benefit of object structure is to limit the client API calls to resolve entities. This is also very useful for client using your API for autocomplete features.\ + 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. + " + 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 + 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 + x-faker: + helpers.arrayElement: [["self"]] + href: + type: string + 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 + description: "Media type. Leave empty for `rel:self`" + x-faker: + helpers.arrayElement: [["text/xml"]] Product: type: object title: 'Product' @@ -1480,7 +1655,9 @@ components: required: [ "term" ] properties: term: - $ref: '#/components/schemas/Topic' + anyOf: + - $ref: '#/components/schemas/Topic' + - $ref: '#/components/schemas/LocalIdentifierRef' # TODO provenance ? contributions: type: array @@ -1496,18 +1673,25 @@ components: type: array description: List of relevant Organisation associated with the `product`, in case the individual affiliations of a `person` are not available. items: - $ref: '#/components/schemas/Organisation' + anyOf: + - $ref: '#/components/schemas/Organisation' + - $ref: '#/components/schemas/LocalIdentifierRef' funding: type: array description: List of `grant` associated with the `product` items: - $ref: '#/components/schemas/GrantLite' + anyOf: + - $ref: '#/components/schemas/GrantLite' + - $ref: '#/components/schemas/LocalIdentifierRef' related_products: - $ref: '#/components/schemas/ProductRelated' - + $ref: '#/components/schemas/ProductsRelated' examples: - - local_identifier: http://example.com/skg-if/api/products/xxx + - local_identifier: product-1-fgp entity_type: product + _links: + - entity_type: "link" + rel: "self" + href: "https://example.com/skg-if/api/products/product-1-fgp" product_type: literature titles : "en": ["The FAIR Guiding Principles for scientific data management and stewardship"] @@ -1530,13 +1714,21 @@ components: identifiers: - value: "0000-0001-6960-357X" scheme: "orcid" - local_identifier: http://example.com/skg-if/api/persons/614a6575-5d6c-416c-a8e1-f49a5d589bf8 + local_identifier: person-5-mw entity_type: "person" + _links: + - entity_type: "link" + rel: "self" + href: "https://example.com/skg-if/api/persons/person-5-mw" declared_affiliations: - name: "Center for Plant Biotechnology and Genomics, Universidad Politécnica de Madrid, Madrid, 28223, Spain" - local_identifier: http://example.com/skg-if/api/persons/32bc66c6-38be-4d5f-85db-d44c9f86921f + local_identifier: affiliation-organisation-1 entity_type: "organisation" country: "ES" + _links: + - entity_type: "link" + rel: "self" + href: "https://example.com/skg-if/api/organisations/affiliation-organisation-1" manifestations: - type: labels: @@ -1545,8 +1737,12 @@ components: class: http://www.example.com/types/onto/localtypemethodology biblio: hosting_data_source: - local_identifier: http://example.com/skg-if/api/datasources/6f368a3a-b1cf-498f-b2de-27135d1e0075 + local_identifier: datasource-1-aa entity_type: datasource + _links: + - entity_type: "link" + rel: "self" + href: "https://example.com/skg-if/api/datasources/datasource-1-aa" name: "An Archive" in: name: "Scientific Data" @@ -1554,8 +1750,12 @@ components: identifiers: - "value": "2052-4463" "scheme": "issn" - local_identifier: http://example.com/skg-if/api/datasources/51f46bc1-00f8-42dd-8221-ac4deb52fb25 + local_identifier: venue-5-sd entity_type: "venue" + _links: + - entity_type: "link" + rel: "self" + href: "https://example.com/skg-if/api/venues/venue-5-sd" dates: # http://api.crossref.org/works/10.1038/sdata.2016.18 publication: - "2016-03-15" @@ -1565,8 +1765,12 @@ components: deposit: - "2023-01-04" funding: - - local_identifier: http://example.com/skg-if/api/grants/614a6575-5d6c-416c-a8e1-f49a5d58999 + - local_identifier: grant-7-zz entity_type: "grant" + _links: + - entity_type: "link" + rel: "self" + href: "https://example.com/skg-if/api/grants/grant-7-zz" titles: - en: "EU grant ZZ" related_products: { @@ -1586,6 +1790,7 @@ components: - $ref: '#/components/schemas/PersonLite' - $ref: '#/components/schemas/Organisation' - $ref: '#/components/schemas/Agent' + - $ref: '#/components/schemas/LocalIdentifierRef' discriminator: propertyName: entity_type mapping: @@ -1596,7 +1801,9 @@ components: description: List of `organisation` that reflect the declared affiliations of a `person` contributing to a `product`. type: array items: - $ref: '#/components/schemas/Organisation' + anyOf: + - $ref: '#/components/schemas/Organisation' + - $ref: '#/components/schemas/LocalIdentifierRef' rank: type: integer x-faker: @@ -1819,43 +2026,64 @@ components: x-faker: fake : ['{{datatype.number(5)}}'] in: - $ref: '#/components/schemas/VenueLite' + anyOf: + - $ref: '#/components/schemas/VenueLite' + - $ref: '#/components/schemas/LocalIdentifierRef' hosting_data_source : - $ref: '#/components/schemas/DataSourceLite' - ProductRelated: + anyOf: + - $ref: '#/components/schemas/DataSourceLite' + - $ref: '#/components/schemas/LocalIdentifierRef' + ProductsRelatedItem: type: object + title: 'Related Products Item' + 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 + title: 'Related Products' description : A dictionary of objects representing related `product`, where the semantics of such relationships is specified as a key. properties : cites: type: array items: - local_identifier: - type: string - description: "`product` local_identifier" + anyOf : + - $ref: '#/components/schemas/ProductsRelatedItem' + - $ref: '#/components/schemas/LocalIdentifierRef' is_supplemented_by: type: array items: - local_identifier: - type: string - description: "`product` local_identifier" + anyOf : + - $ref: '#/components/schemas/ProductsRelatedItem' + - $ref: '#/components/schemas/LocalIdentifierRef' is_documented_by: type: array items: - local_identifier: - type: string - description: "`product` local_identifier" + anyOf: + - $ref: '#/components/schemas/ProductsRelatedItem' + - $ref: '#/components/schemas/LocalIdentifierRef' is_new_version_of: type: array items: - local_identifier: - type: string - description: "`product` local_identifier" + anyOf : + - $ref: '#/components/schemas/ProductsRelatedItem' + - $ref: '#/components/schemas/LocalIdentifierRef' is_part_of: type: array items: - local_identifier: - type: string - description: "`product` local_identifier" + anyOf : + - $ref: '#/components/schemas/ProductsRelatedItem' + - $ref: '#/components/schemas/LocalIdentifierRef' Agent: type: object title: "Agent" @@ -1982,8 +2210,12 @@ components: - research - unspecified examples: - - local_identifier: 'otf_session12324_org_1124' + - local_identifier: 'organisation-2-bu' entity_type: 'organisation' + _links: + - entity_type: "link" + rel: "self" + href: "https://example.com/skg-if/api/organisations/organisation-2-bu" identifiers: - "scheme": ror "value": https://ror.org/05gq02987 @@ -1992,8 +2224,12 @@ components: country: US types: - education - - local_identifier: http://example.com/skg-if/api/organisations/otf_session12325_org_1125 + - local_identifier: organisation-3-jcbl entity_type: 'organisation' + _links: + - entity_type: "link" + rel: "self" + href: "https://example.com/skg-if/api/organisations/organisation-3-jcbl" identifiers: - scheme: ror value: https://ror.org/05gq02987 @@ -2004,11 +2240,19 @@ components: country: US types: - archive - - local_identifier: http://example.com/skg-if/api/organisations/otf_session12325_org_1126 + - local_identifier: organisation-5-lsa entity_type: 'organisation' name: Lab of science, unknown University, Antarctica - - local_identifier: http://example.com/skg-if/api/organisations/otf_session12324_org_1127 + _links: + - entity_type: "link" + rel: "self" + href: "https://example.com/skg-if/api/organisations/organisation-5-lsa" + - local_identifier: organisation-6-eu entity_type: 'organisation' + _links: + - entity_type: "link" + rel: "self" + href: "https://example.com/skg-if/api/organisations/organisation-6-eu" identifiers: - scheme: ror value: https://ror.org/00k4n6c32 @@ -2052,8 +2296,12 @@ components: type: string description: end date. Format [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) compliant string ( "2024-10-01", "2024-10", "2024" ).' examples: - - local_identifier: http://example.com/skg-if/api/persons/otf_session12324_person_1124 + - local_identifier: person-1-jc entity_type: 'person' + _links: + - entity_type: "link" + rel: "self" + href: "https://example.com/skg-if/api/persons/person-1-jc" identifiers: - scheme: orcid value: 0000-0002-1825-0097 @@ -2066,7 +2314,11 @@ components: start: "2010-08-24" end: "2020-08-24" affiliation: - local_identifier: http://example.com/skg-if/api/organisatios/otf_session12324_org_1124 + local_identifier: organisation-2-bu + _links: + - entity_type: "link" + rel: "self" + href: "https://example.com/skg-if/api/organisations/organisation-2-bu" entity_type: 'organisation' identifiers: - scheme: ror @@ -2127,8 +2379,12 @@ components: examples : - Josiah Carberro examples: - - local_identifier: http://example.com/skg-if/api/persons/otf_session12324_person_1124 + - local_identifier: person-1-jc entity_type: 'person' + _links: + - entity_type: "link" + rel: "self" + href: "https://example.com/skg-if/api/persons/person-1-jc" identifiers: - scheme: orcid value: 0000-0002-1825-0097 @@ -2234,12 +2490,16 @@ components: description: "List of `organisation` funded by the `grant`" type: array items: - $ref: '#/components/schemas/Organisation' + anyOf: + - $ref: '#/components/schemas/Organisation' + - $ref: '#/components/schemas/LocalIdentifierRef' contributions: type: array description: List of objects describing a `person` or `organisation`, its role, contribution, rank, when working on the `grant`. items: - $ref: '#/components/schemas/GrantContribution' + anyOf: + - $ref: '#/components/schemas/GrantContribution' + - $ref: '#/components/schemas/LocalIdentifierRef' GrantContribution: type: object title: 'GrantContribution' @@ -2250,6 +2510,7 @@ components: oneOf: - $ref: '#/components/schemas/PersonLite' - $ref: '#/components/schemas/Organisation' + - $ref: '#/components/schemas/LocalIdentifierRef' discriminator: propertyName: entity_type mapping: @@ -2259,7 +2520,9 @@ components: description: List of `organisation` that reflect the declared affiliations of a `person` contributing to a `grant`. type: array items: - $ref: '#/components/schemas/Organisation' + anyOf: + - $ref: '#/components/schemas/Organisation' + - $ref: '#/components/schemas/LocalIdentifierRef' roles: description: | The roles that a `person` or `organisation` had in a `grant`.\ @@ -2507,21 +2770,26 @@ components: type: string description: | Unique local identifier as URL. \ - `https://[your-server-root-skg-if-url]/[products|persons|organisations|datasources|venues|topics]/{short_local_identifier}` \ - example `http://example.com/skg-if/api/products/c66c6-38be-4d5f-85db-d44c9` \ + `https://[your-@base-url]/{identifier string}` \ + example `https://w3id.org/skg-if/sandbox/acme/prod-c66c6-38be-4d5f-85db-d44c9` \ + 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______`. + 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 URL `//`. - x-faker: + For instance, a possible example of such a local identifier would be : `otf___1730027051396___person-1`. + An on-the-fly may not resolve with URL `//`. + You indicate to the client of your API that this local identifier cannot be resolved outside the session context. + x-faker:. fake : ['{{random.uuid}}'] examples: - - http://example.com/skg-if/api/products/c66c6-38be-4d5f-85db-d44c9 - - http://example.com/skg-if/api/products/otf___1730027051396___prod-1 - - http://example.com/skg-if/api/persons/c7777-38be-4d5f-85db-d7777 - - http://example.com/skg-if/api/persons/otf___1730027051396___person-1 + - http://w3id.org/skg-if/sandbox/acme/prod-c66c6-38be-4d5f-85db-d44c9 + - http://w3id.org/skg-if/sandbox/acme/otf___1730027051396___prod-1 + - http://w3id.org/skg-if/sandbox/acme/pers-c7777-38be-4d5f-85db-d7777 + - http://w3id.org/skg-if/sandbox/acme/otf___1730027051396___person-1 identifiers: type: array items: @@ -2535,13 +2803,17 @@ components: type: string entity_type: type: string + _links: + type: array + items: + $ref: '#/components/schemas/Link' Meta: type: object required: [ "local_identifier", "entity_type" ] properties: local_identifier: type: string - description: search result page id + 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 @@ -2565,7 +2837,7 @@ components: properties: local_identifier: type: string - description: search result id as URL + 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 @@ -2592,7 +2864,7 @@ components: properties: local_identifier: type: string - description: search result page id as URL + 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 @@ -2645,22 +2917,27 @@ components: 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/my-skg-acronym" }`' + description : 'Additional context mappings ex: `{ "@base":"https://w3id.org/skg-if/sandbox/acme" }`' properties: "@base": type: string description : | - Default base URL specific to the implementer.\ - common format : `https://w3id.org/skg-if/sandbox/{my-skg-acronym}` \ - example : `https://w3id.org/skg-if/sandbox/openaire/` + Default root URL of the JSON-LD context. \ + To define your `@base`, please refer to the [SKG-IF OpenAPI Implementer documentation](https://docs.google.com/document/d/1t7b7h28UTtM56Sda4NGJIp0hnQfGbcVVGn12fny9wfI/edit?usp=sharing) \ + 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://w3id.org/skg-if/sandbox/openaire/" - - "https://w3id.org/skg-if/sandbox/cessda/" - - "https://w3id.org/skg-if/sandbox/foobar/" + - "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-if/{{random.alpha(3)}}'] + fake : ['http://www.example.com/skg/{{random.alpha(3)}}'] From 39e7af0827c2d7d01497c93aa46325dfbafdecc6 Mon Sep 17 00:00:00 2001 From: rduyme Date: Sat, 21 Mar 2026 17:34:55 +0100 Subject: [PATCH 2/7] description update --- openapi/ver/current/skg-if-openapi.yaml | 112 ++++++++++++------------ 1 file changed, 56 insertions(+), 56 deletions(-) diff --git a/openapi/ver/current/skg-if-openapi.yaml b/openapi/ver/current/skg-if-openapi.yaml index 9a3dbd9..163a2c0 100644 --- a/openapi/ver/current/skg-if-openapi.yaml +++ b/openapi/ver/current/skg-if-openapi.yaml @@ -335,7 +335,7 @@ paths: "@graph": type: array items: - anyOf: + oneOf: - $ref: '#/components/schemas/Product' - $ref: '#/components/schemas/LocalIdentifierRef' required: [ "@context", "meta", "@graph" ] @@ -575,7 +575,7 @@ paths: "@graph": type: array items: - anyOf: + oneOf: - $ref: '#/components/schemas/Person' - $ref: '#/components/schemas/LocalIdentifierRef' required: [ "@context", "meta", "@graph" ] @@ -824,7 +824,7 @@ paths: "@graph": type: array items: - anyOf: + oneOf: - $ref: '#/components/schemas/Organisation' - $ref: '#/components/schemas/LocalIdentifierRef' required: [ "@context", "meta", "@graph" ] @@ -864,9 +864,7 @@ paths: minItems: 1 maxItems: 1 items: - anyOf: - - $ref: "#/components/schemas/Grant" - - $ref: '#/components/schemas/LocalIdentifierRef' + $ref: "#/components/schemas/Grant" examples: GrantEx01: summary: GraspOS grant @@ -1071,7 +1069,7 @@ paths: "@graph": type: array items: - anyOf: + oneOf: - $ref: '#/components/schemas/Grant' - $ref: '#/components/schemas/LocalIdentifierRef' required: [ "@context", "meta", "@graph" ] @@ -1203,7 +1201,7 @@ paths: "@graph": type: array items: - anyOf: + oneOf: - $ref: '#/components/schemas/Venue' - $ref: '#/components/schemas/LocalIdentifierRef' required: [ "@context", "meta", "@graph" ] @@ -1243,9 +1241,7 @@ paths: minItems: 1 maxItems: 1 items: - anyOf: - - $ref: "#/components/schemas/Topic" - - $ref: '#/components/schemas/LocalIdentifierRef' + $ref: "#/components/schemas/Topic" examples: TopicEx01: summary: Computer Science topic @@ -1348,7 +1344,7 @@ paths: "@graph": type: array items: - anyOf: + oneOf: - $ref: '#/components/schemas/Topic' - $ref: '#/components/schemas/LocalIdentifierRef' required: [ "@context", "meta", "@graph" ] @@ -1388,9 +1384,7 @@ paths: minItems: 1 maxItems: 1 items: - anyOf: - - $ref: "#/components/schemas/DataSource" - - $ref: '#/components/schemas/LocalIdentifierRef' + $ref: "#/components/schemas/DataSource" examples: DatasourceEx01: summary: Oxford University Research Archive datasource @@ -1484,7 +1478,7 @@ paths: "@graph": type: array items: - anyOf: + oneOf: - $ref: '#/components/schemas/DataSource' - $ref: '#/components/schemas/LocalIdentifierRef' required: [ "@context", "meta", "@graph" ] @@ -1541,23 +1535,29 @@ components: schemas: LocalIdentifierRef: type: string - title: 'local_identifier' - description: "a local_identifier.\ - You can pass a local_identifier string and not a full object entity structure, but it is not recommnended.\ - When you pass a local_identifier string as reference for a linked entity, you cannot pass the `_links` field. The `_links` allows entity API linking for the client API.\ - We recommend to pass one of the object structure entities compatible with this property, and also fill its properties and `_links`.\ - One additional benefit of object structure is to limit the client API calls to resolve entities. This is also very useful for client using your API for autocomplete features.\ - 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. - " + 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 and `_links`.\ + 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", "_links":[{"entity_type:link", "rel":"self", "href":"http://example.com/skg-if/api/prodcuts/product-1"}], "title":"xxx", ... }\ ` + \ + 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.\ 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` - " + 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" @@ -1566,11 +1566,11 @@ components: 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. - " + 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 x-faker: helpers.arrayElement: [["self"]] @@ -1655,7 +1655,7 @@ components: required: [ "term" ] properties: term: - anyOf: + oneOf: - $ref: '#/components/schemas/Topic' - $ref: '#/components/schemas/LocalIdentifierRef' # TODO provenance ? @@ -1673,14 +1673,14 @@ components: type: array description: List of relevant Organisation associated with the `product`, in case the individual affiliations of a `person` are not available. items: - anyOf: + oneOf: - $ref: '#/components/schemas/Organisation' - $ref: '#/components/schemas/LocalIdentifierRef' funding: type: array description: List of `grant` associated with the `product` items: - anyOf: + oneOf: - $ref: '#/components/schemas/GrantLite' - $ref: '#/components/schemas/LocalIdentifierRef' related_products: @@ -1801,7 +1801,7 @@ components: description: List of `organisation` that reflect the declared affiliations of a `person` contributing to a `product`. type: array items: - anyOf: + oneOf: - $ref: '#/components/schemas/Organisation' - $ref: '#/components/schemas/LocalIdentifierRef' rank: @@ -2026,16 +2026,15 @@ components: x-faker: fake : ['{{datatype.number(5)}}'] in: - anyOf: + oneOf: - $ref: '#/components/schemas/VenueLite' - $ref: '#/components/schemas/LocalIdentifierRef' hosting_data_source : - anyOf: + oneOf: - $ref: '#/components/schemas/DataSourceLite' - $ref: '#/components/schemas/LocalIdentifierRef' ProductsRelatedItem: type: object - title: 'Related Products Item' description: "Reference to a `product` object" allOf: - $ref: "#/components/schemas/Entity" @@ -2051,37 +2050,36 @@ components: helpers.arrayElement: [["product"]] ProductsRelated: type: object - title: 'Related Products' description : A dictionary of objects representing related `product`, where the semantics of such relationships is specified as a key. properties : cites: type: array items: - anyOf : + oneOf : - $ref: '#/components/schemas/ProductsRelatedItem' - $ref: '#/components/schemas/LocalIdentifierRef' is_supplemented_by: type: array items: - anyOf : + oneOf : - $ref: '#/components/schemas/ProductsRelatedItem' - $ref: '#/components/schemas/LocalIdentifierRef' is_documented_by: type: array items: - anyOf: + oneOf: - $ref: '#/components/schemas/ProductsRelatedItem' - $ref: '#/components/schemas/LocalIdentifierRef' is_new_version_of: type: array items: - anyOf : + oneOf : - $ref: '#/components/schemas/ProductsRelatedItem' - $ref: '#/components/schemas/LocalIdentifierRef' is_part_of: type: array items: - anyOf : + oneOf : - $ref: '#/components/schemas/ProductsRelatedItem' - $ref: '#/components/schemas/LocalIdentifierRef' Agent: @@ -2490,14 +2488,14 @@ components: description: "List of `organisation` funded by the `grant`" type: array items: - anyOf: + oneOf: - $ref: '#/components/schemas/Organisation' - $ref: '#/components/schemas/LocalIdentifierRef' contributions: type: array description: List of objects describing a `person` or `organisation`, its role, contribution, rank, when working on the `grant`. items: - anyOf: + oneOf: - $ref: '#/components/schemas/GrantContribution' - $ref: '#/components/schemas/LocalIdentifierRef' GrantContribution: @@ -2520,7 +2518,7 @@ components: description: List of `organisation` that reflect the declared affiliations of a `person` contributing to a `grant`. type: array items: - anyOf: + oneOf: - $ref: '#/components/schemas/Organisation' - $ref: '#/components/schemas/LocalIdentifierRef' roles: @@ -2772,18 +2770,20 @@ components: Unique local identifier as URL. \ `https://[your-@base-url]/{identifier string}` \ example `https://w3id.org/skg-if/sandbox/acme/prod-c66c6-38be-4d5f-85db-d44c9` \ + 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 URL `//`. - You indicate to the client of your API that this local identifier cannot be resolved outside the session context. - x-faker:. + 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/prod-c66c6-38be-4d5f-85db-d44c9 From a6d71d7055150724e717fc5ea76f4a053c6e887d Mon Sep 17 00:00:00 2001 From: rduyme Date: Thu, 11 Jun 2026 22:10:27 +0200 Subject: [PATCH 3/7] openapi add links local id --- openapi/ver/1.0.0/context/skg-if-api.json | 23 +- .../current/sample_data/grants/grant_1.json | 12 +- .../organisations/org_brown_university.json | 4 +- .../products/journal_article_full.json | 50 +- openapi/ver/current/skg-if-openapi.yaml | 636 +++++++++++++----- 5 files changed, 552 insertions(+), 173 deletions(-) diff --git a/openapi/ver/1.0.0/context/skg-if-api.json b/openapi/ver/1.0.0/context/skg-if-api.json index e59988e..506793f 100644 --- a/openapi/ver/1.0.0/context/skg-if-api.json +++ b/openapi/ver/1.0.0/context/skg-if-api.json @@ -9,6 +9,9 @@ "search_result": { "@id": "as:Collection" }, + "single_entity": { + "@id": "as:Object" + }, "part_of": { "@id": "as:partOf" }, @@ -27,6 +30,24 @@ "prev_page": { "@id": "as:prev" }, - "meta": "@nest" + "meta": "@nest", + "api_items": { + "@id": "as:items", + "@container": "@set" + }, + "urls": { + "@id": "as:url", + "@container": "@set" + }, + "rel": { + "@id": "as:rel" + }, + "href": { + "@id": "as:href", + "@type": "@id" + }, + "media_type":{ + "@id": "as:mediaType" + } } } \ No newline at end of file diff --git a/openapi/ver/current/sample_data/grants/grant_1.json b/openapi/ver/current/sample_data/grants/grant_1.json index 73daf2a..0440bdc 100644 --- a/openapi/ver/current/sample_data/grants/grant_1.json +++ b/openapi/ver/current/sample_data/grants/grant_1.json @@ -3,12 +3,12 @@ "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/my-skg-acronym/" + "@base": "https://w3id.org/skg-if/sandbox/acme/" } ], "@graph": [ { - "local_identifier": "http://example.com/skg-if/api/grants/6f368a3a-b1cf-498f-b2de-27135d1e0011", + "local_identifier": "https://w3id.org/skg-if/sandbox/acme/grant-1", "identifiers": [ { "scheme": "doi", @@ -25,7 +25,7 @@ }, "acronym": "GraspOS", "funding_agency": { - "local_identifier": "http://example.com/skg-if/api/organisations/org-xxx", + "local_identifier": "https://w3id.org/skg-if/sandbox/acme/org-1", "entity_type": "organisation", "identifiers": [ { @@ -48,7 +48,7 @@ "website": "https://graspos.eu", "beneficiaries": [ { - "local_identifier": "http://example.com/skg-if/api/organisations/xxx", + "local_identifier": "https://w3id.org/skg-if/sandbox/acme/org-1", "entity_type": "organisation", "identifiers": [ { @@ -65,7 +65,7 @@ "contributions": [ { "by": { - "local_identifier": "http://example.com/skg-if/api/persons/xxx", + "local_identifier": "https://w3id.org/skg-if/sandbox/acme/pers-1", "entity_type": "person", "identifiers": [ { @@ -79,7 +79,7 @@ }, "declared_affiliations": [ { - "local_identifier": "http://example.com/skg-if/api/organisations/xxx", + "local_identifier": "https://w3id.org/skg-if/sandbox/acme/org-1", "entity_type": "organisation", "identifiers": [ { diff --git a/openapi/ver/current/sample_data/organisations/org_brown_university.json b/openapi/ver/current/sample_data/organisations/org_brown_university.json index d1bc04e..3479d1b 100644 --- a/openapi/ver/current/sample_data/organisations/org_brown_university.json +++ b/openapi/ver/current/sample_data/organisations/org_brown_university.json @@ -3,12 +3,12 @@ "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/my-skg-acronym/" + "@base": "https://w3id.org/skg-if/sandbox/acme/" } ], "@graph": [ { - "local_identifier": "http://example.com/skg-if/api/organisations/6f368a3a-b1cf-498f-b2de-222222222", + "local_identifier": "https://w3id.org/skg-if/sandbox/acme/org-1", "entity_type": "organisation", "identifiers": [ { diff --git a/openapi/ver/current/sample_data/products/journal_article_full.json b/openapi/ver/current/sample_data/products/journal_article_full.json index c70f63f..2f93561 100644 --- a/openapi/ver/current/sample_data/products/journal_article_full.json +++ b/openapi/ver/current/sample_data/products/journal_article_full.json @@ -3,12 +3,48 @@ "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/my-skg-acronym/" + "@base": "https://w3id.org/skg-if/sandbox/acme/" } ], + "meta": { + "local_identifier": "https://w3id.org/skg-if/sandbox/acme/prod-1", + "entity_type": "single_entity", + "api_items": [ + { + "local_identifier": "https://w3id.org/skg-if/sandbox/acme/prod-1", + "urls": [ + { + "entity_type": "link", + "rel": "self", + "href": "https://acme.com/skg-if/api/products/prod-1" + } + ] + }, + { + "local_identifier": "https://w3id.org/skg-if/sandbox/acme/pers-1", + "urls": [ + { + "entity_type": "link", + "rel": "self", + "href": "https://acme.com/skg-if/api/persons/pers-1" + } + ] + }, + { + "local_identifier": "https://w3id.org/skg-if/sandbox/acme/venue-1", + "urls": [ + { + "entity_type": "link", + "rel": "self", + "href": "https://acme.com/skg-if/api/venues/venue-1" + } + ] + } + ] + }, "@graph": [ { - "local_identifier": "http://example.com/skg-if/api/products/614a6575-5d6c-416c-a8e1-ddd456d132", + "local_identifier": "https://w3id.org/skg-if/sandbox/acme/prod-1", "entity_type": "product", "product_type": "literature", "titles": { @@ -48,13 +84,13 @@ "scheme": "orcid" } ], - "local_identifier": "http://example.com/skg-if/api/persons/614a6575-5d6c-416c-a8e1-f49a5d589bf8", + "local_identifier": "https://w3id.org/skg-if/sandbox/acme/pers-1", "entity_type": "person" }, "declared_affiliations": [ { "name": "Center for Plant Biotechnology and Genomics, Universidad Politécnica de Madrid, Madrid, 28223, Spain", - "local_identifier": "http://example.com/skg-if/api/organisations/32bc66c6-38be-4d5f-85db-d44c9f86921f", + "local_identifier": "https://w3id.org/skg-if/sandbox/acme/org-1", "entity_type": "organisation", "country": "ES" } @@ -72,7 +108,7 @@ }, "biblio": { "hosting_data_source": { - "local_identifier": "http://example.com/skg-if/api/datasources/6f368a3a-b1cf-498f-b2de-27135d1e0075", + "local_identifier": "https://w3id.org/skg-if/sandbox/acme/datasource-1", "entity_type": "datasource", "name": "An Archive" }, @@ -85,7 +121,7 @@ "scheme": "issn" } ], - "local_identifier": "http://example.com/skg-if/api/venues/51f46bc1-00f8-42dd-8221-ac4deb52fb25", + "local_identifier": "https://w3id.org/skg-if/sandbox/acme/venue-1", "entity_type": "venue" } }, @@ -105,7 +141,7 @@ ], "funding": [ { - "local_identifier": "http://example.com/skg-if/api/grants/614a6575-5d6c-416c-a8e1-f49a5d58999", + "local_identifier": "https://w3id.org/skg-if/sandbox/acme/grant-1", "entity_type": "grant", "titles": { "en": "The EU grant ZZ", diff --git a/openapi/ver/current/skg-if-openapi.yaml b/openapi/ver/current/skg-if-openapi.yaml index acfe2fa..65d674d 100644 --- a/openapi/ver/current/skg-if-openapi.yaml +++ b/openapi/ver/current/skg-if-openapi.yaml @@ -1,6 +1,6 @@ openapi: 3.1.0 info: - version: 1.0.0-alpha + version: 1.0.0 title: SKG-IF OpenAPI termsOfService: 'https://skg-if.github.io/interoperability-framework/' contact: @@ -16,7 +16,7 @@ info: Last version of the SKG-IF OpenAPI is available at : https://skg-if.github.io/api/ # Note for implementers : - - Please refer to [SKG-IF OpenAPI Implementer documentation](https://docs.google.com/document/d/1t7b7h28UTtM56Sda4NGJIp0hnQfGbcVVGn12fny9wfI/edit?usp=sharing) + - 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). @@ -64,7 +64,7 @@ servers: default: skg-if/api description: service provider skg-if api path paths: - '/products/{short_local_identifier}': + '/products/{local_identifier}': get: tags: - Product @@ -73,7 +73,7 @@ paths: 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/shortLocalIdPathParam' + - $ref : '#/components/parameters/localIdPathParam' responses: '200': description: | @@ -95,7 +95,10 @@ paths: - $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/my-skg-acronym/"}] + - ["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 @@ -109,11 +112,40 @@ paths: "@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/my-skg-acronym/"} + {"@base" : "https://w3id.org/skg-if/sandbox/acme/"} ] + "meta" : + local_identifier: product-1-fgp + entity_type: single_entity + api_items: + - local_identifier: product-1-fgp + urls: + - entity_type: "link" + rel: "self" + href: "https://example.com/skg-if/api/products/product-1-fgp" + - 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: http://example.com/skg-if/api/products/prd-c66c6-38be-4d5f-85db-d44c9f869333 - entity_type: product + - local_identifier: "product-1-fgp" + entity_type: "product" product_type: literature titles : "en": ["The FAIR Guiding Principles for scientific data management and stewardship"] @@ -137,11 +169,11 @@ paths: identifiers: - value: "0000-0001-6960-357X" scheme: "orcid" - local_identifier: http://example.com/skg-if/api/persons/otf___1730027051396___person-1 + 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: http://example.com/skg-if/api/otf___1730027051396___person-1-aff-1 + local_identifier: affiliation-organisation-1 entity_type: "organisation" country: "ES" manifestations: @@ -152,7 +184,7 @@ paths: class: http://www.example.com/types/onto/localtypemethodology biblio: hosting_data_source: - local_identifier: http://example.com/skg-if/api/arch-6f368a3a-b1cf-498f-b2de-27135d1e0075 + local_identifier: datasource-1-aa entity_type: datasource name: "An Archive" in: @@ -161,7 +193,7 @@ paths: identifiers: - "value": "2052-4463" "scheme": "issn" - local_identifier: http://example.com/skg-if/api/venues/journal-46bc1-00f8-42dd-8221-ac4deb52fb25 + local_identifier: venue-5-sd entity_type: "venue" dates: # http://api.crossref.org/works/10.1038/sdata.2016.18 publication: @@ -173,18 +205,28 @@ paths: - "2023-01-04" related_products: cites: - - "614a6575-5d6c-416c-a8e1-f49a5d589bf8" - + - 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/my-skg-acronym/"} + {"@base" : "https://w3id.org/skg-if/sandbox/acme/"} ] + "meta" : + local_identifier: product-2-ogd + entity_type: single_entity + api_items: + - local_identifier: product-2-ogd + urls: + - entity_type: "link" + rel: "self" + href: "https://example.com/skg-if/api/products/product-2-ogd" "@graph" : - - local_identifier: http://example.com/skg-if/api/products/prd-c66c6-38be-4d5f-85db-d44c9f869555 + - local_identifier: product-2-ogd entity_type: product product_type: research data titles : @@ -299,14 +341,16 @@ paths: - $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/my-skg-acronym/"}] + - ["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/Meta' + $ref: '#/components/schemas/MetaSearch' "@graph": type: array items: - $ref: '#/components/schemas/Product' + oneOf: + - $ref: '#/components/schemas/Product' + - $ref: '#/components/schemas/LocalIdentifierRef' required: [ "@context", "meta", "@graph" ] examples: JournalArticleListEx01: @@ -315,7 +359,7 @@ paths: "@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/my-skg-acronym/" + - "@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 @@ -326,11 +370,22 @@ paths: 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: http://example.com/skg-if/api/products/prd-c66c6-38be-4d5f-85db-d44c9f869333 + - local_identifier: product-500 entity_type: product - product_type: literature - - local_identifier: http://example.com/skg-if/api/products/prd-c66c6-38be-4d5f-85db-d44c9f869999 + product_type: literature + - local_identifier: product-501 entity_type: product product_type: research data DatasetListEx02: @@ -339,7 +394,7 @@ paths: "@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/my-skg-acronym/" + - "@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 @@ -350,11 +405,22 @@ paths: 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: http://example.com/skg-if/api/products/prd-c66c6-38be-4d5f-85db-d44c9f869888 + - local_identifier: product-1000-ds entity_type: product product_type: research data - - local_identifier: http://example.com/skg-if/api/products/prd-c66c6-38be-4d5f-85db-d44c9f869881 + - local_identifier: product-1001-ds entity_type: product product_type: research data '422': @@ -372,7 +438,7 @@ paths: 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/{short_local_identifier}': + '/persons/{local_identifier}': get: tags: - Person @@ -381,7 +447,7 @@ paths: 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/shortLocalIdPathParam' + - $ref : '#/components/parameters/localIdPathParam' responses: '200': description: Success @@ -401,7 +467,10 @@ paths: - $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/my-skg-acronym/"}] + - ["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 @@ -418,7 +487,7 @@ paths: {"@base" : "http://example.com/"} ] "@graph" : - - local_identifier: http://example.com/skg-if/api/persons/pers-c66c6-38be-4d5f-85db-d44c9f869333 + - local_identifier: person-1-jc entity_type: "person" identifiers: - scheme: orcid @@ -435,9 +504,10 @@ paths: {"@base" : "http://example.com/"} ] "@graph" : - - local_identifier: http://example.com/skg-if/api/persons/otf_126848135_prod-1-pers-1 + - local_identifier: person-2-jd entity_type: "person" name: "John Doe" + '404': description: | Error if entity does not exists @@ -512,14 +582,16 @@ paths: - $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/my-skg-acronym/"}] + - ["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/Meta' + $ref: '#/components/schemas/MetaSearch' "@graph": type: array items: - $ref: '#/components/schemas/Person' + oneOf: + - $ref: '#/components/schemas/Person' + - $ref: '#/components/schemas/LocalIdentifierRef' required: [ "@context", "meta", "@graph" ] examples: PersonEx01: @@ -528,7 +600,7 @@ paths: "@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/my-skg-acronym/" + - "@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 @@ -539,8 +611,19 @@ paths: 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: http://example.com/skg-if/api/persons/pers-c66c6-38be-4d5f-85db-d44c9f869333 + - local_identifier: person-1-jc entity_type: "person" identifiers: - scheme: orcid @@ -548,7 +631,7 @@ paths: given_name: "Josiah" family_name: "Carberry" name: "Josiah Carberry" - - local_identifier: http://example.com/skg-if/api/persons/pers-c66c6-38be-4d5f-85db-d44c9f869888 + - local_identifier: person-2-gc entity_type: "person" given_name: "Gerard" family_name: "Carberry" @@ -561,7 +644,7 @@ paths: operationId: getPersonById parameters: local_identifier: $response.body#/@graph/local_identifier - '/organisations/{short_local_identifier}': + '/organisations/{local_identifier}': get: tags: - Organisation @@ -570,7 +653,7 @@ paths: 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/shortLocalIdPathParam' + - $ref : '#/components/parameters/localIdPathParam' responses: '200': description: Success @@ -591,7 +674,10 @@ paths: - $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/my-skg-acronym/"}] + - ["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 @@ -605,9 +691,9 @@ paths: "@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/my-skg-acronym/" + - "@base" : "https://w3id.org/skg-if/sandbox/acme/" "@graph": - - local_identifier: http://example.com/skg-if/api/organisations/otf_session12324_org_1124 + - local_identifier: organisation-2-bu entity_type: 'organisation' identifiers: - scheme: ror @@ -623,9 +709,9 @@ paths: "@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/my-skg-acronym/" + - "@base" : "https://w3id.org/skg-if/sandbox/acme/" "@graph": - - local_identifier: http://example.com/skg-if/api/organisations/otf_session12325_org_1125 + - local_identifier: organisation-3-jcbl entity_type: 'organisation' identifiers: - scheme: ror @@ -637,15 +723,15 @@ paths: country: US types: - archive - OrgLabScienceNoId: + 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/my-skg-acronym/" + - "@base" : "https://w3id.org/skg-if/sandbox/acme/" "@graph": - - local_identifier: http://example.com/skg-if/api/organisations/otf_session12325_org_1126 + - local_identifier: organisation-5-lsa entity_type: 'organisation' name: Lab of science, unknown University, Antarctica OrgEuropeanCommission: @@ -654,9 +740,9 @@ paths: "@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/my-skg-acronym/" + - "@base" : "https://w3id.org/skg-if/sandbox/acme/" "@graph": - - local_identifier: http://example.com/skg-if/api/organisations/otf_session12324_org_1127 + - local_identifier: organisation-6-eu entity_type: 'organisation' identifiers: - scheme: ror @@ -735,16 +821,18 @@ paths: - $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/my-skg-acronym/"}] + - ["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/Meta' + $ref: '#/components/schemas/MetaSearch' "@graph": type: array items: - $ref: '#/components/schemas/Organisation' + oneOf: + - $ref: '#/components/schemas/Organisation' + - $ref: '#/components/schemas/LocalIdentifierRef' required: [ "@context", "meta", "@graph" ] - '/grants/{short_local_identifier}': + '/grants/{local_identifier}': get: tags: - Grant @@ -753,7 +841,7 @@ paths: 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/shortLocalIdPathParam' + - $ref : '#/components/parameters/localIdPathParam' responses: '200': description: Success @@ -774,13 +862,16 @@ paths: - $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/my-skg-acronym/"}] + - ["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" + $ref: "#/components/schemas/Grant" examples: GrantEx01: summary: GraspOS grant @@ -788,10 +879,34 @@ paths: "@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/my-skg-acronym/"} + {"@base" : "https://w3id.org/skg-if/sandbox/acme/"} ] + "meta" : + local_identifier: grant-1-go + entity_type: "single_entity" + api_items: + - local_identifier: grant-1-go + urls: + - entity_type: "link" + rel: "self" + href: "https://example.com/skg-if/api/grants/grant-1-go" + - 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: http://example.com/skg-if/api/grants/grant-c66c6-38be-4d5f-85db-d44c9f869333 + - local_identifier: grant-1-go entity_type: "grant" identifiers: - scheme: "doi" @@ -804,7 +919,7 @@ paths: } acronym: "GraspOS" funding_agency: - local_identifier: http://example.com/skg-if/api/grants/otf___1730027051396___org-1 + local_identifier: organisation-2-bu entity_type: "organisation" identifiers: - scheme: "ror" @@ -821,7 +936,7 @@ paths: end: "2025-12-31T23:59:59Z" website: "https://graspos.eu" beneficiaries: - - local_identifier: http://example.com/skg-if/api/organisations/otf___1730027051396___org-2 + - local_identifier: organisation-2-bu entity_type: "organisation" identifiers: - scheme: "ror" @@ -832,7 +947,7 @@ paths: website: "https://www.brown.edu/" contributions: - by: - local_identifier: http://example.com/skg-if/api/persons/otf___1730027051396___pers-1 + local_identifier: person-1-jc entity_type: "person" identifiers: - scheme: "orcid" @@ -841,7 +956,7 @@ paths: family_name: "Carberry" name: "Josiah Carberro" declared_affiliations: - - local_identifier": "otf___1730027051396___org-2" + - local_identifier": "organisation-2-bu" entity_type": "organisation" identifiers: - scheme: "ror" @@ -958,16 +1073,18 @@ paths: - $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/my-skg-acronym/"}] + - ["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/Meta' + $ref: '#/components/schemas/MetaSearch' "@graph": type: array items: - $ref: '#/components/schemas/Grant' + oneOf: + - $ref: '#/components/schemas/Grant' + - $ref: '#/components/schemas/LocalIdentifierRef' required: [ "@context", "meta", "@graph" ] - '/venues/{short_local_identifier}': + '/venues/{local_identifier}': get: tags: - Venue @@ -976,7 +1093,7 @@ paths: 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/shortLocalIdPathParam' + - $ref : '#/components/parameters/localIdPathParam' responses: '200': description: Success @@ -997,7 +1114,10 @@ paths: - $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/my-skg-acronym/"}] + - ["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 @@ -1011,10 +1131,19 @@ paths: "@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/my-skg-acronym/"} + {"@base" : "https://w3id.org/skg-if/sandbox/acme/"} ] + "meta" : + local_identifier: venue-1-jp + entity_type: "single_entity" + api_items: + - local_identifier: venue-1-jp + urls: + - entity_type: "link" + rel: "self" + href: "https://example.com/skg-if/api/venues/venue-1-jp" "@graph" : - - local_identifier: http://example.com/skg-if/api/venues/venue-c66c6-38be-4d5f-85db-d44c9f869333 + - local_identifier: venue-1-jp entity_type: "venue" identifiers: - scheme: issn @@ -1084,16 +1213,18 @@ paths: - $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/my-skg-acronym/"}] + - ["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/Meta' + $ref: '#/components/schemas/MetaSearch' "@graph": type: array items: - $ref: '#/components/schemas/Venue' + oneOf: + - $ref: '#/components/schemas/Venue' + - $ref: '#/components/schemas/LocalIdentifierRef' required: [ "@context", "meta", "@graph" ] - '/topics/{short_local_identifier}': + '/topics/{local_identifier}': get: tags: - Topic @@ -1102,7 +1233,7 @@ paths: 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/shortLocalIdPathParam' + - $ref : '#/components/parameters/localIdPathParam' responses: '200': description: Success @@ -1123,7 +1254,10 @@ paths: - $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/my-skg-acronym/"}] + - ["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 @@ -1137,10 +1271,19 @@ paths: "@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/my-skg-acronym/"} + {"@base" : "https://w3id.org/skg-if/sandbox/acme/"} ] + "meta" : + local_identifier: topic-1-cs + entity_type: "single_entity" + api_items: + - local_identifier: topic-1-cs + urls: + - entity_type: "link" + rel: "self" + href: "https://example.com/skg-if/api/topics/topc-1-cs" "@graph" : - - local_identifier: http://example.com/skg-if/api/topics/topic-c66c6-38be-4d5f-85db-d44c9f869333 + - local_identifier: topic-1-cs entity_type: "topic" identifiers: - scheme: wikidata @@ -1221,16 +1364,18 @@ paths: - $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/my-skg-acronym/"}] + - ["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/Meta' + $ref: '#/components/schemas/MetaSearch' "@graph": type: array items: - $ref: '#/components/schemas/Topic' + oneOf: + - $ref: '#/components/schemas/Topic' + - $ref: '#/components/schemas/LocalIdentifierRef' required: [ "@context", "meta", "@graph" ] - '/datasources/{short_local_identifier}': + '/datasources/{local_identifier}': get: tags: - Data Source @@ -1239,7 +1384,7 @@ paths: 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/shortLocalIdPathParam' + - $ref : '#/components/parameters/localIdPathParam' responses: '200': description: Success @@ -1260,13 +1405,16 @@ paths: - $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/my-skg-acronym/"}] + - ["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" + $ref: "#/components/schemas/DataSource" examples: DatasourceEx01: summary: Oxford University Research Archive datasource @@ -1274,10 +1422,19 @@ paths: "@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/my-skg-acronym/"} + {"@base" : "https://w3id.org/skg-if/sandbox/acme/"} ] + "meta" : + local_identifier: datasource-1-oura + entity_type: "single_entity" + api_items: + - local_identifier: datasource-1-oura + urls: + - entity_type: "link" + rel: "self" + href: "https://example.com/skg-if/api/venues/datasource-1-oura" "@graph" : - - local_identifier: http://example.com/skg-if/api/datasources/datasrc-c66c6-38be-4d5f-85db-d44c9f869333 + - local_identifier: datasource-1-oura entity_type: "datasource" identifiers: - scheme: doi @@ -1349,14 +1506,16 @@ paths: - $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/my-skg-acronym/"}] + - ["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/Meta' + $ref: '#/components/schemas/MetaSearch' "@graph": type: array items: - $ref: '#/components/schemas/DataSource' + oneOf: + - $ref: '#/components/schemas/DataSource' + - $ref: '#/components/schemas/LocalIdentifierRef' required: [ "@context", "meta", "@graph" ] components: securitySchemes: @@ -1376,13 +1535,12 @@ components: type: http scheme: basic parameters: - shortLocalIdPathParam: - name: short_local_identifier + localIdPathParam: + name: local_identifier in: path description: | - entity id. URL suffix used in OpenAPI get by id operations. \ - `https://[your-server-root-skg-if-url]/[products|persons|organisations|datasources|venues|topics]/{short_local_identifier}` \ - example `http://example.com/skg-if/api/products/c66c6-38be-4d5f-85db-d44c9` + entity id. URL. \ + example `http://skgbase.example.com/prod-c66c6-38be-4d5f-85db-d44c9` required: true schema: type: string @@ -1410,6 +1568,101 @@ components: 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 + 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 + 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 + x-faker: + helpers.arrayElement: [["self"]] + href: + type: string + 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 + description: "Media type. Leave empty for `rel:self`" + x-faker: + helpers.arrayElement: [["text/xml"]] Product: type: object title: 'Product' @@ -1480,7 +1733,9 @@ components: required: [ "term" ] properties: term: - $ref: '#/components/schemas/Topic' + oneOf: + - $ref: '#/components/schemas/Topic' + - $ref: '#/components/schemas/LocalIdentifierRef' # TODO provenance ? contributions: type: array @@ -1496,17 +1751,20 @@ components: type: array description: List of relevant Organisation associated with the `product`, in case the individual affiliations of a `person` are not available. items: - $ref: '#/components/schemas/Organisation' + oneOf: + - $ref: '#/components/schemas/Organisation' + - $ref: '#/components/schemas/LocalIdentifierRef' funding: type: array description: List of `grant` associated with the `product` items: - $ref: '#/components/schemas/GrantLite' + oneOf: + - $ref: '#/components/schemas/GrantLite' + - $ref: '#/components/schemas/LocalIdentifierRef' related_products: - $ref: '#/components/schemas/ProductRelated' - + $ref: '#/components/schemas/ProductsRelated' examples: - - local_identifier: http://example.com/skg-if/api/products/xxx + - local_identifier: product-1-fgp entity_type: product product_type: literature titles : @@ -1530,11 +1788,11 @@ components: identifiers: - value: "0000-0001-6960-357X" scheme: "orcid" - local_identifier: http://example.com/skg-if/api/persons/614a6575-5d6c-416c-a8e1-f49a5d589bf8 + 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: http://example.com/skg-if/api/persons/32bc66c6-38be-4d5f-85db-d44c9f86921f + local_identifier: affiliation-organisation-1 entity_type: "organisation" country: "ES" manifestations: @@ -1545,7 +1803,7 @@ components: class: http://www.example.com/types/onto/localtypemethodology biblio: hosting_data_source: - local_identifier: http://example.com/skg-if/api/datasources/6f368a3a-b1cf-498f-b2de-27135d1e0075 + local_identifier: datasource-1-aa entity_type: datasource name: "An Archive" in: @@ -1554,7 +1812,7 @@ components: identifiers: - "value": "2052-4463" "scheme": "issn" - local_identifier: http://example.com/skg-if/api/datasources/51f46bc1-00f8-42dd-8221-ac4deb52fb25 + local_identifier: venue-5-sd entity_type: "venue" dates: # http://api.crossref.org/works/10.1038/sdata.2016.18 publication: @@ -1565,7 +1823,7 @@ components: deposit: - "2023-01-04" funding: - - local_identifier: http://example.com/skg-if/api/grants/614a6575-5d6c-416c-a8e1-f49a5d58999 + - local_identifier: grant-7-zz entity_type: "grant" titles: - en: "EU grant ZZ" @@ -1586,6 +1844,7 @@ components: - $ref: '#/components/schemas/PersonLite' - $ref: '#/components/schemas/Organisation' - $ref: '#/components/schemas/Agent' + - $ref: '#/components/schemas/LocalIdentifierRef' discriminator: propertyName: entity_type mapping: @@ -1596,7 +1855,9 @@ components: description: List of `organisation` that reflect the declared affiliations of a `person` contributing to a `product`. type: array items: - $ref: '#/components/schemas/Organisation' + oneOf: + - $ref: '#/components/schemas/Organisation' + - $ref: '#/components/schemas/LocalIdentifierRef' rank: type: integer x-faker: @@ -1819,43 +2080,62 @@ components: x-faker: fake : ['{{datatype.number(5)}}'] in: - $ref: '#/components/schemas/VenueLite' + oneOf: + - $ref: '#/components/schemas/VenueLite' + - $ref: '#/components/schemas/LocalIdentifierRef' hosting_data_source : - $ref: '#/components/schemas/DataSourceLite' - ProductRelated: + oneOf: + - $ref: '#/components/schemas/DataSourceLite' + - $ref: '#/components/schemas/LocalIdentifierRef' + 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 items: - local_identifier: - type: string - description: "`product` local_identifier" + oneOf : + - $ref: '#/components/schemas/ProductsRelatedItem' + - $ref: '#/components/schemas/LocalIdentifierRef' is_supplemented_by: type: array items: - local_identifier: - type: string - description: "`product` local_identifier" + oneOf : + - $ref: '#/components/schemas/ProductsRelatedItem' + - $ref: '#/components/schemas/LocalIdentifierRef' is_documented_by: type: array items: - local_identifier: - type: string - description: "`product` local_identifier" + oneOf: + - $ref: '#/components/schemas/ProductsRelatedItem' + - $ref: '#/components/schemas/LocalIdentifierRef' is_new_version_of: type: array items: - local_identifier: - type: string - description: "`product` local_identifier" + oneOf : + - $ref: '#/components/schemas/ProductsRelatedItem' + - $ref: '#/components/schemas/LocalIdentifierRef' is_part_of: type: array items: - local_identifier: - type: string - description: "`product` local_identifier" + oneOf : + - $ref: '#/components/schemas/ProductsRelatedItem' + - $ref: '#/components/schemas/LocalIdentifierRef' Agent: type: object title: "Agent" @@ -1982,7 +2262,7 @@ components: - research - unspecified examples: - - local_identifier: 'otf_session12324_org_1124' + - local_identifier: 'organisation-2-bu' entity_type: 'organisation' identifiers: - "scheme": ror @@ -1992,7 +2272,7 @@ components: country: US types: - education - - local_identifier: http://example.com/skg-if/api/organisations/otf_session12325_org_1125 + - local_identifier: organisation-3-jcbl entity_type: 'organisation' identifiers: - scheme: ror @@ -2004,10 +2284,10 @@ components: country: US types: - archive - - local_identifier: http://example.com/skg-if/api/organisations/otf_session12325_org_1126 + - local_identifier: organisation-5-lsa entity_type: 'organisation' name: Lab of science, unknown University, Antarctica - - local_identifier: http://example.com/skg-if/api/organisations/otf_session12324_org_1127 + - local_identifier: organisation-6-eu entity_type: 'organisation' identifiers: - scheme: ror @@ -2052,7 +2332,7 @@ components: type: string description: end date. Format [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) compliant string ( "2024-10-01", "2024-10", "2024" ).' examples: - - local_identifier: http://example.com/skg-if/api/persons/otf_session12324_person_1124 + - local_identifier: person-1-jc entity_type: 'person' identifiers: - scheme: orcid @@ -2066,7 +2346,7 @@ components: start: "2010-08-24" end: "2020-08-24" affiliation: - local_identifier: http://example.com/skg-if/api/organisatios/otf_session12324_org_1124 + local_identifier: organisation-2-bu entity_type: 'organisation' identifiers: - scheme: ror @@ -2127,7 +2407,7 @@ components: examples : - Josiah Carberro examples: - - local_identifier: http://example.com/skg-if/api/persons/otf_session12324_person_1124 + - local_identifier: person-1-jc entity_type: 'person' identifiers: - scheme: orcid @@ -2234,12 +2514,16 @@ components: description: "List of `organisation` funded by the `grant`" type: array items: - $ref: '#/components/schemas/Organisation' + oneOf: + - $ref: '#/components/schemas/Organisation' + - $ref: '#/components/schemas/LocalIdentifierRef' contributions: type: array description: List of objects describing a `person` or `organisation`, its role, contribution, rank, when working on the `grant`. items: - $ref: '#/components/schemas/GrantContribution' + oneOf: + - $ref: '#/components/schemas/GrantContribution' + - $ref: '#/components/schemas/LocalIdentifierRef' GrantContribution: type: object title: 'GrantContribution' @@ -2250,6 +2534,7 @@ components: oneOf: - $ref: '#/components/schemas/PersonLite' - $ref: '#/components/schemas/Organisation' + - $ref: '#/components/schemas/LocalIdentifierRef' discriminator: propertyName: entity_type mapping: @@ -2259,7 +2544,9 @@ components: description: List of `organisation` that reflect the declared affiliations of a `person` contributing to a `grant`. type: array items: - $ref: '#/components/schemas/Organisation' + oneOf: + - $ref: '#/components/schemas/Organisation' + - $ref: '#/components/schemas/LocalIdentifierRef' roles: description: | The roles that a `person` or `organisation` had in a `grant`.\ @@ -2506,22 +2793,29 @@ components: local_identifier: type: string description: | - Unique local identifier as URL. \ - `https://[your-server-root-skg-if-url]/[products|persons|organisations|datasources|venues|topics]/{short_local_identifier}` \ - example `http://example.com/skg-if/api/products/c66c6-38be-4d5f-85db-d44c9` \ - \ - If the entity does not have any stable identifier an on-the-fly identifier is returned : `otf______`. + 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 URL `//`. + 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://example.com/skg-if/api/products/c66c6-38be-4d5f-85db-d44c9 - - http://example.com/skg-if/api/products/otf___1730027051396___prod-1 - - http://example.com/skg-if/api/persons/c7777-38be-4d5f-85db-d7777 - - http://example.com/skg-if/api/persons/otf___1730027051396___person-1 + - 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 items: @@ -2535,13 +2829,32 @@ components: type: string entity_type: type: string - Meta: + MetaSingleEntity: + type: object + required: [ "local_identifier", "entity_type" ] + properties: + local_identifier: + type: string + description: entity id as URL + examples: + - http://w3id.org/skg-if/sandbox/acme/product-1 + - http://w3id.org/skg-if/sandbox/acme/person-1 + entity_type: + type: string + description: single entity + enum: + - single_entity + api_items: + type: array + items: + $ref: '#/components/schemas/ApiItem' + MetaSearch: type: object required: [ "local_identifier", "entity_type" ] properties: local_identifier: type: string - description: search result page id + 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 @@ -2565,7 +2878,7 @@ components: properties: local_identifier: type: string - description: search result id as URL + 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 @@ -2587,12 +2900,16 @@ components: description: Last page reference of the search type: object $ref: '#/components/schemas/SearchResultPage' + api_items: + type: array + items: + $ref: '#/components/schemas/ApiItem' SearchResultPage: type: object properties: local_identifier: type: string - description: search result page id as URL + 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 @@ -2645,22 +2962,27 @@ components: 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/my-skg-acronym" }`' + description : 'Additional context mappings ex: `{ "@base":"https://w3id.org/skg-if/sandbox/acme" }`' properties: "@base": type: string description : | - Default base URL specific to the implementer.\ - common format : `https://w3id.org/skg-if/sandbox/{my-skg-acronym}` \ - example : `https://w3id.org/skg-if/sandbox/openaire/` + Default root URL of the JSON-LD context. \ + To define your `@base`, please refer to the [SKG-IF OpenAPI Implementer documentation](https://docs.google.com/document/d/1t7b7h28UTtM56Sda4NGJIp0hnQfGbcVVGn12fny9wfI/edit?usp=sharing) \ + 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://w3id.org/skg-if/sandbox/openaire/" - - "https://w3id.org/skg-if/sandbox/cessda/" - - "https://w3id.org/skg-if/sandbox/foobar/" + - "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-if/{{random.alpha(3)}}'] + fake : ['http://www.example.com/skg/{{random.alpha(3)}}'] From f663d5eed9086d68a26a3ebbf5e19e0c182609b5 Mon Sep 17 00:00:00 2001 From: rduyme Date: Thu, 11 Jun 2026 23:30:07 +0200 Subject: [PATCH 4/7] openapi action exclude context file --- .github/scripts/validate_files.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/scripts/validate_files.py b/.github/scripts/validate_files.py index 4f9daec..c2ab6cf 100644 --- a/.github/scripts/validate_files.py +++ b/.github/scripts/validate_files.py @@ -16,7 +16,7 @@ def get_pushed_files(): - return [f"./{file}" for file in changed_files if file.endswith(".json")] + return [f"./{file}" for file in changed_files if file.endswith(".json") and file != "skg-if-api.json" ] def validate_file(file_path): From cde61a10646c76f7e2637b20c374ae020895580c Mon Sep 17 00:00:00 2001 From: rduyme Date: Thu, 11 Jun 2026 23:39:59 +0200 Subject: [PATCH 5/7] openapi exclude cxt file --- .github/scripts/validate_files.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/scripts/validate_files.py b/.github/scripts/validate_files.py index c2ab6cf..413d15c 100644 --- a/.github/scripts/validate_files.py +++ b/.github/scripts/validate_files.py @@ -16,7 +16,7 @@ def get_pushed_files(): - return [f"./{file}" for file in changed_files if file.endswith(".json") and file != "skg-if-api.json" ] + return [f"./{file}" for file in changed_files if ( file.endswith(".json") and not file.endswith("skg-if-api.json") ) ] def validate_file(file_path): From 6eb4fa8c5b3ec14e0a40b472bc6b89bb4a723220 Mon Sep 17 00:00:00 2001 From: duyme Date: Fri, 12 Jun 2026 14:39:58 +0200 Subject: [PATCH 6/7] openapi version label fix --- openapi/ver/current/context/skg-if-api.json | 23 ++- openapi/ver/current/skg-if-openapi.yaml | 155 ++++++++++---------- 2 files changed, 100 insertions(+), 78 deletions(-) diff --git a/openapi/ver/current/context/skg-if-api.json b/openapi/ver/current/context/skg-if-api.json index e59988e..f23cb87 100644 --- a/openapi/ver/current/context/skg-if-api.json +++ b/openapi/ver/current/context/skg-if-api.json @@ -9,6 +9,9 @@ "search_result": { "@id": "as:Collection" }, + "single_entity": { + "@id": "as:Object" + }, "part_of": { "@id": "as:partOf" }, @@ -27,6 +30,24 @@ "prev_page": { "@id": "as:prev" }, - "meta": "@nest" + "meta": "@nest", + "api_items": { + "@id": "as:items", + "@container": "@set" + }, + "urls": { + "@id": "as:url", + "@container": "@set" + }, + "rel": { + "@id": "as:rel" + }, + "href": { + "@id": "as:href", + "@type": "@id" + }, + "media_type":{ + "@id": "as:mediaType" + } } } \ No newline at end of file diff --git a/openapi/ver/current/skg-if-openapi.yaml b/openapi/ver/current/skg-if-openapi.yaml index 65d674d..fdcd7e4 100644 --- a/openapi/ver/current/skg-if-openapi.yaml +++ b/openapi/ver/current/skg-if-openapi.yaml @@ -1,7 +1,7 @@ openapi: 3.1.0 info: version: 1.0.0 - title: SKG-IF OpenAPI + 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' @@ -117,29 +117,29 @@ paths: "meta" : local_identifier: product-1-fgp entity_type: single_entity - api_items: + api_items: - local_identifier: product-1-fgp - urls: + urls: - entity_type: "link" rel: "self" href: "https://example.com/skg-if/api/products/product-1-fgp" - local_identifier: person-5-mw - urls: + urls: - entity_type: "link" rel: "self" href: "https://example.com/skg-if/api/persons/person-5-mw" - local_identifier: affiliation-organisation-1 - urls: + urls: - entity_type: "link" rel: "self" href: "https://example.com/skg-if/api/organisations/affiliation-organisation-1" - local_identifier: datasource-1-aa - urls: + urls: - entity_type: "link" rel: "self" href: "https://example.com/skg-if/api/datasources/datasource-1-aa" - local_identifier: venue-5-sd - urls: + urls: - entity_type: "link" rel: "self" href: "https://example.com/skg-if/api/venues/venue-5-sd" @@ -207,7 +207,7 @@ paths: cites: - local_identifier: product-10 entity_type: "product" - + DatasetEx02: summary: "Dataset - OpenAIRE Graph dataset new collected projects" value : @@ -219,9 +219,9 @@ paths: "meta" : local_identifier: product-2-ogd entity_type: single_entity - api_items: + api_items: - local_identifier: product-2-ogd - urls: + urls: - entity_type: "link" rel: "self" href: "https://example.com/skg-if/api/products/product-2-ogd" @@ -274,7 +274,8 @@ paths: | funding. identifiers.scheme | `funding. identifiers.scheme:doi` | __Convenience filters__ \ - These filters aren't attributes of the `product` object, but they're handy for solving some common use cases. + 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` | @@ -370,21 +371,21 @@ paths: local_identifier: https://example.com/skg-if/api/products?filter=product_type:literature entity_type: search_result total_items: 54231 - api_items: + api_items: - local_identifier: product-500 - urls: + urls: - entity_type: "link" rel: "self" href: "https://example.com/skg-if/api/products/product-500" - local_identifier: product-501 - urls: + 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 + product_type: literature - local_identifier: product-501 entity_type: product product_type: research data @@ -405,14 +406,14 @@ paths: local_identifier: http://example.com/skg-if/api/products?filter=product_type:research%20data entity_type: search_result total_items: 13202 - api_items: + api_items: - local_identifier: product-500 - urls: + urls: - entity_type: "link" rel: "self" href: "https://example.com/skg-if/api/products/product-1000-ds" - local_identifier: product-501 - urls: + urls: - entity_type: "link" rel: "self" href: "https://example.com/skg-if/api/products/product-1001-ds" @@ -507,7 +508,7 @@ paths: - local_identifier: person-2-jd entity_type: "person" name: "John Doe" - + '404': description: | Error if entity does not exists @@ -535,7 +536,7 @@ paths: | affiliations.role | `affiliations.role:affiliate` | __Convenience filters__ \ - These filters aren't attributes of the `person` object, but they're handy for solving some common use cases. + 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 | | -------- | -------- | ------- | ------- | @@ -611,14 +612,14 @@ paths: local_identifier: https://example.com/skg-if/api/persons?filter=family_name:Carberry entity_type: search_result total_items: 4 - api_items: + api_items: - local_identifier: person-1-jc - urls: + urls: - entity_type: "link" rel: "self" href: "https://example.com/skg-if/api/persons/person-1-jc" - local_identifier: person-2-gc - urls: + urls: - entity_type: "link" rel: "self" href: "https://example.com/skg-if/api/persons/person-2-gc" @@ -775,7 +776,7 @@ paths: | country | `country:US` | __Convenience filters__ \ - These filters aren't attributes of the `organization` object, but they're handy for solving some common use cases. + 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 | | -------- | -------- | ------- | ------- | @@ -828,7 +829,7 @@ paths: "@graph": type: array items: - oneOf: + oneOf: - $ref: '#/components/schemas/Organisation' - $ref: '#/components/schemas/LocalIdentifierRef' required: [ "@context", "meta", "@graph" ] @@ -871,7 +872,7 @@ paths: minItems: 1 maxItems: 1 items: - $ref: "#/components/schemas/Grant" + $ref: "#/components/schemas/Grant" examples: GrantEx01: summary: GraspOS grant @@ -883,28 +884,28 @@ paths: ] "meta" : local_identifier: grant-1-go - entity_type: "single_entity" + entity_type: "single_entity" api_items: - local_identifier: grant-1-go - urls: + urls: - entity_type: "link" rel: "self" - href: "https://example.com/skg-if/api/grants/grant-1-go" + href: "https://example.com/skg-if/api/grants/grant-1-go" - local_identifier: person-1-jc - urls: + urls: - entity_type: "link" rel: "self" href: "https://example.com/skg-if/api/persons/person-1-jc" - local_identifier: person-2-gc - urls: + urls: - entity_type: "link" rel: "self" href: "https://example.com/skg-if/api/persons/person-2-gc" - local_identifier: organisation-2-bu - urls: + urls: - entity_type: "link" rel: "self" - href: "https://example.com/skg-if/api/organisations/organisation-2-bu" + href: "https://example.com/skg-if/api/organisations/organisation-2-bu" "@graph" : - local_identifier: grant-1-go entity_type: "grant" @@ -1023,7 +1024,7 @@ paths: __Convenience filters__ \ - These filters aren't attributes of the `grant` object, but they're handy for solving some common use cases. + 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 | | -------- | -------- | ------- | ------- | @@ -1135,10 +1136,10 @@ paths: ] "meta" : local_identifier: venue-1-jp - entity_type: "single_entity" + entity_type: "single_entity" api_items: - local_identifier: venue-1-jp - urls: + urls: - entity_type: "link" rel: "self" href: "https://example.com/skg-if/api/venues/venue-1-jp" @@ -1175,7 +1176,7 @@ paths: | name | `name:Journal of Psychoceramics` | __Convenience filters__ \ - These filters aren't attributes of the `venue` object, but they're handy for solving some common use cases. + 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 | | -------- | -------- | ------- | ------- | @@ -1220,7 +1221,7 @@ paths: "@graph": type: array items: - oneOf: + oneOf: - $ref: '#/components/schemas/Venue' - $ref: '#/components/schemas/LocalIdentifierRef' required: [ "@context", "meta", "@graph" ] @@ -1275,10 +1276,10 @@ paths: ] "meta" : local_identifier: topic-1-cs - entity_type: "single_entity" + entity_type: "single_entity" api_items: - local_identifier: topic-1-cs - urls: + urls: - entity_type: "link" rel: "self" href: "https://example.com/skg-if/api/topics/topc-1-cs" @@ -1312,7 +1313,7 @@ paths: | identifiers.value | `identifiers.value:https://www.wikidata.org/wiki/Q42` | __Convenience filters__ \ - These filters aren't attributes of the `topic` object, but they're handy for solving some common use cases. + 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 | | -------- | -------- | ------- | ------- | @@ -1371,7 +1372,7 @@ paths: "@graph": type: array items: - oneOf: + oneOf: - $ref: '#/components/schemas/Topic' - $ref: '#/components/schemas/LocalIdentifierRef' required: [ "@context", "meta", "@graph" ] @@ -1414,7 +1415,7 @@ paths: minItems: 1 maxItems: 1 items: - $ref: "#/components/schemas/DataSource" + $ref: "#/components/schemas/DataSource" examples: DatasourceEx01: summary: Oxford University Research Archive datasource @@ -1426,10 +1427,10 @@ paths: ] "meta" : local_identifier: datasource-1-oura - entity_type: "single_entity" + entity_type: "single_entity" api_items: - local_identifier: datasource-1-oura - urls: + urls: - entity_type: "link" rel: "self" href: "https://example.com/skg-if/api/venues/datasource-1-oura" @@ -1468,7 +1469,7 @@ paths: | acronym | `acronym:CIKM` | __Convenience filters__ \ - These filters aren't attributes of the `datasource` object, but they're handy for solving some common use cases. + 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 | | -------- | -------- | ------- | ------- | @@ -1572,38 +1573,38 @@ components: 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: + 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: + ex: ``` - "foo": { - "local_identifier":"product-1", - "entity_type:product", - "title":"xxx", + "foo": { + "local_identifier":"product-1", + "entity_type:product", + "title":"xxx", ... "contributions" : [ { "by": { - "local_identifier":"person-1", - "entity_type:person", - "name":"John Doe", + "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: @@ -1613,7 +1614,7 @@ components: Result element required: [ "local_identifier" - ] + ] properties: local_identifier: type: string @@ -1621,7 +1622,7 @@ components: Unique local identifier as URL 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/person-1 urls: type: array description: | @@ -1635,7 +1636,7 @@ components: 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` + 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" @@ -1662,7 +1663,7 @@ components: type: string description: "Media type. Leave empty for `rel:self`" x-faker: - helpers.arrayElement: [["text/xml"]] + helpers.arrayElement: [["text/xml"]] Product: type: object title: 'Product' @@ -1751,7 +1752,7 @@ components: type: array description: List of relevant Organisation associated with the `product`, in case the individual affiliations of a `person` are not available. items: - oneOf: + oneOf: - $ref: '#/components/schemas/Organisation' - $ref: '#/components/schemas/LocalIdentifierRef' funding: @@ -1855,7 +1856,7 @@ components: description: List of `organisation` that reflect the declared affiliations of a `person` contributing to a `product`. type: array items: - oneOf: + oneOf: - $ref: '#/components/schemas/Organisation' - $ref: '#/components/schemas/LocalIdentifierRef' rank: @@ -2109,7 +2110,7 @@ components: cites: type: array items: - oneOf : + oneOf : - $ref: '#/components/schemas/ProductsRelatedItem' - $ref: '#/components/schemas/LocalIdentifierRef' is_supplemented_by: @@ -2121,7 +2122,7 @@ components: is_documented_by: type: array items: - oneOf: + oneOf: - $ref: '#/components/schemas/ProductsRelatedItem' - $ref: '#/components/schemas/LocalIdentifierRef' is_new_version_of: @@ -2514,7 +2515,7 @@ components: description: "List of `organisation` funded by the `grant`" type: array items: - oneOf: + oneOf: - $ref: '#/components/schemas/Organisation' - $ref: '#/components/schemas/LocalIdentifierRef' contributions: @@ -2793,14 +2794,14 @@ components: 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` - + 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...) - + 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; From ff885aa7c2e8d09b61060321bdf8763510562ba9 Mon Sep 17 00:00:00 2001 From: duyme Date: Fri, 12 Jun 2026 23:01:02 +0200 Subject: [PATCH 7/7] OpenApi Markdown doc --- index.md | 149 ++++++++++++++++++++++-- openapi/ver/current/skg-if-openapi.yaml | 2 +- 2 files changed, 142 insertions(+), 9 deletions(-) diff --git a/index.md b/index.md index 9d997b1..35defc2 100644 --- a/index.md +++ b/index.md @@ -7,21 +7,154 @@ nav_order: 7 # API Specifications {: .highlight } -**Work in progress**: The WG agreed with RDA a 6-month deadline extension (i.e., end of June 2025) in order to deliver full-fledged API specifications that go beyond the "vanilla" resolvers describe in the first iteration of the SKG-IF. We opted for **OpenAPI** to describe the endpoints and the format of the objects to exchange on the wire; the *ALPHA* specifications are shared below. For the sake of completeness, you can check our working document on API development [here](https://docs.google.com/document/d/1t7b7h28UTtM56Sda4NGJIp0hnQfGbcVVGn12fny9wfI/edit?tab=t.0#heading=h.hso3muyqtlhx). +## Versions -The current (i.e., last) version of the SKG-IF OpenAPI specifications is available at [https://w3id.org/skg-if/api/skg-if-openapi.yaml](https://w3id.org/skg-if/api/skg-if-openapi.yaml). +**OpenAPI** is used to describe the endpoints and the format of the objects to exchange on the wire, the specifications are shared below. +For the sake of completeness, you can also check the [SKG-IF OpenAPI Implementer documentation](https://docs.google.com/document/d/1t7b7h28UTtM56Sda4NGJIp0hnQfGbcVVGn12fny9wfI/edit?tab=t.0#heading=h.hso3muyqtlhx). -One can access the OpenAPI specifications of all (current and previous) versions by using a version number in the `w3id.org` URL, before the name of the YAML file, following this pattern: +* The current (i.e., last) version of the SKG-IF OpenAPI specifications is available at [https://w3id.org/skg-if/api/skg-if-openapi.yaml](https://w3id.org/skg-if/api/skg-if-openapi.yaml). +* One can access the OpenAPI specifications of all (current and previous) versions by using a version number in the `w3id.org` URL, following this pattern: +`https://w3id.org/skg-if/api//skg-if-openapi.yaml`. For instance: `https://w3id.org/skg-if/api/1.0.0/skg-if-openapi.yaml` allows to access to version 1.0.0 of the SKG-IF OpenAPI specifications. + +The SKG-IF OpenAPI version, present in the YAML, is independent from the SKG-IF Data model version. + +``` yaml +openapi: 3.1.0 +info: + version: 1.0.0 + title: SKG-IF OpenAPI - compatible with SKG-IF Data Model 1.1.0 + + ... + "@context": + "https://w3id.org/skg-if/context/1.1.0/skg-if.json", // Fixed SKG-IF data model context + "https://w3id.org/skg-if/context/1.0.0/skg-if-api.json", // Fixed SKG-IF API context + { + "@base": "https://w3id.org/skg-if/sandbox/acme/" + } + ... + +``` + +## Viewers + +You can also visualize the OpenAPI specifications with standard tools like : + +* Stoplight : [https://elements-demo.stoplight.io/?spec=https://w3id.org/skg-if/api/skg-if-openapi.yaml](https://elements-demo.stoplight.io/?spec=https://w3id.org/skg-if/api/skg-if-openapi.yaml) +* Swagger : [https://editor.swagger.io/?url=https://w3id.org/skg-if/api/skg-if-openapi.yaml](https://editor.swagger.io/?url=https://w3id.org/skg-if/api/skg-if-openapi.yaml) + + +## Define your @base + +`@base` is a default prefix domain fallback for all identifiers not defined as URLs in the `@graph` +A `local_identifier` value, when not starting with “http”, is interpreted by concatenation to the `@base`. + +For the `local_identifier` domain (your `@base`), you have a few options for the ACME organisation. + +* Use `https://w3id.org/skg-if/sandbox/acme/` . We don’t recommend it for prod because it does not resolve anywhere ( related to the ACME organisation ) +* Define a [w3id.org](https://w3id.org) domain ex: `https://w3id.org/acme/` . You can set up w3id.org to redirect to your catalogue. ex: `https://w3id.org/acme/prod-1` => `https://www.acme.com/product-catalogue/prod-1` +* Use a graph dedicated domain you already have ex: `https://www.acme.com/theskg/`, `https://www.acme.com/theprodgraph/` + +Make sure that you generate distinct URLs ids for person, product... They should not conflict. + +## Endpoints and JSON-LD output + +* The SKG-IF OpenAPI defines 2 types of endpoints + * Get _Entity_ by Id + * Get List of _Entity_ +* The SKG-IF OpenAPI endpoints outputs are JSON-LD and compatible with the [SKG-IF data model](https://skg-if.github.io/interoperability-framework/) + +## API links + +* The `@graph` array contains entities, identified by their `local_identifier`, each entity may have relation to other entities also identified by their `local_identifier`. +* From a client perspective, if the sub entity is not embedded with its fields, you may need to perform sub queries to access these fields. +* The JSON-LD output contains a `meta` section SHOULD provide you API links for each entity, identified by its `local_identifier`. As a client you are not supposed to guess the API URL from the `local_identifier` format, there is no standard for the API domain prefix, each implementer is free to have a domain for its `local_identifier` and another one for its API (It is even recommended). + + +Get Product by Id : `https://acme.com/skg-if/api/products/prod-1` + +``` json +{ + "meta" : { + "local_identifier": "https://w3id.org/skg-if/sandbox/acme/prod-1", // parent local_identifier / PID + "entity_type": "single_entity", + "api_items": [ + { + "local_identifier": "https://w3id.org/skg-if/sandbox/acme/pers-1", // local_identifier / PID + "urls": [ + { + "entity_type": "link", + "rel": "self", + "href": "https://acme.com/skg-if/api/persons/pers-1" // API link + } + ] + } + ] + }, + "@graph": [ + { + "local_identifier": "https://w3id.org/skg-if/sandbox/acme/prod-1", + "contributions": [ + { + "by" : { + "local_identifier": "https://w3id.org/skg-if/sandbox/acme/pers-1" + //... + } + //... + } + ] + //... + } + ] +} ``` -https://w3id.org/skg-if/api//skg-if-openapi.yaml + +Get List of Product : `https://acme.com/skg-if/api/products?filter=xxx&page=1` + +``` json +{ + "meta": { + "local_identifier": "https://acme.com/skg-if/api/products?filter=xxx&page=1", // search identifier, API link + "entity_type": "single_entity", + "api_items": [ + { + "local_identifier": "https://w3id.org/skg-if/sandbox/acme/pers-1", // local_identifier / PID + "urls": [ + { + "entity_type": "link", + "rel": "self", + "href": "https://acme.com/skg-if/api/persons/pers-1" // API link + } + ] + } + ] + + }, + "@graph": [ + { + "local_identifier": "https://w3id.org/skg-if/sandbox/acme/prod-1", + "contributions": [ + { + "by" : { + "local_identifier": "https://w3id.org/skg-if/sandbox/acme/pers-1" + //... + } + //... + } + ] + //... + }, + { + "local_identifier": "https://w3id.org/skg-if/sandbox/acme/prod-1" + //... + }, + + ] +} + ``` -For instance: -* `https://w3id.org/skg-if/api/1.0.0/skg-if-openapi.yaml` allows to access to version 1.0.0 of the OpenAPI specifications; -* `https://w3id.org/skg-if/api/0.2.0/skg-if-openapi.yaml` allows to access to version 0.2.0 of the OpenAPI specifications; -* and so on. diff --git a/openapi/ver/current/skg-if-openapi.yaml b/openapi/ver/current/skg-if-openapi.yaml index fdcd7e4..a127986 100644 --- a/openapi/ver/current/skg-if-openapi.yaml +++ b/openapi/ver/current/skg-if-openapi.yaml @@ -20,7 +20,7 @@ info: - [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-next.swagger.io/) + - 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