adobe / adobe/jsonschema2md

Allow OpenAPI Schema object

Open
#324 1 comment 0 reactions 0 assignees View on GitHub
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:

Screenshot 2021-07-16 at 00 09 19

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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.