partially update your authorization model
curl --request PATCH \
--url https://api.example.com/v1/tenants/{tenant_id}/schemas/partial-write \
--header 'Content-Type: application/json' \
--data '
{
"metadata": {
"schema_version": "<string>"
},
"partials": {}
}
'import requests
url = "https://api.example.com/v1/tenants/{tenant_id}/schemas/partial-write"
payload = {
"metadata": { "schema_version": "<string>" },
"partials": {}
}
headers = {"Content-Type": "application/json"}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({metadata: {schema_version: '<string>'}, partials: {}})
};
fetch('https://api.example.com/v1/tenants/{tenant_id}/schemas/partial-write', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/v1/tenants/{tenant_id}/schemas/partial-write",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'metadata' => [
'schema_version' => '<string>'
],
'partials' => [
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/v1/tenants/{tenant_id}/schemas/partial-write"
payload := strings.NewReader("{\n \"metadata\": {\n \"schema_version\": \"<string>\"\n },\n \"partials\": {}\n}")
req, _ := http.NewRequest("PATCH", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.patch("https://api.example.com/v1/tenants/{tenant_id}/schemas/partial-write")
.header("Content-Type", "application/json")
.body("{\n \"metadata\": {\n \"schema_version\": \"<string>\"\n },\n \"partials\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/v1/tenants/{tenant_id}/schemas/partial-write")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"metadata\": {\n \"schema_version\": \"<string>\"\n },\n \"partials\": {}\n}"
response = http.request(request)
puts response.read_body{
"schema_version": "<string>"
}{
"code": 123,
"message": "<string>",
"details": [
{
"@type": "<string>"
}
]
}Schema Service
Partial Schema Update
PATCH
/
v1
/
tenants
/
{tenant_id}
/
schemas
/
partial-write
partially update your authorization model
curl --request PATCH \
--url https://api.example.com/v1/tenants/{tenant_id}/schemas/partial-write \
--header 'Content-Type: application/json' \
--data '
{
"metadata": {
"schema_version": "<string>"
},
"partials": {}
}
'import requests
url = "https://api.example.com/v1/tenants/{tenant_id}/schemas/partial-write"
payload = {
"metadata": { "schema_version": "<string>" },
"partials": {}
}
headers = {"Content-Type": "application/json"}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({metadata: {schema_version: '<string>'}, partials: {}})
};
fetch('https://api.example.com/v1/tenants/{tenant_id}/schemas/partial-write', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/v1/tenants/{tenant_id}/schemas/partial-write",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'metadata' => [
'schema_version' => '<string>'
],
'partials' => [
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/v1/tenants/{tenant_id}/schemas/partial-write"
payload := strings.NewReader("{\n \"metadata\": {\n \"schema_version\": \"<string>\"\n },\n \"partials\": {}\n}")
req, _ := http.NewRequest("PATCH", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.patch("https://api.example.com/v1/tenants/{tenant_id}/schemas/partial-write")
.header("Content-Type", "application/json")
.body("{\n \"metadata\": {\n \"schema_version\": \"<string>\"\n },\n \"partials\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/v1/tenants/{tenant_id}/schemas/partial-write")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"metadata\": {\n \"schema_version\": \"<string>\"\n },\n \"partials\": {}\n}"
response = http.request(request)
puts response.read_body{
"schema_version": "<string>"
}{
"code": 123,
"message": "<string>",
"details": [
{
"@type": "<string>"
}
]
}As development teams regularly roll out new features or API endpoints, features each addition often necessitates corresponding updates to the Permify schema.
To streamline this process, we have published an endpoint allows authorized users to make partial updates to the schema by adding or modifying actions within individual entities.
body:
The code block above outlines the existing schema definitions for the
By leaving the
Endpoint Definition
/v1/tenants/{tenant_id}/schemas/partial-write
This endpoint allows authorized users to make partial updates to the schema by adding or modifying actions within individual entities.
Request Payload Structure
PATCH /v1/tenants/{tenant_id}/schemas/partial-write
Content-Type: application/json
{
"metadata": {
"schema_version": ""
},
"partials": {
"<entity-name>": {
"write": [],
"delete": [],
"update": []
}
}
}
Behavior Description
When theschema_version in the request metadata is left empty, the system will default to using the latest(head) schema version as the base for updates.
name(string): The name of the entity to be changed.write(string array): Conditions to be added. If a relation or permission/action already exists, it should return an error.delete(string array): Names (permissions/actions) to be deleted. If the relation/permission/action name does not exist, it should return an error. Note: specifying the name is enough as relation/permission/action names should be unique.update(string array): Conditions to be updated.
schema_version is specified, the endpoint will perform the same update process on the given version and generate a new version thereafter.
Partial Schema Endpoint Example Usage
Existing Schema
entity user {}
entity organization {
relation admin @user
relation member @user
}
entity team {
relation owner @user
relation org @organization
permission edit = org.admin or owner
permission delete = org.admin or owner
}
user, organization, and team entities. This includes their respective relationships and permissions within the schema.
Partial Schema Update Request
To update theteam entity by introducing new permissions, the following PATCH request with the accompanying payload is sent:
{
"metadata": {
"schema_version": ""
},
"partials": {
"team": {
"write": [
"relation member @user",
"permission invite = org.admin and (owner or member)",
"permission remove_user = owner"
],
"delete": [
"edit"
],
"update": [
"permission delete = member"
]
}
}
}
schema_version empty string, it signals the system to take the latest(head) schema version as a base for applying updates.
Resulting Schema After Update
After the request is processed, the system outputs a new schema version where theteam entity is revised to include the new permissions as illustrated below:
entity user {}
entity organization {
relation admin @user
relation member @user
}
entity team {
relation owner @user
relation member @user
relation org @organization
permission delete = member
permission invite = org.admin and (owner or member)
permission remove_user = owner
}
invite and remove_user permissions have been added, a member relation has been included, the edit permission has been deleted, and the delete permission has been updated.Path Parameters
tenant_id is a string that identifies the tenant. It must match the pattern "[a-zA-Z0-9-,]+", be a maximum of 64 bytes, and must not be empty.
Body
application/json
SchemaPartialWriteRequestMetadata provides additional information for the Schema Partial Write request. It contains schema_version to specify which version of the schema should be read.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Response
A successful response.
SchemaPartialWriteResponse is the response message for the Parietal Write method in the Schema service. It returns the requested schema.
schema_version is the string that identifies the version of the written schema.