From 5fb1f7040dcf29bfd74073cf175f2c3758192070 Mon Sep 17 00:00:00 2001
From: Rafal Artych <121048129+rartych@users.noreply.github.com>
Date: Thu, 28 Sep 2023 08:21:51 +0200
Subject: [PATCH 01/15] Add files via upload

---
 documentation/Linting-rules.md | 63 ++++++++++++++++++++++++++++++++++
 1 file changed, 63 insertions(+)
 create mode 100644 documentation/Linting-rules.md

diff --git a/documentation/Linting-rules.md b/documentation/Linting-rules.md
new file mode 100644
index 00000000..cd068fca
--- /dev/null
+++ b/documentation/Linting-rules.md
@@ -0,0 +1,63 @@
+# CAMARA API Linting Rules Documentation
+
+## Introduction
+
+
+## 1. Spectral core ruleset
+
+Spectral has a built-in OpenAPI Specification ruleset that can be used to validate OpenAPI files.
+
+With `extends: "spectral:oas"` ("oas" being shorthand for OpenAPI Specification) in the ruleset file to rules for OpenAPI v2 and v3.x, depending on the appropriate OpenAPI version being used (this is automatically detected through formats) are added to the final ruleset.
+
+The full list of the rules in this ruleset are described in [OpenAPI Rules](https://docs.stoplight.io/docs/spectral/4dec24461f3af-open-api-rules).
+
+
+`extends: [[spectral:oas, off]]`  - this avoids running any rules from the extended ruleset as they are disabled. Each rule can [enabled individually](https://docs.stoplight.io/docs/spectral/0a73453054745-recommended-or-all#enabling-rules).
+
+### OpenAPI v2 & v3
+Rules applying to both OpenAPI v2.0, v3.0, and most likely v3.1.
+
+
+|Name| Desc| Recommended|CAMARA use|
+|---|---|---|--|
+|contact-properties| contact object is full of the most useful properties: `name`, `url`, `and email`|No|No |
+|duplicated-entry-in-enum| Each value of an `enum` must be different from one another |Yes  | Yes |
+|info-contact |Info object should contain `contact` object |Yes  | Yes| 
+
+
+
+
+
+
+
+
+## 2. Language
+
+### Spell checking
+
+CAMARA API specification files include inline documentation.
+
+The description attributes should be checked for typos.
+
+_Spectral rule_: [camara-language-spelling]()
+
+
+### Reduce telco-specific terminology in API definitions
+
+API Design Guidelines: [2.5 Reduce telco-specific terminology in API definitions](https://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md#25-reduce-telco-specific-terminology-in-api-definitions)
+
+Consider and account for how the API can be fulfilled on a range of network types.
+Avoid terms/types specific to a given telco domain -  terms should be inclusive beyond mobile network. 
+
+See also [CAMARA Glossary](https://github.com/camaraproject/Commonalities/blob/main/documentation/Glossary.md)
+
+
+| ❌ &nbsp; Not recommended | 👍  &nbsp; Recommended |
+|----------------------------|-------------------------|
+| `UE`                 | `device`           |
+| `MSISDN`                 | `phone number`           |
+| `mobile network`      | `network`         |
+
+
+_Spectral rule_: [camara-language-avoid-telco]()
+

From c141ae254651d122e892d67a24ec4fce366e655e Mon Sep 17 00:00:00 2001
From: Rafal Artych <121048129+rartych@users.noreply.github.com>
Date: Thu, 28 Sep 2023 08:25:43 +0200
Subject: [PATCH 02/15] Create README.md

---
 artifacts/Github_actions/.workflows/README.md | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 artifacts/Github_actions/.workflows/README.md

diff --git a/artifacts/Github_actions/.workflows/README.md b/artifacts/Github_actions/.workflows/README.md
new file mode 100644
index 00000000..b172552b
--- /dev/null
+++ b/artifacts/Github_actions/.workflows/README.md
@@ -0,0 +1 @@
+Configuration files for Github Actions

From f38bd84245f5cc7b019c2119cda51163db04bb3f Mon Sep 17 00:00:00 2001
From: Rafal Artych <121048129+rartych@users.noreply.github.com>
Date: Tue, 3 Oct 2023 22:51:41 +0200
Subject: [PATCH 03/15] Update Linting-rules.md

---
 documentation/Linting-rules.md | 80 +++++++++++++++++++++++++++++-----
 1 file changed, 69 insertions(+), 11 deletions(-)

diff --git a/documentation/Linting-rules.md b/documentation/Linting-rules.md
index cd068fca..ba15be7f 100644
--- a/documentation/Linting-rules.md
+++ b/documentation/Linting-rules.md
@@ -18,21 +18,51 @@ The full list of the rules in this ruleset are described in [OpenAPI Rules](http
 Rules applying to both OpenAPI v2.0, v3.0, and most likely v3.1.
 
 
-|Name| Desc| Recommended|CAMARA use|
-|---|---|---|--|
-|contact-properties| contact object is full of the most useful properties: `name`, `url`, `and email`|No|No |
-|duplicated-entry-in-enum| Each value of an `enum` must be different from one another |Yes  | Yes |
-|info-contact |Info object should contain `contact` object |Yes  | Yes| 
-
-
-
-
-
+|Name| Desc| Recom mended|CAMARA use|Spectral  level | CAMARA Level 
+|---|---|---|--|---|--|
+|contact-properties| contact object is full of the most useful properties: `name`, `url`, `and email`|No|No |  |  |
+|duplicated-entry-in-enum| Each value of an `enum` must be different from one another |Yes  | Yes |  |  |
+|info-contact |Info object should contain `contact` object |Yes  | Yes|   |  |
+|info-description |Info object should contain `description` object |Yes  | Yes|  |  | 
+|info-license |Info object should contain `license` object |Yes  | Yes|   |  |
+|license-url | link to the full text of licence | Yes | Yes|  |  |
+|no-$ref-siblings| Before OpenAPI v3.1, keywords next to $ref were ignored | Yes | Yes|   |  |
+|no-eval-in-markdown | injecting `eval()` JavaScript statements could lead to an XSS attack |Yes |Yes |  |  |
+|no-script-tags-in-markdown |  injecting `<script>` tags could lead to execution of an arbitrary | Yes |Yes |  |  |
+|openapi-tags | OpenAPI object should have non-empty `tags` array |??? | ??? (No) |   |  |
+| openapi-tags-alphabetical | OpenAPI object should have alphabetical `tags` | No |No |  |  |
+| openapi-tags-uniqueness | OpenAPI object must not have duplicated tag names | No | No |  |  |
+|operation-description | ???| Yes| ???|  |  |
+|operation-operationId | a reference for the operation = the value `lower-hyphen-case` |Yes| Yes|  |  |
+| operation-operationId-unique | Every operation must have a unique operationId | Yes| Yes|  |  |
+| operation-operationId-valid-in-url | avoid non-URL-safe characters| Yes| Yes|  |  |
+|operation-parameters | Operation parameters are unique and non-repeating | Yes| Yes|  |  |
+| operation-singular-tag | Use just one tag for an operation | No| ???|  |  |
+|operation-success-response | Operation must have at least one `2xx` or `3xx` response | Yes| Yes|  |  |
+|operation-tags | Operation should have non-empty `tags` array| Yes| Yes|  |  |
+| operation-tag-defined | Operation tags should be defined in global tags| Yes| Yes|  |  |
+| path-declarations-must-exist | Path parameter declarations cannot be empty, ex.`/given/{}` is invalid.  | Yes| Yes|  |  |
+| path-keys-no-trailing-slash | Keep trailing slashes off of paths,  | Yes| Yes|  |  |
+| path-not-include-query | Don't put query string items in the path, they belong in parameters with `in: query`| Yes| Yes|  |  |
+|path-params | Path parameters are correct and valid | Yes| Yes|  |  |
+|tag-description | global tags have description | No | ???|  |  |
+| typed-enum | Enum values should respect the type specifier. | Yes| Yes|  |  |
+||||| |
+|oas3-api-servers | OpenAPI servers must be present and non-empty array | Yes| Yes|  |  |
+|oas3-examples-value-or-externalValue | Examples for requestBody or response examples can have an `externalValue` or a `value`, but they cannot have both| Yes| Yes|  |  |
+|**oas3-operation-security-defined** | Operation `security` values must match a scheme defined in the `components.securitySchemes` object. | Yes| Yes|  |  |
+|oas3-parameter-description | Parameter objects should have a description| No| Yes?|  |  |
+| oas3-schema | Validate structure of OpenAPI v3 specification | Yes| Yes|  |  |
+|oas3-server-not-example.com | Server URL should not point to *example.com*| No| Yes?|  |  |
+|oas3-server-trailing-slash | Server URL should not have a trailing slash | Yes| Yes|  |  |
+|oas3-unused-component | Potential unused reusable components entry has been detected  | Yes| Yes|  |  |
+|oas3-valid-media-example | Examples must be valid against their defined schema. This rule is applied to *Media Type objects*  | Yes| Yes|  |  |
+|oas3-valid-schema-example | Examples must be valid against their defined schema. This rule is applied to *Schema objects* | Yes| Yes|  |  |
+|oas3-server-variables | This rule ensures that server variables defined in OpenAPI Specification 3 (OAS3) and 3.1 are valid, not unused | Yes| Yes|  |  |
 
 
 
 ## 2. Language
-
 ### Spell checking
 
 CAMARA API specification files include inline documentation.
@@ -61,3 +91,31 @@ See also [CAMARA Glossary](https://github.com/camaraproject/Commonalities/blob/m
 
 _Spectral rule_: [camara-language-avoid-telco]()
 
+
+## 3. API Definition
+### Path parameters
+
+API Design Guidelines: 
+[3.4 Path Parameters Use](https://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md#34-path-parameters-use)
+
+
+Point 2 The attribute must be identifying itself, it is not enough with "{id}"
+
+`/users/{id}`
+
+| ❌ &nbsp; Not recommended | 👍  &nbsp; Recommended |
+|----------------------------|-------------------------|
+| `/users/{id}/documents/{documentId}`                 | `/users/{userId}/documents/{documentId}`           |
+
+_Spectral rule_: [camara-path-param-id]()
+
+Point 3 The identifier should have a similar morphology on all endpoints. For example, “*xxxxId*”, where *xxx* is the name of the entity it reference
+
+| 👍  &nbsp; Recommended |
+|-------------------------|
+| `/users/{userId}` |
+|`/accounts/{accountId}` |
+|`/vehicles/{vehicleId}` |
+|`/users/{userId}/vehicles/{vehicleId}` |
+
+_Spectral rule_: [camara-path-param-id-morphology]()

From ffafb962ac21e889895e1fc57b02ccc0ea16c773 Mon Sep 17 00:00:00 2001
From: Rafal Artych <121048129+rartych@users.noreply.github.com>
Date: Fri, 6 Oct 2023 10:41:14 +0200
Subject: [PATCH 04/15] Update Linting-rules.md

Problem with operation-operationId
---
 documentation/Linting-rules.md | 17 +++++++++++++++--
 1 file changed, 15 insertions(+), 2 deletions(-)

diff --git a/documentation/Linting-rules.md b/documentation/Linting-rules.md
index ba15be7f..0a632c94 100644
--- a/documentation/Linting-rules.md
+++ b/documentation/Linting-rules.md
@@ -14,11 +14,16 @@ The full list of the rules in this ruleset are described in [OpenAPI Rules](http
 
 `extends: [[spectral:oas, off]]`  - this avoids running any rules from the extended ruleset as they are disabled. Each rule can [enabled individually](https://docs.stoplight.io/docs/spectral/0a73453054745-recommended-or-all#enabling-rules).
 
+### Rule severity
+
+The `severity` keyword is optional in rule definition and can be `error`, `warn`, `info`, `hint`, or `off`.
+The default value is `warn`.
+
 ### OpenAPI v2 & v3
 Rules applying to both OpenAPI v2.0, v3.0, and most likely v3.1.
 
 
-|Name| Desc| Recom mended|CAMARA use|Spectral  level | CAMARA Level 
+|Name| Desc| Recom mended|CAMARA use|Spectral severity | CAMARA severity
 |---|---|---|--|---|--|
 |contact-properties| contact object is full of the most useful properties: `name`, `url`, `and email`|No|No |  |  |
 |duplicated-entry-in-enum| Each value of an `enum` must be different from one another |Yes  | Yes |  |  |
@@ -33,7 +38,7 @@ Rules applying to both OpenAPI v2.0, v3.0, and most likely v3.1.
 | openapi-tags-alphabetical | OpenAPI object should have alphabetical `tags` | No |No |  |  |
 | openapi-tags-uniqueness | OpenAPI object must not have duplicated tag names | No | No |  |  |
 |operation-description | ???| Yes| ???|  |  |
-|operation-operationId | a reference for the operation = the value `lower-hyphen-case` |Yes| Yes|  |  |
+|operation-operationId | a reference for the operation - the value `lower-hyphen-case` **CAMARA: OperationIds are defined in `lowerCamelCase` For example: `helloWorld`** |Yes| Yes|  |  |
 | operation-operationId-unique | Every operation must have a unique operationId | Yes| Yes|  |  |
 | operation-operationId-valid-in-url | avoid non-URL-safe characters| Yes| Yes|  |  |
 |operation-parameters | Operation parameters are unique and non-repeating | Yes| Yes|  |  |
@@ -71,6 +76,7 @@ The description attributes should be checked for typos.
 
 _Spectral rule_: [camara-language-spelling]()
 
+*Severity*: `warn`
 
 ### Reduce telco-specific terminology in API definitions
 
@@ -91,6 +97,7 @@ See also [CAMARA Glossary](https://github.com/camaraproject/Commonalities/blob/m
 
 _Spectral rule_: [camara-language-avoid-telco]()
 
+*Severity*: `hint`
 
 ## 3. API Definition
 ### Path parameters
@@ -109,6 +116,8 @@ Point 2 The attribute must be identifying itself, it is not enough with "{id}"
 
 _Spectral rule_: [camara-path-param-id]()
 
+*Severity*: `warn`
+
 Point 3 The identifier should have a similar morphology on all endpoints. For example, “*xxxxId*”, where *xxx* is the name of the entity it reference
 
 | 👍  &nbsp; Recommended |
@@ -119,3 +128,7 @@ Point 3 The identifier should have a similar morphology on all endpoints. For ex
 |`/users/{userId}/vehicles/{vehicleId}` |
 
 _Spectral rule_: [camara-path-param-id-morphology]()
+
+*Severity*: `warn`
+
+

From f93bb29ab156d302c7155a724f61ab12ddf75303 Mon Sep 17 00:00:00 2001
From: Rafal Artych <121048129+rartych@users.noreply.github.com>
Date: Mon, 9 Oct 2023 17:15:46 +0200
Subject: [PATCH 05/15] Update Linting-rules.md

---
 documentation/Linting-rules.md | 135 ++++++++++++++++++++++++++++++---
 1 file changed, 124 insertions(+), 11 deletions(-)

diff --git a/documentation/Linting-rules.md b/documentation/Linting-rules.md
index 0a632c94..897aeac7 100644
--- a/documentation/Linting-rules.md
+++ b/documentation/Linting-rules.md
@@ -12,7 +12,7 @@ With `extends: "spectral:oas"` ("oas" being shorthand for OpenAPI Specification)
 The full list of the rules in this ruleset are described in [OpenAPI Rules](https://docs.stoplight.io/docs/spectral/4dec24461f3af-open-api-rules).
 
 
-`extends: [[spectral:oas, off]]`  - this avoids running any rules from the extended ruleset as they are disabled. Each rule can [enabled individually](https://docs.stoplight.io/docs/spectral/0a73453054745-recommended-or-all#enabling-rules).
+`extends: [[spectral:oas, off]]`  - this avoids running any rules from the extended ruleset as they are disabled. Each rule can be[enabled individually](https://docs.stoplight.io/docs/spectral/0a73453054745-recommended-or-all#enabling-rules).
 
 ### Rule severity
 
@@ -35,29 +35,29 @@ Rules applying to both OpenAPI v2.0, v3.0, and most likely v3.1.
 |no-eval-in-markdown | injecting `eval()` JavaScript statements could lead to an XSS attack |Yes |Yes |  |  |
 |no-script-tags-in-markdown |  injecting `<script>` tags could lead to execution of an arbitrary | Yes |Yes |  |  |
 |openapi-tags | OpenAPI object should have non-empty `tags` array |??? | ??? (No) |   |  |
-| openapi-tags-alphabetical | OpenAPI object should have alphabetical `tags` | No |No |  |  |
-| openapi-tags-uniqueness | OpenAPI object must not have duplicated tag names | No | No |  |  |
+|openapi-tags-alphabetical | OpenAPI object should have alphabetical `tags` | No |No |  |  |
+|openapi-tags-uniqueness | OpenAPI object must not have duplicated tag names | No | No |  |  |
 |operation-description | ???| Yes| ???|  |  |
 |operation-operationId | a reference for the operation - the value `lower-hyphen-case` **CAMARA: OperationIds are defined in `lowerCamelCase` For example: `helloWorld`** |Yes| Yes|  |  |
 | operation-operationId-unique | Every operation must have a unique operationId | Yes| Yes|  |  |
-| operation-operationId-valid-in-url | avoid non-URL-safe characters| Yes| Yes|  |  |
+|operation-operationId-valid-in-url | avoid non-URL-safe characters| Yes| Yes|  |  |
 |operation-parameters | Operation parameters are unique and non-repeating | Yes| Yes|  |  |
-| operation-singular-tag | Use just one tag for an operation | No| ???|  |  |
+|operation-singular-tag | Use just one tag for an operation | No| ???|  |  |
 |operation-success-response | Operation must have at least one `2xx` or `3xx` response | Yes| Yes|  |  |
 |operation-tags | Operation should have non-empty `tags` array| Yes| Yes|  |  |
-| operation-tag-defined | Operation tags should be defined in global tags| Yes| Yes|  |  |
-| path-declarations-must-exist | Path parameter declarations cannot be empty, ex.`/given/{}` is invalid.  | Yes| Yes|  |  |
-| path-keys-no-trailing-slash | Keep trailing slashes off of paths,  | Yes| Yes|  |  |
-| path-not-include-query | Don't put query string items in the path, they belong in parameters with `in: query`| Yes| Yes|  |  |
+|operation-tag-defined | Operation tags should be defined in global tags| Yes| Yes|  |  |
+|path-declarations-must-exist | Path parameter declarations cannot be empty, ex.`/given/{}` is invalid.  | Yes| Yes|  |  |
+|path-keys-no-trailing-slash | Keep trailing slashes off of paths,  | Yes| Yes|  |  |
+|path-not-include-query | Don't put query string items in the path, they belong in parameters with `in: query`| Yes| Yes|  |  |
 |path-params | Path parameters are correct and valid | Yes| Yes|  |  |
 |tag-description | global tags have description | No | ???|  |  |
-| typed-enum | Enum values should respect the type specifier. | Yes| Yes|  |  |
+|typed-enum | Enum values should respect the type specifier. | Yes| Yes|  |  |
 ||||| |
 |oas3-api-servers | OpenAPI servers must be present and non-empty array | Yes| Yes|  |  |
 |oas3-examples-value-or-externalValue | Examples for requestBody or response examples can have an `externalValue` or a `value`, but they cannot have both| Yes| Yes|  |  |
 |**oas3-operation-security-defined** | Operation `security` values must match a scheme defined in the `components.securitySchemes` object. | Yes| Yes|  |  |
 |oas3-parameter-description | Parameter objects should have a description| No| Yes?|  |  |
-| oas3-schema | Validate structure of OpenAPI v3 specification | Yes| Yes|  |  |
+|oas3-schema | Validate structure of OpenAPI v3 specification | Yes| Yes|  |  |
 |oas3-server-not-example.com | Server URL should not point to *example.com*| No| Yes?|  |  |
 |oas3-server-trailing-slash | Server URL should not have a trailing slash | Yes| Yes|  |  |
 |oas3-unused-component | Potential unused reusable components entry has been detected  | Yes| Yes|  |  |
@@ -131,4 +131,117 @@ _Spectral rule_: [camara-path-param-id-morphology]()
 
 *Severity*: `warn`
 
+### Reserved words
 
+API Design Guidelines: 
+[11. Definition in OpenAPI](https://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md#11-definition-in-openapi)
+
+To avoid issues with implementation using Open API generators:
+
+    Reserved words must not be used in the following parts of an API specification:
+      - Path and operation names
+      - Path or query parameter names
+      - Request and response body property names
+      - Security schemes
+      - Component names
+      - OperationIds
+
+
+A reserved word is one whose usage is reserved by any of the following Open API generators:
+- [Python Flask](https://openapi-generator.tech/docs/generators/python-flask/#reserved-words)
+- [OpenAPI Generator (Java)](https://openapi-generator.tech/docs/generators/java/#reserved-words)
+- [OpenAPI Generator (Go)](https://openapi-generator.tech/docs/generators/go/#reserved-words)
+- [OpenAPI Generator (Kotlin)](https://openapi-generator.tech/docs/generators/kotlin/#reserved-words)
+- [OpenAPI Generator (Swift5)](https://openapi-generator.tech/docs/generators/swift5#reserved-words)
+
+_Spectral rule_: [camara-reserved-words]()
+
+*Severity*: `warn`
+
+### Usage of discriminator
+
+API Design Guidelines: 
+[11.5.1 Usage of discriminator](https://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md#1151-usage-of-discriminator)
+
+When request bodies or response payloads may be one of a number of different schemas (containing `oneOf` or `anyOf` section), a `discriminator` object can be used to aid in serialization, deserialization, and validation. 
+
+_Spectral rule_: [camara-discriminator-use]()
+
+*Severity*: `warn`
+
+### Casing convention
+
+Spectral core functions: [casing](https://docs.stoplight.io/docs/spectral/cb95cf0d26b83-core-functions#casing) can be used to verify text match a certain case. Available types are:
+|name	|sample|
+|---|----|
+|flat|	verylongname|
+|camel|	veryLongName|
+|pascal|	VeryLongName|
+|kebab|	very-long-name|
+|cobol|	VERY-LONG-NAME|
+|snake|	very_long_name|
+|macro|	VERY_LONG_NAME|
+
+
+#### Enum
+
+API Design Guidelines: **No clear requirement**
+
+❓ This rule verifies that `enum` fields contain values that follow a specific case convention: `macro`.
+
+_Spectral rule_: [camara-enum-casing-convention]()
+
+*Severity*: `info`
+
+
+
+#### Operation Id
+
+API Design Guidelines: 
+[4.1 URL Definition](https://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md#41-url-definition)
+>   OperationIds are defined in lowerCamelCase: For example: `helloWorld`
+
+Operation ids should follow a specific case convention: `camel` case.
+
+_Spectral rule_: [camara-operationid-casing-convention]()
+
+**Contradiction with Spectral rule `operation-operationId `** 
+>  a reference for the operation - the value `lower-hyphen-case`
+
+*Severity*: `error`
+
+#### Path parameters / Query parameters
+
+API Design Guidelines: [4.1 URL Definition](https://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md#41-url-definition)
+> URI with lowercase and hyphens. URIs must be "human readable" to facilitate identification of the offered resources. Lowercase words and hyphenation (kebab-case) help achieve this best practice. For example: `/customer-segments`
+
+Path parameter should follow a specific case convention, with the default being `kebab` case.
+
+_Spectral rule_: [camara-parameter-casing-convention]()
+
+*Severity*: `error`
+
+#### Property names
+
+API Design Guidelines: [4.1 URL Definition](https://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md#41-url-definition)
+
+> Objects are defined in CamelCase inside properties field. For example: Greetings, ExampleObject.
+
+❓ **Should it be lowerCamelCase in DG?**
+
+Property names should follow a specific case convention, with the default being `camel` case.
+
+_Spectral rule_: [camara-property-casing-convention]()
+
+*Severity*: `error`
+
+#### Schema names
+
+API Design Guidelines: **No clear requirement**
+
+Schema names (the keys in `components -> schemas`) should follow the "upper camel case" convention - `pascal`
+
+
+_Spectral rule_: [camara-schema-casing-convention]()
+
+*Severity*: `warn`

From a41b82d198afffd1053def40e7ec1be847b2be71 Mon Sep 17 00:00:00 2001
From: Rafal Artych <121048129+rartych@users.noreply.github.com>
Date: Thu, 12 Oct 2023 12:07:58 +0200
Subject: [PATCH 06/15] Update Linting-rules.md

---
 documentation/Linting-rules.md | 78 +++++++++++++++++-----------------
 1 file changed, 39 insertions(+), 39 deletions(-)

diff --git a/documentation/Linting-rules.md b/documentation/Linting-rules.md
index 897aeac7..31572a9e 100644
--- a/documentation/Linting-rules.md
+++ b/documentation/Linting-rules.md
@@ -12,7 +12,7 @@ With `extends: "spectral:oas"` ("oas" being shorthand for OpenAPI Specification)
 The full list of the rules in this ruleset are described in [OpenAPI Rules](https://docs.stoplight.io/docs/spectral/4dec24461f3af-open-api-rules).
 
 
-`extends: [[spectral:oas, off]]`  - this avoids running any rules from the extended ruleset as they are disabled. Each rule can be[enabled individually](https://docs.stoplight.io/docs/spectral/0a73453054745-recommended-or-all#enabling-rules).
+`extends: [[spectral:oas, off]]`  - this avoids running any rules from the extended ruleset as they are disabled. Each rule then can be [enabled individually](https://docs.stoplight.io/docs/spectral/0a73453054745-recommended-or-all#enabling-rules).
 
 ### Rule severity
 
@@ -25,45 +25,45 @@ Rules applying to both OpenAPI v2.0, v3.0, and most likely v3.1.
 
 |Name| Desc| Recom mended|CAMARA use|Spectral severity | CAMARA severity
 |---|---|---|--|---|--|
-|contact-properties| contact object is full of the most useful properties: `name`, `url`, `and email`|No|No |  |  |
-|duplicated-entry-in-enum| Each value of an `enum` must be different from one another |Yes  | Yes |  |  |
-|info-contact |Info object should contain `contact` object |Yes  | Yes|   |  |
-|info-description |Info object should contain `description` object |Yes  | Yes|  |  | 
-|info-license |Info object should contain `license` object |Yes  | Yes|   |  |
-|license-url | link to the full text of licence | Yes | Yes|  |  |
-|no-$ref-siblings| Before OpenAPI v3.1, keywords next to $ref were ignored | Yes | Yes|   |  |
-|no-eval-in-markdown | injecting `eval()` JavaScript statements could lead to an XSS attack |Yes |Yes |  |  |
-|no-script-tags-in-markdown |  injecting `<script>` tags could lead to execution of an arbitrary | Yes |Yes |  |  |
-|openapi-tags | OpenAPI object should have non-empty `tags` array |??? | ??? (No) |   |  |
-|openapi-tags-alphabetical | OpenAPI object should have alphabetical `tags` | No |No |  |  |
-|openapi-tags-uniqueness | OpenAPI object must not have duplicated tag names | No | No |  |  |
-|operation-description | ???| Yes| ???|  |  |
-|operation-operationId | a reference for the operation - the value `lower-hyphen-case` **CAMARA: OperationIds are defined in `lowerCamelCase` For example: `helloWorld`** |Yes| Yes|  |  |
-| operation-operationId-unique | Every operation must have a unique operationId | Yes| Yes|  |  |
-|operation-operationId-valid-in-url | avoid non-URL-safe characters| Yes| Yes|  |  |
-|operation-parameters | Operation parameters are unique and non-repeating | Yes| Yes|  |  |
-|operation-singular-tag | Use just one tag for an operation | No| ???|  |  |
-|operation-success-response | Operation must have at least one `2xx` or `3xx` response | Yes| Yes|  |  |
-|operation-tags | Operation should have non-empty `tags` array| Yes| Yes|  |  |
-|operation-tag-defined | Operation tags should be defined in global tags| Yes| Yes|  |  |
-|path-declarations-must-exist | Path parameter declarations cannot be empty, ex.`/given/{}` is invalid.  | Yes| Yes|  |  |
-|path-keys-no-trailing-slash | Keep trailing slashes off of paths,  | Yes| Yes|  |  |
-|path-not-include-query | Don't put query string items in the path, they belong in parameters with `in: query`| Yes| Yes|  |  |
-|path-params | Path parameters are correct and valid | Yes| Yes|  |  |
-|tag-description | global tags have description | No | ???|  |  |
-|typed-enum | Enum values should respect the type specifier. | Yes| Yes|  |  |
+|contact-properties| contact object is full of the most useful properties: `name`, `url`, `and email`|No|No | Warning |  |
+|duplicated-entry-in-enum| Each value of an `enum` must be different from one another |Yes  | Yes | Warning |  |
+|info-contact |Info object should contain `contact` object |Yes  | Yes| Warning  |  |
+|info-description |Info object should contain `description` object |Yes  | Yes| Warning |  | 
+|info-license |Info object should contain `license` object |Yes  | Yes|  Warning |  |
+|license-url | link to the full text of licence | Yes | Yes| Warning  |  |
+|no-$ref-siblings| Before OpenAPI v3.1, keywords next to $ref were ignored | Yes | Yes| Error |  |
+|no-eval-in-markdown | injecting `eval()` JavaScript statements could lead to an XSS attack |Yes |Yes |Warning  |  |
+|no-script-tags-in-markdown |  injecting `<script>` tags could lead to execution of an arbitrary | Yes |Yes | Warning |  |
+|openapi-tags | OpenAPI object should have non-empty `tags` array |No | Yes | Warning |  |
+|openapi-tags-alphabetical | OpenAPI object should have alphabetical `tags` | No |No | Warning |  |
+|openapi-tags-uniqueness | OpenAPI object must not have duplicated tag names | No | No | Error |  |
+|operation-description | Operation `description` must be present and non-empty string | Yes| Yes| Warning  |  |
+|operation-operationId | Operation must have `operationId` |Yes| Yes| Warning |  |
+|operation-operationId-unique | Every operation must have a unique operationId | Yes| Yes| Error |  |
+|operation-operationId-valid-in-url | avoid non-URL-safe characters| Yes| Yes| Warning |  |
+|operation-parameters | Operation parameters are unique and non-repeating | Yes| Yes| Warning  |  |
+|operation-singular-tag | Use just one tag for an operation | No| Yes| Warning |  |
+|operation-success-response | Operation must have at least one `2xx` or `3xx` response | Yes| Yes| Warning |  |
+|operation-tags | Operation should have non-empty `tags` array| Yes| Yes| Warning |  |
+|operation-tag-defined | Operation tags should be defined in global tags| Yes| Yes| Warning |  |
+|path-declarations-must-exist | Path parameter declarations cannot be empty, ex.`/given/{}` is invalid.  | Yes| Yes| Warning |  |
+|path-keys-no-trailing-slash | Keep trailing slashes off of paths,  | Yes| Yes| Warning |  |
+|path-not-include-query | Don't put query string items in the path, they belong in parameters with `in: query`| Yes| Yes| Warning |  |
+|path-params | Path parameters are correct and valid | Yes| Yes| Error |  |
+|tag-description | global tags have description | No | ???| Warning |  |
+|typed-enum | Enum values should respect the type specifier. | Yes| Yes| Warning |  |
 ||||| |
-|oas3-api-servers | OpenAPI servers must be present and non-empty array | Yes| Yes|  |  |
-|oas3-examples-value-or-externalValue | Examples for requestBody or response examples can have an `externalValue` or a `value`, but they cannot have both| Yes| Yes|  |  |
-|**oas3-operation-security-defined** | Operation `security` values must match a scheme defined in the `components.securitySchemes` object. | Yes| Yes|  |  |
-|oas3-parameter-description | Parameter objects should have a description| No| Yes?|  |  |
-|oas3-schema | Validate structure of OpenAPI v3 specification | Yes| Yes|  |  |
-|oas3-server-not-example.com | Server URL should not point to *example.com*| No| Yes?|  |  |
-|oas3-server-trailing-slash | Server URL should not have a trailing slash | Yes| Yes|  |  |
-|oas3-unused-component | Potential unused reusable components entry has been detected  | Yes| Yes|  |  |
-|oas3-valid-media-example | Examples must be valid against their defined schema. This rule is applied to *Media Type objects*  | Yes| Yes|  |  |
-|oas3-valid-schema-example | Examples must be valid against their defined schema. This rule is applied to *Schema objects* | Yes| Yes|  |  |
-|oas3-server-variables | This rule ensures that server variables defined in OpenAPI Specification 3 (OAS3) and 3.1 are valid, not unused | Yes| Yes|  |  |
+|oas3-api-servers | OpenAPI servers must be present and non-empty array | Yes| Yes| Warning |  |
+|oas3-examples-value-or-externalValue | Examples for requestBody or response examples can have an `externalValue` or a `value`, but they cannot have both| Yes| Yes| Warning |  |
+|**oas3-operation-security-defined** | Operation `security` values must match a scheme defined in the `components.securitySchemes` object. | Yes| Yes| Warning |  |
+|oas3-parameter-description | Parameter objects should have a description| No| Yes?| Warning |  |
+|oas3-schema | Validate structure of OpenAPI v3 specification | Yes| Yes| Warning |  |
+|oas3-server-not-example.com | Server URL should not point to *example.com*| No| Yes?| Warning |  |
+|oas3-server-trailing-slash | Server URL should not have a trailing slash | Yes| Yes| Warning |  |
+|oas3-unused-component | Potential unused reusable components entry has been detected  | Yes| Yes| Warning |  |
+|oas3-valid-media-example | Examples must be valid against their defined schema. This rule is applied to *Media Type objects*  | Yes| Yes| Warning  |  |
+|oas3-valid-schema-example | Examples must be valid against their defined schema. This rule is applied to *Schema objects* | Yes| Yes| Warning   |  |
+|oas3-server-variables | This rule ensures that server variables defined in OpenAPI Specification 3 (OAS3) and 3.1 are valid, not unused | Yes| Yes| Warning  |  |
 
 
 

From 7e20374d3a9e5d9d3d5c1597b220365cba2e1180 Mon Sep 17 00:00:00 2001
From: Rafal Artych <121048129+rartych@users.noreply.github.com>
Date: Mon, 23 Oct 2023 19:03:56 +0200
Subject: [PATCH 07/15] Update Linting-rules.md

New rules for topics: 1, 2, 3, 4, 9, 10, 11, 13, 14, 18 added
---
 documentation/Linting-rules.md | 113 ++++++++++++++++++++++++++++++++-
 1 file changed, 111 insertions(+), 2 deletions(-)

diff --git a/documentation/Linting-rules.md b/documentation/Linting-rules.md
index 31572a9e..7a59ad70 100644
--- a/documentation/Linting-rules.md
+++ b/documentation/Linting-rules.md
@@ -52,7 +52,12 @@ Rules applying to both OpenAPI v2.0, v3.0, and most likely v3.1.
 |path-params | Path parameters are correct and valid | Yes| Yes| Error |  |
 |tag-description | global tags have description | No | ???| Warning |  |
 |typed-enum | Enum values should respect the type specifier. | Yes| Yes| Warning |  |
-||||| |
+
+### OpenAPI v3-only
+Rules applicable only to OpenAPI v3.0 documents.
+
+|Name| Desc| Recom mended|CAMARA use|Spectral severity | CAMARA severity
+|---|---|---|--|---|--|
 |oas3-api-servers | OpenAPI servers must be present and non-empty array | Yes| Yes| Warning |  |
 |oas3-examples-value-or-externalValue | Examples for requestBody or response examples can have an `externalValue` or a `value`, but they cannot have both| Yes| Yes| Warning |  |
 |**oas3-operation-security-defined** | Operation `security` values must match a scheme defined in the `components.securitySchemes` object. | Yes| Yes| Warning |  |
@@ -99,13 +104,62 @@ _Spectral rule_: [camara-language-avoid-telco]()
 
 *Severity*: `hint`
 
+
+
+
 ## 3. API Definition
+
+
+### Openapi property
+
+API Design Guidelines: 
+[11. Definition in OpenAPI](https://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md#11-definition-in-openapi)
+
+The API functionalities must be implemented following the specifications of the **Open API version 3.0.3** 
+
+`/users/{id}`
+
+| ❌ &nbsp; Not recommended | 👍  &nbsp; Recommended |
+|----------------------------|-------------------------|
+| `openapi: 3.0.1`                 | `openapi: 3.0.3`           |
+
+_Spectral rule_: [camara-oas-version]()
+
+*Severity*: `error`
+
+### Info object
+
+API Design Guidelines: 
+[11.1 General Information](hhttps://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md#111-general-information)
+
+
+Info object must include the following information: API title with public name.
+
+
+_Spectral rule_: [camara-info−title]()
+
+*Severity*: `warn`
+
+
+API Design Guidelines: 
+[11.1 General Information](hhttps://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md#111-general-information)
+
+
+Info object must include the following information: API Version in the format: X.Y.Z.
+
+
+_Spectral rule_: [camara-info−version-format]()
+
+*Severity*: `warn` <br>
+❕ Note: Currently the format like  `version: 0.10.0-wip` is used in the API development branch
+
+
+
 ### Path parameters
 
 API Design Guidelines: 
 [3.4 Path Parameters Use](https://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md#34-path-parameters-use)
 
-
 Point 2 The attribute must be identifying itself, it is not enough with "{id}"
 
 `/users/{id}`
@@ -131,6 +185,37 @@ _Spectral rule_: [camara-path-param-id-morphology]()
 
 *Severity*: `warn`
 
+
+### Sensitive data 
+Sensitive data (msisdn/imsi) cannot be a path or query parameter.
+<br>❕ Note: Needs to list down if we have other sensitive parameters other than MSISDN/IMSI - cf.  *monite-security-no-secrets-in-path-or-query-parameters*
+
+
+_Spectral rule_: [camara-security-no-secrets-in-path-or-query-parameters]()
+
+*Severity*: `warn`
+
+### HTTP verbs
+
+API Design Guidelines: 
+[3.1 API REST](https://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md#31-api-rest)
+
+Valid methods are: GET, PUT, POST, DELETE, PATCH, OPTIONS
+
+_Spectral rule_: [camara-http-methods]()
+
+*Severity*: `error`
+
+
+
+'GET' and 'DELETE' http methods MUST NOT accept a 'requestBody' attribute 
+<br>❕ Note: https://github.com/team-monite/api-style-guide/blob/main/spectral/monite.section8-requests.yaml
+
+_Spectral rule_: [camara-get-no-request-body]()
+
+*Severity*: `error`
+
+
 ### Reserved words
 
 API Design Guidelines: 
@@ -158,6 +243,30 @@ _Spectral rule_: [camara-reserved-words]()
 
 *Severity*: `warn`
 
+
+Resources must not contain the method name get, put, post, delete, patch.
+
+_Spectral rule_: [camara-resource-reserved-words]()
+
+*Severity*: `warn`
+
+ 
+### Descriptions
+
+API Design Guidelines: [11.3 Request Parameters](https://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md#113-request-parameters)
+
+All parameters must have a description. 
+
+_Spectral rule_: [camara-parameters-descriptions]()
+
+*Severity*: `warn`
+
+API Design Guidelines: [11.2 Published Routes](https://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md#112-published-routes)
+Summary must be defined on each operation, describing with a short summary what the operation does.  
+_Spectral rule_: [camara-operation-summary]()
+
+*Severity*: `warn`
+
 ### Usage of discriminator
 
 API Design Guidelines: 

From d2726fdc7b9d0c7d3492fc87a69dca91a8a9c5a6 Mon Sep 17 00:00:00 2001
From: Rafal Artych <121048129+rartych@users.noreply.github.com>
Date: Thu, 2 Nov 2023 12:41:10 +0100
Subject: [PATCH 08/15] Update Linting-rules.md

OperationId casing clarified - no contradiction with Spectral core rules
---
 documentation/Linting-rules.md | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/documentation/Linting-rules.md b/documentation/Linting-rules.md
index 7a59ad70..3a765009 100644
--- a/documentation/Linting-rules.md
+++ b/documentation/Linting-rules.md
@@ -314,9 +314,6 @@ Operation ids should follow a specific case convention: `camel` case.
 
 _Spectral rule_: [camara-operationid-casing-convention]()
 
-**Contradiction with Spectral rule `operation-operationId `** 
->  a reference for the operation - the value `lower-hyphen-case`
-
 *Severity*: `error`
 
 #### Path parameters / Query parameters

From 367303b03253e8d2039b27e434114d121dda15d4 Mon Sep 17 00:00:00 2001
From: Rafal Artych <121048129+rartych@users.noreply.github.com>
Date: Fri, 3 Nov 2023 09:15:10 +0100
Subject: [PATCH 09/15] Update documentation/Linting-rules.md

Co-authored-by: Jose Luis Urien <jlurien@gmail.com>
---
 documentation/Linting-rules.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/documentation/Linting-rules.md b/documentation/Linting-rules.md
index 3a765009..54bb6ae1 100644
--- a/documentation/Linting-rules.md
+++ b/documentation/Linting-rules.md
@@ -25,7 +25,8 @@ Rules applying to both OpenAPI v2.0, v3.0, and most likely v3.1.
 
 |Name| Desc| Recom mended|CAMARA use|Spectral severity | CAMARA severity
 |---|---|---|--|---|--|
-|contact-properties| contact object is full of the most useful properties: `name`, `url`, `and email`|No|No | Warning |  |
+|contact-properties| contact object is full of the most useful properties: `name`, `url`, and `email`|No|No | Warning |  |
+
 |duplicated-entry-in-enum| Each value of an `enum` must be different from one another |Yes  | Yes | Warning |  |
 |info-contact |Info object should contain `contact` object |Yes  | Yes| Warning  |  |
 |info-description |Info object should contain `description` object |Yes  | Yes| Warning |  | 

From 6c27f4a3c06fbf8ee966beca1d47b2590a421070 Mon Sep 17 00:00:00 2001
From: Rafal Artych <121048129+rartych@users.noreply.github.com>
Date: Fri, 3 Nov 2023 13:56:57 +0100
Subject: [PATCH 10/15] Update Linting-rules.md

Clarifications on Spectral core ruleset
---
 documentation/Linting-rules.md | 11 +++++++----
 1 file changed, 7 insertions(+), 4 deletions(-)

diff --git a/documentation/Linting-rules.md b/documentation/Linting-rules.md
index 54bb6ae1..f83a775c 100644
--- a/documentation/Linting-rules.md
+++ b/documentation/Linting-rules.md
@@ -9,24 +9,27 @@ Spectral has a built-in OpenAPI Specification ruleset that can be used to valida
 
 With `extends: "spectral:oas"` ("oas" being shorthand for OpenAPI Specification) in the ruleset file to rules for OpenAPI v2 and v3.x, depending on the appropriate OpenAPI version being used (this is automatically detected through formats) are added to the final ruleset.
 
-The full list of the rules in this ruleset are described in [OpenAPI Rules](https://docs.stoplight.io/docs/spectral/4dec24461f3af-open-api-rules).
+All of the rules in this ruleset are described in [OpenAPI Rules](https://docs.stoplight.io/docs/spectral/4dec24461f3af-open-api-rules).
 
 
 `extends: [[spectral:oas, off]]`  - this avoids running any rules from the extended ruleset as they are disabled. Each rule then can be [enabled individually](https://docs.stoplight.io/docs/spectral/0a73453054745-recommended-or-all#enabling-rules).
 
+### Recommended rules
+Spectral's built-in OpenAPI ruleset is a two-tier system: with subset of rules marked as [recommended](https://docs.stoplight.io/docs/spectral/0a73453054745-recommended-or-all#recommended-or-all) to be used by default, and addtional rules marked with `recommended: false`.
+Recommended rules cover more basic requirements.
+
 ### Rule severity
 
 The `severity` keyword is optional in rule definition and can be `error`, `warn`, `info`, `hint`, or `off`.
 The default value is `warn`.
 
 ### OpenAPI v2 & v3
-Rules applying to both OpenAPI v2.0, v3.0, and most likely v3.1.
 
+Rules applying to both OpenAPI v2.0, v3.0, and most likely v3.1 - details are described in [Spectral Documentation](https://docs.stoplight.io/docs/spectral/4dec24461f3af-open-api-rules#openapi-v2--v3).
 
 |Name| Desc| Recom mended|CAMARA use|Spectral severity | CAMARA severity
 |---|---|---|--|---|--|
 |contact-properties| contact object is full of the most useful properties: `name`, `url`, and `email`|No|No | Warning |  |
-
 |duplicated-entry-in-enum| Each value of an `enum` must be different from one another |Yes  | Yes | Warning |  |
 |info-contact |Info object should contain `contact` object |Yes  | Yes| Warning  |  |
 |info-description |Info object should contain `description` object |Yes  | Yes| Warning |  | 
@@ -55,7 +58,7 @@ Rules applying to both OpenAPI v2.0, v3.0, and most likely v3.1.
 |typed-enum | Enum values should respect the type specifier. | Yes| Yes| Warning |  |
 
 ### OpenAPI v3-only
-Rules applicable only to OpenAPI v3.0 documents.
+Rules applicable only to OpenAPI v3.0 documents - details are described in [Spectral Documentation](https://docs.stoplight.io/docs/spectral/4dec24461f3af-open-api-rules#openapi-v3-only).
 
 |Name| Desc| Recom mended|CAMARA use|Spectral severity | CAMARA severity
 |---|---|---|--|---|--|

From 22d6a04fc2772dd63267e96fd23aca8c3eabdb6f Mon Sep 17 00:00:00 2001
From: Rafal Artych <121048129+rartych@users.noreply.github.com>
Date: Fri, 8 Dec 2023 15:35:38 +0100
Subject: [PATCH 11/15] Update Linting-rules.md

Table summarizing camara- linting rules
---
 documentation/Linting-rules.md | 107 ++++++++++++++++++++-------------
 1 file changed, 66 insertions(+), 41 deletions(-)

diff --git a/documentation/Linting-rules.md b/documentation/Linting-rules.md
index f83a775c..faf2f3d4 100644
--- a/documentation/Linting-rules.md
+++ b/documentation/Linting-rules.md
@@ -27,52 +27,52 @@ The default value is `warn`.
 
 Rules applying to both OpenAPI v2.0, v3.0, and most likely v3.1 - details are described in [Spectral Documentation](https://docs.stoplight.io/docs/spectral/4dec24461f3af-open-api-rules#openapi-v2--v3).
 
-|Name| Desc| Recom mended|CAMARA use|Spectral severity | CAMARA severity
+|Name| Desc| Recom mended|CAMARA use|Spectral severity | CAMARA severity |
 |---|---|---|--|---|--|
-|contact-properties| contact object is full of the most useful properties: `name`, `url`, and `email`|No|No | Warning |  |
-|duplicated-entry-in-enum| Each value of an `enum` must be different from one another |Yes  | Yes | Warning |  |
-|info-contact |Info object should contain `contact` object |Yes  | Yes| Warning  |  |
-|info-description |Info object should contain `description` object |Yes  | Yes| Warning |  | 
-|info-license |Info object should contain `license` object |Yes  | Yes|  Warning |  |
-|license-url | link to the full text of licence | Yes | Yes| Warning  |  |
-|no-$ref-siblings| Before OpenAPI v3.1, keywords next to $ref were ignored | Yes | Yes| Error |  |
-|no-eval-in-markdown | injecting `eval()` JavaScript statements could lead to an XSS attack |Yes |Yes |Warning  |  |
-|no-script-tags-in-markdown |  injecting `<script>` tags could lead to execution of an arbitrary | Yes |Yes | Warning |  |
-|openapi-tags | OpenAPI object should have non-empty `tags` array |No | Yes | Warning |  |
-|openapi-tags-alphabetical | OpenAPI object should have alphabetical `tags` | No |No | Warning |  |
-|openapi-tags-uniqueness | OpenAPI object must not have duplicated tag names | No | No | Error |  |
-|operation-description | Operation `description` must be present and non-empty string | Yes| Yes| Warning  |  |
-|operation-operationId | Operation must have `operationId` |Yes| Yes| Warning |  |
-|operation-operationId-unique | Every operation must have a unique operationId | Yes| Yes| Error |  |
-|operation-operationId-valid-in-url | avoid non-URL-safe characters| Yes| Yes| Warning |  |
-|operation-parameters | Operation parameters are unique and non-repeating | Yes| Yes| Warning  |  |
-|operation-singular-tag | Use just one tag for an operation | No| Yes| Warning |  |
-|operation-success-response | Operation must have at least one `2xx` or `3xx` response | Yes| Yes| Warning |  |
-|operation-tags | Operation should have non-empty `tags` array| Yes| Yes| Warning |  |
-|operation-tag-defined | Operation tags should be defined in global tags| Yes| Yes| Warning |  |
-|path-declarations-must-exist | Path parameter declarations cannot be empty, ex.`/given/{}` is invalid.  | Yes| Yes| Warning |  |
-|path-keys-no-trailing-slash | Keep trailing slashes off of paths,  | Yes| Yes| Warning |  |
-|path-not-include-query | Don't put query string items in the path, they belong in parameters with `in: query`| Yes| Yes| Warning |  |
-|path-params | Path parameters are correct and valid | Yes| Yes| Error |  |
-|tag-description | global tags have description | No | ???| Warning |  |
-|typed-enum | Enum values should respect the type specifier. | Yes| Yes| Warning |  |
+|contact-properties| contact object is full of the most useful properties: `name`, `url`, and `email`| No | No | Warning | Warning |
+|duplicated-entry-in-enum| Each value of an `enum` must be different from one another | Yes | Yes | Warning | Warning |
+|info-contact |Info object should contain `contact` object |Yes | Yes | Warning | Warning |
+|info-description |Info object should contain `description` object | Yes | Yes| Warning | Warning | 
+|info-license |Info object should contain `license` object |Yes | Yes |  Warning | Warning |
+|license-url | link to the full text of licence | Yes | Yes| Warning | Warning |
+|no-$ref-siblings| Before OpenAPI v3.1, keywords next to $ref were ignored | Yes | Yes| Error | Error  |
+|no-eval-in-markdown | injecting `eval()` JavaScript statements could lead to an XSS attack | Yes | Yes | Warning | Warning |
+|no-script-tags-in-markdown |  injecting `<script>` tags could lead to execution of an arbitrary | Yes |Yes | Warning | Warning |
+|openapi-tags | OpenAPI object should have non-empty `tags` array |No | No | Warning | Warning |
+|openapi-tags-alphabetical | OpenAPI object should have alphabetical `tags` | No |No | Warning | Warning |
+|openapi-tags-uniqueness | OpenAPI object must not have duplicated tag names | No | No | Error | Error |
+|operation-description | Operation `description` must be present and non-empty string | Yes| Yes| Warning | Warning |
+|operation-operationId | Operation must have `operationId` | Yes | Yes | Warning | Warning |
+|operation-operationId-unique | Every operation must have a unique operationId | Yes| Yes| Error | Error |
+|operation-operationId-valid-in-url | avoid non-URL-safe characters| Yes| Yes| Warning | Warning |
+|operation-parameters | Operation parameters are unique and non-repeating | Yes| Yes| Warning | Warning |
+|operation-singular-tag | Use just one tag for an operation | No| Yes| Warning | Warning |
+|operation-success-response | Operation must have at least one `2xx` or `3xx` response | Yes| Yes| Warning | Warning |
+|operation-tags | Operation should have non-empty `tags` array| Yes| Yes| Warning | Warning |
+|operation-tag-defined | Operation tags should be defined in global tags| Yes| Yes| Warning | Warning |
+|path-declarations-must-exist | Path parameter declarations cannot be empty, ex.`/given/{}` is invalid | Yes | Yes | Warning | Warning |
+|path-keys-no-trailing-slash | Keep trailing slashes off of paths | Yes | Yes | Warning | Warning |
+|path-not-include-query | Don't put query string items in the path, they belong in parameters with `in: query`| Yes| Yes| Warning | Warning |
+|path-params | Path parameters are correct and valid | Yes | Yes | Error | Error |
+|tag-description | global tags have description | No | No | Warning | Warning |
+|typed-enum | Enum values should respect the type specifier. | Yes| Yes| Warning | Warning |
 
 ### OpenAPI v3-only
 Rules applicable only to OpenAPI v3.0 documents - details are described in [Spectral Documentation](https://docs.stoplight.io/docs/spectral/4dec24461f3af-open-api-rules#openapi-v3-only).
 
-|Name| Desc| Recom mended|CAMARA use|Spectral severity | CAMARA severity
+|Name| Desc| Recom mended|CAMARA use|Spectral severity | CAMARA severity |
 |---|---|---|--|---|--|
-|oas3-api-servers | OpenAPI servers must be present and non-empty array | Yes| Yes| Warning |  |
-|oas3-examples-value-or-externalValue | Examples for requestBody or response examples can have an `externalValue` or a `value`, but they cannot have both| Yes| Yes| Warning |  |
-|**oas3-operation-security-defined** | Operation `security` values must match a scheme defined in the `components.securitySchemes` object. | Yes| Yes| Warning |  |
-|oas3-parameter-description | Parameter objects should have a description| No| Yes?| Warning |  |
-|oas3-schema | Validate structure of OpenAPI v3 specification | Yes| Yes| Warning |  |
-|oas3-server-not-example.com | Server URL should not point to *example.com*| No| Yes?| Warning |  |
-|oas3-server-trailing-slash | Server URL should not have a trailing slash | Yes| Yes| Warning |  |
-|oas3-unused-component | Potential unused reusable components entry has been detected  | Yes| Yes| Warning |  |
-|oas3-valid-media-example | Examples must be valid against their defined schema. This rule is applied to *Media Type objects*  | Yes| Yes| Warning  |  |
-|oas3-valid-schema-example | Examples must be valid against their defined schema. This rule is applied to *Schema objects* | Yes| Yes| Warning   |  |
-|oas3-server-variables | This rule ensures that server variables defined in OpenAPI Specification 3 (OAS3) and 3.1 are valid, not unused | Yes| Yes| Warning  |  |
+|oas3-api-servers | OpenAPI servers must be present and non-empty array | Yes | Yes | Warning | Warning |
+|oas3-examples-value-or-externalValue | Examples for requestBody or response examples can have an `externalValue` or a `value`, but they cannot have both| Yes| Yes| Warning | Warning |
+|oas3-operation-security-defined | Operation `security` values must match a scheme defined in the `components.securitySchemes` object. | Yes| Yes| Warning | Warning |
+|oas3-parameter-description | Parameter objects should have a description| No | No | Warning | Warning |
+|oas3-schema | Validate structure of OpenAPI v3 specification | Yes| Yes | Warning | Warning |
+|oas3-server-not-example.com | Server URL should not point to *example.com*| No| No| Warning | Warning |
+|oas3-server-trailing-slash | Server URL should not have a trailing slash | Yes| Yes| Warning | Warning |
+|oas3-unused-component | Potential unused reusable components entry has been detected  | Yes| Yes| Warning | Warning |
+|oas3-valid-media-example | Examples must be valid against their defined schema. This rule is applied to *Media Type objects*  | Yes| Yes| Warning  | Warning |
+|oas3-valid-schema-example | Examples must be valid against their defined schema. This rule is applied to *Schema objects* | Yes | Yes | Warning | Warning |
+|oas3-server-variables | This rule ensures that server variables defined in OpenAPI Specification 3 (OAS3) and 3.1 are valid, not unused | Yes| Yes| Warning | Warning |
 
 
 
@@ -248,7 +248,7 @@ _Spectral rule_: [camara-reserved-words]()
 *Severity*: `warn`
 
 
-Resources must not contain the method name get, put, post, delete, patch.
+Resource names must not contain the method name: get, put, post, delete, patch.
 
 _Spectral rule_: [camara-resource-reserved-words]()
 
@@ -355,3 +355,28 @@ Schema names (the keys in `components -> schemas`) should follow the "upper came
 _Spectral rule_: [camara-schema-casing-convention]()
 
 *Severity*: `warn`
+
+## 4. Summary of proposed CAMARA rules
+
+|Name| Desc| Recom mended|CAMARA use|  CAMARA severity |
+|---|---|---|---|--|
+|camara-language-spelling | Check spellin in description fields | No | No | Warning |
+|camara-language-avoid-telco | Avoid terms/types specific to the telco domain | Yes | Yes | Hint |
+|camara-oas-version | Open API version 3.0.3 | Yes | Yes | Warning |
+|camara-info−title | API title with public name | tbd | tbd | Warning |
+|camara-info−version-format | API Version in the format: X.Y.Z. | tbd | tbd | Warning |
+|camara-path-param-id | Use 'resource_id' instead of just 'id' for your path parameters | Yes | Yes | Warning |
+|camara-security-no-secrets-in-path-or-query-parameters| Sensitive data (msisdn/imsi) cannot be a path or query parameter | Yes | Yes | Warning |
+|camara-http-methods | Valid methods are: GET, PUT, POST, DELETE, PATCH, OPTIONS | Yes | Yes | Error |
+|camara-get-no-request-body | 'GET' and 'DELETE' http methods MUST NOT accept a 'requestBody' attribute | Yes | Yes | Error |
+|camara-reserved-words | Reserved words must not be used | Yes | Yes | Warning |
+|camara-resource-reserved-words| Resources must not contain the method name | Yes | Yes | Warning |
+|camara-parameters-descriptions | All parameters must have a description | Yes | Yes | Warning |
+|camara-operation-summary | Summary must be defined on each operation | Yes | Yes | Warning |
+|camara-discriminator-use | discriminator object can be used to aid in serialization, deserialization, and validation | Yes | Yes | Warning |
+|camara-operationid-casing-convention | Operation ids should follow a specific case convention: camel case | Yes | Yes | Hint |
+|camara-schema-casing-convention | Schema should follow a specific case convention pascal case (upper camel case) | Yes | Yes | Warning |
+|camara-parameter-casing-convention | Path parameter should follow a specific case convention, with the default being kebab-case | Yes | Yes | Error |
+|camara-schema-casing-convention | Schema should follow a specific case convention pascal case (upper camel case) | Yes | Yes | Warning |
+|camara-enum-casing-convention | enum fields contain values that follow a specific case convention: macro (CAPITAL_LETTERS) | tbd | tbd | Info |
+|camara-property-casing-convention | Property names should follow a specific case convention, with the default being camel case | tbd | tbd | Error |

From 802838a6142331687feb5a8a5f825575bae67ae4 Mon Sep 17 00:00:00 2001
From: Rafal Artych <121048129+rartych@users.noreply.github.com>
Date: Mon, 11 Dec 2023 11:59:31 +0100
Subject: [PATCH 12/15] Update Linting-rules.md

camara-oas-version severity
---
 documentation/Linting-rules.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/documentation/Linting-rules.md b/documentation/Linting-rules.md
index faf2f3d4..0fbcb9dd 100644
--- a/documentation/Linting-rules.md
+++ b/documentation/Linting-rules.md
@@ -362,7 +362,7 @@ _Spectral rule_: [camara-schema-casing-convention]()
 |---|---|---|---|--|
 |camara-language-spelling | Check spellin in description fields | No | No | Warning |
 |camara-language-avoid-telco | Avoid terms/types specific to the telco domain | Yes | Yes | Hint |
-|camara-oas-version | Open API version 3.0.3 | Yes | Yes | Warning |
+|camara-oas-version | Open API version 3.0.3 | Yes | Yes | Error |
 |camara-info−title | API title with public name | tbd | tbd | Warning |
 |camara-info−version-format | API Version in the format: X.Y.Z. | tbd | tbd | Warning |
 |camara-path-param-id | Use 'resource_id' instead of just 'id' for your path parameters | Yes | Yes | Warning |

From f2447e6a6b89fdfba236c45b40fb18ebec896f39 Mon Sep 17 00:00:00 2001
From: Rafal Artych <121048129+rartych@users.noreply.github.com>
Date: Fri, 26 Jan 2024 19:38:04 +0100
Subject: [PATCH 13/15] Update Linting-rules.md

More granular rules for objects descriptions
---
 documentation/Linting-rules.md | 33 ++++++++++++++++++++++++++++++---
 1 file changed, 30 insertions(+), 3 deletions(-)

diff --git a/documentation/Linting-rules.md b/documentation/Linting-rules.md
index 0fbcb9dd..e6f86739 100644
--- a/documentation/Linting-rules.md
+++ b/documentation/Linting-rules.md
@@ -64,7 +64,7 @@ Rules applicable only to OpenAPI v3.0 documents - details are described in [Spec
 |---|---|---|--|---|--|
 |oas3-api-servers | OpenAPI servers must be present and non-empty array | Yes | Yes | Warning | Warning |
 |oas3-examples-value-or-externalValue | Examples for requestBody or response examples can have an `externalValue` or a `value`, but they cannot have both| Yes| Yes| Warning | Warning |
-|oas3-operation-security-defined | Operation `security` values must match a scheme defined in the `components.securitySchemes` object. | Yes| Yes| Warning | Warning |
+|oas3-operation-security-defined | Operation `security` values must match a scheme defined in the `components.securitySchemes` object. | Yes| No| Warning | Warning |
 |oas3-parameter-description | Parameter objects should have a description| No | No | Warning | Warning |
 |oas3-schema | Validate structure of OpenAPI v3 specification | Yes| Yes | Warning | Warning |
 |oas3-server-not-example.com | Server URL should not point to *example.com*| No| No| Warning | Warning |
@@ -74,7 +74,7 @@ Rules applicable only to OpenAPI v3.0 documents - details are described in [Spec
 |oas3-valid-schema-example | Examples must be valid against their defined schema. This rule is applied to *Schema objects* | Yes | Yes | Warning | Warning |
 |oas3-server-variables | This rule ensures that server variables defined in OpenAPI Specification 3 (OAS3) and 3.1 are valid, not unused | Yes| Yes| Warning | Warning |
 
-
+Note: oas3-operation-security-defined rule is not fully compatible with OpenIdConnect.
 
 ## 2. Language
 ### Spell checking
@@ -257,6 +257,14 @@ _Spectral rule_: [camara-resource-reserved-words]()
  
 ### Descriptions
 
+API Design Guidelines: [11.2 Published routes](https://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md#112-published-routes)
+
+Functionality methods must have a description.
+
+_Spectral rule_: [camara-routes-descriptions]()
+
+*Severity*: `warn`
+
 API Design Guidelines: [11.3 Request Parameters](https://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md#113-request-parameters)
 
 All parameters must have a description. 
@@ -265,6 +273,22 @@ _Spectral rule_: [camara-parameters-descriptions]()
 
 *Severity*: `warn`
 
+API Design Guidelines: [11.4 Response Structure](https://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md#114-response-structure)
+
+All response objects must have a description. 
+
+_Spectral rule_: [camara-response-descriptions]()
+
+*Severity*: `warn`
+
+API Design Guidelines: [11.5 Data Definitions](https://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md#115-data-definitions)
+
+All properties within the object must have a description. 
+
+_Spectral rule_: [camara-properties-descriptions]()
+
+*Severity*: `warn`
+
 API Design Guidelines: [11.2 Published Routes](https://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md#112-published-routes)
 Summary must be defined on each operation, describing with a short summary what the operation does.  
 _Spectral rule_: [camara-operation-summary]()
@@ -370,8 +394,11 @@ _Spectral rule_: [camara-schema-casing-convention]()
 |camara-http-methods | Valid methods are: GET, PUT, POST, DELETE, PATCH, OPTIONS | Yes | Yes | Error |
 |camara-get-no-request-body | 'GET' and 'DELETE' http methods MUST NOT accept a 'requestBody' attribute | Yes | Yes | Error |
 |camara-reserved-words | Reserved words must not be used | Yes | Yes | Warning |
-|camara-resource-reserved-words| Resources must not contain the method name | Yes | Yes | Warning |
+|camara-resource-reserved-words | Resources must not contain the method name | Yes | Yes | Warning |
+|camara-routes-description | Functionality methods must have a description. | Yes | Yes | Warning |
 |camara-parameters-descriptions | All parameters must have a description | Yes | Yes | Warning |
+|camara-response-descriptions| All response objects must have a description | Yes | Yes | Warning |
+|camara-properties-descriptions | All properties within the object must have a description | Yes | Yes | Warning |
 |camara-operation-summary | Summary must be defined on each operation | Yes | Yes | Warning |
 |camara-discriminator-use | discriminator object can be used to aid in serialization, deserialization, and validation | Yes | Yes | Warning |
 |camara-operationid-casing-convention | Operation ids should follow a specific case convention: camel case | Yes | Yes | Hint |

From ae2bf349cc3e936189ac53afbcfdcd7943435ca1 Mon Sep 17 00:00:00 2001
From: Rafal Artych <121048129+rartych@users.noreply.github.com>
Date: Fri, 26 Jan 2024 19:40:26 +0100
Subject: [PATCH 14/15] Delete artifacts/Github_actions/.workflows/README.md

Artifacts are proposed in the other PR
---
 artifacts/Github_actions/.workflows/README.md | 1 -
 1 file changed, 1 deletion(-)
 delete mode 100644 artifacts/Github_actions/.workflows/README.md

diff --git a/artifacts/Github_actions/.workflows/README.md b/artifacts/Github_actions/.workflows/README.md
deleted file mode 100644
index b172552b..00000000
--- a/artifacts/Github_actions/.workflows/README.md
+++ /dev/null
@@ -1 +0,0 @@
-Configuration files for Github Actions

From da583114971df2608135495d64a241de66b10ea8 Mon Sep 17 00:00:00 2001
From: Rafal Artych <121048129+rartych@users.noreply.github.com>
Date: Mon, 29 Jan 2024 15:45:22 +0100
Subject: [PATCH 15/15] Update Linting-rules.md

---
 documentation/Linting-rules.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/documentation/Linting-rules.md b/documentation/Linting-rules.md
index e6f86739..625a9694 100644
--- a/documentation/Linting-rules.md
+++ b/documentation/Linting-rules.md
@@ -304,7 +304,7 @@ When request bodies or response payloads may be one of a number of different sch
 
 _Spectral rule_: [camara-discriminator-use]()
 
-*Severity*: `warn`
+*Severity*: `hint`
 
 ### Casing convention