Context and Problem Statement
OpenAPI supports either JSON or YAML. We must consider if we wish to standardize on one or the other or permit both in APIs (consumer and platform).
Decision Drivers
- Ease of writing documentation by humans.
- Ease of reading documentation, in plain text format, by humans.
- Ease of processing documentation by programs.
- Standardization of format.
- Use of format to avoid duplication in documentation.
Decision Outcome
Chosen option: Use YAML as the standard for API docs.
Considered Options
- Use JSON exclusively.
- Use YAML exclusively.
- Allow mixing YAML and JSON.
Pros and Cons of the Options
Continue to use JSON
Pros
- JSON is a format which most systems/programs can easily process.
- Requirements for enforcing a style standardization in JSON are lower, as there are less ways to express the same information.
Cons
- JSON can be hard for humans to write.
- JSON can be hard for humans to read.
- Format tends to increase duplication of documentation components, e.g. models, responses, etc.
- Duplication for documentation components can lead to some components not getting updated properly.
Switch to using YAML
Pros
- YAML can be easier for humans to write.
- YAML can be easier for humans to read.
- Format has built in primitives for reducing duplication of documentation.
- Can be processed by most programs easily.
- Can be compiled into various formats as needed, including JSON.
Cons
- Not all programs can process YAML directly as easily as JSON.
- The increased expressiveness of YAML allows for stylistic differences in the documentation to develop. This could be somewhat mitigated by using a linter to enforce a standard.
Allow mixing YAML and JSON
Pros
Cons
- Makes standardization basically impossible.
- If a program needs to process the documentation, it would need to discriminate on each file and then selectively choose a processor based on the input type.
- Doesn’t really solve documentation duplication.