From 3f21ee11008488682302b201626f1d351bc8eeed Mon Sep 17 00:00:00 2001 From: stripodi Date: Sat, 30 Aug 2025 19:19:52 +0200 Subject: [PATCH 1/8] feat: ProblemDetails 2020-12 JSON Schema initial checkin --- schema.yaml | 560 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 560 insertions(+) create mode 100644 schema.yaml diff --git a/schema.yaml b/schema.yaml new file mode 100644 index 0000000..8da495e --- /dev/null +++ b/schema.yaml @@ -0,0 +1,560 @@ +# Copyright 2023-2025 SmartBear +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +$schema: 'https://json-schema.org/draft//schema' +$id: 'https://problems-registry.smartbear.com/ProblemDetails/1.0.0' +$ref: '#/$defs/ProblemDetails' + +$defs: + + ErrorDetail: + type: object + description: >- + An object to provide explicit details on a problem towards an API consumer. + required: + - detail + properties: + detail: + type: string + description: >- + A granular description on the specific error related to a body + property, query parameter, path parameters, and/or header. + maxLength: 4096 + enum: + - 'about:blank' + - 'https://problems-registry.smartbear.com/already-exists' + - 'https://problems-registry.smartbear.com/bad-request' + - 'https://problems-registry.smartbear.com/business-rule-violation' + - 'https://problems-registry.smartbear.com/forbidden' + - 'https://problems-registry.smartbear.com/invalid-body-property-format' + - 'https://problems-registry.smartbear.com/invalid-body-property-value' + - 'https://problems-registry.smartbear.com/invalid-parameters' + - 'https://problems-registry.smartbear.com/invalid-request-header-format' + - 'https://problems-registry.smartbear.com/invalid-request-parameter-format' + - 'https://problems-registry.smartbear.com/invalid-request-parameter-value' + - 'https://problems-registry.smartbear.com/license-cancelled' + - 'https://problems-registry.smartbear.com/license-expired' + - 'https://problems-registry.smartbear.com/missing-body-property' + - 'https://problems-registry.smartbear.com/missing-request-header' + - 'https://problems-registry.smartbear.com/not-found' + - 'https://problems-registry.smartbear.com/server-error' + - 'https://problems-registry.smartbear.com/service-unavailable' + - 'https://problems-registry.smartbear.com/unauthorized' + - 'https://problems-registry.smartbear.com/validation-error' + pointer: + type: string + description: >- + A JSON Pointer to a specific request body property that is the + source of error. + maxLength: 1024 + parameter: + type: string + description: The name of the query or path parameter that is the source of error. + maxLength: 1024 + header: + type: string + description: The name of the header that is the source of error. + maxLength: 1024 + code: + type: string + description: >- + A string containing additional provider specific codes to identify + the error context. + maxLength: 50 + + Errors: + type: array + description: An array of error details to accompany a problem details response. + maxItems: 1000 + items: + $ref: '#/$defs/ErrorDetail' + + ProblemDetails: + type: object + description: >- + The `ProblemDetails` object provides detailed information about an errors that occurred during an API call execution. + This problem object conforms to the [RFC9457](https://www.rfc-editor.org/info/rfc9457) (formerly [RFC7807](https://tools.ietf.org/html/rfc7807)). + + The object is extended with the following properties: + - `code` - a string identifier to aid the provider team better understand the error + - `errors` - and array of errors providing contextual information on the root cause of the problem + + The `ProblemDetails` referenced by this domain utilize the [SmartBear Problems Registry](https://problems-registry.smartbear.com/). + required: + - detail + properties: + type: + type: string + description: A URI reference that identifies the problem type. + format: uri + maxLength: 1024 + status: + type: integer + description: >- + The HTTP status code generated by the origin server for this occurrence of + the problem. + format: int32 + minimum: 100 + maximum: 599 + title: + type: string + description: >- + A short, human-readable summary of the problem type. It should not change + from occurrence to occurrence of the problem, except for purposes of + localization. + maxLength: 1024 + detail: + type: string + description: A human-readable explanation specific to this occurrence of the problem. + maxLength: 4096 + instance: + type: string + description: >- + A URI reference that identifies the specific occurrence of the problem. It + may or may not yield further information if dereferenced. + maxLength: 1024 + code: + type: string + description: >- + An API specific error code aiding the provider team understand the error + based on their own potential taxonomy or registry. + maxLength: 50 + errors: + ref: '#/$defs/Errors' + +# Utility objects + + AlreadyExists: + type: object + description: >- + This problem occurs when the resource being created is found to already exist on the server. + + Your client application tried to create a resource that already exists. Perhaps review your client logic to determine if a user should be able to send such a request. + allOf: + - $ref: "#/$defs/ProblemDetails" + properties: + type: + type: string + description: A URI reference that identifies the problem type. + format: uri + const: 'https://problems-registry.smartbear.com/already-exists' + status: + type: integer + description: >- + The HTTP status code generated by the origin server for this occurrence of + the problem. + format: int32 + const: 409 + + BadRequest: + type: object + description: >- + The server cannot or will not process the request due to something that is perceived to be a client error (for example, malformed request syntax, invalid request message framing, or deceptive request routing). + + Your client application initiated a request that is malformed. Please review your client request against the defined semantics for the API. + allOf: + - $ref: "#/$defs/ProblemDetails" + properties: + type: + type: string + description: A URI reference that identifies the problem type. + format: uri + const: 'https://problems-registry.smartbear.com/bad-request' + status: + type: integer + description: >- + The HTTP status code generated by the origin server for this occurrence of + the problem. + format: int32 + const: 400 + + BusinessRuleViolation: + type: object + description: >- + This problem occurs when the request is deemed invalid as it fails to meet business rule expectations. + + Your client issued a request that failed business rule validation. Please review your request to determine if you can remain within appropriate business rules. + allOf: + - $ref: "#/$defs/ProblemDetails" + properties: + type: + type: string + description: A URI reference that identifies the problem type. + format: uri + const: 'https://problems-registry.smartbear.com/business-rule-violation' + status: + type: integer + description: >- + The HTTP status code generated by the origin server for this occurrence of + the problem. + format: int32 + const: 422 + + Forbidden: + type: object + description: >- + This problem occurs when the requested resource (and/or operation combination) is not authorized for the requesting client (and or authorization context). + + Your client application tried to perform an operation on a resource that it's not authorized to perform in the given context. + allOf: + - $ref: "#/$defs/ProblemDetails" + properties: + type: + type: string + description: A URI reference that identifies the problem type. + format: uri + const: 'https://problems-registry.smartbear.com/forbidden' + status: + type: integer + description: >- + The HTTP status code generated by the origin server for this occurrence of + the problem. + format: int32 + const: 403 + + InvalidBodyPropertyFormat: + type: object + description: >- + This problem occurs when the request body contain a malformed property. + + Your client issued a request that contained a malformed body property. Please review your request and compare against the shared API definition. + allOf: + - $ref: "#/$defs/ProblemDetails" + properties: + type: + type: string + description: A URI reference that identifies the problem type. + format: uri + const: 'https://problems-registry.smartbear.com/invalid-body-property-format' + status: + type: integer + description: >- + The HTTP status code generated by the origin server for this occurrence of + the problem. + format: int32 + const: 400 + + InvalidBodyPropertyValue: + type: object + description: >- + This problem occurs when the request body contains a invalid property value. + + Your client issued a request that contained an invalid body property value. Please review your request and compare against the shared API definition where applicable. + allOf: + - $ref: "#/$defs/ProblemDetails" + properties: + type: + type: string + description: A URI reference that identifies the problem type. + format: uri + const: 'https://problems-registry.smartbear.com/invalid-body-property-value' + status: + type: integer + description: >- + The HTTP status code generated by the origin server for this occurrence of + the problem. + format: int32 + const: 400 + + InvalidParameters: + type: object + description: >- + This problem occurs when a client request contains invalid or malformed parameters causing the server to reject the request. + + Your client application issued a request to an API that contains invalid or malformed parameters. + allOf: + - $ref: "#/$defs/ProblemDetails" + properties: + type: + type: string + description: A URI reference that identifies the problem type. + format: uri + const: 'https://problems-registry.smartbear.com/invalid-parameters' + status: + type: integer + description: >- + The HTTP status code generated by the origin server for this occurrence of + the problem. + format: int32 + const: 400 + + InvalidRequestHeaderFormat: + type: object + description: >- + This problem occurs when the request contains a malformed request header. + + Your client issued a request that contained a malformed request header. Please review your request parameters and compare against the shared API definition when applicable. + allOf: + - $ref: "#/$defs/ProblemDetails" + properties: + type: + type: string + description: A URI reference that identifies the problem type. + format: uri + const: 'https://problems-registry.smartbear.com/invalid-request-header-format' + status: + type: integer + description: >- + The HTTP status code generated by the origin server for this occurrence of + the problem. + format: int32 + const: 400 + + InvalidRequestParameterFormat: + type: object + description: >- + This problem occurs when the request contains a malformed query or path parameter. + + Your client issued a request that contained a malformed query or path parameter. + Please review your request parameters and compare against the shared API definition. + allOf: + - $ref: "#/$defs/ProblemDetails" + properties: + type: + type: string + description: A URI reference that identifies the problem type. + format: uri + const: 'https://problems-registry.smartbear.com/invalid-request-parameter-format' + status: + type: integer + description: >- + The HTTP status code generated by the origin server for this occurrence of + the problem. + format: int32 + const: 400 + + InvalidRequestParameterValue: + type: object + description: >- + This problem occurs when the request contains a invalid query or path parameter value. + + Your client issued a request that contained an invalid query or path parameter value. + Please review your request and compare against the shared API definition where applicable. + allOf: + - $ref: "#/$defs/ProblemDetails" + properties: + type: + type: string + description: A URI reference that identifies the problem type. + format: uri + const: 'https://problems-registry.smartbear.com/invalid-request-parameter-value' + status: + type: integer + description: >- + The HTTP status code generated by the origin server for this occurrence of + the problem. + format: int32 + const: 400 + + LicenseCancelled: + type: object + description: >- + This problem occurs when the license associated with the client has been cancelled thus rendering the service unavailable. + + The license associated with your client/organization has been cancelled. + Please contact your account manager or representative. + allOf: + - $ref: "#/$defs/ProblemDetails" + properties: + type: + type: string + description: A URI reference that identifies the problem type. + format: uri + const: 'https://problems-registry.smartbear.com/license-cancelled' + status: + type: integer + description: >- + The HTTP status code generated by the origin server for this occurrence of + the problem. + format: int32 + const: 503 + + LicenseExpired: + type: object + description: >- + This problem occurs when the license associated with the client has expired thus rendering the service unavailable. + + The license associated with your client/organization has expired. + Please contact your account manager or representative. + allOf: + - $ref: "#/$defs/ProblemDetails" + properties: + type: + type: string + description: A URI reference that identifies the problem type. + format: uri + const: 'https://problems-registry.smartbear.com/license-expired' + status: + type: integer + description: >- + The HTTP status code generated by the origin server for this occurrence of + the problem. + format: int32 + const: 503 + + MissingBodyProperty: + type: object + description: >- + This problem occurs when the request sent to the API is missing an expected body property. + + Your client issued a request that omitted an expected body property. + allOf: + - $ref: "#/$defs/ProblemDetails" + properties: + type: + type: string + description: A URI reference that identifies the problem type. + format: uri + const: 'https://problems-registry.smartbear.com/missing-body-property' + status: + type: integer + description: >- + The HTTP status code generated by the origin server for this occurrence of + the problem. + format: int32 + const: 400 + + MissingRequestHeader: + type: object + description: >- + This problem occurs when the request sent to the API is missing an expected request header. + + Your client issued a request that omitted an expected request header. + allOf: + - $ref: "#/$defs/ProblemDetails" + properties: + type: + type: string + description: A URI reference that identifies the problem type. + format: uri + const: 'https://problems-registry.smartbear.com/missing-request-header' + status: + type: integer + description: >- + The HTTP status code generated by the origin server for this occurrence of + the problem. + format: int32 + const: 400 + + NotFound: + type: object + description: >- + This problem occurs when the requested resource could not be found. + + Your client application tried to access a resource that does not exist (or could not be found). + allOf: + - $ref: "#/$defs/ProblemDetails" + properties: + type: + type: string + description: A URI reference that identifies the problem type. + format: uri + const: 'https://problems-registry.smartbear.com/not-found' + status: + type: integer + description: >- + The HTTP status code generated by the origin server for this occurrence of + the problem. + format: int32 + const: 404 + + ServerError: + type: object + description: >- + This problem occurs when the server encounters an unexpected condition that prevents it from fulfilling the request. + + Your client application did everything correct. Unfortunately our API encountered a condition that resulted in this problem. + allOf: + - $ref: "#/$defs/ProblemDetails" + properties: + type: + type: string + description: A URI reference that identifies the problem type. + format: uri + const: 'https://problems-registry.smartbear.com/server-error' + status: + type: integer + description: >- + The HTTP status code generated by the origin server for this occurrence of + the problem. + format: int32 + const: 500 + + ServiceUnavailable: + type: object + description: >- + This problem occurs when the service requested is currently unavailable and the server is not ready to handle the request. + + Your client application did everything correct. Unfortunately our API is currently unavailable. + allOf: + - $ref: "#/$defs/ProblemDetails" + properties: + type: + type: string + description: A URI reference that identifies the problem type. + format: uri + const: 'https://problems-registry.smartbear.com/service-unavailable' + status: + type: integer + description: >- + The HTTP status code generated by the origin server for this occurrence of + the problem. + format: int32 + const: 503 + + Unauthorized: + type: object + description: >- + This problem occurs when the requested resource could not be returned as the client request lacked valid authentication credentials. + + Your client application issued a requested to a protected resource without supplying the required auth details. + allOf: + - $ref: "#/$defs/ProblemDetails" + properties: + type: + type: string + description: A URI reference that identifies the problem type. + format: uri + const: 'https://problems-registry.smartbear.com/unauthorized' + status: + type: integer + description: >- + The HTTP status code generated by the origin server for this occurrence of + the problem. + format: int32 + const: 401 + + ValidationError: + type: object + description: >- + This problem occurs when the request is deemed unprocessable. + + Your client issued a request that failed validation. Certain validation libraries return multi-errors and cannot be easily parsed into discreet types. This problem type, afforded the provider with the ability to surface all validation errors and negate the need for a trial and error workflow on your side. + + Please review your request to determine if you can remain within appropriate business rules. Consider validating your request against available metadata (e.g. schemas) prior to sending to the server. + allOf: + - $ref: "#/$defs/ProblemDetails" + properties: + type: + type: string + description: A URI reference that identifies the problem type. + format: uri + const: 'https://problems-registry.smartbear.com/validation-error' + status: + type: integer + description: >- + The HTTP status code generated by the origin server for this occurrence of + the problem. + format: int32 + const: 422 From ed2b3d3e0c4165cf7f3e8a480e85824fbcf247e6 Mon Sep 17 00:00:00 2001 From: stripodi Date: Sat, 30 Aug 2025 20:35:10 +0200 Subject: [PATCH 2/8] fix: added missing missing-request-parameter --- schema.yaml | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/schema.yaml b/schema.yaml index 8da495e..5d49aea 100644 --- a/schema.yaml +++ b/schema.yaml @@ -447,6 +447,28 @@ $defs: format: int32 const: 400 + MissingRequestParameter: + type: object + description: >- + This problem occurs when the request sent to the API is missing an query or path parameter. + + Your client issued a request that omitted an expected query or path par. + allOf: + - $ref: "#/$defs/ProblemDetails" + properties: + type: + type: string + description: A URI reference that identifies the problem type. + format: uri + const: 'https://problems-registry.smartbear.com/missing-request-parameter' + status: + type: integer + description: >- + The HTTP status code generated by the origin server for this occurrence of + the problem. + format: int32 + const: 400 + NotFound: type: object description: >- From 169a802391f5650fd53fcb3bb40fe770cf0ff40c Mon Sep 17 00:00:00 2001 From: stripodi Date: Sat, 30 Aug 2025 21:57:26 +0200 Subject: [PATCH 3/8] fix: misplaced 'type' values --- schema.yaml | 42 +++++++++++++++++++++--------------------- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/schema.yaml b/schema.yaml index 5d49aea..077aaaf 100644 --- a/schema.yaml +++ b/schema.yaml @@ -31,27 +31,6 @@ $defs: A granular description on the specific error related to a body property, query parameter, path parameters, and/or header. maxLength: 4096 - enum: - - 'about:blank' - - 'https://problems-registry.smartbear.com/already-exists' - - 'https://problems-registry.smartbear.com/bad-request' - - 'https://problems-registry.smartbear.com/business-rule-violation' - - 'https://problems-registry.smartbear.com/forbidden' - - 'https://problems-registry.smartbear.com/invalid-body-property-format' - - 'https://problems-registry.smartbear.com/invalid-body-property-value' - - 'https://problems-registry.smartbear.com/invalid-parameters' - - 'https://problems-registry.smartbear.com/invalid-request-header-format' - - 'https://problems-registry.smartbear.com/invalid-request-parameter-format' - - 'https://problems-registry.smartbear.com/invalid-request-parameter-value' - - 'https://problems-registry.smartbear.com/license-cancelled' - - 'https://problems-registry.smartbear.com/license-expired' - - 'https://problems-registry.smartbear.com/missing-body-property' - - 'https://problems-registry.smartbear.com/missing-request-header' - - 'https://problems-registry.smartbear.com/not-found' - - 'https://problems-registry.smartbear.com/server-error' - - 'https://problems-registry.smartbear.com/service-unavailable' - - 'https://problems-registry.smartbear.com/unauthorized' - - 'https://problems-registry.smartbear.com/validation-error' pointer: type: string description: >- @@ -99,6 +78,27 @@ $defs: description: A URI reference that identifies the problem type. format: uri maxLength: 1024 + enum: + - 'about:blank' + - 'https://problems-registry.smartbear.com/already-exists' + - 'https://problems-registry.smartbear.com/bad-request' + - 'https://problems-registry.smartbear.com/business-rule-violation' + - 'https://problems-registry.smartbear.com/forbidden' + - 'https://problems-registry.smartbear.com/invalid-body-property-format' + - 'https://problems-registry.smartbear.com/invalid-body-property-value' + - 'https://problems-registry.smartbear.com/invalid-parameters' + - 'https://problems-registry.smartbear.com/invalid-request-header-format' + - 'https://problems-registry.smartbear.com/invalid-request-parameter-format' + - 'https://problems-registry.smartbear.com/invalid-request-parameter-value' + - 'https://problems-registry.smartbear.com/license-cancelled' + - 'https://problems-registry.smartbear.com/license-expired' + - 'https://problems-registry.smartbear.com/missing-body-property' + - 'https://problems-registry.smartbear.com/missing-request-header' + - 'https://problems-registry.smartbear.com/not-found' + - 'https://problems-registry.smartbear.com/server-error' + - 'https://problems-registry.smartbear.com/service-unavailable' + - 'https://problems-registry.smartbear.com/unauthorized' + - 'https://problems-registry.smartbear.com/validation-error' status: type: integer description: >- From 8482b1e63203800704722c1b1fbee59bdae3f386 Mon Sep 17 00:00:00 2001 From: stripodi Date: Sat, 30 Aug 2025 23:02:34 +0200 Subject: [PATCH 4/8] feat: updated OpenAPI initial checkin --- openapi.yaml | 1096 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1096 insertions(+) create mode 100644 openapi.yaml diff --git a/openapi.yaml b/openapi.yaml new file mode 100644 index 0000000..3ccce68 --- /dev/null +++ b/openapi.yaml @@ -0,0 +1,1096 @@ +# Copyright 2023-2025 SmartBear +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +openapi: 3.0.0 + +info: + title: ProblemDetailsRegistry + version: 1.0.0 + description: > + The SmartBear Problem Details Registry acts as a well known location for problem detail types returned by various SmartBear APIs. + It acts as a central registry to promote reuse and clarity of problem detail types conforming to [RFC9457](https://www.rfc-editor.org/info/rfc9457) (formerly [RFC7807](https://tools.ietf.org/html/rfc7807)). + + contact: + name: SmartBear Problem Details Registry + url: https://problems-registry.smartbear.com/ + + license: + name: Apache 2.0 + url: http://www.apache.org/licenses/LICENSE-2.0.html + +components: + + schemas: + + ErrorDetail: + type: object + description: >- + An object to provide explicit details on a problem towards an API consumer. + required: + - detail + properties: + detail: + type: string + description: >- + A granular description on the specific error related to a body + property, query parameter, path parameters, and/or header. + maxLength: 4096 + pointer: + type: string + description: >- + A JSON Pointer to a specific request body property that is the + source of error. + maxLength: 1024 + parameter: + type: string + description: The name of the query or path parameter that is the source of error. + maxLength: 1024 + header: + type: string + description: The name of the header that is the source of error. + maxLength: 1024 + code: + type: string + description: >- + A string containing additional provider specific codes to identify + the error context. + maxLength: 50 + + Errors: + type: array + description: An array of error details to accompany a problem details response. + maxItems: 1000 + items: + $ref: '#/components/schemas/ErrorDetail' + + ProblemDetails: + type: object + description: >- + The `ProblemDetails` object provides detailed information about an errors that occurred during an API call execution. + This problem object conforms to the [RFC9457](https://www.rfc-editor.org/info/rfc9457) (formerly [RFC7807](https://tools.ietf.org/html/rfc7807)). + + The object is extended with the following properties: + - `code` - a string identifier to aid the provider team better understand the error + - `errors` - and array of errors providing contextual information on the root cause of the problem + + The `ProblemDetails` referenced by this domain utilize the [SmartBear Problems Registry](https://problems-registry.smartbear.com/). + required: + - detail + properties: + title: + type: string + description: >- + A short, human-readable summary of the problem type. It should not change + from occurrence to occurrence of the problem, except for purposes of + localization. + maxLength: 1024 + detail: + type: string + description: A human-readable explanation specific to this occurrence of the problem. + maxLength: 4096 + instance: + type: string + description: >- + A URI reference that identifies the specific occurrence of the problem. It + may or may not yield further information if dereferenced. + maxLength: 1024 + code: + type: string + description: >- + An API specific error code aiding the provider team understand the error + based on their own potential taxonomy or registry. + maxLength: 50 + errors: + $ref: '#/components/schemas/Errors' + + # Utility objects + + AlreadyExists: + type: object + description: >- + This problem occurs when the resource being created is found to already exist on the server. + + Your client application tried to create a resource that already exists. Perhaps review your client logic to determine if a user should be able to send such a request. + allOf: + - $ref: "#/components/schemas/ProblemDetails" + properties: + type: + type: string + description: A URI reference that identifies the problem type. + format: uri + enum: + - 'https://problems-registry.smartbear.com/already-exists' + status: + type: integer + description: >- + The HTTP status code generated by the origin server for this occurrence of + the problem. + format: int32 + enum: + - 409 + + BadRequest: + type: object + description: >- + The server cannot or will not process the request due to something that is perceived to be a client error (for example, malformed request syntax, invalid request message framing, or deceptive request routing). + + Your client application initiated a request that is malformed. Please review your client request against the defined semantics for the API. + allOf: + - $ref: "#/components/schemas/ProblemDetails" + properties: + type: + type: string + description: A URI reference that identifies the problem type. + format: uri + enum: + - 'https://problems-registry.smartbear.com/bad-request' + status: + type: integer + description: >- + The HTTP status code generated by the origin server for this occurrence of + the problem. + format: int32 + enum: + - 400 + + BusinessRuleViolation: + type: object + description: >- + This problem occurs when the request is deemed invalid as it fails to meet business rule expectations. + + Your client issued a request that failed business rule validation. Please review your request to determine if you can remain within appropriate business rules. + allOf: + - $ref: "#/components/schemas/ProblemDetails" + properties: + type: + type: string + description: A URI reference that identifies the problem type. + format: uri + enum: + - 'https://problems-registry.smartbear.com/business-rule-violation' + status: + type: integer + description: >- + The HTTP status code generated by the origin server for this occurrence of + the problem. + format: int32 + enum: + - 422 + + Forbidden: + type: object + description: >- + This problem occurs when the requested resource (and/or operation combination) is not authorized for the requesting client (and or authorization context). + + Your client application tried to perform an operation on a resource that it's not authorized to perform in the given context. + allOf: + - $ref: "#/components/schemas/ProblemDetails" + properties: + type: + type: string + description: A URI reference that identifies the problem type. + format: uri + enum: + - 'https://problems-registry.smartbear.com/forbidden' + status: + type: integer + description: >- + The HTTP status code generated by the origin server for this occurrence of + the problem. + format: int32 + enum: + - 403 + + InvalidBodyPropertyFormat: + type: object + description: >- + This problem occurs when the request body contain a malformed property. + + Your client issued a request that contained a malformed body property. Please review your request and compare against the shared API definition. + allOf: + - $ref: "#/components/schemas/ProblemDetails" + properties: + type: + type: string + description: A URI reference that identifies the problem type. + format: uri + enum: + - 'https://problems-registry.smartbear.com/invalid-body-property-format' + status: + type: integer + description: >- + The HTTP status code generated by the origin server for this occurrence of + the problem. + format: int32 + enum: + - 400 + + InvalidBodyPropertyValue: + type: object + description: >- + This problem occurs when the request body contains a invalid property value. + + Your client issued a request that contained an invalid body property value. Please review your request and compare against the shared API definition where applicable. + allOf: + - $ref: "#/components/schemas/ProblemDetails" + properties: + type: + type: string + description: A URI reference that identifies the problem type. + format: uri + enum: + - 'https://problems-registry.smartbear.com/invalid-body-property-value' + status: + type: integer + description: >- + The HTTP status code generated by the origin server for this occurrence of + the problem. + format: int32 + enum: + - 400 + + InvalidParameters: + type: object + description: >- + This problem occurs when a client request contains invalid or malformed parameters causing the server to reject the request. + + Your client application issued a request to an API that contains invalid or malformed parameters. + allOf: + - $ref: "#/components/schemas/ProblemDetails" + properties: + type: + type: string + description: A URI reference that identifies the problem type. + format: uri + enum: + - 'https://problems-registry.smartbear.com/invalid-parameters' + status: + type: integer + description: >- + The HTTP status code generated by the origin server for this occurrence of + the problem. + format: int32 + enum: + - 400 + + InvalidRequestHeaderFormat: + type: object + description: >- + This problem occurs when the request contains a malformed request header. + + Your client issued a request that contained a malformed request header. Please review your request parameters and compare against the shared API definition when applicable. + allOf: + - $ref: "#/components/schemas/ProblemDetails" + properties: + type: + type: string + description: A URI reference that identifies the problem type. + format: uri + enum: + - 'https://problems-registry.smartbear.com/invalid-request-header-format' + status: + type: integer + description: >- + The HTTP status code generated by the origin server for this occurrence of + the problem. + format: int32 + enum: + - 400 + + InvalidRequestParameterFormat: + type: object + description: >- + This problem occurs when the request contains a malformed query or path parameter. + + Your client issued a request that contained a malformed query or path parameter. + Please review your request parameters and compare against the shared API definition. + allOf: + - $ref: "#/components/schemas/ProblemDetails" + properties: + type: + type: string + description: A URI reference that identifies the problem type. + format: uri + enum: + - 'https://problems-registry.smartbear.com/invalid-request-parameter-format' + status: + type: integer + description: >- + The HTTP status code generated by the origin server for this occurrence of + the problem. + format: int32 + enum: + - 400 + + InvalidRequestParameterValue: + type: object + description: >- + This problem occurs when the request contains a invalid query or path parameter value. + + Your client issued a request that contained an invalid query or path parameter value. + Please review your request and compare against the shared API definition where applicable. + allOf: + - $ref: "#/components/schemas/ProblemDetails" + properties: + type: + type: string + description: A URI reference that identifies the problem type. + format: uri + enum: + - 'https://problems-registry.smartbear.com/invalid-request-parameter-value' + status: + type: integer + description: >- + The HTTP status code generated by the origin server for this occurrence of + the problem. + format: int32 + enum: + - 400 + + LicenseCancelled: + type: object + description: >- + This problem occurs when the license associated with the client has been cancelled thus rendering the service unavailable. + + The license associated with your client/organization has been cancelled. + Please contact your account manager or representative. + allOf: + - $ref: "#/components/schemas/ProblemDetails" + properties: + type: + type: string + description: A URI reference that identifies the problem type. + format: uri + enum: + - 'https://problems-registry.smartbear.com/license-cancelled' + status: + type: integer + description: >- + The HTTP status code generated by the origin server for this occurrence of + the problem. + format: int32 + enum: + - 503 + + LicenseExpired: + type: object + description: >- + This problem occurs when the license associated with the client has expired thus rendering the service unavailable. + + The license associated with your client/organization has expired. + Please contact your account manager or representative. + allOf: + - $ref: "#/components/schemas/ProblemDetails" + properties: + type: + type: string + description: A URI reference that identifies the problem type. + format: uri + enum: + - 'https://problems-registry.smartbear.com/license-expired' + status: + type: integer + description: >- + The HTTP status code generated by the origin server for this occurrence of + the problem. + format: int32 + enum: + - 503 + + MissingBodyProperty: + type: object + description: >- + This problem occurs when the request sent to the API is missing an expected body property. + + Your client issued a request that omitted an expected body property. + allOf: + - $ref: "#/components/schemas/ProblemDetails" + properties: + type: + type: string + description: A URI reference that identifies the problem type. + format: uri + enum: + - 'https://problems-registry.smartbear.com/missing-body-property' + status: + type: integer + description: >- + The HTTP status code generated by the origin server for this occurrence of + the problem. + format: int32 + enum: + - 400 + + MissingRequestHeader: + type: object + description: >- + This problem occurs when the request sent to the API is missing an expected request header. + + Your client issued a request that omitted an expected request header. + allOf: + - $ref: "#/components/schemas/ProblemDetails" + properties: + type: + type: string + description: A URI reference that identifies the problem type. + format: uri + enum: + - 'https://problems-registry.smartbear.com/missing-request-header' + status: + type: integer + description: >- + The HTTP status code generated by the origin server for this occurrence of + the problem. + format: int32 + enum: + - 400 + + MissingRequestParameter: + type: object + description: >- + This problem occurs when the request sent to the API is missing an query or path parameter. + + Your client issued a request that omitted an expected query or path par. + allOf: + - $ref: "#/components/schemas/ProblemDetails" + properties: + type: + type: string + description: A URI reference that identifies the problem type. + format: uri + enum: + - 'https://problems-registry.smartbear.com/missing-request-parameter' + status: + type: integer + description: >- + The HTTP status code generated by the origin server for this occurrence of + the problem. + format: int32 + enum: + - 400 + + NotFound: + type: object + description: >- + This problem occurs when the requested resource could not be found. + + Your client application tried to access a resource that does not exist (or could not be found). + allOf: + - $ref: "#/components/schemas/ProblemDetails" + properties: + type: + type: string + description: A URI reference that identifies the problem type. + format: uri + enum: + - 'https://problems-registry.smartbear.com/not-found' + status: + type: integer + description: >- + The HTTP status code generated by the origin server for this occurrence of + the problem. + format: int32 + enum: + - 404 + + ServerError: + type: object + description: >- + This problem occurs when the server encounters an unexpected condition that prevents it from fulfilling the request. + + Your client application did everything correct. Unfortunately our API encountered a condition that resulted in this problem. + allOf: + - $ref: "#/components/schemas/ProblemDetails" + properties: + type: + type: string + description: A URI reference that identifies the problem type. + format: uri + enum: + - 'https://problems-registry.smartbear.com/server-error' + status: + type: integer + description: >- + The HTTP status code generated by the origin server for this occurrence of + the problem. + format: int32 + enum: + - 500 + + ServiceUnavailable: + type: object + description: >- + This problem occurs when the service requested is currently unavailable and the server is not ready to handle the request. + + Your client application did everything correct. Unfortunately our API is currently unavailable. + allOf: + - $ref: "#/components/schemas/ProblemDetails" + properties: + type: + type: string + description: A URI reference that identifies the problem type. + format: uri + enum: + - 'https://problems-registry.smartbear.com/service-unavailable' + status: + type: integer + description: >- + The HTTP status code generated by the origin server for this occurrence of + the problem. + format: int32 + enum: + - 503 + + Unauthorized: + type: object + description: >- + This problem occurs when the requested resource could not be returned as the client request lacked valid authentication credentials. + + Your client application issued a requested to a protected resource without supplying the required auth details. + allOf: + - $ref: "#/components/schemas/ProblemDetails" + properties: + type: + type: string + description: A URI reference that identifies the problem type. + format: uri + enum: + - 'https://problems-registry.smartbear.com/unauthorized' + status: + type: integer + description: >- + The HTTP status code generated by the origin server for this occurrence of + the problem. + format: int32 + enum: + - 401 + + ValidationError: + type: object + description: >- + This problem occurs when the request is deemed unprocessable. + + Your client issued a request that failed validation. Certain validation libraries return multi-errors and cannot be easily parsed into discreet types. This problem type, afforded the provider with the ability to surface all validation errors and negate the need for a trial and error workflow on your side. + + Please review your request to determine if you can remain within appropriate business rules. Consider validating your request against available metadata (e.g. schemas) prior to sending to the server. + allOf: + - $ref: "#/components/schemas/ProblemDetails" + properties: + type: + type: string + description: A URI reference that identifies the problem type. + format: uri + enum: + - 'https://problems-registry.smartbear.com/validation-error' + status: + type: integer + description: >- + The HTTP status code generated by the origin server for this occurrence of + the problem. + format: int32 + enum: + - 422 + + responses: + + BadRequest: + description: | + The request was malformed or could not be processed. + + `Bad Request` problem detail responses: + + - [The request is invalid or malformed](https://problems-registry.smartbear.com/bad-request/) + - [Invalid body property format](https://problems-registry.smartbear.com/invalid-body-property-format/) + - [Invalid body property value](https://problems-registry.smartbear.com/invalid-body-property-value/) + - [Invalid Parameters](https://problems-registry.smartbear.com/invalid-parameters/) + - [Invalid request header format](https://problems-registry.smartbear.com/invalid-request-header-format/) + - [Invalid request parameter format](https://problems-registry.smartbear.com/invalid-request-parameter-format/) + - [Invalid request parameter value](https://problems-registry.smartbear.com/invalid-request-parameter-value/) + - [Missing body property](https://problems-registry.smartbear.com/missing-body-property/) + - [Missing request header](https://problems-registry.smartbear.com/missing-request-header/) + - [Missing request parameter](https://problems-registry.smartbear.com/missing-request-parameter/) + content: + application/problem+json: + schema: + oneOf: + - $ref: '#/components/schemas/BadRequest' + - $ref: '#/components/schemas/InvalidBodyPropertyFormat' + - $ref: '#/components/schemas/InvalidBodyPropertyValue' + - $ref: '#/components/schemas/InvalidParameters' + - $ref: '#/components/schemas/InvalidRequestHeaderFormat' + - $ref: '#/components/schemas/InvalidRequestParameterFormat' + - $ref: '#/components/schemas/InvalidRequestParameterValue' + - $ref: '#/components/schemas/MissingBodyProperty' + - $ref: '#/components/schemas/MissingRequestHeader' + - $ref: '#/components/schemas/MissingRequestParameter' + examples: + requestInvalidOrMalformed: + $ref: '#/components/examples/request_invalid_malformed' + missingBodyProperty: + $ref: '#/components/examples/missing-body-property' + missingBodyPropertyWithErrors: + $ref: '#/components/examples/missing-body-property-with-errors' + missingRequestParameter: + $ref: '#/components/examples/missing-request-parameter' + missingRequestParameterWithErrors: + $ref: '#/components/examples/missing-request-parameter-with-errors' + missingRequestHeader: + $ref: '#/components/examples/missing-request-header' + missingRequestHeaderWithErrors: + $ref: '#/components/examples/missing-request-header-with-errors' + invalidBodyPropertyFormat: + $ref: '#/components/examples/invalid-body-property-format' + invalidBodyPropertyFormatWithErrors: + $ref: '#/components/examples/invalid-body-property-format-with-errors' + invalidRequestParameterFormat: + $ref: '#/components/examples/invalid-request-parameter-format' + invalidRequestParameterFormatWithErrors: + $ref: '#/components/examples/invalid-request-parameter-format-with-errors' + invalidRequestHeaderFormat: + $ref: '#/components/examples/invalid-request-header-format' + invalidRequestHeaderFormatWithErrors: + $ref: '#/components/examples/invalid-request-header-format-with-errors' + invalidBodyPropertyValue: + $ref: '#/components/examples/invalid-body-property-value' + invalidBodyPropertyValueWithErrors: + $ref: '#/components/examples/invalid-body-property-value-with-errors' + invalidRequestParameterValue: + $ref: '#/components/examples/invalid-request-parameter-value' + invalidRequestParameterValueWithErrors: + $ref: '#/components/examples/invalid-request-parameter-value-with-errors' + + Unauthorized: + description: Access token is not set or invalid. + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Unauthorized' + examples: + unauthorized: + $ref: '#/components/examples/unauthorized' + + Forbidden: + description: >- + The requestor is not authorized to perform this operation on the + resource. + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Forbidden' + examples: + forbidden: + $ref: '#/components/examples/forbidden' + + NotFound: + description: The requested resource was not found. + content: + application/problem+json: + schema: + $ref: '#/components/schemas/NotFound' + examples: + notFound: + $ref: '#/components/examples/not-found' + + ResourceAlreadyExists: + description: The resource being created is found to already exist on the server. + content: + application/problem+json: + schema: + $ref: '#/components/schemas/AlreadyExists' + examples: + alreadyExists: + $ref: '#/components/examples/resource-already-exists' + + BusinessRuleViolation: + description: >- + The request is deemed invalid as it fails to meet business rule + expectations. + content: + application/problem+json: + schema: + $ref: '#/components/schemas/BusinessRuleViolation' + examples: + businessRuleViolation: + $ref: '#/components/examples/business-rule-violation' + + ValidationError: + description: Your client issued a request that failed validation. + content: + application/problem+json: + schema: + $ref: '#/components/schemas/ValidationError' + examples: + validationError: + $ref: '#/components/examples/validation-error' + + ServerError: + description: The server encountered an unexpected error + content: + application/problem+json: + schema: + $ref: '#/components/schemas/ServerError' + examples: + serverError: + $ref: '#/components/examples/server-error' + + ServiceUnavailable: + description: The service requested is unavailable + content: + application/problem+json: + schema: + $ref: '#/components/schemas/ServiceUnavailable' + examples: + serviceUnavailable: + $ref: '#/components/examples/service-unavailable' + licenseExpired: + $ref: '#/components/examples/license-expired' + licenseCancelled: + $ref: '#/components/examples/license-cancelled' + + examples: + + request_invalid_malformed: + description: >- + Representation of a 400 Bad Request response where the server would not + process the request due to something the server considered to be a client error. + value: + type: 'https://problems-registry.smartbear.com/bad-request' + status: 400 + title: Malformed request syntax + detail: Request body could not be read properly. + code: 400-01 + + missing-body-property: + description: >- + Representation of a 400 Bad Request response where a rquired `body` + property was omitted by the consumer. + value: + type: 'https://problems-registry.smartbear.com/missing-body-property' + status: 400 + title: Missing body property + detail: The request is missing an expected body property. + code: 400-09 + + missing-body-property-with-errors: + description: >- + Representation of a 400 Bad Request response where a rquired `body` + property was omitted by the consumer. + value: + type: 'https://problems-registry.smartbear.com/missing-body-property' + status: 400 + title: Missing body property + detail: The request is missing an expected body property. + code: 400-09 + errors: + - detail: 'The body property {name} is required.' + pointer: /name + + missing-request-parameter: + description: >- + Representation of a 400 Bad Request response where a `query` or `path` + parameter was omitted by the consumer. + value: + type: 'https://problems-registry.smartbear.com/missing-request-parameter' + status: 400 + title: Missing request parameter + detail: The request is missing an expected query or path parameter. + code: 400-03 + + missing-request-parameter-with-errors: + description: >- + Representation of a 400 Bad Request response where a `query` or `path` + parameter was omitted by the consumer. + value: + type: 'https://problems-registry.smartbear.com/missing-request-parameter' + status: 400 + title: Missing request parameter + detail: The request is missing an expected query or path parameter. + code: 400-03 + errors: + - detail: 'The query parameter {name} is required.' + parameter: name + + missing-request-header: + description: >- + Representation of a 400 Bad Request response where a `header` parameter + was omitted by the consumer. + value: + type: 'https://problems-registry.smartbear.com/missing-request-header' + status: 400 + title: Missing request header + detail: The request is missing an expected HTTP request header. + code: 400-02 + + missing-request-header-with-errors: + description: >- + Representation of a 400 Bad Request response where a `header` parameter + was omitted by the consumer. + value: + type: 'https://problems-registry.smartbear.com/missing-request-header' + status: 400 + title: Missing request header + detail: The request is missing an expected HTTP request header. + code: 400-02 + errors: + - detail: 'The header {Accept} is required' + header: Accept + + invalid-body-property-format: + description: >- + Representation of a 400 Bad Request response where a body property does + not leverage the correct format + value: + type: 'https://problems-registry.smartbear.com/invalid-body-property-format' + status: 400 + title: Invalid Body Property Format + detail: The request body contains a malformed property. + code: 400-04 + + invalid-body-property-format-with-errors: + description: >- + Representation of a 400 Bad Request response where a body property does + not leverage the correct format + value: + type: 'https://problems-registry.smartbear.com/invalid-body-property-format' + status: 400 + title: Invalid Body Property Format + detail: The request body contains a malformed property. + code: 400-04 + errors: + - detail: Must be a positive integer + pointer: /quantity + + invalid-request-parameter-format: + description: >- + Representation of a 400 Bad Request response where a query or path + parameter is malformed. + value: + type: >- + https://problems-registry.smartbear.com/invalid-request-parameter-format + status: 400 + title: Invalid Request Parameter Format + detail: The request contains a malformed query parameter. + code: 400-05 + + invalid-request-parameter-format-with-errors: + description: >- + Representation of a 400 Bad Request response where a query or path + parameter is malformed. + value: + type: >- + https://problems-registry.smartbear.com/invalid-request-parameter-format + status: 400 + title: Invalid Request Parameter Format + detail: The request contains a malformed query parameter. + code: 400-05 + errors: + - detail: The expected string values are ASC or DSC + parameter: sort + + invalid-request-header-format: + description: >- + Representation of a 400 Bad Request response where request header + provided was malformed + value: + type: 'https://problems-registry.smartbear.com/invalid-request-header-format' + status: 400 + title: Invalid Request Header Format + detail: The request contains a malformed request header parameter. + code: 400-06 + + invalid-request-header-format-with-errors: + description: >- + Representation of a 400 Bad Request response where a query or path + parameter is malformed. + value: + type: 'https://problems-registry.smartbear.com/invalid-request-header-format' + status: 400 + title: Invalid Request Header Format + detail: The request contains a malformed request header parameter. + code: 400-06 + errors: + - detail: The request header was malformed + header: Accept + + invalid-body-property-value: + description: >- + Representation of a 400 Bad Request response where the request body + contains a invalid property value + value: + type: 'https://problems-registry.smartbear.com/invalid-body-property-value' + status: 400 + title: Invalid Body Property Value + detail: The request body contains an invalid body property value. + code: 400-07 + + invalid-body-property-value-with-errors: + description: >- + Representation of a 400 Bad Request response where the request body + contains a invalid property value + value: + type: 'https://problems-registry.smartbear.com/invalid-body-property-value' + status: 400 + title: Invalid Body Property Value + detail: The request body contains an invalid body property value. + code: 400-07 + errors: + - detail: >- + A value `Never` is an invalid. Please provide `monthly` or + `quarterly` + pointer: '#/marketingCommunication/frequency' + + invalid-request-parameter-value: + description: >- + Representation of a 400 Bad Request response where the request contains + a invalid query or path parameter value. + value: + type: >- + https://problems-registry.smartbear.com/invalid-request-parameter-value + status: 400 + title: Invalid Request Parameter Value + detail: The request body contains an invalid request parameter value. + code: 400-08 + + invalid-request-parameter-value-with-errors: + description: >- + Representation of a 400 Bad Request response where the request contains + a invalid query or path parameter value. + value: + type: >- + https://problems-registry.smartbear.com/invalid-request-parameter-value + status: 400 + title: Invalid Request Parameter Value + detail: The request body contains an invalid request parameter value. + code: 400-08 + errors: + - detail: >- + The value `top-down` is not a valid sort parameter value. The + expected string values are `ASC` or `DSC` + parameter: sort + + unauthorized: + value: + type: 'https://problems-registry.smartbear.com/unauthorized' + title: Unauthorized + detail: >- + Access token not set or invalid. The requested resource could not be + returned + status: 401 + + forbidden: + value: + type: 'https://problems-registry.smartbear.com/forbidden' + title: Forbidden + detail: The resource could not be returned as the requestor is not authorized + status: 403 + + not-found: + value: + type: 'https://problems-registry.smartbear.com/not-found' + title: Not found + detail: The requested resource was not found + status: 404 + + resource-already-exists: + description: >- + Representation of a 409 Conflict response where a consumer is trying + to create a resource that already exists + value: + type: 'https://problems-registry.smartbear.com/already-exists' + status: 409 + title: Already exists + detail: The resource being created already exists. + code: 409-01 + + validation-error: + description: > + This problem occurs when the request is deemed unprocessable. + + + The client issued a request that failed validation. Certain validation + libraries return multi-errors and cannot be easily parsed into discreet + types. This problem type, afforded the provider with the ability to + surface all validation errors and negate the need for a trial and error + workflow on your side. + value: + type: 'https://problems-registry.smartbear.com/validation-error' + status: 422 + title: Validation Error + detail: The request is invalid. + code: 422-02 + errors: + - detail: 'Your request does not contain the required property {name}' + pointer: /name + - detail: The path parameter does not conform to the expected format + header: petId + + business-rule-violation: + description: >- + Representation of a 422 Bad Request response where the request is deemed + invalid as if fails to meet certain business rule expectations. + value: + type: 'https://problems-registry.smartbear.com/business-rule-violation' + status: 422 + title: Business Rule Violation + detail: The request body is invalid and not meeting business rules. + code: 422-01 + errors: + - detail: Maximum quantity allowed in 999 + pointer: /quantity + - detail: We do not offer `next-day` delivery to non-EU addresses + pointer: /shippingAddress/country + - detail: We do not offer `next-day` delivery to non-EU addresses + pointer: /shippingOption + + license-expired: + description: >- + Representation of a 503 Service Unavailable response when the license + associated with the client has expired thus rendering the service + unavailable. + value: + type: 'https://problems-registry.smartbear.com/license-expired' + status: 503 + title: License Expired + detail: >- + The service is unavailable as the license associated with your client + or organization has expired. Please contact your account manager or + representative. + + license-cancelled: + description: >- + Representation of a 503 Service Unavailable response when the license + associated with the client has been cancelled thus rendering the service + unavailable. + value: + type: 'https://problems-registry.smartbear.com/license-cancelled' + status: 503 + title: License Cancelled + detail: >- + The service is unavailable as the license associated with your client + or organization has been cancelled. Please contact your account + manager or representative. + + server-error: + value: + type: 'https://problems-registry.smartbear.com/server-error' + title: Server Error + detail: The server encountered an unexpected error + status: 500 + + service-unavailable: + value: + type: 'https://problems-registry.smartbear.com/service-unavailable' + title: Service Unavailable + detail: The service is currently unavailable + status: 500 From 17073a8591de7297df729977cc6bee54944b6e4e Mon Sep 17 00:00:00 2001 From: stripodi Date: Fri, 5 Sep 2025 18:52:14 +0200 Subject: [PATCH 5/8] feat: removed additional element that forces the generated Python model to set an auxiliary object --- schema.yaml | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/schema.yaml b/schema.yaml index 077aaaf..7026244 100644 --- a/schema.yaml +++ b/schema.yaml @@ -52,13 +52,6 @@ $defs: the error context. maxLength: 50 - Errors: - type: array - description: An array of error details to accompany a problem details response. - maxItems: 1000 - items: - $ref: '#/$defs/ErrorDetail' - ProblemDetails: type: object description: >- @@ -131,7 +124,11 @@ $defs: based on their own potential taxonomy or registry. maxLength: 50 errors: - ref: '#/$defs/Errors' + type: array + description: An array of error details to accompany a problem details response. + maxItems: 1000 + items: + $ref: '#/$defs/ErrorDetail' # Utility objects From e10c8a058a660977708a0775b0ec0c43076c7d8f Mon Sep 17 00:00:00 2001 From: stripodi Date: Fri, 5 Sep 2025 19:12:10 +0200 Subject: [PATCH 6/8] feat: more fixed values for already defined entities --- schema.yaml | 220 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 220 insertions(+) diff --git a/schema.yaml b/schema.yaml index 7026244..1c31582 100644 --- a/schema.yaml +++ b/schema.yaml @@ -153,6 +153,17 @@ $defs: the problem. format: int32 const: 409 + title: + type: string + description: >- + A short, human-readable summary of the problem type. It should not change + from occurrence to occurrence of the problem, except for purposes of + localization. + const: 'Already exists' + detail: + type: string + description: A human-readable explanation specific to this occurrence of the problem. + const: 'The resource being created already exists.' BadRequest: type: object @@ -175,6 +186,17 @@ $defs: the problem. format: int32 const: 400 + title: + type: string + description: >- + A short, human-readable summary of the problem type. It should not change + from occurrence to occurrence of the problem, except for purposes of + localization. + const: 'Bad Request' + detail: + type: string + description: A human-readable explanation specific to this occurrence of the problem. + const: 'The request is invalid or malformed.' BusinessRuleViolation: type: object @@ -197,6 +219,17 @@ $defs: the problem. format: int32 const: 422 + title: + type: string + description: >- + A short, human-readable summary of the problem type. It should not change + from occurrence to occurrence of the problem, except for purposes of + localization. + const: 'Business Rule Violation' + detail: + type: string + description: A human-readable explanation specific to this occurrence of the problem. + const: 'The request body is invalid and not meeting business rules.' Forbidden: type: object @@ -219,6 +252,17 @@ $defs: the problem. format: int32 const: 403 + title: + type: string + description: >- + A short, human-readable summary of the problem type. It should not change + from occurrence to occurrence of the problem, except for purposes of + localization. + const: 'Forbidden' + detail: + type: string + description: A human-readable explanation specific to this occurrence of the problem. + const: 'The resource could not be returned as the requestor is not authorized.' InvalidBodyPropertyFormat: type: object @@ -241,6 +285,17 @@ $defs: the problem. format: int32 const: 400 + title: + type: string + description: >- + A short, human-readable summary of the problem type. It should not change + from occurrence to occurrence of the problem, except for purposes of + localization. + const: 'Invalid Body Property Format' + detail: + type: string + description: A human-readable explanation specific to this occurrence of the problem. + const: 'The request body contains a malformed property.' InvalidBodyPropertyValue: type: object @@ -263,6 +318,17 @@ $defs: the problem. format: int32 const: 400 + title: + type: string + description: >- + A short, human-readable summary of the problem type. It should not change + from occurrence to occurrence of the problem, except for purposes of + localization. + const: 'Invalid Body Property Value' + detail: + type: string + description: A human-readable explanation specific to this occurrence of the problem. + const: 'The request body contains an invalid body property value.' InvalidParameters: type: object @@ -285,6 +351,17 @@ $defs: the problem. format: int32 const: 400 + title: + type: string + description: >- + A short, human-readable summary of the problem type. It should not change + from occurrence to occurrence of the problem, except for purposes of + localization. + const: 'Invalid parameters' + detail: + type: string + description: A human-readable explanation specific to this occurrence of the problem. + const: 'The request contained invalid, or malformed parameters (path or header or query).' InvalidRequestHeaderFormat: type: object @@ -307,6 +384,17 @@ $defs: the problem. format: int32 const: 400 + title: + type: string + description: >- + A short, human-readable summary of the problem type. It should not change + from occurrence to occurrence of the problem, except for purposes of + localization. + const: 'Invalid Request Header Format' + detail: + type: string + description: A human-readable explanation specific to this occurrence of the problem. + const: 'The request contains a malformed request header parameter.' InvalidRequestParameterFormat: type: object @@ -330,6 +418,17 @@ $defs: the problem. format: int32 const: 400 + title: + type: string + description: >- + A short, human-readable summary of the problem type. It should not change + from occurrence to occurrence of the problem, except for purposes of + localization. + const: 'Invalid Request Parameter Format' + detail: + type: string + description: A human-readable explanation specific to this occurrence of the problem. + const: 'The request contains a malformed request query parameter.' InvalidRequestParameterValue: type: object @@ -353,6 +452,17 @@ $defs: the problem. format: int32 const: 400 + title: + type: string + description: >- + A short, human-readable summary of the problem type. It should not change + from occurrence to occurrence of the problem, except for purposes of + localization. + const: 'Invalid Request Parameter Value' + detail: + type: string + description: A human-readable explanation specific to this occurrence of the problem. + const: 'The request body contains an invalid request parameter value.' LicenseCancelled: type: object @@ -376,6 +486,17 @@ $defs: the problem. format: int32 const: 503 + title: + type: string + description: >- + A short, human-readable summary of the problem type. It should not change + from occurrence to occurrence of the problem, except for purposes of + localization. + const: 'License Cancelled' + detail: + type: string + description: A human-readable explanation specific to this occurrence of the problem. + const: 'The service is unavailable as the license associated with your client or organization has been cancelled. Please contact your account manager or representative.' LicenseExpired: type: object @@ -399,6 +520,17 @@ $defs: the problem. format: int32 const: 503 + title: + type: string + description: >- + A short, human-readable summary of the problem type. It should not change + from occurrence to occurrence of the problem, except for purposes of + localization. + const: 'License Expired' + detail: + type: string + description: A human-readable explanation specific to this occurrence of the problem. + const: 'The service is unavailable as the license associated with your client or organization has expired. Please contact your account manager or representative.' MissingBodyProperty: type: object @@ -421,6 +553,17 @@ $defs: the problem. format: int32 const: 400 + title: + type: string + description: >- + A short, human-readable summary of the problem type. It should not change + from occurrence to occurrence of the problem, except for purposes of + localization. + const: 'Missing body property' + detail: + type: string + description: A human-readable explanation specific to this occurrence of the problem. + const: 'The request is missing an expected body property.' MissingRequestHeader: type: object @@ -443,6 +586,17 @@ $defs: the problem. format: int32 const: 400 + title: + type: string + description: >- + A short, human-readable summary of the problem type. It should not change + from occurrence to occurrence of the problem, except for purposes of + localization. + const: 'Missing request header' + detail: + type: string + description: A human-readable explanation specific to this occurrence of the problem. + const: 'The request is missing an expected HTTP request header.' MissingRequestParameter: type: object @@ -465,6 +619,17 @@ $defs: the problem. format: int32 const: 400 + title: + type: string + description: >- + A short, human-readable summary of the problem type. It should not change + from occurrence to occurrence of the problem, except for purposes of + localization. + const: 'Missing request parameter' + detail: + type: string + description: A human-readable explanation specific to this occurrence of the problem. + const: 'The request is missing an expected query or path parameter.' NotFound: type: object @@ -487,6 +652,17 @@ $defs: the problem. format: int32 const: 404 + title: + type: string + description: >- + A short, human-readable summary of the problem type. It should not change + from occurrence to occurrence of the problem, except for purposes of + localization. + const: 'Not Found' + detail: + type: string + description: A human-readable explanation specific to this occurrence of the problem. + const: 'The requested resource was not found.' ServerError: type: object @@ -509,6 +685,17 @@ $defs: the problem. format: int32 const: 500 + title: + type: string + description: >- + A short, human-readable summary of the problem type. It should not change + from occurrence to occurrence of the problem, except for purposes of + localization. + const: 'Server Error' + detail: + type: string + description: A human-readable explanation specific to this occurrence of the problem. + const: 'The server encountered an unexpected error.' ServiceUnavailable: type: object @@ -531,6 +718,17 @@ $defs: the problem. format: int32 const: 503 + title: + type: string + description: >- + A short, human-readable summary of the problem type. It should not change + from occurrence to occurrence of the problem, except for purposes of + localization. + const: 'Service Unavailable' + detail: + type: string + description: A human-readable explanation specific to this occurrence of the problem. + const: 'The service is currently unavailable.' Unauthorized: type: object @@ -553,6 +751,17 @@ $defs: the problem. format: int32 const: 401 + title: + type: string + description: >- + A short, human-readable summary of the problem type. It should not change + from occurrence to occurrence of the problem, except for purposes of + localization. + const: 'Unauthorized' + detail: + type: string + description: A human-readable explanation specific to this occurrence of the problem. + const: 'Access token not set or invalid, and the requested resource could not be returned.' ValidationError: type: object @@ -577,3 +786,14 @@ $defs: the problem. format: int32 const: 422 + title: + type: string + description: >- + A short, human-readable summary of the problem type. It should not change + from occurrence to occurrence of the problem, except for purposes of + localization. + const: 'Validation Error' + detail: + type: string + description: A human-readable explanation specific to this occurrence of the problem. + const: 'The request is not valid.' From 987acbc149231c18f66a0b1b6a453e890b41e766 Mon Sep 17 00:00:00 2001 From: stripodi Date: Fri, 5 Sep 2025 19:24:41 +0200 Subject: [PATCH 7/8] defining default value to instrument code generators --- schema.yaml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/schema.yaml b/schema.yaml index 1c31582..3ed709c 100644 --- a/schema.yaml +++ b/schema.yaml @@ -37,20 +37,24 @@ $defs: A JSON Pointer to a specific request body property that is the source of error. maxLength: 1024 + default: null parameter: type: string description: The name of the query or path parameter that is the source of error. maxLength: 1024 + default: null header: type: string description: The name of the header that is the source of error. maxLength: 1024 + default: null code: type: string description: >- A string containing additional provider specific codes to identify the error context. maxLength: 50 + default: null ProblemDetails: type: object From 835f9afbd4521268426459c83f5acd9dceca5ad0 Mon Sep 17 00:00:00 2001 From: stripodi Date: Fri, 5 Sep 2025 19:28:24 +0200 Subject: [PATCH 8/8] feat: revert useless instrumentation --- schema.yaml | 4 ---- 1 file changed, 4 deletions(-) diff --git a/schema.yaml b/schema.yaml index 3ed709c..1c31582 100644 --- a/schema.yaml +++ b/schema.yaml @@ -37,24 +37,20 @@ $defs: A JSON Pointer to a specific request body property that is the source of error. maxLength: 1024 - default: null parameter: type: string description: The name of the query or path parameter that is the source of error. maxLength: 1024 - default: null header: type: string description: The name of the header that is the source of error. maxLength: 1024 - default: null code: type: string description: >- A string containing additional provider specific codes to identify the error context. maxLength: 50 - default: null ProblemDetails: type: object