From c9566542a4350a9016b408e078f8f73a53fa7d9f Mon Sep 17 00:00:00 2001 From: duyme Date: Mon, 15 Jun 2026 14:16:47 +0200 Subject: [PATCH] openapi fix get entity by id meta local-identifier --- index.md | 60 +++++++++++++++---- .../products/journal_article_full.json | 12 +--- openapi/ver/current/skg-if-openapi.yaml | 56 ++++------------- 3 files changed, 62 insertions(+), 66 deletions(-) diff --git a/index.md b/index.md index 49ea561..88e1377 100644 --- a/index.md +++ b/index.md @@ -77,16 +77,16 @@ 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 + "local_identifier": "https://acme.com/skg-if/api/products/prod-1", // parent entity : API URL "entity_type": "single_entity", "api_items": [ { - "local_identifier": "https://w3id.org/skg-if/sandbox/acme/pers-1", // local_identifier / PID + "local_identifier": "https://w3id.org/skg-if/sandbox/acme/pers-1", // child entity : local_identifier / PID "urls": [ { "entity_type": "link", "rel": "self", - "href": "https://acme.com/skg-if/api/persons/pers-1" // API link + "href": "https://acme.com/skg-if/api/persons/pers-1" // child entity : API link } ] } @@ -94,11 +94,11 @@ Get Product by Id : `https://acme.com/skg-if/api/products/prod-1` }, "@graph": [ { - "local_identifier": "https://w3id.org/skg-if/sandbox/acme/prod-1", + "local_identifier": "https://w3id.org/skg-if/sandbox/acme/prod-1", // parent entity : local_identifier / PID "contributions": [ { "by" : { - "local_identifier": "https://w3id.org/skg-if/sandbox/acme/pers-1" + "local_identifier": "https://w3id.org/skg-if/sandbox/acme/pers-1" // child entity : local_identifier / PID //... } //... @@ -119,25 +119,45 @@ Get List of Product : `https://acme.com/skg-if/api/products?filter=xxx&page=1` "entity_type": "single_entity", "api_items": [ { - "local_identifier": "https://w3id.org/skg-if/sandbox/acme/pers-1", // local_identifier / PID + "local_identifier": "https://w3id.org/skg-if/sandbox/acme/prod-1", // search result 1 - parent entity : local_identifier / PID "urls": [ { "entity_type": "link", "rel": "self", - "href": "https://acme.com/skg-if/api/persons/pers-1" // API link + "href": "https://acme.com/skg-if/api/products/prod-1" // search result 1 - parent entity : API link } ] - } + }, + { + "local_identifier": "https://w3id.org/skg-if/sandbox/acme/pers-1", // search result 1 - child entity : local_identifier / PID + "urls": [ + { + "entity_type": "link", + "rel": "self", + "href": "https://acme.com/skg-if/api/persons/pers-1" // search result 1 - child entity : API link + } + ] + }, + { + "local_identifier": "https://w3id.org/skg-if/sandbox/acme/prod-2", // search result 2 - parent entity : local_identifier / PID + "urls": [ + { + "entity_type": "link", + "rel": "self", + "href": "https://acme.com/skg-if/api/products/prod-2" // search result 2 - parent entity : API link + } + ] + }, ] }, "@graph": [ { - "local_identifier": "https://w3id.org/skg-if/sandbox/acme/prod-1", + "local_identifier": "https://w3id.org/skg-if/sandbox/acme/prod-1", // search result 1 - parent entity : local_identifier / PID "contributions": [ { "by" : { - "local_identifier": "https://w3id.org/skg-if/sandbox/acme/pers-1" + "local_identifier": "https://w3id.org/skg-if/sandbox/acme/pers-1" // search result 1 - child entity : local_identifier / PID //... } //... @@ -146,7 +166,7 @@ Get List of Product : `https://acme.com/skg-if/api/products?filter=xxx&page=1` //... }, { - "local_identifier": "https://w3id.org/skg-if/sandbox/acme/prod-1" + "local_identifier": "https://w3id.org/skg-if/sandbox/acme/prod-2" // search result 2 - parent entity : local_identifier / PID //... }, @@ -156,5 +176,23 @@ Get List of Product : `https://acme.com/skg-if/api/products?filter=xxx&page=1` ``` +## API Get Entity by Id, single entity resolving + +Single entity resolve API format follows this format `https://acme.com/skg-if/api/{entity-type}/{local_identifier}` + +For example : `https://acme.com/skg-if/api/products/prod-1` + +Your API _MUST_ also be able to resolve full local_identifiers including the domain/base : + +`https://acme.com/skg-if/api/products/https://w3id.org/skg-if/sandbox/acme/prod-1` + + +Note : this pattern is also used in standard SKG API like Crossref + +* http://api.crossref.org/works/https://doi.org/10.1039/d1cb00160d => OK +* http://api.crossref.org/works/10.1039/d1cb00160d => OK + + + 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 2f93561..e3ee541 100644 --- a/openapi/ver/current/sample_data/products/journal_article_full.json +++ b/openapi/ver/current/sample_data/products/journal_article_full.json @@ -7,19 +7,9 @@ } ], "meta": { - "local_identifier": "https://w3id.org/skg-if/sandbox/acme/prod-1", + "local_identifier": "https://acme.com/skg-if/api/products/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": [ diff --git a/openapi/ver/current/skg-if-openapi.yaml b/openapi/ver/current/skg-if-openapi.yaml index a127986..930f38f 100644 --- a/openapi/ver/current/skg-if-openapi.yaml +++ b/openapi/ver/current/skg-if-openapi.yaml @@ -115,14 +115,9 @@ paths: {"@base" : "https://w3id.org/skg-if/sandbox/acme/"} ] "meta" : - local_identifier: product-1-fgp + local_identifier: https://example.com/skg-if/api/products/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" @@ -217,14 +212,8 @@ paths: {"@base" : "https://w3id.org/skg-if/sandbox/acme/"} ] "meta" : - local_identifier: product-2-ogd + local_identifier: https://example.com/skg-if/api/products/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: product-2-ogd entity_type: product @@ -883,14 +872,9 @@ paths: {"@base" : "https://w3id.org/skg-if/sandbox/acme/"} ] "meta" : - local_identifier: grant-1-go + local_identifier: https://example.com/skg-if/api/grants/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" @@ -1135,14 +1119,8 @@ paths: {"@base" : "https://w3id.org/skg-if/sandbox/acme/"} ] "meta" : - local_identifier: venue-1-jp + local_identifier: https://example.com/skg-if/api/venues/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: venue-1-jp entity_type: "venue" @@ -1275,14 +1253,8 @@ paths: {"@base" : "https://w3id.org/skg-if/sandbox/acme/"} ] "meta" : - local_identifier: topic-1-cs + local_identifier: https://example.com/skg-if/api/topics/topc-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: topic-1-cs entity_type: "topic" @@ -1426,14 +1398,8 @@ paths: {"@base" : "https://w3id.org/skg-if/sandbox/acme/"} ] "meta" : - local_identifier: datasource-1-oura + local_identifier: https://example.com/skg-if/api/venues/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: datasource-1-oura entity_type: "datasource" @@ -2836,10 +2802,12 @@ components: properties: local_identifier: type: string - description: entity id as URL + description: Entity API URL. local_identifier can be expressed with ot without full domain. Full domain, including your @base, MUST also resolve examples: - - http://w3id.org/skg-if/sandbox/acme/product-1 - - http://w3id.org/skg-if/sandbox/acme/person-1 + - https://example.com/skg-if/api/products/product-1 + - https://example.com/skg-if/api/persons/person-1 + - https://acme.com/skg-if/api/products/https://w3id.org/skg-if/sandbox/acme/prod-1 + - https://acme.com/skg-if/api/persons/https://w3id.org/skg-if/sandbox/acme/person-1 entity_type: type: string description: single entity @@ -2969,7 +2937,7 @@ components: type: string description : | 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) \ + To define your `@base`, please refer to the [SKG-IF API doc](https://skg-if.github.io/api/) \ Your `@base` should end with a `/` \ common formats : \ - `https://acme.com/skg/` \