Added style guide (#89)

Author: delvedor

.github/PULL_REQUEST_TEMPLATE.md

@@ -7,6 +7,7 @@ Please make sure to follow the steps below when opening a pr:
 
 - Tag the relative issue (if any) and give a brief explanation on what your changes are doing
 - If you did a spec change, remember to generate again the outputs, you can do it by running `make generate-spec`
+- Make sure your code follows the lint rules, you can fix them by running `npm run lint:fix --prefix specification`
 - Sign the CLA https://www.elastic.co/contributor-agreement/
 
 Happy coding!

.github/workflows/code-format.yml

@@ -0,0 +1,25 @@
+name: Code style
+
+on: [pull_request]
+
+jobs:
+ build:
+
+ runs-on: ubuntu-latest
+
+ steps:
+ - uses: actions/checkout@v2
+
+ - name: Use Node.js 14.x
+ uses: actions/setup-node@v1
+ with:
+ node-version: 14.x
+
+ - name: Install
+ run: |
+ npm install --prefix specification
+
+ - name: Code style check
+ run: |
+ npm run format:check --prefix specification
+

Makefile

@@ -20,6 +20,10 @@ validation-api-response: ## Validate response of Endpoint with param: api=<api-
 @echo ">> validating response of Endpoint: $(api)"
 ./run-validations.sh --api $(api) --response
 
+format-code: ## Format the spec according to the style guide
+@echo ">> validating formatting code"
+@npm run format:fix --prefix specification
+
 generate-spec: ## Generate the output spec
 @echo ">> generating the spec .."
 @npm run compile:canonical-json

README.md

@@ -184,147 +184,6 @@ Namespaced APIs can be validated in the same way, for example:
 ./run-validations.sh --api cat.health --request
 ```
 
-## Custom types
-
-The goal of the specification is to be used by different languages, from dynamically typed to statically typed.
-To achieve this goal the specification contains a series of custom types that do not have a meaning
-for the target language, but they should be translated to the most approriate construct.
-
-The specification is written in [TypeScript](https://www.typescriptlang.org/), you can find all
-the basic types [here](https://www.typescriptlang.org/docs/handbook/basic-types.html), while
-in [`docs/special-classes.md`](./docs/special-classes.md) you can find custom classes for
-defining set of APIs.
-
-### Dictionary
-
-Represents a dynamic key value map:
-
-```ts
-property: Dictionary<string, TypeDefinition>
-```
-
-For example:
-
-```json
-{
- "property1": "type",
- "property2": "other-type",
-}
-```
-
-### SingleKeyDictionary
-
-Represents a dynamic key value map with a single top level key:
-
-```ts
-property: SingleKeyDictionary<string, TypeDefinition>
-```
-
-For example:
-
-```json
-{
- "onlyKey": "type"
-}
-```
-
-### Array
-
-Represents an array of the given value:
-
-```ts
-// generics syntax
-property: Array<string>
-
-// short syntax
-property: string[]
-```
-
-### Union
-
-Represents a type that can accept multiple types:
-
-```ts
-property: string | long
-```
-
-It can be combined with other types:
-```ts
-// array
-property: Array<string | long>
-
-// dictionary
-property: Dictionary<string, string | long>
-```
-
-### Enum
-
-Represents a set of allowed values:
-
-```ts
-enum MyEnum {
- first = 0,
- second = 1,
- third = 2
-}
-
-property: MyEnum
-```
-
-### User defined value
-
-Represents a value that will be defined by the user and has no specific type.
-
-```ts
-property: UserDefinedValue
-```
-
-### Numbers
-
-The numeric type in TypeScript is `number`, but given that this specification target mutliple languages,
-it offers a bunch of alias that represents the type that should be used if the language supports it:
-
-```ts
-type short = number
-type byte = number
-type integer = number
-type long = number
-type float = number
-type double = number
-```
-
-### Strings
-
-The string type in TypeScript is `string`. It's ok to use it in the spec, but to offer a more developer
-friendly specification, we do offer a set of aliases based on which string we do expect, for example:
-
-```ts
-type ScrollId = string
-type ScrollIds = string
-type CategoryId = string
-type ActionIds = string
-type Field = string
-type Id = string | number
-type Ids = string | number | string[]
-type IndexName = string
-type Indices = string | string[]
-...
-```
-
-You can find the full list [here](https://github.com/elastic/elastic-client-generator/blob/update-docs/specification/specs/common.ts),
-feel free to add more if it feels appropriate!
-
-### Dates
-
-The `Date` type in TypeScript refers to the JavaScript `Date` object,
-since Elasticsearch needs a string or a numeric value, there are aliases also for date types:
-
-```ts
-type Timestamp = string
-type TimeSpan = string
-interface Date {}
-```
-
 ## FAQ
 
 ### A specific property is not always present, how do I define it?

docs/behaviors.md

@@ -0,0 +1,43 @@
+# Behaviors
+
+Some APIs needs to be handled differenlty based on the output language, while others share many common parameters.
+This document contains the list of this special interfaces and where those should be used.
+Behaviors should be used via `implements` in the specification.
+
+You can find all the special classes and aliases in in the [modeling guide](./modeling-guide.md).
+
+## AdditionalProperties
+
+In some places in the specification an object consists of the union of a set of known properties
+and a set of runtime injected properties. Meaning that object should theoretically extend Dictionary but expose
+a set of known keys and possibly. The object might already be part of an object graph and have a parent class.
+This puts it into a bind that needs a client specific solution.
+We therefore document the requirement to behave like a dictionary for unknown properties with this interface.
+
+```ts
+class IpRangeBucket implements AdditionalProperties<AggregateName, Aggregate> {}
+```
+
+## ArrayResponse
+
+A response formatted as an array of records.
+Some languages can't represent this easily and need to wrap the
+array inside an object.
+
+```ts
+class CatAliasesResponse
+ extends ResponseBase
+ implements ArrayResponse<CatAliasesRecord> {}
+```
+
+## EmptyResponseBase
+
+HEAD APIs can have a different behavior based on the language,
+the response body is always empty to it's up to language generators
+to define how those should be represented.
+
+```ts
+class DocumentExistsResponse
+ extends ResponseBase
+ implements EmptyResponseBase {}
+```

docs/modeling-guide.md

@@ -0,0 +1,140 @@
+# Modeling Guide
+
+The goal of the specification is to be used by different languages, from dynamically typed to statically typed.
+To achieve this goal the specification contains a series of custom types that do not have a meaning
+for the target language, but they should be translated to the most approriate construct.
+
+The specification is written in [TypeScript](https://www.typescriptlang.org/), you can find all
+the basic types [here](https://www.typescriptlang.org/docs/handbook/basic-types.html),
+while in [behaviors](./behaviors.md) you can find the list of special interfaces used
+for describing APIs that can't be represented in the specification.
+
+### Dictionary
+
+Represents a dynamic key value map:
+
+```ts
+property: Dictionary<string, TypeDefinition>
+```
+
+For example:
+
+```json
+{
+ "property1": "type",
+ "property2": "other-type",
+}
+```
+
+### SingleKeyDictionary
+
+Represents a dynamic key value map with a single top level key:
+
+```ts
+property: SingleKeyDictionary<string, TypeDefinition>
+```
+
+For example:
+
+```json
+{
+ "onlyKey": "type"
+}
+```
+
+### Array
+
+Represents an array of the given value:
+
+```ts
+// generics syntax
+property: Array<string>
+
+// short syntax
+property: string[]
+```
+
+### Union
+
+Represents a type that can accept multiple types:
+
+```ts
+property: string | long
+```
+
+It can be combined with other types:
+```ts
+// array
+property: Array<string | long>
+
+// dictionary
+property: Dictionary<string, string | long>
+```
+
+### Enum
+
+Represents a set of allowed values:
+
+```ts
+enum MyEnum {
+ first = 0,
+ second = 1,
+ third = 2
+}
+
+property: MyEnum
+```
+
+### User defined value
+
+Represents a value that will be defined by the user and has no specific type.
+
+```ts
+property: UserDefinedValue
+```
+
+### Numbers
+
+The numeric type in TypeScript is `number`, but given that this specification target mutliple languages,
+it offers a bunch of alias that represents the type that should be used if the language supports it:
+
+```ts
+type short = number
+type byte = number
+type integer = number
+type long = number
+type float = number
+type double = number
+```
+
+### Strings
+
+The string type in TypeScript is `string`. It's ok to use it in the spec, but to offer a more developer
+friendly specification, we do offer a set of aliases based on which string we do expect, for example:
+
+```ts
+type ScrollId = string
+type ScrollIds = string
+type CategoryId = string
+type ActionIds = string
+type Field = string
+type Id = string | number
+type Ids = string | number | string[]
+type IndexName = string
+type Indices = string | string[]
+...
+```
+
+You can find the full list [here](https://github.com/elastic/elastic-client-generator/blob/update-docs/specification/specs/common.ts),
+feel free to add more if it feels appropriate!
+
+### Dates
+
+The `Date` type in TypeScript refers to the JavaScript `Date` object,
+since Elasticsearch needs a string or a numeric value, there are aliases also for date types:
+
+```ts
+type Timestamp = string
+type TimeSpan = string
+interface Date {}
+```