elastic / elastic/elasticsearch-specification

Add `@codegen_required` annotation to mark preferred location to serialize a parameter as required

Open
#1,024 5 comments 0 reactions 0 assignees View on GitHub
enhancement spec validation
Dominant language
TypeScript
Stars
158
Forks
136
Avg merge
19h 48m
Merged PRs (30d)
54

Description

In many places of the Elasticsearch API we allow serializing a parameter in multiple locations (path, query, body). The only way we can represent this within the spec is by marking all of these parameters as optional. However when generating a client there is only one place where a parameter "should" be serialized and therefore that parameter from a client perspective should be required, not optional.

I propose the annotation `@codegen_required` for this purpose. This is potentially what that would look like on the `ClearScrollRequest`:

```ts
import { RequestBase } from '@_types/Base'
import { Ids } from '@_types/common'

export interface Request extends RequestBase {
path_parts: {
scroll_id?: Ids
}
body: {
/**
* @codegen_required
*/
scroll_id?: Ids
}
}
```

which result in the following in the model (note `codegenRequired` in `body.properties.0`):

```json
{
"attachedBehaviors": [
"CommonQueryParameters"
],
"body": {
"kind": "properties",
"properties": [
{
"name": "scroll_id",
"required": false,
"codegenRequired": true,
"type": {
"kind": "instance_of",
"type": {
"name": "Ids",
"namespace": "_types"
}
}
}
]
},
"description": "Explicitly clears the search context for a scroll.",
"inherits": {
"type": {
"name": "RequestBase",
"namespace": "_types"
}
},
"kind": "request",
"name": {
"name": "Request",
"namespace": "_global.clear_scroll"
},
"path": [
{
"description": "A comma-separated list of scroll IDs to clear",
"name": "scroll_id",
"required": false,
"type": {
"kind": "instance_of",
"type": {
"name": "Ids",
"namespace": "_types"
}
}
}
],
"query": []
}
```

Contributor guide

Open the contributing guide

Research direction

Start by tracing how the TypeScript request example for ClearScrollRequest is parsed into the generated model JSON. Verify how a @codegen_required annotation would be represented as codegenRequired while the specification remains optional, and confirm that client generation treats the preferred location as required.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
backend-api-design, tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.