Allow OpenAPI Schema object
- Dominant language
- JavaScript
- Stars
- 724
- Forks
- 150
- Avg merge
- 18h 22m
- Merged PRs (30d)
- 4
Description
### Expected Behaviour
When defining a schema object (which is an extended subset of the JSON Schema Specification) in the context of a OpenAPI document, a few keywords might have a different meaning than in the standard JSON Schema specification (details [here](https://swagger.io/specification/#fixed-fields-20)). I would like to have an option to signal that my schema actually follows the OpenAPI definition at least for keywords such as `readOnly` and `writeOnly`. Also, it would be nice to have additional keywords such as `nullable` and `externalDocs` be taken into account while rendering the Markdown file.
### Actual Behaviour
Keywords such as `readOnly` and `writeOnly` can only follow the definition specified in the [JSON Schema draft 2019-09](https://json-schema.org/draft/2019-09/json-schema-validation.html#rfc.section.9.4). If a definition would look like this:
```json
{
"$schema": "https://json-schema.org/draft/2019-09/schema",
"$id": "https://json-schema.org/draft/2019-09/output/schema",
"description": "A sample schema",
"title": "Sample",
"properties": {
"Id": {
"type": "string",
"readOnly": true
}
}
}
```
It would give the following output file:

Even though, for this schema `readOnly` means:
> it MAY be sent as part of a response but SHOULD NOT be sent as part of the request.
Therefore, the property being marked as Optional (as well as the text in the Access Restrictions section) gives the wrong impression that the API actually allows it to be passed by the user.
### Reproduce Scenario
#### Steps to Reproduce
#### Platform and Version
MacOS
jsonschema2md v6.1.0
#### Sample Code that illustrates the problem
#### Logs taken while reproducing problem
Contributor guide
Research direction
Start by tracing how jsonschema2md currently interprets readOnly and writeOnly when rendering the sample schema, then compare that behavior with the linked OpenAPI Schema Object rules. Define the option and rendering behavior for OpenAPI keywords including nullable and externalDocs, and verify that the generated Markdown reflects the requested access restrictions.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100