From 2c5d1ca605838f86549ab7912d2f1dabbbf0caef Mon Sep 17 00:00:00 2001 From: Lin Zhou Date: Thu, 15 Oct 2026 18:06:07 -0700 Subject: [PATCH 1/8] Update profile file description about icebergEndpoint --- spec/protocols/OVERVIEW.md | 39 +++++++++++++++++++++++++++----------- 1 file changed, 28 insertions(+), 11 deletions(-) diff --git a/spec/protocols/OVERVIEW.md b/spec/protocols/OVERVIEW.md index 5bddb1bcb..dd58f2f22 100644 --- a/spec/protocols/OVERVIEW.md +++ b/spec/protocols/OVERVIEW.md @@ -1,8 +1,10 @@ - - + + + + # OpenSharing Protocol - + This document describes the OpenSharing Protocol's general concepts, including the profile file format and naming requirements. @@ -10,13 +12,15 @@ This document describes the OpenSharing Protocol's general concepts, including t A profile file is a JSON file that contains the information for a recipient to access shared data on a OpenSharing server. There are a few fields in this file as listed below. -Field Name | Descrption --|- -shareCredentialsVersion | The file format version of the profile file. This version will be increased whenever non-forward-compatible changes are made to the profile format. When a client is running an unsupported profile file format version, it should show an error message instructing the user to upgrade to a newer version of their client. -endpoint | The url of the sharing server. -icebergEndpoint | The url of the sharing server that supports the iceberg table endpoints. -bearerToken | The [bearer token](https://tools.ietf.org/html/rfc6750) to access the server. -expirationTime | The expiration time of the bearer token in [ISO 8601 format](https://www.w3.org/TR/NOTE-datetime). This field is optional and if it is not provided, the bearer token can be seen as never expire. + +| Field Name | Descrption | Note | +| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | +| shareCredentialsVersion | The file format version of the profile file. This version will be increased whenever non-forward-compatible changes are made to the profile format. When a client is running an unsupported profile file format version, it should show an error message instructing the user to upgrade to a newer version of their client. | [] | +| endpoint | The url of the sharing server. | [required] | +| icebergEndpoint | The url of the sharing server that supports the iceberg table endpoints, which is always `endpoint` + `/iceberg` | [optional] | +| bearerToken | The [bearer token](https://tools.ietf.org/html/rfc6750) to access the server. | [required] | +| expirationTime | The expiration time of the bearer token in [ISO 8601 format](https://www.w3.org/TR/NOTE-datetime). This field is optional and if it is not provided, the bearer token can be seen as never expire. | [optional] | + Example: @@ -30,15 +34,28 @@ Example: } ``` +or + +```json +{ + "shareCredentialsVersion": 1, + "endpoint": "https://sharing.opensharing.io/open-sharing/", + "bearerToken": "" +} +``` + +OpenSharing servers providing tables in iceberg format must provide their IRC endpoint, i.e., `icebergEndpoint`, under `{endpoint}/iceberg`, enabling IRC clients to leverage the same as their IRC base url, e.g. `{endpoint}/shares/`, with iceberg tables would be explored as `{endpoint}/iceberg/v1/config?warehouse=`. + ## Names Share, Schema, and shared objects are identifiable by names. To ensure compatibility and avoid issues across different sharing servers, the following limitations apply for object names: - Object names cannot exceed 255 characters. - The following special characters are not allowed for all object names: - - Space (` `) + - Space ( ``) - Forward slash (`/`) - All ASCII control characters (`00-1F` hex) - The DELETE character (`7f` hex) - Schema and shared object names additionally do not allow special character Period (`.`) - Object names are case-insensitive + From 5d32e0057d15640673af8de30c85a68b1d24467c Mon Sep 17 00:00:00 2001 From: Lin Zhou Date: Fri, 16 Oct 2026 08:29:47 -0700 Subject: [PATCH 2/8] resolve comment --- spec/protocols/OVERVIEW.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec/protocols/OVERVIEW.md b/spec/protocols/OVERVIEW.md index dd58f2f22..566d56f2d 100644 --- a/spec/protocols/OVERVIEW.md +++ b/spec/protocols/OVERVIEW.md @@ -15,7 +15,7 @@ A profile file is a JSON file that contains the information for a recipient to a | Field Name | Descrption | Note | | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | -| shareCredentialsVersion | The file format version of the profile file. This version will be increased whenever non-forward-compatible changes are made to the profile format. When a client is running an unsupported profile file format version, it should show an error message instructing the user to upgrade to a newer version of their client. | [] | +| shareCredentialsVersion | The file format version of the profile file. This version will be increased whenever non-forward-compatible changes are made to the profile format. When a client is running an unsupported profile file format version, it should show an error message instructing the user to upgrade to a newer version of their client. | [required] | | endpoint | The url of the sharing server. | [required] | | icebergEndpoint | The url of the sharing server that supports the iceberg table endpoints, which is always `endpoint` + `/iceberg` | [optional] | | bearerToken | The [bearer token](https://tools.ietf.org/html/rfc6750) to access the server. | [required] | @@ -52,7 +52,7 @@ Share, Schema, and shared objects are identifiable by names. To ensure compatibi - Object names cannot exceed 255 characters. - The following special characters are not allowed for all object names: - - Space ( ``) + - Space (` `) - Forward slash (`/`) - All ASCII control characters (`00-1F` hex) - The DELETE character (`7f` hex) From 4799ed26081c89c95bea572f63272447213ae388 Mon Sep 17 00:00:00 2001 From: Lin Zhou Date: Tue, 20 Oct 2026 09:49:28 -0700 Subject: [PATCH 3/8] resolve comment --- spec/protocols/OVERVIEW.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/protocols/OVERVIEW.md b/spec/protocols/OVERVIEW.md index 566d56f2d..aaa6e65b8 100644 --- a/spec/protocols/OVERVIEW.md +++ b/spec/protocols/OVERVIEW.md @@ -44,7 +44,7 @@ or } ``` -OpenSharing servers providing tables in iceberg format must provide their IRC endpoint, i.e., `icebergEndpoint`, under `{endpoint}/iceberg`, enabling IRC clients to leverage the same as their IRC base url, e.g. `{endpoint}/shares/`, with iceberg tables would be explored as `{endpoint}/iceberg/v1/config?warehouse=`. +OpenSharing servers that share tables in Iceberg format may optionally provide an `icebergEndpoint` in the profile file. If provided, it must be `{endpoint}/iceberg`. Clients must not assume `icebergEndpoint` is present and should handle its absence gracefully. ## Names From beed401d6fcbcd7c8f208d59c906aa1d53f9f990 Mon Sep 17 00:00:00 2001 From: Lin Zhou Date: Tue, 20 Oct 2026 10:00:34 -0700 Subject: [PATCH 4/8] fix format --- spec/protocols/OVERVIEW.md | 19 ++++++++----------- 1 file changed, 8 insertions(+), 11 deletions(-) diff --git a/spec/protocols/OVERVIEW.md b/spec/protocols/OVERVIEW.md index aaa6e65b8..20bd1a82e 100644 --- a/spec/protocols/OVERVIEW.md +++ b/spec/protocols/OVERVIEW.md @@ -1,10 +1,7 @@ - - - - + + # OpenSharing Protocol - - + This document describes the OpenSharing Protocol's general concepts, including the profile file format and naming requirements. @@ -13,9 +10,9 @@ This document describes the OpenSharing Protocol's general concepts, including t A profile file is a JSON file that contains the information for a recipient to access shared data on a OpenSharing server. There are a few fields in this file as listed below. -| Field Name | Descrption | Note | +| Field Name | Description | Note | | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | -| shareCredentialsVersion | The file format version of the profile file. This version will be increased whenever non-forward-compatible changes are made to the profile format. When a client is running an unsupported profile file format version, it should show an error message instructing the user to upgrade to a newer version of their client. | [required] | +| shareCredentialsVersion | The file format version of the profile file. This version will be increased whenever non-forward-compatible changes are made to the profile format. When a client is running an unsupported profile file format version, it should show an error message instructing the user to upgrade to a newer version of their client. | [required] | | endpoint | The url of the sharing server. | [required] | | icebergEndpoint | The url of the sharing server that supports the iceberg table endpoints, which is always `endpoint` + `/iceberg` | [optional] | | bearerToken | The [bearer token](https://tools.ietf.org/html/rfc6750) to access the server. | [required] | @@ -27,8 +24,8 @@ Example: ```json { "shareCredentialsVersion": 1, - "endpoint": "https://sharing.opensharing.io/open-sharing/", - "icebergEndpoint": "https://sharing.opensharing.io/open-sharing/iceberg/", + "endpoint": "https://sharing.opensharing.io/open-sharing", + "icebergEndpoint": "https://sharing.opensharing.io/open-sharing/iceberg", "bearerToken": "", "expirationTime": "2021-11-12T00:12:29.0Z" } @@ -39,7 +36,7 @@ or ```json { "shareCredentialsVersion": 1, - "endpoint": "https://sharing.opensharing.io/open-sharing/", + "endpoint": "https://sharing.opensharing.io/open-sharing", "bearerToken": "" } ``` From 6602b5376cc00ea36a5f12d1bc399d6616ad0492 Mon Sep 17 00:00:00 2001 From: Lin Zhou Date: Tue, 20 Oct 2026 10:39:51 -0700 Subject: [PATCH 5/8] fix format --- spec/protocols/OVERVIEW.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/spec/protocols/OVERVIEW.md b/spec/protocols/OVERVIEW.md index 20bd1a82e..46c3ec4bd 100644 --- a/spec/protocols/OVERVIEW.md +++ b/spec/protocols/OVERVIEW.md @@ -1,6 +1,7 @@ # OpenSharing Protocol + This document describes the OpenSharing Protocol's general concepts, including the profile file format and naming requirements. @@ -31,7 +32,7 @@ Example: } ``` -or +or ```json { From fa8100b7e902801b827b9f6a71fe1792eef68c80 Mon Sep 17 00:00:00 2001 From: Lin Zhou Date: Tue, 20 Oct 2026 10:47:35 -0700 Subject: [PATCH 6/8] format --- spec/protocols/OVERVIEW.md | 1 - 1 file changed, 1 deletion(-) diff --git a/spec/protocols/OVERVIEW.md b/spec/protocols/OVERVIEW.md index 46c3ec4bd..cf48dd4e8 100644 --- a/spec/protocols/OVERVIEW.md +++ b/spec/protocols/OVERVIEW.md @@ -56,4 +56,3 @@ Share, Schema, and shared objects are identifiable by names. To ensure compatibi - The DELETE character (`7f` hex) - Schema and shared object names additionally do not allow special character Period (`.`) - Object names are case-insensitive - From 4ed7ada5ce651ba24591fdc27620b850a93918c7 Mon Sep 17 00:00:00 2001 From: Lin Zhou Date: Tue, 20 Oct 2026 10:54:37 -0700 Subject: [PATCH 7/8] fix wording --- spec/protocols/OVERVIEW.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec/protocols/OVERVIEW.md b/spec/protocols/OVERVIEW.md index cf48dd4e8..0372c6feb 100644 --- a/spec/protocols/OVERVIEW.md +++ b/spec/protocols/OVERVIEW.md @@ -11,11 +11,11 @@ This document describes the OpenSharing Protocol's general concepts, including t A profile file is a JSON file that contains the information for a recipient to access shared data on a OpenSharing server. There are a few fields in this file as listed below. -| Field Name | Description | Note | +| Field Name | Description | Note | | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | | shareCredentialsVersion | The file format version of the profile file. This version will be increased whenever non-forward-compatible changes are made to the profile format. When a client is running an unsupported profile file format version, it should show an error message instructing the user to upgrade to a newer version of their client. | [required] | | endpoint | The url of the sharing server. | [required] | -| icebergEndpoint | The url of the sharing server that supports the iceberg table endpoints, which is always `endpoint` + `/iceberg` | [optional] | +| icebergEndpoint | The url of the sharing server's Iceberg REST catalog endpoint. If provided, it must be `{endpoint}/iceberg`. | [optional] | | bearerToken | The [bearer token](https://tools.ietf.org/html/rfc6750) to access the server. | [required] | | expirationTime | The expiration time of the bearer token in [ISO 8601 format](https://www.w3.org/TR/NOTE-datetime). This field is optional and if it is not provided, the bearer token can be seen as never expire. | [optional] | From 8de5ea3839801cad8fbe9bc06ab05e4cf0dcd861 Mon Sep 17 00:00:00 2001 From: Lin Zhou Date: Tue, 20 Oct 2026 11:43:52 -0700 Subject: [PATCH 8/8] format --- spec/protocols/OVERVIEW.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/spec/protocols/OVERVIEW.md b/spec/protocols/OVERVIEW.md index 0372c6feb..e90af8781 100644 --- a/spec/protocols/OVERVIEW.md +++ b/spec/protocols/OVERVIEW.md @@ -10,7 +10,6 @@ This document describes the OpenSharing Protocol's general concepts, including t A profile file is a JSON file that contains the information for a recipient to access shared data on a OpenSharing server. There are a few fields in this file as listed below. - | Field Name | Description | Note | | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | | shareCredentialsVersion | The file format version of the profile file. This version will be increased whenever non-forward-compatible changes are made to the profile format. When a client is running an unsupported profile file format version, it should show an error message instructing the user to upgrade to a newer version of their client. | [required] | @@ -19,7 +18,6 @@ A profile file is a JSON file that contains the information for a recipient to a | bearerToken | The [bearer token](https://tools.ietf.org/html/rfc6750) to access the server. | [required] | | expirationTime | The expiration time of the bearer token in [ISO 8601 format](https://www.w3.org/TR/NOTE-datetime). This field is optional and if it is not provided, the bearer token can be seen as never expire. | [optional] | - Example: ```json