From 32b96cb922875ec04e0e24f275e581422b33c8ec Mon Sep 17 00:00:00 2001 From: Gustas Badaitis Date: Thu, 21 May 2026 13:40:48 +0300 Subject: [PATCH 1/9] Documentation change --- openapi/docs.md | 46 +++++++++++++++++++++++++++++----------------- 1 file changed, 29 insertions(+), 17 deletions(-) diff --git a/openapi/docs.md b/openapi/docs.md index 389cd26..d343ad1 100644 --- a/openapi/docs.md +++ b/openapi/docs.md @@ -23,7 +23,7 @@ and this (in future) can be done in Data Portal (data.gov.lt). - [DSA](https://ivpk.github.io/dsa) - Data Structure Mapping table format specification, describes a table format, for mapping data models between - Physical, Logical and Conceptual data models. + Physical, Logical, and Conceptual data models. Logical data model from DSA tables are used as API schemas. UAPI only describes protocol, DSA tables provides data schemas for UAPI API. @@ -70,7 +70,7 @@ components: - **Data** source and **Data Service** or **Resource** when referred to one or the other - these components represents all data sources, including variuos - databases, web services, CSV, XLSX or other data files maintained by all the + databases, web services, CSV, XLSX, or other data files maintained by all the government institutions. Data might be read directly from a primary data source or through a data @@ -95,7 +95,7 @@ components: Data Catalog receives DSA tables from Data Agent, provides modified versions of DSA tables back to Data Agent, exports API specifications to API Gateway - in OpenAPI format and exports available data scopes and information about + in OpenAPI format, and exports available data scopes and information about smart contracts into Auth service. Data Catalog does not have access to data, it is used only to manage metadata @@ -169,7 +169,7 @@ components: 3. **API Gateway** works as a reverse proxy and load balancer, accepts requests from data users, validates these requests against OpenAPI schemas received from **Data Catalog**, validates authorization tokens with **Auth service**, - provides request logging, rate limiting and other services. + provides request logging, rate limiting, and other services. **API Gateway** after initial validation, passed requests to **Data Agent**, which reads data from primary sources and provides protocol and format @@ -195,10 +195,12 @@ All API URI's are constructed using one of the following patters: catalog `/` dataset `/` version `/` - model + model - Get single object: + If the id is an integer, UUID, or composite type: + `/datasets/` form `/` org `/` @@ -208,6 +210,17 @@ All API URI's are constructed using one of the following patters: model `/` id + If the id is any other type: + + `/datasets/` + form `/` + org `/` + catalog `/` + dataset `/` + version `/` + model `/` + =id + - Get an older version of a single object: `/datasets/` @@ -296,9 +309,9 @@ Meaning of dynamic URI parts explained bellow: - version - data schema version of a dataset. - model - a set of objects provided under the same data model. -- id - unique object identifier in UUID format. +- id - unique object identifier in UUID, integer, string, or Base32 format. - revision - unique identifier for an older object - version in UUID format. + version in UUID, integer, string, or Base32 format. - property - a subresource used for some property data types liek files or arrays, in order to retrieve large content blobs. - action - an action performed with objects or a @@ -362,7 +375,7 @@ building, since building is the same, single global identifier must be used: ## Model Real world entities are identified using global identifiers. Each real world -entity might have different data shape, form or schema. +entity might have different data shape, form, or schema. Single real world entity might be represented using multiple different data models using different set of properties, but different models must share the @@ -537,8 +550,7 @@ Version number is a singe positive integer number. All objects must have a revision number provided as reserved `_revision` property name. -Revision is a string, that identifies object version. This might be a UUID -string. +Revision can be represented as a string, UUID, integer, or Base32 value, and serves to identify a specific version of an object. When update action is made on an object, revision number must always be provided, in order to compare object version received by the Client and object @@ -618,9 +630,9 @@ the parties participating in data exchange process: is a Authorization Server. - **Catalog** - a data catalog, a place where all information about agents, - resource, clients and smart contracts are registered. + resource, clients, and smart contracts are registered. -- **Resource** - a data service, a database or a data file, place where data +- **Resource** - a data service, a database, or a data file, place where data are stored. - **Agent** - a software responsible for data exchange, accepts data queries, @@ -655,7 +667,7 @@ steps must be completed: what data can be use for exchange outside if Resource and published this information for Client developers. -4. Client developers discovers published datasets, registers client and +4. Client developers discovers published datasets, registers client, and requests access to data they need, specifying list of scopes that are required for the Client. After registration, clients receive client id and client secret assigned by the Authorization server. @@ -751,7 +763,7 @@ In order to make requests, following steps are needed: client acts on itself. 4. Finally Agent transforms an UAPI request into a protocol, that is understood - by a Resource, retrieves data and transforms result back to UAPI. + by a Resource, retrieves data, and transforms result back to UAPI. @@ -925,7 +937,7 @@ representative `sub` identifier, which might be used when filtering data. # Query -Actions might use URI query to filter, limit, sort or otherwise influence +Actions might use URI query to filter, limit, sort, or otherwise influence result returned by an action. URI consists of following components (there are more components, but for @@ -959,7 +971,7 @@ Parameter names can have attributes: attribute `=` value `&` -There can be none, one or more than one attribute. +There can be none, one, or more than one attribute. For query examples following data model will be used. @@ -1092,7 +1104,7 @@ City?_select=country.name,name This will select data from both `City` and `Country` models, because `City/country` property is a Reference to the `Country` model. -Joins can be used with for selecting, filtering, sorting and other places, +Joins can be used with for selecting, filtering, sorting, and other places, where a property can be specified. From 7920e8ff5f42f16a58f98207e1db6426c1c6d38b Mon Sep 17 00:00:00 2001 From: Gustas Badaitis Date: Thu, 28 May 2026 12:52:13 +0300 Subject: [PATCH 2/9] Revert "Documentation change" This reverts commit 32b96cb922875ec04e0e24f275e581422b33c8ec. --- openapi/docs.md | 46 +++++++++++++++++----------------------------- 1 file changed, 17 insertions(+), 29 deletions(-) diff --git a/openapi/docs.md b/openapi/docs.md index d343ad1..389cd26 100644 --- a/openapi/docs.md +++ b/openapi/docs.md @@ -23,7 +23,7 @@ and this (in future) can be done in Data Portal (data.gov.lt). - [DSA](https://ivpk.github.io/dsa) - Data Structure Mapping table format specification, describes a table format, for mapping data models between - Physical, Logical, and Conceptual data models. + Physical, Logical and Conceptual data models. Logical data model from DSA tables are used as API schemas. UAPI only describes protocol, DSA tables provides data schemas for UAPI API. @@ -70,7 +70,7 @@ components: - **Data** source and **Data Service** or **Resource** when referred to one or the other - these components represents all data sources, including variuos - databases, web services, CSV, XLSX, or other data files maintained by all the + databases, web services, CSV, XLSX or other data files maintained by all the government institutions. Data might be read directly from a primary data source or through a data @@ -95,7 +95,7 @@ components: Data Catalog receives DSA tables from Data Agent, provides modified versions of DSA tables back to Data Agent, exports API specifications to API Gateway - in OpenAPI format, and exports available data scopes and information about + in OpenAPI format and exports available data scopes and information about smart contracts into Auth service. Data Catalog does not have access to data, it is used only to manage metadata @@ -169,7 +169,7 @@ components: 3. **API Gateway** works as a reverse proxy and load balancer, accepts requests from data users, validates these requests against OpenAPI schemas received from **Data Catalog**, validates authorization tokens with **Auth service**, - provides request logging, rate limiting, and other services. + provides request logging, rate limiting and other services. **API Gateway** after initial validation, passed requests to **Data Agent**, which reads data from primary sources and provides protocol and format @@ -195,12 +195,10 @@ All API URI's are constructed using one of the following patters: catalog `/` dataset `/` version `/` - model + model - Get single object: - If the id is an integer, UUID, or composite type: - `/datasets/` form `/` org `/` @@ -210,17 +208,6 @@ All API URI's are constructed using one of the following patters: model `/` id - If the id is any other type: - - `/datasets/` - form `/` - org `/` - catalog `/` - dataset `/` - version `/` - model `/` - =id - - Get an older version of a single object: `/datasets/` @@ -309,9 +296,9 @@ Meaning of dynamic URI parts explained bellow: - version - data schema version of a dataset. - model - a set of objects provided under the same data model. -- id - unique object identifier in UUID, integer, string, or Base32 format. +- id - unique object identifier in UUID format. - revision - unique identifier for an older object - version in UUID, integer, string, or Base32 format. + version in UUID format. - property - a subresource used for some property data types liek files or arrays, in order to retrieve large content blobs. - action - an action performed with objects or a @@ -375,7 +362,7 @@ building, since building is the same, single global identifier must be used: ## Model Real world entities are identified using global identifiers. Each real world -entity might have different data shape, form, or schema. +entity might have different data shape, form or schema. Single real world entity might be represented using multiple different data models using different set of properties, but different models must share the @@ -550,7 +537,8 @@ Version number is a singe positive integer number. All objects must have a revision number provided as reserved `_revision` property name. -Revision can be represented as a string, UUID, integer, or Base32 value, and serves to identify a specific version of an object. +Revision is a string, that identifies object version. This might be a UUID +string. When update action is made on an object, revision number must always be provided, in order to compare object version received by the Client and object @@ -630,9 +618,9 @@ the parties participating in data exchange process: is a Authorization Server. - **Catalog** - a data catalog, a place where all information about agents, - resource, clients, and smart contracts are registered. + resource, clients and smart contracts are registered. -- **Resource** - a data service, a database, or a data file, place where data +- **Resource** - a data service, a database or a data file, place where data are stored. - **Agent** - a software responsible for data exchange, accepts data queries, @@ -667,7 +655,7 @@ steps must be completed: what data can be use for exchange outside if Resource and published this information for Client developers. -4. Client developers discovers published datasets, registers client, and +4. Client developers discovers published datasets, registers client and requests access to data they need, specifying list of scopes that are required for the Client. After registration, clients receive client id and client secret assigned by the Authorization server. @@ -763,7 +751,7 @@ In order to make requests, following steps are needed: client acts on itself. 4. Finally Agent transforms an UAPI request into a protocol, that is understood - by a Resource, retrieves data, and transforms result back to UAPI. + by a Resource, retrieves data and transforms result back to UAPI. @@ -937,7 +925,7 @@ representative `sub` identifier, which might be used when filtering data. # Query -Actions might use URI query to filter, limit, sort, or otherwise influence +Actions might use URI query to filter, limit, sort or otherwise influence result returned by an action. URI consists of following components (there are more components, but for @@ -971,7 +959,7 @@ Parameter names can have attributes: attribute `=` value `&` -There can be none, one, or more than one attribute. +There can be none, one or more than one attribute. For query examples following data model will be used. @@ -1104,7 +1092,7 @@ City?_select=country.name,name This will select data from both `City` and `Country` models, because `City/country` property is a Reference to the `Country` model. -Joins can be used with for selecting, filtering, sorting, and other places, +Joins can be used with for selecting, filtering, sorting and other places, where a property can be specified. From 60c34c1a4438afdf334c6164fc584716fb0b9a07 Mon Sep 17 00:00:00 2001 From: Gustas Badaitis Date: Tue, 2 Jun 2026 10:47:49 +0300 Subject: [PATCH 3/9] Documentation change for _id --- draft/openapi/components/parameters/id.yaml | 4 +-- draft/openapi/components/schemas/id.yaml | 9 +++++-- draft/openapi/docs.md | 28 ++++++++++++++++++--- 3 files changed, 32 insertions(+), 9 deletions(-) diff --git a/draft/openapi/components/parameters/id.yaml b/draft/openapi/components/parameters/id.yaml index d0019eb..cb31712 100644 --- a/draft/openapi/components/parameters/id.yaml +++ b/draft/openapi/components/parameters/id.yaml @@ -4,9 +4,7 @@ required: true schema: $ref: ../schemas/id.yaml description: | - Public global object identifier. - - Identifiers should be UUID v4. + Public global object identifier, see [_id URI representation](#section/Concepts/Identifier/_id-URI-representation). Once object is assigned a global identifier, it should never change. Internally local identifiers, should be associated with public diff --git a/draft/openapi/components/schemas/id.yaml b/draft/openapi/components/schemas/id.yaml index e38483d..254fe7a 100644 --- a/draft/openapi/components/schemas/id.yaml +++ b/draft/openapi/components/schemas/id.yaml @@ -1,4 +1,9 @@ -type: string -pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ +oneOf: + - type: integer + - type: string + pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|=[^\s]+|[^=\s][^\s]*)$ examples: - abdd1245-bbf9-4085-9366-f11c0f737c1d + - =some-string-id + - 42,LT + - 123 diff --git a/draft/openapi/docs.md b/draft/openapi/docs.md index 0662289..88ba69b 100644 --- a/draft/openapi/docs.md +++ b/draft/openapi/docs.md @@ -202,7 +202,7 @@ All API URL's are constructed using one of the following patters: dataset `/` model -- Get single object: +- Get single object, see [_id URI representation](#section/Concepts/Identifier/_id-URI-representation): `https://` domain `/` @@ -782,7 +782,7 @@ same building, but the global identifier must be the same for all datasets. Global identifiers must be assigned to all objects using a reserved property name `_id`. -For example we can have multiple datasets containing data abould the same +For example we can have multiple datasets containing data about the same building, since building is the same, single global identifier must be used: ```text @@ -790,6 +790,22 @@ building, since building is the same, single global identifier must be used: /datasets/gov/rc/ntr/uapi/report/Pastatas/e96cc0cc-08be-460d-a887-98f80612a402 ``` +Global identifiers should be defined in the manifest, using `_id` as the property +name. `_id` can be defined as one of these types: +- String +- Base32 +- UUID +- Integer + +### _id URI representation + +The operations, which use `_id` in their URI, change depending on the fields type. +If the `_id` is of type String or Base32, then the `_id` is specified in the URI with an equal sign: + + ```code + \=id + ``` + ## Model Real world entities are identified using global identifiers. Each real world @@ -964,8 +980,12 @@ Version number is a singe positive integer number specifying major version of th All objects must have a revision number provided as reserved `_revision` property name. -Revision is a string, that identifies object version. This might be a UUID -string. +Revision can be defined in the manifest, using `_revision` as the property +name. `_revision` can be defined as one of these types: +- String +- Base32 +- UUID +- Integer When update action is made on an object, revision number must always be provided, in order to compare object version received by the Client and object From 8c299bf49eb3577481078efb983325a02c303468 Mon Sep 17 00:00:00 2001 From: Gustas Badaitis Date: Tue, 2 Jun 2026 10:53:44 +0300 Subject: [PATCH 4/9] Working url --- draft/openapi/components/parameters/id.yaml | 2 +- draft/openapi/docs.md | 4 +++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/draft/openapi/components/parameters/id.yaml b/draft/openapi/components/parameters/id.yaml index cb31712..3637e64 100644 --- a/draft/openapi/components/parameters/id.yaml +++ b/draft/openapi/components/parameters/id.yaml @@ -4,7 +4,7 @@ required: true schema: $ref: ../schemas/id.yaml description: | - Public global object identifier, see [_id URI representation](#section/Concepts/Identifier/_id-URI-representation). + Public global object identifier, see [_id URI representation](#id-uri-representation). Once object is assigned a global identifier, it should never change. Internally local identifiers, should be associated with public diff --git a/draft/openapi/docs.md b/draft/openapi/docs.md index 88ba69b..9a70951 100644 --- a/draft/openapi/docs.md +++ b/draft/openapi/docs.md @@ -202,7 +202,7 @@ All API URL's are constructed using one of the following patters: dataset `/` model -- Get single object, see [_id URI representation](#section/Concepts/Identifier/_id-URI-representation): +- Get single object, see [_id URI representation](#id-uri-representation): `https://` domain `/` @@ -797,6 +797,8 @@ name. `_id` can be defined as one of these types: - UUID - Integer + + ### _id URI representation The operations, which use `_id` in their URI, change depending on the fields type. From 204cceac170ddee9f09ad2bbc9e22de44a8b6618 Mon Sep 17 00:00:00 2001 From: Gustas Badaitis Date: Tue, 2 Jun 2026 10:56:58 +0300 Subject: [PATCH 5/9] Additional changes --- draft/openapi/docs.md | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/draft/openapi/docs.md b/draft/openapi/docs.md index 9a70951..87599ca 100644 --- a/draft/openapi/docs.md +++ b/draft/openapi/docs.md @@ -790,6 +790,10 @@ building, since building is the same, single global identifier must be used: /datasets/gov/rc/ntr/uapi/report/Pastatas/e96cc0cc-08be-460d-a887-98f80612a402 ``` + + +### _id URI representation + Global identifiers should be defined in the manifest, using `_id` as the property name. `_id` can be defined as one of these types: - String @@ -797,17 +801,20 @@ name. `_id` can be defined as one of these types: - UUID - Integer - - -### _id URI representation -The operations, which use `_id` in their URI, change depending on the fields type. +The operations, which use `_id` in their URI, change depending on the field type. If the `_id` is of type String or Base32, then the `_id` is specified in the URI with an equal sign: ```code - \=id + /=id ``` +Otherwise, for UUID and Integer types, the `_id` is specified in the URI directly without an equal sign: +`` + ```code`` + /id`` + ````` + ## Model Real world entities are identified using global identifiers. Each real world From a9e41c2431b310b56146865ce69ebf06b125deed Mon Sep 17 00:00:00 2001 From: Gustas Badaitis Date: Wed, 3 Jun 2026 10:44:24 +0300 Subject: [PATCH 6/9] Review changes --- draft/openapi/components/schemas/id.yaml | 23 +++++-- draft/openapi/docs.md | 86 +++++++++++++++++++----- 2 files changed, 86 insertions(+), 23 deletions(-) diff --git a/draft/openapi/components/schemas/id.yaml b/draft/openapi/components/schemas/id.yaml index 254fe7a..c604aad 100644 --- a/draft/openapi/components/schemas/id.yaml +++ b/draft/openapi/components/schemas/id.yaml @@ -1,9 +1,20 @@ oneOf: - type: integer + description: Integer identifier (Int model type) + examples: + - 123 - type: string - pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|=[^\s]+|[^=\s][^\s]*)$ -examples: - - abdd1245-bbf9-4085-9366-f11c0f737c1d - - =some-string-id - - 42,LT - - 123 + description: UUID identifier (Uuid model type) + pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ + examples: + - abdd1245-bbf9-4085-9366-f11c0f737c1d + - type: string + description: String or Base32 identifier, prefixed with = (Str, Base32, CompBase32 model types) + pattern: ^=[^\s]+$ + examples: + - =some-name + - type: string + description: Composite string identifier (Comp model type) + pattern: ^[^=\s][^\s]*$ + examples: + - 42,LT diff --git a/draft/openapi/docs.md b/draft/openapi/docs.md index 87599ca..54291b2 100644 --- a/draft/openapi/docs.md +++ b/draft/openapi/docs.md @@ -790,30 +790,82 @@ building, since building is the same, single global identifier must be used: /datasets/gov/rc/ntr/uapi/report/Pastatas/e96cc0cc-08be-460d-a887-98f80612a402 ``` +## Identifier formats + -### _id URI representation +### Integer identifier -Global identifiers should be defined in the manifest, using `_id` as the property -name. `_id` can be defined as one of these types: -- String -- Base32 -- UUID -- Integer +Integer identifiers are stored as a plain integer in JSON and used directly in the URI. +JSON: +```json +{"_id": 123} +``` -The operations, which use `_id` in their URI, change depending on the field type. -If the `_id` is of type String or Base32, then the `_id` is specified in the URI with an equal sign: +URI: +``` +/Model/123 +``` - ```code - /=id - ``` +### UUID identifier + +UUID identifiers are stored as a UUID string in JSON and used directly in the URI. + +JSON: +```json +{"_id": "abdd1245-bbf9-4085-9366-f11c0f737c1d"} +``` + +URI: +``` +/Model/abdd1245-bbf9-4085-9366-f11c0f737c1d +``` + +### String identifier + +String identifiers are stored as a plain string in JSON. In the URI they are prefixed with `=` to distinguish them from models and properties. + +JSON: +```json +{"_id": "some-name"} +``` + +URI: +``` +/Model/=some-name +``` + +### Composite identifier + +Composite identifiers combine multiple fields into a comma-separated string in JSON and used directly in the URI. + +JSON: +```json +{"_id": "42,LT"} +``` + +URI: +``` +/Model/42,LT +``` + +### Base32 identifier + +Base32 identifiers are stored as a Base32-encoded string in JSON and prefixed with `=` in the URI. For simple values, the +raw value is Base32-encoded directly. For composite values, CBOR encoding is applied first, then the result is Base32-encoded. +In both cases the JSON and URI representation follow the same format. + +JSON: +```json +{"_id": "BASE32ENCODED"} +``` + +URI: +``` +/Model/=BASE32ENCODED +``` -Otherwise, for UUID and Integer types, the `_id` is specified in the URI directly without an equal sign: -`` - ```code`` - /id`` - ````` ## Model From cd7e223f3697cfd3e97621b28a80631269535a32 Mon Sep 17 00:00:00 2001 From: Gustas Badaitis Date: Wed, 3 Jun 2026 11:01:57 +0300 Subject: [PATCH 7/9] Additional id change --- draft/openapi/components/schemas/id.yaml | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/draft/openapi/components/schemas/id.yaml b/draft/openapi/components/schemas/id.yaml index c604aad..15bd260 100644 --- a/draft/openapi/components/schemas/id.yaml +++ b/draft/openapi/components/schemas/id.yaml @@ -1,20 +1,27 @@ oneOf: - type: integer - description: Integer identifier (Int model type) + description: Integer identifier + minimum: 1 examples: - 123 - type: string - description: UUID identifier (Uuid model type) + format: uuid + description: UUID identifier pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ examples: - abdd1245-bbf9-4085-9366-f11c0f737c1d - type: string - description: String or Base32 identifier, prefixed with = (Str, Base32, CompBase32 model types) + description: String identifier, prefixed with = pattern: ^=[^\s]+$ examples: - =some-name - type: string - description: Composite string identifier (Comp model type) + description: Composite string identifier pattern: ^[^=\s][^\s]*$ examples: - 42,LT + - type: string + description: Base32 identifier, prefixed with = + pattern: ^=[A-Z2-7]+=*$ + examples: + - =NBSWY3DP From 906ed84fdf8d4e7b1ddf1e2ddae956ddebd02ca2 Mon Sep 17 00:00:00 2001 From: Gustas Badaitis Date: Wed, 3 Jun 2026 15:17:46 +0300 Subject: [PATCH 8/9] Review changes --- draft/openapi/components/schemas/id.yaml | 18 +++++--- draft/openapi/docs.md | 58 ++++++++++++++++-------- 2 files changed, 51 insertions(+), 25 deletions(-) diff --git a/draft/openapi/components/schemas/id.yaml b/draft/openapi/components/schemas/id.yaml index 15bd260..6a7ed0f 100644 --- a/draft/openapi/components/schemas/id.yaml +++ b/draft/openapi/components/schemas/id.yaml @@ -1,27 +1,33 @@ oneOf: - - type: integer + - title: Integer + type: integer description: Integer identifier minimum: 1 examples: - 123 - - type: string + - title: UUID + type: string format: uuid description: UUID identifier pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ examples: - abdd1245-bbf9-4085-9366-f11c0f737c1d - - type: string + - title: String + type: string description: String identifier, prefixed with = pattern: ^=[^\s]+$ examples: - =some-name - - type: string + - title: Composite + type: string description: Composite string identifier pattern: ^[^=\s][^\s]*$ examples: - 42,LT - - type: string - description: Base32 identifier, prefixed with = + - title: Base32 + type: string + format: base32 + description: Base32 identifier, prefixed with =. See [Base32 identifier](#id-uri-representation). pattern: ^=[A-Z2-7]+=*$ examples: - =NBSWY3DP diff --git a/draft/openapi/docs.md b/draft/openapi/docs.md index 54291b2..f6377fa 100644 --- a/draft/openapi/docs.md +++ b/draft/openapi/docs.md @@ -790,13 +790,13 @@ building, since building is the same, single global identifier must be used: /datasets/gov/rc/ntr/uapi/report/Pastatas/e96cc0cc-08be-460d-a887-98f80612a402 ``` -## Identifier formats +### Identifier formats -### Integer identifier +#### Integer identifier -Integer identifiers are stored as a plain integer in JSON and used directly in the URI. +Identifier can be stored as a plain integer in JSON and is used directly in the URI. JSON: ```json @@ -805,12 +805,12 @@ JSON: URI: ``` -/Model/123 +Model/123 ``` -### UUID identifier +#### UUID identifier -UUID identifiers are stored as a UUID string in JSON and used directly in the URI. +Identifier can be stored as a UUID string in JSON and is used directly in the URI. JSON: ```json @@ -819,12 +819,12 @@ JSON: URI: ``` -/Model/abdd1245-bbf9-4085-9366-f11c0f737c1d +Model/abdd1245-bbf9-4085-9366-f11c0f737c1d ``` -### String identifier +#### String identifier -String identifiers are stored as a plain string in JSON. In the URI they are prefixed with `=` to distinguish them from models and properties. +Identifier can be stored as a plain string in JSON. In the URI it is prefixed with `=` to distinguish it from model and property names. JSON: ```json @@ -833,12 +833,12 @@ JSON: URI: ``` -/Model/=some-name +Model/=some-name ``` -### Composite identifier +#### Composite identifier -Composite identifiers combine multiple fields into a comma-separated string in JSON and used directly in the URI. +Identifier can be stored as a comma-separated string of multiple fields in JSON and is used directly in the URI. JSON: ```json @@ -847,23 +847,43 @@ JSON: URI: ``` -/Model/42,LT +Model/42,LT ``` -### Base32 identifier +#### Base32 identifier -Base32 identifiers are stored as a Base32-encoded string in JSON and prefixed with `=` in the URI. For simple values, the -raw value is Base32-encoded directly. For composite values, CBOR encoding is applied first, then the result is Base32-encoded. -In both cases the JSON and URI representation follow the same format. +Identifier can be stored as a Base32-encoded string in JSON and is prefixed with `=` in the URI. + +For a simple (non-composite) value, the raw value is Base32-encoded directly: + +``` +"hello" → NBSWY3DP +``` + +JSON: +```json +{"_id": "NBSWY3DP"} +``` + +URI: +``` +Model/=NBSWY3DP +``` + +For a composite value, the fields are put into an array and encoded using CBOR encoding, then the result is Base32-encoded: + +``` +[42, "LT"] → CBOR → 82182a624c54 → Base32 → QIMCMJSGK3TF +``` JSON: ```json -{"_id": "BASE32ENCODED"} +{"_id": "QIMCMJSGK3TF"} ``` URI: ``` -/Model/=BASE32ENCODED +Model/=QIMCMJSGK3TF ``` From 4cf6f115d1ad298095f579c515084fa88b6295d1 Mon Sep 17 00:00:00 2001 From: Gustas Badaitis Date: Wed, 3 Jun 2026 15:26:58 +0300 Subject: [PATCH 9/9] Revision change --- draft/openapi/docs.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/draft/openapi/docs.md b/draft/openapi/docs.md index f6377fa..991120b 100644 --- a/draft/openapi/docs.md +++ b/draft/openapi/docs.md @@ -1067,6 +1067,8 @@ name. `_revision` can be defined as one of these types: - Base32 - UUID - Integer +- Composite +The formats follow the same rules, as `_id` formats, see [Identifier formats](#id-uri-representation). When update action is made on an object, revision number must always be provided, in order to compare object version received by the Client and object