Start of a style guide for contributing to the spec

README.md

@@ -23,6 +23,49 @@ The following SDKs are generated from the OpenAPI Specification. They are automa
 | Java                  | [GitHub](https://github.com/LukeHagar/plexjava)   | [Releases](https://github.com/LukeHagar/plexjava/releases)                                       | -                                                       |
 | C#                    | [GitHub](https://github.com/LukeHagar/plexcsharp) | [Releases](https://github.com/LukeHagar/plexcsharp/releases)                                     | -                                                       |
 
+## Project Structure
+
+The main OpenAPI Specification is located in the root directory as [pms-spec.yaml](https://github.com/LukeHagar/plex-api-spec/blob/main/pms-spec.yaml). Which references 
+
+ - [**/paths**](https://github.com/LukeHagar/plex-api-spec/tree/main/paths): The endpoints for the Plex Media Server API. Each endpoint is defined in a separate file.
+ - [**/models**](https://github.com/LukeHagar/plex-api-spec/tree/main/models): The schema models used in the specification.
+ - [**/parameters**](https://github.com/LukeHagar/plex-api-spec/tree/main/parameters): The parameters used in the specification.
+ - [**/responses**](https://github.com/LukeHagar/plex-api-spec/tree/main/responses): The responses used in the specification.
+
+In addition, there is a bundled single file OpenAPI Specification, [plex-media-server-spec-dereferenced.yaml](https://github.com/LukeHagar/plex-api-spec/blob/main/plex-media-server-spec-dereferenced.yaml) which is automatically bundled on any changes to the main specification.
+
+## Styleguide
+
+All spec files should adhere to the 3.1 OpenAPI Specification.
+Every endpoint is defined in the /paths directory. Each endpoint is defined in a separate file. The file name should be the endpoint name with the method type. For example, the endpoint /library/sections is defined in the file /paths/library_sections.get.yaml. 
+
+The file should contain data in the following order:
+
+```yaml
+
+[get/post/put/delete]:
+  servers:
+  security:
+  tags:
+  summary:
+  description:
+  operationId:
+  parameters:
+    $ref:
+        name:
+        description:
+        required:
+        schema:
+  responses:
+    2XX:
+    4XX:
+    5XX:
+  
+```
+
+### Rules
+ - A property in the response is only marked as required if it is always returned, regardless of the parameters sent with the request.
+
 ## Questions?
 
 Reach out to me on the [Discord Server](https://discord.gg/mxqjsJHwUm)