Merge pull request #6 from riteris13/wip-oas

Updated after comments from 2024-03-05

openapi/components/parameters/file.yaml

@@ -1,8 +1,8 @@
 name: file
-in: header
-required: false
+in: path
+required: true
 description: |
-  `file` header is used to indicate the file that needs to be retrieved form the object structure.
+  `file` parameter is used to indicate the file that needs to be retrieved form the object structure.
 schema:
   type: string
   examples:

openapi/components/responses/error400.yaml

@@ -6,7 +6,3 @@ content:
   application/json:
     schema:
       $ref: ../schemas/errors.yaml
-      examples:
-        - errors:
-            error: Invalid_client
-            error_description: Invalid client name

openapi/components/responses/error403.yaml

@@ -6,12 +6,3 @@ content:
   application/json:
     schema:
       $ref: ../schemas/errors.yaml
-      examples:
-        - errors:
-            - items:
-                code: InsufficientPermission
-                context:
-                  scope: auth_clients
-                message: You need to have 'auth_clients' in order to access this API endpoint.
-                template: You need to have {scope!r} in order to access this API endpoint.
-                type: system

openapi/components/responses/error404.yaml

@@ -6,7 +6,3 @@ content:
   application/json:
     schema:
       $ref: ../schemas/errors.yaml
-      examples:
-        - errors:
-            error: ItemDoesNotExist
-            error_description: Resource 'c9b40700-ddbf-48d9-b747-d1f90a37e32c' not found.

openapi/components/schemas/URI.yaml

@@ -0,0 +1,2 @@
+description: Uniform Resource Identifier. Used to provide an identifier of an external resource, in an RDF data model it is subject indentifier.
+type: string

openapi/components/schemas/URL.yaml

@@ -0,0 +1,2 @@
+description: Uniform Resource Locator. Used to provide links to external sources.
+type: string

openapi/components/schemas/_op.yaml

@@ -0,0 +1,4 @@
+type: string
+enum:
+  - "insert"
+  - "patch"

openapi/components/schemas/_type.yaml

@@ -0,0 +1,5 @@
+description: |
+  Name of the namespace or model
+type: string
+examples:
+  - "datasets/gov/dc/geo/Continent"

openapi/components/schemas/absent.yaml

@@ -0,0 +1,7 @@
+description: For objects that have been deleted during change, `type` value is changed to `absent`
+type: object
+properties:
+  type:
+    type: string
+    enum:
+      - absent

openapi/components/schemas/array.yaml

@@ -0,0 +1,2 @@
+description: Array of data. It is recommended to avoid this type and instead use `backref`
+type: array

openapi/components/schemas/backref.yaml

@@ -0,0 +1,3 @@
+description: Backwards link showing that another model has a link to this one. This item does not hold any data
+type: string
+enum:

openapi/components/schemas/binary.yaml

@@ -0,0 +1,3 @@
+description: Binary string of data. A single set should not exceed 1G
+type: string
+patternProerties: "[0-1]+"

openapi/components/schemas/boolean.yaml

@@ -0,0 +1,10 @@
+description: Logical value of true or false, depending on maturity level this value can be expressed in a non standard true/false values if maturity level is lower than 3
+oneOf: 
+  - type: string
+    description: Maturity level < 3
+    examples:
+      - true
+      - 1
+      - taip
+  - type: boolean
+    description: Maturity level >= 3

openapi/components/schemas/changes.yaml

@@ -1,9 +1,7 @@
 type: object
 properties:
   _type:
-    type: string
-    examples:
-      - datasets/gov/dc/geo/Continent
+    $ref: ./_type.yaml
   _data:
     type: array
     items:

openapi/components/schemas/date.yaml

@@ -0,0 +1,13 @@
+description: |
+  Date provided in a standard format based on [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)
+
+  Minimum value: `0001-01-01`
+  Maximum value: `999-12-31`
+
+  If the resoliution of data is lower than a day or a month 01 can be used instead.
+
+  Based on maturity level data can be:
+  - maturity level 1 - provided in diffent formats or free text
+  - maturity level 2 - not according to standard but all in the same format. Or different parts of data are avalable in different fields (eg. year in one field and a month in another)
+  - maturity level >=3 - data provided according to `ISO 8601` standard
+type: string

openapi/components/schemas/dateTime.yaml

@@ -0,0 +1,11 @@
+description: |
+  Date and time provided in a standard format based on [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)
+
+  Minimum value: `0001-01-01T00:00:00`
+  Maximum value: `999-12-31T23:59:59.999999`
+
+  Based on maturity level data can be:
+  - maturity level 1 - provided in diffent formats or free text
+  - maturity level 2 - not according to standard but all in the same format. Or different parts of data are avalable in different fields (eg. year in one field and a month in another)
+  - maturity level >=3 - data provided according to `ISO 8601` standard
+type: string

openapi/components/schemas/error.yaml

@@ -2,7 +2,7 @@ type: object
 description: |
   In addition to usual HTTP error codes, additional error information available from the processing system is passed to the client.
 
-  This would include a more detailed overview of the internal, business logic or request processing errors that have occurred.
+  This should include a more detailed overview of the internal, business logic or request processing errors that have occurred.
 
   More complex errors can further expand this structure.
 properties:
@@ -14,21 +14,47 @@ properties:
       - model
       - property
   code:
-    type: string
-    pattern: ^[A-Z]([A-Z]?[a-z0-9]+)*$
-    examples:
-      - NotImplementedError
-      - TypeError
+    description: Each code corresponds to template text for that code
+    type: integer
+    enum:
+      - 400
+      - 401
+      - 403
+      - 404
+      - 409
+      - 500
+      - 503
   template:
+    description: Corresponds to HTTP code
     type: string
+    enum:
+      - Bad Request
+      - Unauthorised
+      - Forbidden
+      - Not Found
+      - Conflict
+      - Internal Server Error
+      - Service Unavalable
   message:
+    description: |
+      Message within the error object contains a more detailed description of the server errors.
+      These should include more detailed overview of the internal, business logic or request processing errors that have occurred.
+
+      For example:
+        - "Could not find signature for and: <DaskDataFrameQueryBuilder, Expr>"
+        - "Cannot use .astype to convert from timezone-aware dtype to timezone-naive dtype. Use obj.tz_localize(None) or obj.tz_convert('UTC').tz_localize(None) instead."
+        - "Property {property!r} not found"
+        - "Given value {value} is not defined in enum."
+        - "New item has revision already set"
+        - "You do not have permission to push this property."
     type: string
     examples:
-      - 'Could not find signature for and: <DaskDataFrameQueryBuilder, Expr>'
-      - >-
-        Cannot use .astype to convert from timezone-aware dtype to
-        timezone-naive dtype. Use obj.tz_localize(None) or
-        obj.tz_convert('UTC').tz_localize(None) instead.
+      - "Could not find signature for and: <DaskDataFrameQueryBuilder, Expr>"
+      - "Cannot use .astype to convert from timezone-aware dtype to timezone-naive dtype. Use obj.tz_localize(None) or obj.tz_convert('UTC').tz_localize(None) instead."
+      - "Property {property!r} not found"
+      - "Given value {value} is not defined in enum."
+      - "New item has revision already set"
+      - "You do not have permission to push this property."
   context:
     type: object
     properties:
@@ -40,4 +66,4 @@ properties:
         $ref: ./property.yaml
       id:
         $ref: ./id.yaml
-    additionalProperties: true
+    additionalProperties: true

openapi/components/schemas/file.yaml

@@ -0,0 +1,14 @@
+type: object
+properties:
+  id:
+    description: File unique identifier. During storage this will become an indetifier for the file.
+    type: string
+    format: UUID
+  name:
+    type: string
+  type:
+    description: A [Media type](https://en.wikipedia.org/wiki/Media_type) of the file.
+    type: string
+  size:
+    description: File size in bytes.
+    type: integer

openapi/components/schemas/generic.yaml

@@ -0,0 +1,10 @@
+description: Dynamic relationship with a model. Used when there is a need to reflect a dynamic link to another model - not only via id, but also via it's name. Using this, one element can be linked to multiple models.
+type: object
+properties:
+  object_model:
+    description: Full name of a linked model
+    type: string
+  object_id:
+    description: Linked model ID
+    type: string
+    format: UUID

openapi/components/schemas/geometry.yaml

@@ -0,0 +1,83 @@
+description: |
+  Geometry data. Data provided in [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format, using [EPSG](https://epsg.org/home.html) database parameters, for different projections.
+  It can be presented as:
+    - geometry(form, crs) - providing form and coordinate system
+    - geometry(crs) - providing coordinate system only
+    - geometry(form) - providing form only
+    - geometry - no arguments.
+
+  Depending on maturity level:
+    - Level 1 - Coordinate system is not defined and data is provided in different coordinate systems. Mixed axes, for example some data is provided as `x, y`, other as `y, x`. Mixed measurements, for example some data is in meters, other in degrees. Adress is provided without coordinates.
+    - Level 2 - Coordinate system is not defined, but all data is provided according to a single coordinate system.
+    - Level 3 - Data accuracy in meters element `property.ref` is not provided.
+
+oneOf:
+  - type: object
+    properties:
+      form:
+        description: Geometry form can have these types - `point`, `linestring`, `polygon`, `multipoint`, `multilinestring`, `multipolygon`. Each of these types can have `z` (height), `m` (selected measurement like time, distance, width, etc.) or `zm` (height and a selected measurement) designations after the type.
+        type: string
+        enum:
+          - point
+          - point z
+          - point m
+          - point zm
+          - linestring
+          - linestring z
+          - linestring m
+          - linestring zm
+          - polygon
+          - polygon z
+          - polygon m
+          - polygon zm
+          - multipoint
+          - multipoint z
+          - multipoint m
+          - multipoint zm
+          - multilinestring
+          - multilinestring z
+          - multilinestring m
+          - multilinestring zm
+          - multipolygon
+          - multipolygon z
+          - multipolygon m
+          - multipolygon zm
+      crs:
+        description: A [SRID](https://en.wikipedia.org/wiki/Spatial_reference_system#Identifier) number, which is and identification number of a coordinate system in [EPSG](https://epsg.org/home.html) database. If the number is not provided, it is assumed that data corresponds to `4326` ( [WGS84](https://epsg.io/4326) )
+        type: integer
+  - type: object
+    properties:
+      form:
+        description: Geometry form can have these types - `point`, `linestring`, `polygon`, `multipoint`, `multilinestring`, `multipolygon`. Each of these types can have `z` (height), `m` (selected measurement like time, distance, width, etc.) or `zm` (height and a selected measurement) designations after the type.
+        type: string
+        enum:
+          - point
+          - point z
+          - point m
+          - point zm
+          - linestring
+          - linestring z
+          - linestring m
+          - linestring zm
+          - polygon
+          - polygon z
+          - polygon m
+          - polygon zm
+          - multipoint
+          - multipoint z
+          - multipoint m
+          - multipoint zm
+          - multilinestring
+          - multilinestring z
+          - multilinestring m
+          - multilinestring zm
+          - multipolygon
+          - multipolygon z
+          - multipolygon m
+          - multipolygon zm
+  - type: object
+    properties:
+      crs:
+        description: A [SRID](https://en.wikipedia.org/wiki/Spatial_reference_system#Identifier) number, which is and identification number of a coordinate system in [EPSG](https://epsg.org/home.html) database. If the number is not provided, it is assumed that data corresponds to `4326` ( [WGS84](https://epsg.io/4326) )
+        type: integer
+  - type: string

openapi/components/schemas/image.yaml

@@ -0,0 +1,3 @@
+image:
+description: Image file with a same structure as file.
+$ref: ./file.yaml

openapi/components/schemas/integer.yaml

@@ -0,0 +1,4 @@
+description: A value of a whole number
+type: integer
+minimum: -2147483648
+maximum: 2147483647

openapi/components/schemas/money.yaml

@@ -0,0 +1,2 @@
+description: The amount of a certain currency. Currency code is provided in `property.ref` in accordance to [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217).
+type: number

openapi/components/schemas/multiInsert.yaml

@@ -4,13 +4,6 @@ properties:
     type: array
     items:
       anyOf:
-        - _op:
-          type: string
-          enum:
-            - insert
-            - patch
-        - _type:
-          type: string
-          examples:
-            - datasets/gov/dc/geo/Continent
-        - $ref: insert.yaml
+        - $ref: ./_op.yaml
+        - $ref: ./_type.yaml
+        - $ref: ./insert.yaml

openapi/components/schemas/number.yaml

@@ -0,0 +1,2 @@
+description: A value of a real number, based on Floating-Point Arithmetic (IEEE 754), with a decimal point marked with `.`. Whole number can be up to 6 characters in lengh.
+type: number