From 297072edb2e83f97ffbd81446072a70dcc94c659 Mon Sep 17 00:00:00 2001
From: duyme <duyme@esrf.fr>
Date: Sun, 16 Nov 2025 19:17:55 +0100
Subject: [PATCH 01/11] openapi json-ld search context

---
 openapi/ver/current/context/skg-if-api.json   |  32 ++
 .../current/sample_data/grants/grant_1.json   |  13 +-
 .../organisations/org_brown_university.json   |   5 +-
 .../products/journal_article_full.json        |  15 +-
 ...{test.json => journal_article_simple.json} |   5 +-
 openapi/ver/current/skg-if-openapi.yaml       | 367 +++++++++++-------
 6 files changed, 274 insertions(+), 163 deletions(-)
 create mode 100644 openapi/ver/current/context/skg-if-api.json
 rename openapi/ver/current/sample_data/products/{test.json => journal_article_simple.json} (73%)

diff --git a/openapi/ver/current/context/skg-if-api.json b/openapi/ver/current/context/skg-if-api.json
new file mode 100644
index 0000000..16691da
--- /dev/null
+++ b/openapi/ver/current/context/skg-if-api.json
@@ -0,0 +1,32 @@
+{
+    "@context": {
+        "@version": 1.0,
+        "@protected": true,
+        "as": "http://www.w3.org/ns/activitystreams#",
+        "search_result_page": {
+            "@id": "as:CollectionPage"
+        },
+        "search_result": {
+            "@id": "as:Collection"
+        },
+        "part_of": {
+            "@id": "as:partOf"
+        },
+        "total_items": {
+            "@id": "as:totalItems"
+        },
+        "next_page": {
+            "@id": "as:next"
+        },
+        "first_page": {
+            "@id": "as:first"
+        },
+        "last_page": {
+            "@id": "as:last"
+        },
+        "prev_page": {
+            "@id": "as:prev"
+        },
+        "meta": "@nest"
+    }
+}
\ 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 f0ee2bf..73daf2a 100644
--- a/openapi/ver/current/sample_data/grants/grant_1.json
+++ b/openapi/ver/current/sample_data/grants/grant_1.json
@@ -1,13 +1,14 @@
 {
     "@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/myprov/"
+            "@base": "https://w3id.org/skg-if/sandbox/my-skg-acronym/"
         }
     ],
     "@graph": [
         {
-            "local_identifier": "6f368a3a-b1cf-498f-b2de-27135d1e0011",
+            "local_identifier": "http://example.com/skg-if/api/grants/6f368a3a-b1cf-498f-b2de-27135d1e0011",
             "identifiers": [
                 {
                     "scheme": "doi",
@@ -24,7 +25,7 @@
             },
             "acronym": "GraspOS",
             "funding_agency": {
-                "local_identifier": "xxx",
+                "local_identifier": "http://example.com/skg-if/api/organisations/org-xxx",
                 "entity_type": "organisation",
                 "identifiers": [
                     {
@@ -47,7 +48,7 @@
             "website": "https://graspos.eu",
             "beneficiaries": [
                 {
-                    "local_identifier": "xxx",
+                    "local_identifier": "http://example.com/skg-if/api/organisations/xxx",
                     "entity_type": "organisation",
                     "identifiers": [
                         {
@@ -64,7 +65,7 @@
             "contributions": [
                 {
                     "by": {
-                        "local_identifier": "xxx",
+                        "local_identifier": "http://example.com/skg-if/api/persons/xxx",
                         "entity_type": "person",
                         "identifiers": [
                             {
@@ -78,7 +79,7 @@
                     },
                     "declared_affiliations": [
                         {
-                            "local_identifier": "xxx",
+                            "local_identifier": "http://example.com/skg-if/api/organisations/xxx",
                             "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 3b6084d..d1bc04e 100644
--- a/openapi/ver/current/sample_data/organisations/org_brown_university.json
+++ b/openapi/ver/current/sample_data/organisations/org_brown_university.json
@@ -1,13 +1,14 @@
 {
     "@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/myprov/"
+            "@base": "https://w3id.org/skg-if/sandbox/my-skg-acronym/"
         }
     ],
     "@graph": [
         {
-            "local_identifier": "6f368a3a-b1cf-498f-b2de-222222222",
+            "local_identifier": "http://example.com/skg-if/api/organisations/6f368a3a-b1cf-498f-b2de-222222222",
             "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 8221abf..c70f63f 100644
--- a/openapi/ver/current/sample_data/products/journal_article_full.json
+++ b/openapi/ver/current/sample_data/products/journal_article_full.json
@@ -1,13 +1,14 @@
 {
     "@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/myprov/"
+            "@base": "https://w3id.org/skg-if/sandbox/my-skg-acronym/"
         }
     ],
     "@graph": [
         {
-            "local_identifier": "614a6575-5d6c-416c-a8e1-ddd456d132",
+            "local_identifier": "http://example.com/skg-if/api/products/614a6575-5d6c-416c-a8e1-ddd456d132",
             "entity_type": "product",
             "product_type": "literature",
             "titles": {
@@ -47,13 +48,13 @@
                                 "scheme": "orcid"
                             }
                         ],
-                        "local_identifier": "614a6575-5d6c-416c-a8e1-f49a5d589bf8",
+                        "local_identifier": "http://example.com/skg-if/api/persons/614a6575-5d6c-416c-a8e1-f49a5d589bf8",
                         "entity_type": "person"
                     },
                     "declared_affiliations": [
                         {
                             "name": "Center for Plant Biotechnology and Genomics, Universidad Politécnica de Madrid, Madrid, 28223, Spain",
-                            "local_identifier": "32bc66c6-38be-4d5f-85db-d44c9f86921f",
+                            "local_identifier": "http://example.com/skg-if/api/organisations/32bc66c6-38be-4d5f-85db-d44c9f86921f",
                             "entity_type": "organisation",
                             "country": "ES"
                         }
@@ -71,7 +72,7 @@
                     },
                     "biblio": {
                         "hosting_data_source": {
-                            "local_identifier": "6f368a3a-b1cf-498f-b2de-27135d1e0075",
+                            "local_identifier": "http://example.com/skg-if/api/datasources/6f368a3a-b1cf-498f-b2de-27135d1e0075",
                             "entity_type": "datasource",
                             "name": "An Archive"
                         },
@@ -84,7 +85,7 @@
                                     "scheme": "issn"
                                 }
                             ],
-                            "local_identifier": "51f46bc1-00f8-42dd-8221-ac4deb52fb25",
+                            "local_identifier": "http://example.com/skg-if/api/venues/51f46bc1-00f8-42dd-8221-ac4deb52fb25",
                             "entity_type": "venue"
                         }
                     },
@@ -104,7 +105,7 @@
             ],
             "funding": [
                 {
-                    "local_identifier": "614a6575-5d6c-416c-a8e1-f49a5d58999",
+                    "local_identifier": "http://example.com/skg-if/api/grants/614a6575-5d6c-416c-a8e1-f49a5d58999",
                     "entity_type": "grant",
                     "titles": {
                         "en": "The EU grant ZZ",
diff --git a/openapi/ver/current/sample_data/products/test.json b/openapi/ver/current/sample_data/products/journal_article_simple.json
similarity index 73%
rename from openapi/ver/current/sample_data/products/test.json
rename to openapi/ver/current/sample_data/products/journal_article_simple.json
index 3102ae8..6ab81f3 100644
--- a/openapi/ver/current/sample_data/products/test.json
+++ b/openapi/ver/current/sample_data/products/journal_article_simple.json
@@ -1,13 +1,14 @@
 {
   "@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://example.com/skg-if/api/"
+      "@base": "https://w3id.org/skg-if/sandbox/my-skg-acronym/"
     }
   ],
   "@graph": [
     {
-      "local_identifier": "nl_47_id_47_dataset_47_toegang_47_2.05.32.01",
+      "local_identifier": "http://example.com/skg-if/api/products/nl_47_id_47_dataset_47_toegang_47_2.05.32.01",
       "identifiers": [
         {
           "scheme": "doi",
diff --git a/openapi/ver/current/skg-if-openapi.yaml b/openapi/ver/current/skg-if-openapi.yaml
index 8d1078f..cd9da05 100644
--- a/openapi/ver/current/skg-if-openapi.yaml
+++ b/openapi/ver/current/skg-if-openapi.yaml
@@ -13,20 +13,14 @@ info:
   description: |
     OpenAPI end points specifications for [SKG-IF](https://skg-if.github.io/interoperability-framework/)
 
+    Last version of the SKG-IF OpenAPI is available at : https://skg-if.github.io/api/
+
     # Note for implementers :
       - Please refer to [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](https://elements-demo.stoplight.io/)  (Use a public URL exposing the current file)
-      - This OpenAPI is compatible with [StopLight PRISM](https://docs.stoplight.io/docs/prism/).
-        - You can run a mock server, for testing purpose, before implementation.
-        - You can test your server implementation compatibility.
-      - All the errors returned MUST conform to format [RFC7807](https://datatracker.ietf.org/doc/html/rfc7807)
-
-    # JSON Output compatibility
-      - The JSON output of single entity operations _/entity-type/{local_identifier}_ are compatible with SKG-IF JSON-LD context (see @context version in response specifications).
-      - The JSON output of search entity operations _/entity-type?filter=xxx_ are JSON only.
-
-    __2025/03 : This is alpha unversionned release make sure you refresh/download the YAML regularly to get the last fixes__
+      - 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/)
 
 externalDocs:
   description: SKG-IF
@@ -52,9 +46,9 @@ tags: # upper case name
     description: Pagination description (can use markdown syntax)
     x-traitTag: true
 servers:
-  - url: 'http://example.com/api'
+  - url: 'http://example.com/skg-if/api'
 paths:
-  '/products/{local_identifier}':
+  '/products/{short_local_identifier}':
     get:
       tags:
           - Product
@@ -63,12 +57,11 @@ 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/localIdPathParam'
+        - $ref : '#/components/parameters/shortLocalIdPathParam'
       responses:
         '200':
           description: |
             Success.
-            Important : the output is JSON-LD and contains a `@context` and `@graph` keys.
           content:
             # not 'application/json-ld' to be compatible with StopLight PRISM tool
             application/json:
@@ -90,10 +83,11 @@ paths:
                   value :
                     "@context": [
                       "https://w3id.org/skg-if/context/1.1.0/skg-if.json",
-                      {"@base" : "https://w3id.org/skg-if/sandbox/myprov/"}
+                      "https://w3id.org/skg-if/context/1.0.0/skg-if-api.json",
+                      {"@base" : "https://w3id.org/skg-if/sandbox/my-skg-acronym/"}
                     ]
                     "@graph" :
-                      - local_identifier: prd-c66c6-38be-4d5f-85db-d44c9f869333
+                      - local_identifier: http://example.com/skg-if/api/products/prd-c66c6-38be-4d5f-85db-d44c9f869333
                         entity_type: product
                         product_type: literature
                         titles :
@@ -118,11 +112,11 @@ paths:
                               identifiers:
                               - value: "0000-0001-6960-357X"
                                 scheme: "orcid"
-                              local_identifier: "otf___1730027051396___person-1"
+                              local_identifier: http://example.com/skg-if/api/persons/otf___1730027051396___person-1
                               entity_type: "person"
                             declared_affiliations:
                               - name: "Center for Plant Biotechnology and Genomics, Universidad Politécnica de Madrid, Madrid, 28223, Spain"
-                                local_identifier: "otf___1730027051396___person-1-aff-1"
+                                local_identifier: http://example.com/skg-if/api/otf___1730027051396___person-1-aff-1
                                 entity_type: "organisation"
                                 country: "ES"
                         manifestations:
@@ -133,7 +127,7 @@ paths:
                               class: http://www.example.com/types/onto/localtypemethodology
                             biblio:
                               hosting_data_source:
-                                local_identifier: arch-6f368a3a-b1cf-498f-b2de-27135d1e0075
+                                local_identifier: http://example.com/skg-if/api/arch-6f368a3a-b1cf-498f-b2de-27135d1e0075
                                 entity_type: datasource
                                 name: "An Archive"
                               in:
@@ -142,7 +136,7 @@ paths:
                                 identifiers:
                                   - "value": "2052-4463"
                                     "scheme": "issn"
-                                local_identifier: "journal-46bc1-00f8-42dd-8221-ac4deb52fb25"
+                                local_identifier: http://example.com/skg-if/api/venues/journal-46bc1-00f8-42dd-8221-ac4deb52fb25
                                 entity_type: "venue"
                             dates: # http://api.crossref.org/works/10.1038/sdata.2016.18
                               publication:
@@ -161,10 +155,11 @@ paths:
                   value :
                     "@context": [
                        "https://w3id.org/skg-if/context/1.1.0/skg-if.json",
-                       {"@base" : "https://w3id.org/skg-if/sandbox/myprov/"}
+                       "https://w3id.org/skg-if/context/1.0.0/skg-if-api.json",
+                       {"@base" : "https://w3id.org/skg-if/sandbox/my-skg-acronym/"}
                     ]
                     "@graph" :
-                      - local_identifier: prd-c66c6-38be-4d5f-85db-d44c9f869555
+                      - local_identifier: http://example.com/skg-if/api/products/prd-c66c6-38be-4d5f-85db-d44c9f869555
                         entity_type: product
                         product_type: research data
                         titles :
@@ -192,13 +187,13 @@ paths:
           | product_type |  `product_type:literature` |
           | identifiers.id | `identifiers.id:10.1038/sdata.2016.18` |
           | identifiers.scheme | `identifiers.scheme:doi` |
-          | contributions.by. local_identifier |   `contributions.by. local_identifier:prod_1` |
+          | contributions.by. local_identifier |   `contributions.by. local_identifier:https://example.com/skg-if/api/products/prod_c66c6-38be-4d5f-85db-d44c9f869881` |
           | contributions.by. identifiers.id | `contributions.by. identifiers.id:0000-0002-1825-0097` |
           | contributions.by. identifiers.scheme | `contributions.by. identifiers.scheme:orcid` |
           | contributions.by. family_name |   `contributions.by. family_name:smith` |
           | contributions.by. given_name |   `contributions.by. given_name:john` |
           | contributions.by. name |   `contributions.by. name:john smith` |
-          | contributions.declared_affiliations. local_identifier | `contributions.declared_affiliations. local_identifier:org_1` |
+          | contributions.declared_affiliations. local_identifier | `contributions.declared_affiliations. local_identifier:https://example.com/skg-if/api/organisations/org_c66c6-38be-4d5f-85db-d44c9f869881` |
           | contributions.declared_affiliations. identifiers.id | `contributions.declared_affiliations. identifiers.id:05gq02987` |
           | contributions.declared_affiliations. identifiers.scheme | `contributions.declared_affiliations. identifiers.scheme:ror` |
           | contributions.declared_affiliations. name | `contributions.declared_affiliations. name:brown university` |
@@ -261,7 +256,6 @@ paths:
         '200':
           description: |
             Success.
-            Important : The output is JSON with `meta` and `results` keys. It is not JSON-LD, it does not contain any `@context` or `@graph` keys. There is an issue [#9](https://github.com/skg-if/context/issues/9) to fix this.
           content:
             application/json:
               schema:
@@ -269,38 +263,50 @@ paths:
                   meta:
                     type: object
                     $ref: '#/components/schemas/Meta'
-                  results:
+                  "@graph":
                     type: array
                     items:
                       $ref: '#/components/schemas/Product'
-                required: [ "meta", "results" ]
+                required: [ "meta", "@graph" ]
               examples:
                 JournalArticleListEx01:
                     summary: A list of journal articles
                     value :
                       meta:
-                        count: 2
-                        page: 1
-                        page_size: 10
-                      results:
-                        - local_identifier: prd-c66c6-38be-4d5f-85db-d44c9f869333
+                        local_identifier: https://example.com/skg-if/api/products?filter=product_type:literature&page=1
+                        entity_type: search_result_page
+                        next_page:
+                          local_identifier: https://example.com/skg-if/api/products?filter=product_type:literature&page=2
+                          entity_type: search_result_page
+                        part_of:
+                          local_identifier: https://example.com/skg-if/api/products?filter=product_type:literature
+                          entity_type: search_result
+                          total_items: 54231
+                      "@graph":
+                        - local_identifier: http://example.com/skg-if/api/products/prd-c66c6-38be-4d5f-85db-d44c9f869333
                           entity_type: product
                           product_type: literature
-                        - local_identifier: prd-c66c6-38be-4d5f-85db-d44c9f869999
+                        - local_identifier: http://example.com/skg-if/api/products/prd-c66c6-38be-4d5f-85db-d44c9f869999
                           entity_type: product
                           product_type: research data
                 DatasetListEx02:
                     summary: A list of datasets
                     value :
                       meta:
-                        count: 2
-                        page: 1
-                        page_size: 10
-                      results:
-                        - local_identifier: prd-c66c6-38be-4d5f-85db-d44c9f869888
+                        local_identifier: http://example.com/skg-if/api/products?filter=product_type:research%20data&page=1
+                        entity_type: search_result_page
+                        next_page:
+                          local_identifier: http://example.com/skg-if/api/products?filter=product_type:research%20data&page=2
+                          entity_type: search_result_page
+                        part_of:
+                          local_identifier: http://example.com/skg-if/api/products?filter=product_type:research%20data
+                          entity_type: search_result
+                          total_items: 13202
+                      "@graph":
+                        - local_identifier: http://example.com/skg-if/api/products/prd-c66c6-38be-4d5f-85db-d44c9f869888
                           entity_type: product
                           product_type: research data
-                        - local_identifier: prd-c66c6-38be-4d5f-85db-d44c9f869881
+                        - local_identifier: http://example.com/skg-if/api/products/prd-c66c6-38be-4d5f-85db-d44c9f869881
                           entity_type: product
                           product_type: research data
         '422':
@@ -318,7 +324,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/{local_identifier}':
+  '/persons/{short_local_identifier}':
     get:
       tags:
           - Person
@@ -327,7 +333,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/localIdPathParam'
+        - $ref : '#/components/parameters/shortLocalIdPathParam'
       responses:
         '200':
           description: Success
@@ -351,10 +357,11 @@ paths:
                   value :
                     "@context": [
                       "https://w3id.org/skg-if/context/1.1.0/skg-if.json",
+                      "https://w3id.org/skg-if/context/1.0.0/skg-if-api.json",
                       {"@base" : "http://example.com/"}
                     ]
                     "@graph" :
-                      - local_identifier: pers-c66c6-38be-4d5f-85db-d44c9f869333
+                      - local_identifier: http://example.com/skg-if/api/persons/pers-c66c6-38be-4d5f-85db-d44c9f869333
                         entity_type: "person"
                         identifiers:
                           - scheme: orcid
@@ -367,10 +374,11 @@ paths:
                   value :
                     "@context": [
                       "https://w3id.org/skg-if/context/1.1.0/skg-if.json",
+                      "https://w3id.org/skg-if/context/1.0.0/skg-if-api.json",
                       {"@base" : "http://example.com/"}
                     ]
                     "@graph" :
-                      - local_identifier: otf_126848135_prod-1-pers-1
+                      - local_identifier: http://example.com/skg-if/api/persons/otf_126848135_prod-1-pers-1
                         entity_type: "person"
                         name: "John Doe"
   '/persons':
@@ -391,7 +399,7 @@ paths:
           | given_name | `given_name:Josiah` |
           | family_name |  `family_name:Carberry` |
           | name |  `name:Josiah Carberro` |
-          | affiliations.affiliation.local_identifier | `affiliations.affiliation.local_identifier:pers_1` |
+          | affiliations.affiliation.local_identifier | `affiliations.affiliation.local_identifier:http://example.com/skg-if/api/organisations/org-c66c6-38be-4d5f-85db-d44c9f869333` |
           | affiliations.affiliation.name | `affiliations.affiliation.name:Brown University` |
           | affiliations.affiliation.short_name |  `affiliations.affiliation.short_name:BU` |
           | affiliations.role | `affiliations.role:affiliate` |
@@ -436,21 +444,27 @@ paths:
                   meta:
                     type: object
                     $ref: '#/components/schemas/Meta'
-                  results:
+                  "@graph":
                     type: array
                     items:
                       $ref: '#/components/schemas/Person'
-                required: [ "meta", "results" ]
+                required: [ "meta", "@graph" ]
               examples:
                 PersonEx01:
                     summary: a list of persons
                     value :
                       meta:
-                        count: 2
-                        page: 1
-                        page_size: 10
-                      results:
-                        - local_identifier: pers-c66c6-38be-4d5f-85db-d44c9f869333
+                          local_identifier: https://example.com/skg-if/api/persons?filter=family_name:Carberry&page=1
+                          entity_type: search_result_page
+                          next_page:
+                            local_identifier: https://example.com/skg-if/api/persons?filter=family_name:Carberry&page=2
+                            entity_type: search_result_page
+                          part_of:
+                            local_identifier: https://example.com/skg-if/api/persons?filter=family_name:Carberry
+                            entity_type: search_result
+                            total_items: 4
+                      "@graph":
+                        - local_identifier: http://example.com/skg-if/api/persons/pers-c66c6-38be-4d5f-85db-d44c9f869333
                           entity_type: "person"
                           identifiers:
                             - scheme: orcid
@@ -458,11 +472,11 @@ paths:
                           given_name: "Josiah"
                           family_name:  "Carberry"
                           name: "Josiah Carberry"
-                        - local_identifier: pers-c66c6-38be-4d5f-85db-d44c9f869888
+                        - local_identifier: http://example.com/skg-if/api/persons/pers-c66c6-38be-4d5f-85db-d44c9f869888
                           entity_type: "person"
-                          given_name: "Botul"
-                          family_name:  "Jean-Baptiste"
-                          name: "Jean-Baptiste Botul"
+                          given_name: "Gerard"
+                          family_name:  "Carberry"
+                          name: "Gerard Carberry"
                 #PersonEx02: # commented KO on StopLight UI, OK on Redoc UI, Not used in PRISM
                 #  summary: "a list of persons - external URL"
                 #  externalValue: "https://raw.githubusercontent.com/skg-if/examples/refs/heads/main/OpenCitations/oc_1.json"
@@ -470,8 +484,8 @@ paths:
             address:
               operationId: getPersonById
               parameters:
-                local_identifier: $response.body#/results/local_identifier
-  '/organisations/{local_identifier}':
+                local_identifier: $response.body#/@graph/local_identifier
+  '/organisations/{short_local_identifier}':
     get:
       tags:
           - Organisation
@@ -480,7 +494,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/localIdPathParam'
+        - $ref : '#/components/parameters/shortLocalIdPathParam'
       responses:
         '200':
           description: Success
@@ -505,9 +519,10 @@ paths:
                   value :
                     "@context":
                       - "https://w3id.org/skg-if/context/1.1.0/skg-if.json"
-                      - "@base" : "https://w3id.org/skg-if/sandbox/myprov/"
+                      - "https://w3id.org/skg-if/context/1.0.0/skg-if-api.json"
+                      - "@base" : "https://w3id.org/skg-if/sandbox/my-skg-acronym/"
                     "@graph":
-                      - local_identifier: 'otf_session12324_org_1124'
+                      - local_identifier: http://example.com/skg-if/api/organisations/otf_session12324_org_1124
                         entity_type: 'organisation'
                         identifiers:
                           - scheme: ror
@@ -522,9 +537,10 @@ paths:
                   value :
                     "@context":
                       - "https://w3id.org/skg-if/context/1.1.0/skg-if.json"
-                      - "@base" : "https://w3id.org/skg-if/sandbox/myprov/"
+                      - "https://w3id.org/skg-if/context/1.0.0/skg-if-api.json"
+                      - "@base" : "https://w3id.org/skg-if/sandbox/my-skg-acronym/"
                     "@graph":
-                      - local_identifier: 'otf_session12325_org_1125'
+                      - local_identifier: http://example.com/skg-if/api/organisations/otf_session12325_org_1125
                         entity_type: 'organisation'
                         identifiers:
                           - scheme: ror
@@ -541,9 +557,10 @@ paths:
                   value :
                     "@context":
                       - "https://w3id.org/skg-if/context/1.1.0/skg-if.json"
-                      - "@base" : "https://w3id.org/skg-if/sandbox/myprov/"
+                      - "https://w3id.org/skg-if/context/1.0.0/skg-if-api.json"
+                      - "@base" : "https://w3id.org/skg-if/sandbox/my-skg-acronym/"
                     "@graph":
-                      - local_identifier: 'otf_session12325_org_1126'
+                      - local_identifier: http://example.com/skg-if/api/organisations/otf_session12325_org_1126
                         entity_type: 'organisation'
                         name: Lab of science, unknown University, Antarctica
                 OrgEuropeanCommission:
@@ -551,9 +568,10 @@ paths:
                   value :
                     "@context":
                       - "https://w3id.org/skg-if/context/1.1.0/skg-if.json"
-                      - "@base" : "https://w3id.org/skg-if/sandbox/myprov/"
+                      - "https://w3id.org/skg-if/context/1.0.0/skg-if-api.json"
+                      - "@base" : "https://w3id.org/skg-if/sandbox/my-skg-acronym/"
                     "@graph":
-                      - local_identifier: 'otf_session12324_org_1127'
+                      - local_identifier: http://example.com/skg-if/api/organisations/otf_session12324_org_1127
                         entity_type: 'organisation'
                         identifiers:
                           - scheme: ror
@@ -621,12 +639,12 @@ paths:
                   meta:
                     type: object
                     $ref: '#/components/schemas/Meta'
-                  results:
+                  "@graph":
                     type: array
                     items:
                       $ref: '#/components/schemas/Organisation'
-                required: [ "meta", "results" ]
-  '/grants/{local_identifier}':
+                required: [ "meta", "@graph" ]
+  '/grants/{short_local_identifier}':
     get:
       tags:
           - Grant
@@ -635,7 +653,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/localIdPathParam'
+        - $ref : '#/components/parameters/shortLocalIdPathParam'
       responses:
         '200':
           description: Success
@@ -660,10 +678,11 @@ paths:
                   value :
                     "@context": [
                       "https://w3id.org/skg-if/context/1.1.0/skg-if.json",
-                      {"@base" : "http://example.com/"}
+                      "https://w3id.org/skg-if/context/1.0.0/skg-if-api.json",
+                      {"@base" : "https://w3id.org/skg-if/sandbox/my-skg-acronym/"}
                     ]
                     "@graph" :
-                      - local_identifier: grant-c66c6-38be-4d5f-85db-d44c9f869333
+                      - local_identifier: http://example.com/skg-if/api/grants/grant-c66c6-38be-4d5f-85db-d44c9f869333
                         entity_type: "grant"
                         identifiers:
                           - scheme: "doi"
@@ -676,7 +695,7 @@ paths:
                         }
                         acronym: "GraspOS"
                         funding_agency:
-                          local_identifier: "otf___1730027051396___org-1"
+                          local_identifier: http://example.com/skg-if/api/grants/otf___1730027051396___org-1
                           entity_type: "organisation"
                           identifiers:
                             - scheme: "ror"
@@ -693,7 +712,7 @@ paths:
                           end: "2025-12-31T23:59:59Z"
                         website: "https://graspos.eu"
                         beneficiaries:
-                          - local_identifier: "otf___1730027051396___org-2"
+                          - local_identifier: http://example.com/skg-if/api/organisations/otf___1730027051396___org-2
                             entity_type: "organisation"
                             identifiers:
                               - scheme: "ror"
@@ -704,7 +723,7 @@ paths:
                             website: "https://www.brown.edu/"
                         contributions:
                           - by:
-                              local_identifier: "otf___1730027051396___pers-1"
+                              local_identifier: http://example.com/skg-if/api/persons/otf___1730027051396___pers-1
                               entity_type: "person"
                               identifiers:
                                 - scheme: "orcid"
@@ -749,13 +768,13 @@ paths:
           | beneficiaries.short_name |  `beneficiaries.short_name:BU` |
           | beneficiaries.website | `beneficiaries.website:https://www.brown.edu` |
           | beneficiaries.country | `beneficiaries.country:US` |
-          | contributions.by.local_identifier | `contributions.by.local_identifier:xxx` |
+          | contributions.by.local_identifier | `contributions.by.local_identifier:http://example.com/skg-if/api/persons/yyy` |
           | contributions.by.identifiers.scheme | `contributions.by.identifiers.scheme:orcid` |
           | contributions.by.identifiers.value | `contributions.by.identifiers.value:0000-0002-1825-0097` |
           | contributions.by.given_name | `contributions.by.given_name:Josiah` |
           | contributions.by.family_name |  `contributions.by.family_name:Carberry` |
           | contributions.by.name |  `contributions.by.name:Josiah Carberro` |
-          | contributions.declared_affiliations.local_identifier | `contributions.declared_affiliations.local_identifier:yyy` |
+          | contributions.declared_affiliations.local_identifier | `contributions.declared_affiliations.local_identifier:http://example.com/skg-if/api/organisations/ooo` |
           | contributions.declared_affiliations.identifiers.scheme | `contributions.declared_affiliations.identifiers.scheme:ror` |
           | contributions.declared_affiliations.identifiers.value | `contributions.declared_affiliations.identifiers.value:https://ror.org/05gq02987` |
           | contributions.declared_affiliations.name | `contributions.declared_affiliations.name:Brown University` |
@@ -819,12 +838,12 @@ paths:
                   meta:
                     type: object
                     $ref: '#/components/schemas/Meta'
-                  results:
+                  "@graph":
                     type: array
                     items:
                       $ref: '#/components/schemas/Grant'
-                required: [ "meta", "results" ]
-  '/venues/{local_identifier}':
+                required: [ "meta", "@graph" ]
+  '/venues/{short_local_identifier}':
     get:
       tags:
           - Venue
@@ -833,7 +852,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/localIdPathParam'
+        - $ref : '#/components/parameters/shortLocalIdPathParam'
       responses:
         '200':
           description: Success
@@ -858,10 +877,11 @@ paths:
                   value :
                     "@context": [
                       "https://w3id.org/skg-if/context/1.1.0/skg-if.json",
-                      {"@base" : "http://example.com/"}
+                      "https://w3id.org/skg-if/context/1.0.0/skg-if-api.json",
+                      {"@base" : "https://w3id.org/skg-if/sandbox/my-skg-acronym/"}
                     ]
                     "@graph" :
-                      - local_identifier: venue-c66c6-38be-4d5f-85db-d44c9f869333
+                      - local_identifier: http://example.com/skg-if/api/venues/venue-c66c6-38be-4d5f-85db-d44c9f869333
                         entity_type: "venue"
                         identifiers:
                           - scheme: issn
@@ -920,12 +940,12 @@ paths:
                   meta:
                     type: object
                     $ref: '#/components/schemas/Meta'
-                  results:
+                  "@graph":
                     type: array
                     items:
                       $ref: '#/components/schemas/Venue'
-                required: [ "meta", "results" ]
-  '/topics/{local_identifier}':
+                required: [ "meta", "@graph" ]
+  '/topics/{short_local_identifier}':
     get:
       tags:
           - Topic
@@ -934,7 +954,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/localIdPathParam'
+        - $ref : '#/components/parameters/shortLocalIdPathParam'
       responses:
         '200':
           description: Success
@@ -959,10 +979,11 @@ paths:
                   value :
                     "@context": [
                       "https://w3id.org/skg-if/context/1.1.0/skg-if.json",
-                      {"@base" : "http://example.com/"}
+                      "https://w3id.org/skg-if/context/1.0.0/skg-if-api.json",
+                      {"@base" : "https://w3id.org/skg-if/sandbox/my-skg-acronym/"}
                     ]
                     "@graph" :
-                      - local_identifier: topic-c66c6-38be-4d5f-85db-d44c9f869333
+                      - local_identifier: http://example.com/skg-if/api/topics/topic-c66c6-38be-4d5f-85db-d44c9f869333
                         entity_type: "topic"
                         identifiers:
                           - scheme: wikidata
@@ -1032,12 +1053,12 @@ paths:
                   meta:
                     type: object
                     $ref: '#/components/schemas/Meta'
-                  results:
+                  "@graph":
                     type: array
                     items:
                       $ref: '#/components/schemas/Topic'
-                required: [ "meta", "results" ]
-  '/datasources/{local_identifier}':
+                required: [ "meta", "@graph" ]
+  '/datasources/{short_local_identifier}':
     get:
       tags:
           - Data Source
@@ -1046,7 +1067,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/localIdPathParam'
+        - $ref : '#/components/parameters/shortLocalIdPathParam'
       responses:
         '200':
           description: Success
@@ -1071,10 +1092,11 @@ paths:
                   value :
                     "@context": [
                       "https://w3id.org/skg-if/context/1.1.0/skg-if.json",
-                      {"@base" : "http://example.com/"}
+                      "https://w3id.org/skg-if/context/1.0.0/skg-if-api.json",
+                      {"@base" : "https://w3id.org/skg-if/sandbox/my-skg-acronym/"}
                     ]
                     "@graph" :
-                      - local_identifier: datasrc-c66c6-38be-4d5f-85db-d44c9f869333
+                      - local_identifier: http://example.com/skg-if/api/datasources/datasrc-c66c6-38be-4d5f-85db-d44c9f869333
                         entity_type: "datasource"
                         identifiers:
                           - scheme: doi
@@ -1135,11 +1157,11 @@ paths:
                   meta:
                     type: object
                     $ref: '#/components/schemas/Meta'
-                  results:
+                  "@graph":
                     type: array
                     items:
                       $ref: '#/components/schemas/DataSource'
-                required: [ "meta", "results" ]
+                required: [ "meta", "@graph" ]
 components:
   securitySchemes:
     main_auth:
@@ -1158,10 +1180,13 @@ components:
       type: http
       scheme: basic
   parameters:
-    localIdPathParam:
-      name: local_identifier
+    shortLocalIdPathParam:
+      name: short_local_identifier
       in: path
-      description: The [local identifier](https://skg-if.github.io/interoperability-framework/#local-identifiers-of-entities) that needs to be fetched
+      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`
       required: true
       schema:
         type: string
@@ -1177,14 +1202,14 @@ components:
       name: page
       in: query
       description: |
-            Search page number.
+            Search page reference (page number or search iteration token)
       schema:
-        type: integer
+        type: string
     pageSizeQueryParam:
       name: page_size
       in: query
       description: |
-            Search page size.
+            Search page size. limit search result size.
       schema:
         type: integer
   schemas:
@@ -1284,7 +1309,7 @@ components:
               $ref: '#/components/schemas/ProductRelated'
 
       examples:
-        - local_identifier: xxx
+        - local_identifier: http://example.com/skg-if/api/products/xxx
           entity_type: product
           product_type: literature
           titles :
@@ -1308,11 +1333,11 @@ components:
                 identifiers:
                 - value: "0000-0001-6960-357X"
                   scheme: "orcid"
-                local_identifier: "614a6575-5d6c-416c-a8e1-f49a5d589bf8"
+                local_identifier: http://example.com/skg-if/api/persons/614a6575-5d6c-416c-a8e1-f49a5d589bf8
                 entity_type: "person"
               declared_affiliations:
                 - name: "Center for Plant Biotechnology and Genomics, Universidad Politécnica de Madrid, Madrid, 28223, Spain"
-                  local_identifier: "32bc66c6-38be-4d5f-85db-d44c9f86921f"
+                  local_identifier: http://example.com/skg-if/api/persons/32bc66c6-38be-4d5f-85db-d44c9f86921f
                   entity_type: "organisation"
                   country: "ES"
           manifestations:
@@ -1323,7 +1348,7 @@ components:
                 class: http://www.example.com/types/onto/localtypemethodology
               biblio:
                 hosting_data_source:
-                  local_identifier: 6f368a3a-b1cf-498f-b2de-27135d1e0075
+                  local_identifier: http://example.com/skg-if/api/datasources/6f368a3a-b1cf-498f-b2de-27135d1e0075
                   entity_type: datasource
                   name: "An Archive"
                 in:
@@ -1332,7 +1357,7 @@ components:
                   identifiers:
                     - "value": "2052-4463"
                       "scheme": "issn"
-                  local_identifier: "51f46bc1-00f8-42dd-8221-ac4deb52fb25"
+                  local_identifier: http://example.com/skg-if/api/datasources/51f46bc1-00f8-42dd-8221-ac4deb52fb25
                   entity_type: "venue"
               dates: # http://api.crossref.org/works/10.1038/sdata.2016.18
                 publication:
@@ -1343,7 +1368,7 @@ components:
                 deposit:
                   - "2023-01-04"
           funding:
-            - local_identifier: "614a6575-5d6c-416c-a8e1-f49a5d58999"
+            - local_identifier: http://example.com/skg-if/api/grants/614a6575-5d6c-416c-a8e1-f49a5d58999
               entity_type: "grant"
               titles:
                - en: "EU grant ZZ"
@@ -1770,7 +1795,7 @@ components:
           country: US
           types":
             - education
-        - local_identifier: 'otf_session12325_org_1125'
+        - local_identifier: http://example.com/skg-if/api/organisations/otf_session12325_org_1125
           entity_type: 'organisation'
           identifiers:
             - scheme: ror
@@ -1782,10 +1807,10 @@ components:
           country: US
           types:
             - archive
-        - local_identifier: 'otf_session12325_org_1126'
+        - local_identifier: http://example.com/skg-if/api/organisations/otf_session12325_org_1126
           entity_type: 'organisation'
           name: Lab of science, unknown University, Antarctica
-        - local_identifier: 'otf_session12324_org_1127'
+        - local_identifier: http://example.com/skg-if/api/organisations/otf_session12324_org_1127
           entity_type: 'organisation'
           identifiers:
             - scheme: ror
@@ -1830,7 +1855,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: 'otf_session12324_person_1124'
+        - local_identifier: http://example.com/skg-if/api/persons/otf_session12324_person_1124
           entity_type: 'person'
           identifiers:
             - scheme: orcid
@@ -1844,7 +1869,7 @@ components:
               start: "2010-08-24"
               end: "2020-08-24"
             affiliation:
-              local_identifier: 'otf_session12324_org_1124'
+              local_identifier: http://example.com/skg-if/api/organisatios/otf_session12324_org_1124
               entity_type: 'organisation'
               identifiers:
                 - scheme: ror
@@ -1905,7 +1930,7 @@ components:
               examples :
                 - Josiah Carberro
       examples:
-        - local_identifier: 'otf_session12324_person_1124'
+        - local_identifier: http://example.com/skg-if/api/persons/otf_session12324_person_1124
           entity_type: 'person'
           identifiers:
             - scheme: orcid
@@ -2284,8 +2309,9 @@ components:
         local_identifier:
           type: string
           description: |
-            Unique local identifier of the entity. \
-              It should be resolvable with the URL `/<entity_type_get_operation>/<local_identifier>` ex: `/products/c66c6-38be-4d5f-85db-d44c9` \
+            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___<session identifier>___<identifier string>`.
             -  `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;
@@ -2295,7 +2321,10 @@ components:
           x-faker:
             fake : ['{{random.uuid}}']
           examples:
-            - c66c6-38be-4d5f-85db-d44c9
+            - 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
         identifiers:
           type: array
           items:
@@ -2312,21 +2341,59 @@ components:
     Meta:
       type: object
       properties:
-        count:
-          description: total results count
-          type: integer
-          x-faker:
-            datatype.number: [{min: 100, max: 200}]
-        page:
-          description: current result page
-          type: integer
-          x-faker:
-            datatype.number: [{min: 1, max: 3}]
-        page_size:
-          description: page size
-          type: integer
-          x-faker:
-            datatype.number: [{min: 10, max: 10}]
+        local_identifier:
+          type: string
+          description: search result page id
+          examples:
+            - https://example.com/skg-if/api/products?filter=xxx&page=y
+            - https://example.com/skg-if/api/persons?filter=xxx&page=y
+        entity_type:
+          type: string
+          description: search result page type
+          enum:
+            - search_result_page
+        prev_page:
+          type: object
+          $ref: '#/components/schemas/SearchResultPage'
+        next_page:
+          type: object
+          $ref: '#/components/schemas/SearchResultPage'
+        part_of:
+          type: object
+          properties:
+            local_identifier:
+              type: string
+              description: search id. URL
+              examples:
+                - https://example.com/skg-if/api/products?filter=xxx
+                - https://example.com/skg-if/api/persons?filter=xxx
+            entity_type:
+              type: string
+              description: search type
+              enum:
+                - search_result
+            total_items:
+              description: search number of items
+              type: integer
+              x-faker:
+                datatype.number: [{min: 10, max: 100}]
+            first_page:
+              type: object
+              $ref: '#/components/schemas/SearchResultPage'
+            last_page:
+              type: object
+              $ref: '#/components/schemas/SearchResultPage'
+    SearchResultPage:
+        type: object
+        properties:
+          local_identifier:
+                type: string
+                description: search result page id. URL
+          entity_type:
+            type: string
+            description: search result page type
+            enum:
+              - search_result_page
     Error:
         type: object
         properties:
@@ -2358,33 +2425,41 @@ components:
               information if dereferenced.
     JsonLdCtx:
       type: object
-      description: "This JSON-LD context for SKG-IF entities"
+      description: "JSON-LD context for SKG-IF OpenAPI output"
       properties:
         "@context":
-          description: JSON-LD context for SKG-IF entities
+          description: JSON-LD context
           type: array
-          minItems: 1
-          maxItems: 2
+          minItems: 3 # http://../skg-if.json, http://../skg-if-api.json and @base
+          uniqueItems: true
           items:
             anyOf:
               - type: string
-                description: "URL to SKG-IF context supported by the current OpenApi"
+                description: "URL to SKG-IF data model context supported by the current OpenAPI"
                 enum:
                   - https://w3id.org/skg-if/context/1.1.0/skg-if.json
-                #default: "https://w3id.org/skg-if/context/1.1.0/skg-if.json"
                 x-faker:
                   fake: ['https://w3id.org/skg-if/context/1.1.0/skg-if.json']
-                #examples:
-                # - "https://w3id.org/skg-if/context/1.1.0/skg-if.json"
+              - type: string
+                description: "URL to SKG-IF API context supported by the current OpenAPI"
+                enum:
+                  - https://w3id.org/skg-if/context/1.0.0/skg-if-api.json
+                x-faker:
+                  fake: ['https://w3id.org/skg-if/context/1.0.0/skg-if-api.json']
               - type: object
                 properties:
                   "@base":
                     type: string
-                    description : "Default base URL specific to the implementer. https://w3id.org/skg-if/sandbox/provider_accronym/"
+                    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/`
                     x-faker:
-                      fake: ['https://w3id.org/skg-if/sandbox/my_prov/']
+                      fake: ['https://w3id.org/skg-if/sandbox/{{random.alpha(5)}}/']
                     examples:
-                     - "https://w3id.org/skg-if/sandbox/my_prov/"
+                     - "https://w3id.org/skg-if/sandbox/openaire/"
+                     - "https://w3id.org/skg-if/sandbox/cessda/"
+                     - "https://w3id.org/skg-if/sandbox/foobar/"
                 #required: ["@base"]
                 additionalProperties:
                   type: string
@@ -2398,5 +2473,5 @@ components:
           #]
           additionalProperties: false
           examples:
-            - ["https://w3id.org/skg-if/context/1.1.0/skg-if.json", {"@base" : "https://w3id.org/skg-if/sandbox/my_prov/"}]
+            - ["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/"}]
       required: [ "@context" ]

From 5aded786e9723169a07d824c483fbe02da3c3db3 Mon Sep 17 00:00:00 2001
From: duyme <duyme@esrf.fr>
Date: Sun, 16 Nov 2025 19:36:20 +0100
Subject: [PATCH 02/11] openapi remove journal_article_simple.json

---
 .../products/journal_article_simple.json      | 32 -------------------
 1 file changed, 32 deletions(-)
 delete mode 100644 openapi/ver/current/sample_data/products/journal_article_simple.json

diff --git a/openapi/ver/current/sample_data/products/journal_article_simple.json b/openapi/ver/current/sample_data/products/journal_article_simple.json
deleted file mode 100644
index 6ab81f3..0000000
--- a/openapi/ver/current/sample_data/products/journal_article_simple.json
+++ /dev/null
@@ -1,32 +0,0 @@
-{
-  "@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/"
-    }
-  ],
-  "@graph": [
-    {
-      "local_identifier": "http://example.com/skg-if/api/products/nl_47_id_47_dataset_47_toegang_47_2.05.32.01",
-      "identifiers": [
-        {
-          "scheme": "doi",
-          "value": "https://archief.nl/id/dataset/toegang/2.05.32.01"
-        }
-      ],
-      "entity_type": "product",
-      "product_type": "literature",
-      "titles": {
-        "nl": [
-          "Inventaris van het archief van het Ministerie van Buitenlandse Zaken: Bureau Bescherming, 1916-1939"
-        ]
-      },
-      "abstracts": {
-        "nl": [
-          "Inventaris van het archief van het Ministerie van Buitenlandse Zaken: Bureau Bescherming, 1916-1939"
-        ]
-      }
-    }
-  ]
-}
\ No newline at end of file

From f2e86754101103dc62734ab4672dfe57a76275f9 Mon Sep 17 00:00:00 2001
From: duyme <duyme@esrf.fr>
Date: Sun, 16 Nov 2025 20:19:59 +0100
Subject: [PATCH 03/11] openapi meta section comments

---
 openapi/ver/current/skg-if-openapi.yaml | 20 +++++++++++++++-----
 1 file changed, 15 insertions(+), 5 deletions(-)

diff --git a/openapi/ver/current/skg-if-openapi.yaml b/openapi/ver/current/skg-if-openapi.yaml
index cd9da05..f3fffaa 100644
--- a/openapi/ver/current/skg-if-openapi.yaml
+++ b/openapi/ver/current/skg-if-openapi.yaml
@@ -2340,6 +2340,7 @@ components:
           type: string
     Meta:
       type: object
+      required: [ "local_identifier", "entity_type" ]
       properties:
         local_identifier:
           type: string
@@ -2353,34 +2354,40 @@ components:
           enum:
             - search_result_page
         prev_page:
+          description: Previous page reference
           type: object
           $ref: '#/components/schemas/SearchResultPage'
         next_page:
+          description: Next page reference
           type: object
           $ref: '#/components/schemas/SearchResultPage'
         part_of:
+          description: Reference for the search result as a whole (all pages)
           type: object
+          required: [ "local_identifier", "entity_type" ]
           properties:
             local_identifier:
               type: string
-              description: search id. URL
+              description: search result id as URL
               examples:
                 - https://example.com/skg-if/api/products?filter=xxx
                 - https://example.com/skg-if/api/persons?filter=xxx
             entity_type:
               type: string
-              description: search type
+              description: search type. Value must be `search_result`
               enum:
                 - search_result
             total_items:
-              description: search number of items
+              description: total number of item entities for the search
               type: integer
               x-faker:
                 datatype.number: [{min: 10, max: 100}]
             first_page:
+              description: First page reference of the search
               type: object
               $ref: '#/components/schemas/SearchResultPage'
             last_page:
+              description: Last page reference of the search
               type: object
               $ref: '#/components/schemas/SearchResultPage'
     SearchResultPage:
@@ -2388,10 +2395,13 @@ components:
         properties:
           local_identifier:
                 type: string
-                description: search result page id. URL
+                description: search result page id as URL
+                examples:
+                  - https://example.com/skg-if/api/products?filter=xxx&page=y
+                  - https://example.com/skg-if/api/persons?filter=xxx&page=y
           entity_type:
             type: string
-            description: search result page type
+            description: search result page type. Value must be `search_result_page`
             enum:
               - search_result_page
     Error:

From 564efd16253808db5090a6a8c11d95985b0be5ae Mon Sep 17 00:00:00 2001
From: duyme <duyme@esrf.fr>
Date: Sun, 16 Nov 2025 20:47:21 +0100
Subject: [PATCH 04/11] openapi add 404 doc

---
 openapi/ver/current/skg-if-openapi.yaml | 38 +++++++++++++++++++++++--
 1 file changed, 35 insertions(+), 3 deletions(-)

diff --git a/openapi/ver/current/skg-if-openapi.yaml b/openapi/ver/current/skg-if-openapi.yaml
index f3fffaa..df16ac2 100644
--- a/openapi/ver/current/skg-if-openapi.yaml
+++ b/openapi/ver/current/skg-if-openapi.yaml
@@ -171,6 +171,9 @@ paths:
                             scheme: "doi"
                           - value: "W4393781519"
                             scheme: "openalex"
+        '404':
+          description: |
+            Error if entity does not exists
   '/products':
     get:
       tags:
@@ -381,6 +384,9 @@ paths:
                       - local_identifier: http://example.com/skg-if/api/persons/otf_126848135_prod-1-pers-1
                         entity_type: "person"
                         name: "John Doe"
+        '404':
+          description: |
+            Error if entity does not exists
   '/persons':
     get:
       tags:
@@ -580,6 +586,9 @@ paths:
                         short_name: EU
                         types:
                           - funder
+        '404':
+          description: |
+            Error if entity does not exists
   '/organisations':
     get:
       tags:
@@ -743,6 +752,9 @@ paths:
                                   website: "https://www.brown.edu/"
                               roles:
                                 - "co-applicant"
+        '404':
+          description: |
+            Error if entity does not exists
   '/grants':
     get:
       tags:
@@ -889,6 +901,9 @@ paths:
                         name: Journal of Psychoceramics
                         acronym: JPC
                         type: journal
+        '404':
+          description: |
+            Error if entity does not exists
   '/venues':
     get:
       tags:
@@ -991,6 +1006,9 @@ paths:
                         labels:
                           en: "Computer Science"
                           it: "Informatica"
+        '404':
+          description: |
+            Error if entity does not exists
   '/topics':
     get:
       tags:
@@ -1106,6 +1124,9 @@ paths:
                         research_product_types:
                           - "research data"
                           - "literature"
+        '404':
+          description: |
+            Error if entity does not exists
   '/datasources':
     get:
       tags:
@@ -1202,7 +1223,8 @@ components:
       name: page
       in: query
       description: |
-            Search page reference (page number or search iteration token)
+            Search page reference (page number or search iteration token).\
+            Note: As a client application you should build your iterating logic using the `meta.next_page.local_identifier` and `meta.prev_page.local_identifier` URLs
       schema:
         type: string
     pageSizeQueryParam:
@@ -2435,7 +2457,17 @@ components:
               information if dereferenced.
     JsonLdCtx:
       type: object
-      description: "JSON-LD context for SKG-IF OpenAPI output"
+      description: |
+        JSON-LD context for SKG-IF OpenAPI output \
+        ``` json
+          "@context": [
+            "https://w3id.org/skg-if/context/1.1.0/skg-if.json", => SKG-IF data model context elements
+            "https://w3id.org/skg-if/context/1.0.0/skg-if-api.json", => SKG-IF API context elements (meta section)
+            {
+              "@base": "https://w3id.org/skg-if/sandbox/my-skg-acronym/" => JSON-LD @base fallback.
+            }
+          ]
+        ```
       properties:
         "@context":
           description: JSON-LD context
@@ -2451,7 +2483,7 @@ components:
                 x-faker:
                   fake: ['https://w3id.org/skg-if/context/1.1.0/skg-if.json']
               - type: string
-                description: "URL to SKG-IF API context supported by the current OpenAPI"
+                description: "URL to SKG-IF API context (meta section) supported by the current OpenAPI"
                 enum:
                   - https://w3id.org/skg-if/context/1.0.0/skg-if-api.json
                 x-faker:

From 86ec646bf979b0db3804eb8fbae2c23e82ef996d Mon Sep 17 00:00:00 2001
From: duyme <duyme@esrf.fr>
Date: Sun, 16 Nov 2025 20:54:03 +0100
Subject: [PATCH 05/11] openapi JsonLdCtx doc

---
 openapi/ver/current/skg-if-openapi.yaml | 24 ++++++++++++------------
 1 file changed, 12 insertions(+), 12 deletions(-)

diff --git a/openapi/ver/current/skg-if-openapi.yaml b/openapi/ver/current/skg-if-openapi.yaml
index df16ac2..de1c352 100644
--- a/openapi/ver/current/skg-if-openapi.yaml
+++ b/openapi/ver/current/skg-if-openapi.yaml
@@ -2457,20 +2457,20 @@ components:
               information if dereferenced.
     JsonLdCtx:
       type: object
-      description: |
-        JSON-LD context for SKG-IF OpenAPI output \
-        ``` json
-          "@context": [
-            "https://w3id.org/skg-if/context/1.1.0/skg-if.json", => SKG-IF data model context elements
-            "https://w3id.org/skg-if/context/1.0.0/skg-if-api.json", => SKG-IF API context elements (meta section)
-            {
-              "@base": "https://w3id.org/skg-if/sandbox/my-skg-acronym/" => JSON-LD @base fallback.
-            }
-          ]
-        ```
+      description: ""
       properties:
         "@context":
-          description: JSON-LD context
+          description: |
+            JSON-LD context for SKG-IF OpenAPI output.
+            ``` json
+            "@context": [
+              "https://w3id.org/skg-if/context/1.1.0/skg-if.json", => SKG-IF data model context elements
+              "https://w3id.org/skg-if/context/1.0.0/skg-if-api.json", => SKG-IF API context elements (meta section)
+              {
+                "@base": "https://w3id.org/skg-if/sandbox/my-skg-acronym/" => JSON-LD @base fallback.
+              }
+            ]
+            ```
           type: array
           minItems: 3 # http://../skg-if.json, http://../skg-if-api.json and @base
           uniqueItems: true

From 2b80b0ef492e7fb965b067aaea203e0e7b4256f8 Mon Sep 17 00:00:00 2001
From: duyme <duyme@esrf.fr>
Date: Sun, 16 Nov 2025 21:03:15 +0100
Subject: [PATCH 06/11] openapi JsonLdCtx title

---
 openapi/ver/current/skg-if-openapi.yaml | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/openapi/ver/current/skg-if-openapi.yaml b/openapi/ver/current/skg-if-openapi.yaml
index de1c352..fda42e4 100644
--- a/openapi/ver/current/skg-if-openapi.yaml
+++ b/openapi/ver/current/skg-if-openapi.yaml
@@ -2460,7 +2460,7 @@ components:
       description: ""
       properties:
         "@context":
-          description: |
+          title: |
             JSON-LD context for SKG-IF OpenAPI output.
             ``` json
             "@context": [
@@ -2489,6 +2489,7 @@ components:
                 x-faker:
                   fake: ['https://w3id.org/skg-if/context/1.0.0/skg-if-api.json']
               - type: object
+                description : "additional context mappings (ex: @base)"
                 properties:
                   "@base":
                     type: string

From b0da1fed7f23bb62ffc45fc1838aa75bb1d0c5e0 Mon Sep 17 00:00:00 2001
From: duyme <duyme@esrf.fr>
Date: Sun, 16 Nov 2025 21:30:42 +0100
Subject: [PATCH 07/11] openapi JsonLdCtx search operation

---
 openapi/ver/current/skg-if-openapi.yaml | 299 +++++++++++++-----------
 1 file changed, 164 insertions(+), 135 deletions(-)

diff --git a/openapi/ver/current/skg-if-openapi.yaml b/openapi/ver/current/skg-if-openapi.yaml
index fda42e4..6654446 100644
--- a/openapi/ver/current/skg-if-openapi.yaml
+++ b/openapi/ver/current/skg-if-openapi.yaml
@@ -66,17 +66,17 @@ paths:
             # not 'application/json-ld' to be compatible with StopLight PRISM tool
             application/json:
               schema:
-                allOf:
-                  - $ref: "#/components/schemas/JsonLdCtx"
-                  - type: object
-                    required: ['@graph']
-                    properties:
-                      "@graph":
-                        type: array
-                        minItems: 1
-                        maxItems: 1
-                        items:
-                          $ref: "#/components/schemas/Product"
+                required: ['@context','@graph']
+                properties:
+                  "@context":
+                    type: object
+                    $ref: '#/components/schemas/JsonLdCtx'
+                  "@graph":
+                    type: array
+                    minItems: 1
+                    maxItems: 1
+                    items:
+                      $ref: "#/components/schemas/Product"
               examples:
                 JournalArticleEx01:
                   summary: "Journal article - FAIR Guiding Principles"
@@ -263,6 +263,9 @@ paths:
             application/json:
               schema:
                 properties:
+                  "@context":
+                    type: object
+                    $ref: '#/components/schemas/JsonLdCtx'
                   meta:
                     type: object
                     $ref: '#/components/schemas/Meta'
@@ -270,11 +273,15 @@ paths:
                     type: array
                     items:
                       $ref: '#/components/schemas/Product'
-                required: [ "meta", "@graph" ]
+                required: [ "@context", "meta", "@graph" ]
               examples:
                 JournalArticleListEx01:
                     summary: A list of journal articles
                     value :
+                      "@context":
+                       - "https://w3id.org/skg-if/context/1.1.0/skg-if.json"
+                       - "https://w3id.org/skg-if/context/1.0.0/skg-if-api.json"
+                       - "@base" : "https://w3id.org/skg-if/sandbox/my-skg-acronym/"
                       meta:
                         local_identifier: https://example.com/skg-if/api/products?filter=product_type:literature&page=1
                         entity_type: search_result_page
@@ -295,6 +302,10 @@ paths:
                 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/"
                       meta:
                         local_identifier: http://example.com/skg-if/api/products?filter=product_type:research%20data&page=1
                         entity_type: search_result_page
@@ -343,17 +354,17 @@ paths:
           content:
             application/json:
               schema:
-                allOf:
-                  - $ref: "#/components/schemas/JsonLdCtx"
-                  - type: object
-                    required: ['@graph']
-                    properties:
-                      "@graph":
-                        type: array
-                        minItems: 1
-                        maxItems: 1
-                        items:
-                          $ref: "#/components/schemas/Person"
+                required: ['@context','@graph']
+                properties:
+                  "@context":
+                    type: object
+                    $ref: '#/components/schemas/JsonLdCtx'
+                  "@graph":
+                    type: array
+                    minItems: 1
+                    maxItems: 1
+                    items:
+                      $ref: "#/components/schemas/Person"
               examples:
                 PersonEx01:
                   summary: Josiah Carberry person
@@ -447,6 +458,9 @@ paths:
             application/json:
               schema:
                 properties:
+                  "@context":
+                    type: object
+                    $ref: '#/components/schemas/JsonLdCtx'
                   meta:
                     type: object
                     $ref: '#/components/schemas/Meta'
@@ -454,11 +468,15 @@ paths:
                     type: array
                     items:
                       $ref: '#/components/schemas/Person'
-                required: [ "meta", "@graph" ]
+                required: [ "@context", "meta", "@graph" ]
               examples:
                 PersonEx01:
                     summary: a list of persons
                     value :
+                      "@context":
+                       - "https://w3id.org/skg-if/context/1.1.0/skg-if.json"
+                       - "https://w3id.org/skg-if/context/1.0.0/skg-if-api.json"
+                       - "@base" : "https://w3id.org/skg-if/sandbox/my-skg-acronym/"
                       meta:
                           local_identifier: https://example.com/skg-if/api/persons?filter=family_name:Carberry&page=1
                           entity_type: search_result_page
@@ -508,17 +526,17 @@ paths:
             # not 'application/json-ld' to be compatible with StopLight PRISM tool
             application/json:
               schema:
-                allOf:
-                  - $ref: "#/components/schemas/JsonLdCtx"
-                  - type: object
-                    required: ['@graph']
-                    properties:
-                      "@graph":
-                        type: array
-                        minItems: 1
-                        maxItems: 1
-                        items:
-                          $ref: "#/components/schemas/Organisation"
+                required: ['@context','@graph']
+                properties:
+                  "@context":
+                    type: object
+                    $ref: '#/components/schemas/JsonLdCtx'
+                  "@graph":
+                    type: array
+                    minItems: 1
+                    maxItems: 1
+                    items:
+                      $ref: "#/components/schemas/Organisation"
               examples:
                 OrgBrownUniversity:
                   summary: "Brown University"
@@ -645,6 +663,9 @@ paths:
             application/json:
               schema:
                 properties:
+                  "@context":
+                    type: object
+                    $ref: '#/components/schemas/JsonLdCtx'
                   meta:
                     type: object
                     $ref: '#/components/schemas/Meta'
@@ -652,7 +673,7 @@ paths:
                     type: array
                     items:
                       $ref: '#/components/schemas/Organisation'
-                required: [ "meta", "@graph" ]
+                required: [ "@context", "meta", "@graph" ]
   '/grants/{short_local_identifier}':
     get:
       tags:
@@ -670,17 +691,17 @@ paths:
             # not 'application/json-ld' to be compatible with StopLight PRISM tool
             application/json:
               schema:
-                allOf:
-                  - $ref: "#/components/schemas/JsonLdCtx"
-                  - type: object
-                    required: ['@graph']
-                    properties:
-                      "@graph":
-                        type: array
-                        minItems: 1
-                        maxItems: 1
-                        items:
-                          $ref: "#/components/schemas/Grant"
+                required: ['@context','@graph']
+                properties:
+                  "@context":
+                    type: object
+                    $ref: '#/components/schemas/JsonLdCtx'
+                  "@graph":
+                    type: array
+                    minItems: 1
+                    maxItems: 1
+                    items:
+                      $ref: "#/components/schemas/Grant"
               examples:
                 GrantEx01:
                   summary: GraspOS grant
@@ -847,6 +868,9 @@ paths:
             application/json:
               schema:
                 properties:
+                  "@context":
+                    type: object
+                    $ref: '#/components/schemas/JsonLdCtx'
                   meta:
                     type: object
                     $ref: '#/components/schemas/Meta'
@@ -854,7 +878,7 @@ paths:
                     type: array
                     items:
                       $ref: '#/components/schemas/Grant'
-                required: [ "meta", "@graph" ]
+                required: [ "@context", "meta", "@graph" ]
   '/venues/{short_local_identifier}':
     get:
       tags:
@@ -872,17 +896,17 @@ paths:
             # not 'application/json-ld' to be compatible with StopLight PRISM tool
             application/json:
               schema:
-                allOf:
-                  - $ref: "#/components/schemas/JsonLdCtx"
-                  - type: object
-                    required: ['@graph']
-                    properties:
-                      "@graph":
-                        type: array
-                        minItems: 1
-                        maxItems: 1
-                        items:
-                          $ref: "#/components/schemas/Venue"
+                required: ['@context','@graph']
+                properties:
+                  "@context":
+                    type: object
+                    $ref: '#/components/schemas/JsonLdCtx'
+                  "@graph":
+                    type: array
+                    minItems: 1
+                    maxItems: 1
+                    items:
+                      $ref: "#/components/schemas/Venue"
               examples:
                 VenueEx01:
                   summary: Journal of Psychoceramics venue
@@ -952,6 +976,9 @@ paths:
             application/json:
               schema:
                 properties:
+                  "@context":
+                    type: object
+                    $ref: '#/components/schemas/JsonLdCtx'
                   meta:
                     type: object
                     $ref: '#/components/schemas/Meta'
@@ -959,7 +986,7 @@ paths:
                     type: array
                     items:
                       $ref: '#/components/schemas/Venue'
-                required: [ "meta", "@graph" ]
+                required: [ "@context", "meta", "@graph" ]
   '/topics/{short_local_identifier}':
     get:
       tags:
@@ -977,17 +1004,17 @@ paths:
             # not 'application/json-ld' to be compatible with StopLight PRISM tool
             application/json:
               schema:
-                allOf:
-                  - $ref: "#/components/schemas/JsonLdCtx"
-                  - type: object
-                    required: ['@graph']
-                    properties:
-                      "@graph":
-                        type: array
-                        minItems: 1
-                        maxItems: 1
-                        items:
-                         $ref: "#/components/schemas/Topic"
+                required: ['@context','@graph']
+                properties:
+                  "@context":
+                    type: object
+                    $ref: '#/components/schemas/JsonLdCtx'
+                  "@graph":
+                    type: array
+                    minItems: 1
+                    maxItems: 1
+                    items:
+                      $ref: "#/components/schemas/Topic"
               examples:
                 TopicEx01:
                   summary: Computer Science topic
@@ -1068,6 +1095,9 @@ paths:
             application/json:
               schema:
                 properties:
+                  "@context":
+                    type: object
+                    $ref: '#/components/schemas/JsonLdCtx'
                   meta:
                     type: object
                     $ref: '#/components/schemas/Meta'
@@ -1075,7 +1105,7 @@ paths:
                     type: array
                     items:
                       $ref: '#/components/schemas/Topic'
-                required: [ "meta", "@graph" ]
+                required: [ "@context", "meta", "@graph" ]
   '/datasources/{short_local_identifier}':
     get:
       tags:
@@ -1093,17 +1123,17 @@ paths:
             # not 'application/json-ld' to be compatible with StopLight PRISM tool
             application/json:
               schema:
-                allOf:
-                  - $ref: "#/components/schemas/JsonLdCtx"
-                  - type: object
-                    required: ['@graph']
-                    properties:
-                      "@graph":
-                        type: array
-                        minItems: 1
-                        maxItems: 1
-                        items:
-                          $ref: "#/components/schemas/DataSource"
+                required: ['@context','@graph']
+                properties:
+                  "@context":
+                    type: object
+                    $ref: '#/components/schemas/JsonLdCtx'
+                  "@graph":
+                    type: array
+                    minItems: 1
+                    maxItems: 1
+                    items:
+                      $ref: "#/components/schemas/DataSource"
               examples:
                 DatasourceEx01:
                   summary: Oxford University Research Archive datasource
@@ -1175,6 +1205,9 @@ paths:
             application/json:
               schema:
                 properties:
+                  "@context":
+                    type: object
+                    $ref: '#/components/schemas/JsonLdCtx'
                   meta:
                     type: object
                     $ref: '#/components/schemas/Meta'
@@ -1182,7 +1215,7 @@ paths:
                     type: array
                     items:
                       $ref: '#/components/schemas/DataSource'
-                required: [ "meta", "@graph" ]
+                required: [ "@context", "meta", "@graph" ]
 components:
   securitySchemes:
     main_auth:
@@ -2456,11 +2489,8 @@ components:
               occurrence of the problem.  It may or may not yield further
               information if dereferenced.
     JsonLdCtx:
-      type: object
-      description: ""
-      properties:
-        "@context":
-          title: |
+      type: array
+      description: |
             JSON-LD context for SKG-IF OpenAPI output.
             ``` json
             "@context": [
@@ -2471,50 +2501,49 @@ components:
               }
             ]
             ```
-          type: array
-          minItems: 3 # http://../skg-if.json, http://../skg-if-api.json and @base
-          uniqueItems: true
-          items:
-            anyOf:
-              - type: string
-                description: "URL to SKG-IF data model context supported by the current OpenAPI"
-                enum:
-                  - https://w3id.org/skg-if/context/1.1.0/skg-if.json
-                x-faker:
-                  fake: ['https://w3id.org/skg-if/context/1.1.0/skg-if.json']
-              - type: string
-                description: "URL to SKG-IF API context (meta section) supported by the current OpenAPI"
-                enum:
-                  - https://w3id.org/skg-if/context/1.0.0/skg-if-api.json
+      minItems: 3 # http://../skg-if.json, http://../skg-if-api.json and @base
+      uniqueItems: true
+      items:
+        anyOf:
+          - type: string
+            description: "URL to SKG-IF data model context supported by the current OpenAPI"
+            enum:
+              - https://w3id.org/skg-if/context/1.1.0/skg-if.json
+            x-faker:
+              fake: ['https://w3id.org/skg-if/context/1.1.0/skg-if.json']
+          - type: string
+            description: "URL to SKG-IF API context (meta section) supported by the current OpenAPI"
+            enum:
+              - https://w3id.org/skg-if/context/1.0.0/skg-if-api.json
+            x-faker:
+              fake: ['https://w3id.org/skg-if/context/1.0.0/skg-if-api.json']
+          - type: object
+            description : "additional context mappings (ex: @base)"
+            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/`
                 x-faker:
-                  fake: ['https://w3id.org/skg-if/context/1.0.0/skg-if-api.json']
-              - type: object
-                description : "additional context mappings (ex: @base)"
-                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/`
-                    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/"
-                #required: ["@base"]
-                additionalProperties:
-                  type: string
-                  description: "context URL of extension entities"
-                  x-faker:
-                    fake : ['http://www.example.com/skg-if/{{random.alpha(3)}}']
-            #required: [ skgifjson]
-          #anyOf: [
-          #  required: [ skgifjson, skgifimpl],
-          #  required: [ skgifjson]
-          #]
-          additionalProperties: false
-          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/"}]
-      required: [ "@context" ]
+                  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/"
+            #required: ["@base"]
+            additionalProperties:
+              type: string
+              description: "context URL of extension entities"
+              x-faker:
+                fake : ['http://www.example.com/skg-if/{{random.alpha(3)}}']
+        #required: [ skgifjson]
+      #anyOf: [
+      #  required: [ skgifjson, skgifimpl],
+      #  required: [ skgifjson]
+      #]
+      additionalProperties: false
+      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/"}]
+

From c5ed4d5a8a96861b193ce3cdb747f0d7c56187f7 Mon Sep 17 00:00:00 2001
From: duyme <duyme@esrf.fr>
Date: Sun, 16 Nov 2025 21:44:07 +0100
Subject: [PATCH 08/11] openapi JsonLdCtx

---
 openapi/ver/current/skg-if-openapi.yaml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/openapi/ver/current/skg-if-openapi.yaml b/openapi/ver/current/skg-if-openapi.yaml
index 6654446..ec284c0 100644
--- a/openapi/ver/current/skg-if-openapi.yaml
+++ b/openapi/ver/current/skg-if-openapi.yaml
@@ -70,6 +70,7 @@ paths:
                 properties:
                   "@context":
                     type: object
+                    description: JSON-LD context
                     $ref: '#/components/schemas/JsonLdCtx'
                   "@graph":
                     type: array

From c69ee488b66d4995159703977af9dbee23da0b03 Mon Sep 17 00:00:00 2001
From: duyme <duyme@esrf.fr>
Date: Sun, 16 Nov 2025 21:52:35 +0100
Subject: [PATCH 09/11] openapi context doc

---
 openapi/ver/current/skg-if-openapi.yaml | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/openapi/ver/current/skg-if-openapi.yaml b/openapi/ver/current/skg-if-openapi.yaml
index ec284c0..122ec8e 100644
--- a/openapi/ver/current/skg-if-openapi.yaml
+++ b/openapi/ver/current/skg-if-openapi.yaml
@@ -70,7 +70,7 @@ paths:
                 properties:
                   "@context":
                     type: object
-                    description: JSON-LD context
+                    description: JSON-LD context # not displayed in Stoplight elements
                     $ref: '#/components/schemas/JsonLdCtx'
                   "@graph":
                     type: array
@@ -2491,7 +2491,7 @@ components:
               information if dereferenced.
     JsonLdCtx:
       type: array
-      description: |
+      description: | # not displayed in Stoplight elements
             JSON-LD context for SKG-IF OpenAPI output.
             ``` json
             "@context": [
@@ -2507,19 +2507,19 @@ components:
       items:
         anyOf:
           - type: string
-            description: "URL to SKG-IF data model context supported by the current OpenAPI"
+            description: "URL to SKG-IF data model context supported by the current OpenAPI `https://w3id.org/skg-if/context/1.1.0/skg-if.json`"
             enum:
               - https://w3id.org/skg-if/context/1.1.0/skg-if.json
             x-faker:
               fake: ['https://w3id.org/skg-if/context/1.1.0/skg-if.json']
           - type: string
-            description: "URL to SKG-IF API context (meta section) supported by the current OpenAPI"
+            description: "URL to SKG-IF API context (meta section) supported by the current OpenAPI `https://w3id.org/skg-if/context/1.0.0/skg-if-api.json`"
             enum:
               - https://w3id.org/skg-if/context/1.0.0/skg-if-api.json
             x-faker:
               fake: ['https://w3id.org/skg-if/context/1.0.0/skg-if-api.json']
           - type: object
-            description : "additional context mappings (ex: @base)"
+            description : 'Additional context mappings ex: `{ "@base":"https://w3id.org/skg-if/sandbox/my-skg-acronym" }`'
             properties:
               "@base":
                 type: string

From 63e485f19b16cabfb6b5a3f44c305d4141d995bd Mon Sep 17 00:00:00 2001
From: duyme <duyme@esrf.fr>
Date: Sun, 16 Nov 2025 22:12:01 +0100
Subject: [PATCH 10/11] openapi context version fix

---
 openapi/ver/current/context/skg-if-api.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/openapi/ver/current/context/skg-if-api.json b/openapi/ver/current/context/skg-if-api.json
index 16691da..e59988e 100644
--- a/openapi/ver/current/context/skg-if-api.json
+++ b/openapi/ver/current/context/skg-if-api.json
@@ -1,6 +1,6 @@
 {
     "@context": {
-        "@version": 1.0,
+        "@version": 1.1,
         "@protected": true,
         "as": "http://www.w3.org/ns/activitystreams#",
         "search_result_page": {

From be76939d55fdd08606a2ec6206d773a5d2c5c981 Mon Sep 17 00:00:00 2001
From: duyme <duyme@esrf.fr>
Date: Mon, 17 Nov 2025 09:28:52 +0100
Subject: [PATCH 11/11] openapi context array validation fix

---
 openapi/ver/current/skg-if-openapi.yaml | 274 ++++++++++++++++--------
 1 file changed, 187 insertions(+), 87 deletions(-)

diff --git a/openapi/ver/current/skg-if-openapi.yaml b/openapi/ver/current/skg-if-openapi.yaml
index 122ec8e..dbf3ef7 100644
--- a/openapi/ver/current/skg-if-openapi.yaml
+++ b/openapi/ver/current/skg-if-openapi.yaml
@@ -69,9 +69,17 @@ paths:
                 required: ['@context','@graph']
                 properties:
                   "@context":
-                    type: object
+                    type: array
                     description: JSON-LD context # not displayed in Stoplight elements
-                    $ref: '#/components/schemas/JsonLdCtx'
+                    minItems: 3 # http://../skg-if.json, http://../skg-if-api.json and @base
+                    uniqueItems: true
+                    items:
+                      anyOf:
+                        - $ref: '#/components/schemas/JsonLdCtxDataModel'
+                        - $ref: '#/components/schemas/JsonLdCtxSearch'
+                        - $ref: '#/components/schemas/JsonLdCtxBaseOrMore'
+                    examples:
+                      - ["https://w3id.org/skg-if/context/1.1.0/skg-if.json", "https://w3id.org/skg-if/context/1.0.0/skg-if-api.json", {"@base" : "https://w3id.org/skg-if/sandbox/my-skg-acronym/"}]
                   "@graph":
                     type: array
                     minItems: 1
@@ -265,8 +273,17 @@ paths:
               schema:
                 properties:
                   "@context":
-                    type: object
-                    $ref: '#/components/schemas/JsonLdCtx'
+                    type: array
+                    description: JSON-LD context # not displayed in Stoplight elements
+                    minItems: 3 # http://../skg-if.json, http://../skg-if-api.json and @base
+                    uniqueItems: true
+                    items:
+                      anyOf:
+                        - $ref: '#/components/schemas/JsonLdCtxDataModel'
+                        - $ref: '#/components/schemas/JsonLdCtxSearch'
+                        - $ref: '#/components/schemas/JsonLdCtxBaseOrMore'
+                    examples:
+                      - ["https://w3id.org/skg-if/context/1.1.0/skg-if.json", "https://w3id.org/skg-if/context/1.0.0/skg-if-api.json", {"@base" : "https://w3id.org/skg-if/sandbox/my-skg-acronym/"}]
                   meta:
                     type: object
                     $ref: '#/components/schemas/Meta'
@@ -358,8 +375,17 @@ paths:
                 required: ['@context','@graph']
                 properties:
                   "@context":
-                    type: object
-                    $ref: '#/components/schemas/JsonLdCtx'
+                    type: array
+                    description: JSON-LD context # not displayed in Stoplight elements
+                    minItems: 3 # http://../skg-if.json, http://../skg-if-api.json and @base
+                    uniqueItems: true
+                    items:
+                      anyOf:
+                        - $ref: '#/components/schemas/JsonLdCtxDataModel'
+                        - $ref: '#/components/schemas/JsonLdCtxSearch'
+                        - $ref: '#/components/schemas/JsonLdCtxBaseOrMore'
+                    examples:
+                      - ["https://w3id.org/skg-if/context/1.1.0/skg-if.json", "https://w3id.org/skg-if/context/1.0.0/skg-if-api.json", {"@base" : "https://w3id.org/skg-if/sandbox/my-skg-acronym/"}]
                   "@graph":
                     type: array
                     minItems: 1
@@ -460,8 +486,17 @@ paths:
               schema:
                 properties:
                   "@context":
-                    type: object
-                    $ref: '#/components/schemas/JsonLdCtx'
+                    type: array
+                    description: JSON-LD context # not displayed in Stoplight elements
+                    minItems: 3 # http://../skg-if.json, http://../skg-if-api.json and @base
+                    uniqueItems: true
+                    items:
+                      anyOf:
+                        - $ref: '#/components/schemas/JsonLdCtxDataModel'
+                        - $ref: '#/components/schemas/JsonLdCtxSearch'
+                        - $ref: '#/components/schemas/JsonLdCtxBaseOrMore'
+                    examples:
+                      - ["https://w3id.org/skg-if/context/1.1.0/skg-if.json", "https://w3id.org/skg-if/context/1.0.0/skg-if-api.json", {"@base" : "https://w3id.org/skg-if/sandbox/my-skg-acronym/"}]
                   meta:
                     type: object
                     $ref: '#/components/schemas/Meta'
@@ -530,8 +565,17 @@ paths:
                 required: ['@context','@graph']
                 properties:
                   "@context":
-                    type: object
-                    $ref: '#/components/schemas/JsonLdCtx'
+                    type: array
+                    description: JSON-LD context # not displayed in Stoplight elements
+                    minItems: 3 # http://../skg-if.json, http://../skg-if-api.json and @base
+                    uniqueItems: true
+                    items:
+                      anyOf:
+                        - $ref: '#/components/schemas/JsonLdCtxDataModel'
+                        - $ref: '#/components/schemas/JsonLdCtxSearch'
+                        - $ref: '#/components/schemas/JsonLdCtxBaseOrMore'
+                    examples:
+                      - ["https://w3id.org/skg-if/context/1.1.0/skg-if.json", "https://w3id.org/skg-if/context/1.0.0/skg-if-api.json", {"@base" : "https://w3id.org/skg-if/sandbox/my-skg-acronym/"}]
                   "@graph":
                     type: array
                     minItems: 1
@@ -665,8 +709,17 @@ paths:
               schema:
                 properties:
                   "@context":
-                    type: object
-                    $ref: '#/components/schemas/JsonLdCtx'
+                    type: array
+                    description: JSON-LD context # not displayed in Stoplight elements
+                    minItems: 3 # http://../skg-if.json, http://../skg-if-api.json and @base
+                    uniqueItems: true
+                    items:
+                      anyOf:
+                        - $ref: '#/components/schemas/JsonLdCtxDataModel'
+                        - $ref: '#/components/schemas/JsonLdCtxSearch'
+                        - $ref: '#/components/schemas/JsonLdCtxBaseOrMore'
+                    examples:
+                      - ["https://w3id.org/skg-if/context/1.1.0/skg-if.json", "https://w3id.org/skg-if/context/1.0.0/skg-if-api.json", {"@base" : "https://w3id.org/skg-if/sandbox/my-skg-acronym/"}]
                   meta:
                     type: object
                     $ref: '#/components/schemas/Meta'
@@ -695,8 +748,17 @@ paths:
                 required: ['@context','@graph']
                 properties:
                   "@context":
-                    type: object
-                    $ref: '#/components/schemas/JsonLdCtx'
+                    type: array
+                    description: JSON-LD context # not displayed in Stoplight elements
+                    minItems: 3 # http://../skg-if.json, http://../skg-if-api.json and @base
+                    uniqueItems: true
+                    items:
+                      anyOf:
+                        - $ref: '#/components/schemas/JsonLdCtxDataModel'
+                        - $ref: '#/components/schemas/JsonLdCtxSearch'
+                        - $ref: '#/components/schemas/JsonLdCtxBaseOrMore'
+                    examples:
+                      - ["https://w3id.org/skg-if/context/1.1.0/skg-if.json", "https://w3id.org/skg-if/context/1.0.0/skg-if-api.json", {"@base" : "https://w3id.org/skg-if/sandbox/my-skg-acronym/"}]
                   "@graph":
                     type: array
                     minItems: 1
@@ -870,8 +932,17 @@ paths:
               schema:
                 properties:
                   "@context":
-                    type: object
-                    $ref: '#/components/schemas/JsonLdCtx'
+                    type: array
+                    description: JSON-LD context # not displayed in Stoplight elements
+                    minItems: 3 # http://../skg-if.json, http://../skg-if-api.json and @base
+                    uniqueItems: true
+                    items:
+                      anyOf:
+                        - $ref: '#/components/schemas/JsonLdCtxDataModel'
+                        - $ref: '#/components/schemas/JsonLdCtxSearch'
+                        - $ref: '#/components/schemas/JsonLdCtxBaseOrMore'
+                    examples:
+                      - ["https://w3id.org/skg-if/context/1.1.0/skg-if.json", "https://w3id.org/skg-if/context/1.0.0/skg-if-api.json", {"@base" : "https://w3id.org/skg-if/sandbox/my-skg-acronym/"}]
                   meta:
                     type: object
                     $ref: '#/components/schemas/Meta'
@@ -900,8 +971,17 @@ paths:
                 required: ['@context','@graph']
                 properties:
                   "@context":
-                    type: object
-                    $ref: '#/components/schemas/JsonLdCtx'
+                    type: array
+                    description: JSON-LD context # not displayed in Stoplight elements
+                    minItems: 3 # http://../skg-if.json, http://../skg-if-api.json and @base
+                    uniqueItems: true
+                    items:
+                      anyOf:
+                        - $ref: '#/components/schemas/JsonLdCtxDataModel'
+                        - $ref: '#/components/schemas/JsonLdCtxSearch'
+                        - $ref: '#/components/schemas/JsonLdCtxBaseOrMore'
+                    examples:
+                      - ["https://w3id.org/skg-if/context/1.1.0/skg-if.json", "https://w3id.org/skg-if/context/1.0.0/skg-if-api.json", {"@base" : "https://w3id.org/skg-if/sandbox/my-skg-acronym/"}]
                   "@graph":
                     type: array
                     minItems: 1
@@ -978,8 +1058,17 @@ paths:
               schema:
                 properties:
                   "@context":
-                    type: object
-                    $ref: '#/components/schemas/JsonLdCtx'
+                    type: array
+                    description: JSON-LD context # not displayed in Stoplight elements
+                    minItems: 3 # http://../skg-if.json, http://../skg-if-api.json and @base
+                    uniqueItems: true
+                    items:
+                      anyOf:
+                        - $ref: '#/components/schemas/JsonLdCtxDataModel'
+                        - $ref: '#/components/schemas/JsonLdCtxSearch'
+                        - $ref: '#/components/schemas/JsonLdCtxBaseOrMore'
+                    examples:
+                      - ["https://w3id.org/skg-if/context/1.1.0/skg-if.json", "https://w3id.org/skg-if/context/1.0.0/skg-if-api.json", {"@base" : "https://w3id.org/skg-if/sandbox/my-skg-acronym/"}]
                   meta:
                     type: object
                     $ref: '#/components/schemas/Meta'
@@ -1008,8 +1097,17 @@ paths:
                 required: ['@context','@graph']
                 properties:
                   "@context":
-                    type: object
-                    $ref: '#/components/schemas/JsonLdCtx'
+                    type: array
+                    description: JSON-LD context # not displayed in Stoplight elements
+                    minItems: 3 # http://../skg-if.json, http://../skg-if-api.json and @base
+                    uniqueItems: true
+                    items:
+                      anyOf:
+                        - $ref: '#/components/schemas/JsonLdCtxDataModel'
+                        - $ref: '#/components/schemas/JsonLdCtxSearch'
+                        - $ref: '#/components/schemas/JsonLdCtxBaseOrMore'
+                    examples:
+                      - ["https://w3id.org/skg-if/context/1.1.0/skg-if.json", "https://w3id.org/skg-if/context/1.0.0/skg-if-api.json", {"@base" : "https://w3id.org/skg-if/sandbox/my-skg-acronym/"}]
                   "@graph":
                     type: array
                     minItems: 1
@@ -1097,8 +1195,17 @@ paths:
               schema:
                 properties:
                   "@context":
-                    type: object
-                    $ref: '#/components/schemas/JsonLdCtx'
+                    type: array
+                    description: JSON-LD context # not displayed in Stoplight elements
+                    minItems: 3 # http://../skg-if.json, http://../skg-if-api.json and @base
+                    uniqueItems: true
+                    items:
+                      anyOf:
+                        - $ref: '#/components/schemas/JsonLdCtxDataModel'
+                        - $ref: '#/components/schemas/JsonLdCtxSearch'
+                        - $ref: '#/components/schemas/JsonLdCtxBaseOrMore'
+                    examples:
+                      - ["https://w3id.org/skg-if/context/1.1.0/skg-if.json", "https://w3id.org/skg-if/context/1.0.0/skg-if-api.json", {"@base" : "https://w3id.org/skg-if/sandbox/my-skg-acronym/"}]
                   meta:
                     type: object
                     $ref: '#/components/schemas/Meta'
@@ -1127,8 +1234,17 @@ paths:
                 required: ['@context','@graph']
                 properties:
                   "@context":
-                    type: object
-                    $ref: '#/components/schemas/JsonLdCtx'
+                    type: array
+                    description: JSON-LD context # not displayed in Stoplight elements
+                    minItems: 3 # http://../skg-if.json, http://../skg-if-api.json and @base
+                    uniqueItems: true
+                    items:
+                      anyOf:
+                        - $ref: '#/components/schemas/JsonLdCtxDataModel'
+                        - $ref: '#/components/schemas/JsonLdCtxSearch'
+                        - $ref: '#/components/schemas/JsonLdCtxBaseOrMore'
+                    examples:
+                      - ["https://w3id.org/skg-if/context/1.1.0/skg-if.json", "https://w3id.org/skg-if/context/1.0.0/skg-if-api.json", {"@base" : "https://w3id.org/skg-if/sandbox/my-skg-acronym/"}]
                   "@graph":
                     type: array
                     minItems: 1
@@ -1207,8 +1323,17 @@ paths:
               schema:
                 properties:
                   "@context":
-                    type: object
-                    $ref: '#/components/schemas/JsonLdCtx'
+                    type: array
+                    description: JSON-LD context # not displayed in Stoplight elements
+                    minItems: 3 # http://../skg-if.json, http://../skg-if-api.json and @base
+                    uniqueItems: true
+                    items:
+                      anyOf:
+                        - $ref: '#/components/schemas/JsonLdCtxDataModel'
+                        - $ref: '#/components/schemas/JsonLdCtxSearch'
+                        - $ref: '#/components/schemas/JsonLdCtxBaseOrMore'
+                    examples:
+                      - ["https://w3id.org/skg-if/context/1.1.0/skg-if.json", "https://w3id.org/skg-if/context/1.0.0/skg-if-api.json", {"@base" : "https://w3id.org/skg-if/sandbox/my-skg-acronym/"}]
                   meta:
                     type: object
                     $ref: '#/components/schemas/Meta'
@@ -2489,62 +2614,37 @@ components:
             description: A URI reference that identifies the specific
               occurrence of the problem.  It may or may not yield further
               information if dereferenced.
-    JsonLdCtx:
-      type: array
-      description: | # not displayed in Stoplight elements
-            JSON-LD context for SKG-IF OpenAPI output.
-            ``` json
-            "@context": [
-              "https://w3id.org/skg-if/context/1.1.0/skg-if.json", => SKG-IF data model context elements
-              "https://w3id.org/skg-if/context/1.0.0/skg-if-api.json", => SKG-IF API context elements (meta section)
-              {
-                "@base": "https://w3id.org/skg-if/sandbox/my-skg-acronym/" => JSON-LD @base fallback.
-              }
-            ]
-            ```
-      minItems: 3 # http://../skg-if.json, http://../skg-if-api.json and @base
-      uniqueItems: true
-      items:
-        anyOf:
-          - type: string
-            description: "URL to SKG-IF data model context supported by the current OpenAPI `https://w3id.org/skg-if/context/1.1.0/skg-if.json`"
-            enum:
-              - https://w3id.org/skg-if/context/1.1.0/skg-if.json
-            x-faker:
-              fake: ['https://w3id.org/skg-if/context/1.1.0/skg-if.json']
-          - type: string
-            description: "URL to SKG-IF API context (meta section) supported by the current OpenAPI `https://w3id.org/skg-if/context/1.0.0/skg-if-api.json`"
-            enum:
-              - https://w3id.org/skg-if/context/1.0.0/skg-if-api.json
-            x-faker:
-              fake: ['https://w3id.org/skg-if/context/1.0.0/skg-if-api.json']
-          - type: object
-            description : 'Additional context mappings ex: `{ "@base":"https://w3id.org/skg-if/sandbox/my-skg-acronym" }`'
-            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/`
-                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/"
-            #required: ["@base"]
-            additionalProperties:
-              type: string
-              description: "context URL of extension entities"
-              x-faker:
-                fake : ['http://www.example.com/skg-if/{{random.alpha(3)}}']
-        #required: [ skgifjson]
-      #anyOf: [
-      #  required: [ skgifjson, skgifimpl],
-      #  required: [ skgifjson]
-      #]
-      additionalProperties: false
-      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/"}]
-
+    JsonLdCtxDataModel:
+      type: string
+      description: "URL to SKG-IF data model context supported by the current OpenAPI `https://w3id.org/skg-if/context/1.1.0/skg-if.json`"
+      enum:
+        - https://w3id.org/skg-if/context/1.1.0/skg-if.json
+      x-faker:
+        fake: ['https://w3id.org/skg-if/context/1.1.0/skg-if.json']
+    JsonLdCtxSearch:
+      type: string
+      description: "URL to SKG-IF API context (meta section) supported by the current OpenAPI `https://w3id.org/skg-if/context/1.0.0/skg-if-api.json`"
+      enum:
+        - https://w3id.org/skg-if/context/1.0.0/skg-if-api.json
+      x-faker:
+        fake: ['https://w3id.org/skg-if/context/1.0.0/skg-if-api.json']
+    JsonLdCtxBaseOrMore:
+      description : 'Additional context mappings ex: `{ "@base":"https://w3id.org/skg-if/sandbox/my-skg-acronym" }`'
+      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/`
+          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/"
+      additionalProperties:
+        type: string
+        description: "context URL of extension entities"
+        x-faker:
+          fake : ['http://www.example.com/skg-if/{{random.alpha(3)}}']