From 8a686f68acadc7537778ba36dbb7256f70b9d285 Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Wed, 5 Feb 2025 15:14:29 +0100 Subject: [PATCH 1/5] as decided in TDC call on 2025-01-23 --- src/oas.md | 32 +++++++++++++++----------------- 1 file changed, 15 insertions(+), 17 deletions(-) diff --git a/src/oas.md b/src/oas.md index 8f0257a318..f1d8314409 100644 --- a/src/oas.md +++ b/src/oas.md @@ -549,7 +549,7 @@ servers: - '443' default: '8443' basePath: - # open meaning there is the opportunity to use special base paths as assigned by the provider, default is `v2` + # open meaning there is the opportunity to use special base paths as assigned by the provider, default is "v2" default: v2 ``` @@ -1746,8 +1746,8 @@ requestBody: name: type: string icon: - # The default content type with "contentEncoding" present - # is application/octet-stream, so we need to set the correct + # The default content type with `contentEncoding` present + # is "application/octet-stream", so we need to set the correct # image media type(s) in the Encoding Object. type: string contentEncoding: base64url @@ -1802,18 +1802,18 @@ requestBody: type: object properties: # default content type for a string without `contentEncoding` - # is `text/plain` + # is "text/plain" id: type: string format: uuid # default content type for a schema without `type` - # is `application/octet-stream` + # is "application/octet-stream" profileImage: {} # default content type for arrays is based on the type # in the `items` subschema, which is an object here, - # so the default content type for each item is `application/json` + # so the default content type for each item is "application/json" addresses: type: array items: @@ -1832,13 +1832,13 @@ requestBody: schema: type: object properties: - # No Encoding Object, so use default `text/plain` + # No Encoding Object, so use default "text/plain" id: type: string format: uuid - # Encoding Object overrides the default `application/json` content type - # for each item in the array with `application/xml; charset=utf-8` + # Encoding Object overrides the default "application/json" content type + # for each item in the array with "application/xml; charset=utf-8" addresses: description: addresses in XML format type: array @@ -1871,7 +1871,7 @@ requestBody: multipart/form-data: schema: properties: - # The property name 'file' will be used for all files. + # The property name `file` will be used for all files. file: type: array items: {} @@ -2425,7 +2425,7 @@ paths: # the target link operationId operationId: getUserAddress parameters: - # get the `id` field from the request path parameter named `id` + # use the value of the request path parameter named "id" userid: $request.path.id # the path item of the linked operation /users/{userid}/address: @@ -2453,7 +2453,7 @@ links: address: operationId: getUserAddressByUUID parameters: - # get the `uuid` field from the `uuid` field in the response body + # use the value of the `uuid` field in the response body userUuid: $response.body#/uuid ``` @@ -2469,7 +2469,6 @@ field in an [Operation Object](#operation-object)), references MAY also be made ```yaml links: UserRepositories: - # returns array of '#/components/schemas/repository' operationRef: '#/paths/~12.0~1repositories~1%7Busername%7D/get' parameters: username: $response.body#/username @@ -2480,7 +2479,6 @@ or a URI `operationRef`: ```yaml links: UserRepositories: - # returns array of '#/components/schemas/repository' operationRef: https://na2.gigantic-server.com/#/paths/~12.0~1repositories~1%7Busername%7D/get parameters: username: $response.body#/username @@ -3396,7 +3394,7 @@ components: allOf: - $ref: '#/components/schemas/Pet' - type: object - # all other properties specific to a `Cat` + # all other properties specific to a "Cat" properties: name: type: string @@ -3404,7 +3402,7 @@ components: allOf: - $ref: '#/components/schemas/Pet' - type: object - # all other properties specific to a `Dog` + # all other properties specific to a "Dog" properties: bark: type: string @@ -3412,7 +3410,7 @@ components: allOf: - $ref: '#/components/schemas/Pet' - type: object - # all other properties specific to a `Lizard` + # all other properties specific to a "Lizard" properties: lovesRocks: type: boolean From 17ab8d6cb4e947c02dd61070aedd532568740e0b Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Wed, 5 Feb 2025 15:23:49 +0100 Subject: [PATCH 2/5] Update CONTRIBUTING.md --- CONTRIBUTING.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7cc369eb4e..0a7542e912 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -214,6 +214,11 @@ Plus some suggestions, rather than rules: * property of a "plain" JSON object that is not an OpenAPI-defined Foo Object -> "property" * "attribute" is only used in the XML context and means "XML attribute" +### Field Names and Values in YAML comments + +Field names and entries such as content types should be in backticks, they would be fixed-width fonts if the markdown was rendered (which the comments are not). +Values like "Dog" should be double quoted as they are a value rather than a keyword. + ## Release Process and Scope This section relates to the 3.x versions only. From 5d505db64de684c163e47ade8f8347c9c320d5d9 Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Thu, 6 Feb 2025 18:50:54 +0100 Subject: [PATCH 3/5] Update CONTRIBUTING.md Co-authored-by: Vincent Biret --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0a7542e912..3d217ec28c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -216,7 +216,7 @@ Plus some suggestions, rather than rules: ### Field Names and Values in YAML comments -Field names and entries such as content types should be in backticks, they would be fixed-width fonts if the markdown was rendered (which the comments are not). +Field names and keys should be in backticks for consistency. Values like "Dog" should be double quoted as they are a value rather than a keyword. ## Release Process and Scope From c2c9aaf9e110485ac3e1942eb75bdb063e2bb67f Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Thu, 6 Feb 2025 21:57:43 +0100 Subject: [PATCH 4/5] Update CONTRIBUTING.md --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3d217ec28c..2c2db67e7b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -216,8 +216,8 @@ Plus some suggestions, rather than rules: ### Field Names and Values in YAML comments -Field names and keys should be in backticks for consistency. -Values like "Dog" should be double quoted as they are a value rather than a keyword. +Field names and keys should be in backticks. +Values like "Dog" should be double quoted. ## Release Process and Scope From 97e7b3d6fead90242a599e09d8ffcf36acead4f7 Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Fri, 7 Feb 2025 11:21:58 +0100 Subject: [PATCH 5/5] Update CONTRIBUTING.md --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2c2db67e7b..b48f0096bc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -216,7 +216,7 @@ Plus some suggestions, rather than rules: ### Field Names and Values in YAML comments -Field names and keys should be in backticks. +Field names and keywords should be in backticks. Values like "Dog" should be double quoted. ## Release Process and Scope