From 32f1b6c5aaf6c86e93fc5e455ea39c85c975a70a Mon Sep 17 00:00:00 2001
From: Simon <simon.dumas@protonmail.com>
Date: Tue, 19 Sep 2023 14:34:13 +0200
Subject: [PATCH] Better document the use of the schema segment (#4280)

* Better document the use of the schema segment

---------

Co-authored-by: Simon Dumas <simon.dumas@epfl.ch>
---
 .../paradox/docs/delta/api/resources-api.md   | 24 ++++++++++++++++---
 1 file changed, 21 insertions(+), 3 deletions(-)

diff --git a/docs/src/main/paradox/docs/delta/api/resources-api.md b/docs/src/main/paradox/docs/delta/api/resources-api.md
index 4686a05724..c15e325974 100644
--- a/docs/src/main/paradox/docs/delta/api/resources-api.md
+++ b/docs/src/main/paradox/docs/delta/api/resources-api.md
@@ -23,8 +23,8 @@ Please visit @ref:[Authentication & authorization](authentication.md) section to
 
 @@@ note { .warning title="Remote contexts" }
 
-From Delta v1.5, remote contexts are only resolved during creates and updates.
-That means that when those get updated, the resources importing them must be also updated to take them into account the new version.
+Remote contexts are only resolved during creates and updates.
+That means that when those get updated, the resources importing them must be also updated to take them into account in a new version.
 
 @@@
 
@@ -68,6 +68,12 @@ The json payload:
 - If the `@id` value is not found on the payload, an @id will be generated as follows: `base:{UUID}`. The `base` is the 
   `prefix` defined on the resource's project (`{project_label}`).
 
+The `{schema_id}` segment allows to define an existing SHACL schema to validate the resource with:
+
+- If `_` is provided, no SHACL validation will be performed
+- If another value is provided, Nexus will attempt to resolve the schema then validate the expanded JSON-LD value generated 
+from the provided payload.
+
 **Example**
 
 Request
@@ -88,7 +94,9 @@ to specify one. The @id will be specified in the last segment of the endpoint UR
 PUT /v1/resources/{org_label}/{project_label}/{schema_id}/{resource_id}
   {...}
 ```
- 
+
+The `{schema_id}` has the same behaviour as @ref:[the creation using post operation](#create-using-post).
+
 Note that if the payload contains an @id different from the `{resource_id}`, the request will fail.
 
 **Example**
@@ -116,6 +124,11 @@ PUT /v1/resources/{org_label}/{project_label}/{schema_id}/{resource_id}?rev={pre
 ```
 ... where `{previous_rev}` is the last known revision number for the resource.
 
+The `{schema_id}` segment allows to define an existing SHACL schema to validate the resource with:
+
+- If `_` is provided, no SHACL validation will be performed with the latest version of its current schema
+- If another value is provided, it has to match the identifier of the current schema as changing the schema of a
+resource is not currently supported. A different revision or tag of this schema can be provided though.
 
 **Example**
 
@@ -252,6 +265,11 @@ where ...
 
 `{rev}` and `{tag}` fields cannot be simultaneously present.
 
+The `{schema_id}` segment allows to pass the resource schema:
+
+- If `_` is provided, the value is ignored
+- If another value is provided, it must match the identifier of the resource schema.
+
 **Example**
 
 Request