hashicorp / hashicorp/terraform-plugin-codegen-openapi
Consider how to handle valid `allOf` constraints - schema composition
- Dominant language
- Go
- Stars
- 91
- Forks
- 20
- Avg merge
- 2d 13h
- Merged PRs (30d)
- 1
Description
References:
- OpenAPI 3.1 is JSON schema compatible: https://json-schema.org/understanding-json-schema/reference/combining.html
- OpenAPI 3.0: https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/
## Background
Usage of the `allOf` constraint describes a JSON schema that must match all subschemas defined, which I've seen used as a way to compose multiple schemas or share a common base model.
Note from JSON schema docs:
> _Instances must **independently** be valid against “all of” the schemas in the allOf._
The [PetStore Expanded 3.0 spec](https://github.com/OAI/OpenAPI-Specification/blob/9dff244e5708fbe16e768738f4f17cf3fddf4066/examples/v3.0/petstore-expanded.yaml#L125-L146) has an example of this:
```yaml
# .. rest of OAS
components:
schemas:
Pet:
allOf:
- $ref: '#/components/schemas/NewPet'
- type: object
required:
- id
properties:
id:
type: integer
format: int64
NewPet:
type: object
required:
- name
properties:
name:
type: string
tag:
type: string
```
## Proposal
I'm wondering for something like above if we can consider the schema as both of them combined, for the example above:
### Original
```yaml
Pet:
allOf:
- $ref: "#/components/schemas/NewPet"
- type: object
required:
- id
properties:
id:
type: integer
format: int64
NewPet:
type: object
required:
- name
properties:
name:
type: string
tag:
type: string
```
### Combined
```yaml
Pet:
type: object
required:
- id
- name
properties:
id:
type: integer
format: int64
name:
type: string
tag:
type: string
```
### Possible IR output
```json
{
"name": "pet",
"schema": {
"attributes": [
{
"name": "id",
"int64": {
"computed_optional_required": "required"
}
},
{
"name": "name",
"string": {
"computed_optional_required": "required"
}
},
{
"name": "tag",
"string": {
"computed_optional_required": "computed_optional"
}
}
]
}
}
```
## Notes
- We'd need to combine the schemas together somehow, duplicate properties with mismatched types/nested children would need to be considered
- There are potential [invalid `allOf` use-cases ](https://json-schema.org/understanding-json-schema/reference/combining.html#illogical-schemas) we'd need to determine how to handle
- The `allOf` keyword can appear anywhere, not just in the root of the schema like shown above 😄 , will need to consider that
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.