Skip to content

Commit

Permalink
update extension keywords; implement string formats and modifiers in …
Browse files Browse the repository at this point in the history 
…x-types-adapter; implement $descirptions in json-schema-adapter
  • Loading branch information
@tatomyr
tatomyr committed Jul 26, 2024
1 parent 2eeb10b commit 9bb8462
Show file tree
Hide file tree
Showing 15 changed files with 2,719 additions and 101 deletions.
37 changes: 14 additions & 23 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,30 +5,21 @@ Any [valid JSON](https://www.json.org/) could be validated against a **JSON X-Ty

## Reserved Keywords

| Keyword | Description | Usage |
| ------------- | ------------------------------------------------------------------------- | ---------- |
| string | String type. | key, value |
| number | Number type. | value |
| boolean | Boolean type. | value |
| `null` | The `null` value. The string "null" value doesn't have a special meaning. | value |
| undefined | Value is not set (the corresponding key is not present). | value |
| array | Array generic. | key |
| any | Any value (not validated). | value |
| $and | Refers to the intersection of an array members ([🔗](#types-combining)). | key |
| $descriptions | Object with descriptions of the fields at the same level. | key |
| $ref | Reference to another **JSON X-Type** ([🔗](#references)). | key |
| $schema | A literal JSON Schema definition ([🔗](#literal-schemas)). | key |
| Keyword | Description | Usage |
| --------- | ------------------------------------------------------------------------------------- | ---------- |
| string | String type. | key, value |
| number | Number type. | value |
| boolean | Boolean type. | value |
| `null` | The `null` value. (Note that the string "null" value doesn't have a special meaning.) | value |
| undefined | Value is not set (the corresponding key is not present). | value |
| array | Array generic. | key |
| any | Any value (not validated). | value |
| $and | Refers to the intersection of an array members ([🔗](#types-combining)). | key |
| $ref | Reference to another **JSON X-Type** ([🔗](#references)). | key |
| $schema | A literal JSON Schema definition ([🔗](#literal-schemas)). | key |

The list could be extended with other `$`-prefixed keywords.
So it's a good idea to escape any values that start with `$` using the `$literal` prefix.

## Prefixes

Prefixes are used to modify what's going after them. Prefixes and the actual values are separated by a colon.

| Prefix | Description | Usage |
| -------- | --------------------------------------------------- | ---------- |
| $literal | Escapes a literal value ([🔗](#literals-escaping)). | key, value |
So it's a good idea to escape any custom keys that start with `$` using the `$literal` prefix ([🔗](#literals-escaping)).

## Objects

Expand Down Expand Up @@ -118,7 +109,7 @@ Impossible combinations should result in the `undefined` type.
## Literals Escaping
Whenever there is a need to use a literal string value instead of a reserved keyword, it needs to be prepended with the `$literal` prefix:
Whenever there is a need to use a literal string value instead of a reserved keyword, it must be prepended with the `$literal:` prefix:
```json
{
Expand Down
58 changes: 38 additions & 20 deletions applications/__tests__/__snapshots__/e2e.test.js.snap
View file
Original file line number Diff line number Diff line change
Expand Up @@ -76,6 +76,7 @@ paths:
- required
additionalProperties:
type: boolean
patternProperties: {}
Ref:
type: number
RefObject:
Expand All @@ -97,6 +98,7 @@ paths:
- somekey
- string
additionalProperties: false
patternProperties: {}
ConditionalRef:
type: object
properties:
Expand All @@ -116,6 +118,7 @@ paths:
- somekey
- string
additionalProperties: false
patternProperties: {}
required:
- Simple
- Or
Expand All @@ -124,6 +127,7 @@ paths:
- Ref
- RefObject
additionalProperties: false
patternProperties: {}
components:
x-types:
Foo: number
Expand Down Expand Up @@ -198,6 +202,7 @@ paths:
- string
additionalProperties:
type: boolean
patternProperties: {}
description: An array of boolean records with the fixed 'string' property.
Conditional:
type: string
Expand All @@ -221,6 +226,7 @@ paths:
required:
- ReferencedAgain
additionalProperties: false
patternProperties: {}
description: A reference with nested references.
required:
- Plain
Expand All @@ -229,6 +235,7 @@ paths:
- Referenced
- NestedReferenced
additionalProperties: false
patternProperties: {}
components:
x-types:
Referenced: string
Expand Down Expand Up @@ -277,6 +284,7 @@ paths:
- az
- vidh
additionalProperties: false
patternProperties: {}
- type: object
properties:
bukh:
Expand All @@ -287,6 +295,7 @@ paths:
- bukh
- vidh
additionalProperties: false
patternProperties: {}
components: {}
"
`;
Expand Down Expand Up @@ -365,6 +374,7 @@ paths:
- WrongSchemaFormat
- Referenced
additionalProperties: false
patternProperties: {}
components:
schemas:
Foo:
Expand Down Expand Up @@ -444,6 +454,7 @@ paths:
- foo
- bar
additionalProperties: false
patternProperties: {}
application/problems+json:
x-type:
WrongAndFormat:
Expand All @@ -470,6 +481,7 @@ paths:
- Empty
- ImpossibleArraysCombination
additionalProperties: false
patternProperties: {}
components:
x-types:
CorrectAnd:
Expand Down Expand Up @@ -526,6 +538,7 @@ paths:
- AFieldWithRegularRef
- AFieldWithInlineRef
additionalProperties: false
patternProperties: {}
'201':
description: A bare ref
content:
Expand Down Expand Up @@ -599,6 +612,7 @@ paths:
required:
- AWrongRef
additionalProperties: false
patternProperties: {}
components:
x-types:
Foo: any
Expand Down Expand Up @@ -667,9 +681,11 @@ paths:
- Number
- Integer
additionalProperties: false
patternProperties: {}
required:
- Formats
additionalProperties: false
patternProperties: {}
components: {}
"
`;
Expand Down Expand Up @@ -783,10 +799,12 @@ paths:
required:
- bukh
additionalProperties: false
patternProperties: {}
required:
- Or
- ComplexOr
additionalProperties: false
patternProperties: {}
components:
x-types:
Or:
Expand Down Expand Up @@ -964,48 +982,48 @@ referenced from applications/outputs/x-openapi-with-refs.yaml:13:15 at #/paths/~
Error was generated by the no-invalid-media-type-examples rule.
[4] applications/outputs/x-openapi-with-refs.yaml:72:26 at #/paths/~1test/get/responses/202/content/application~1json/examples/Incorrect/value
[4] applications/outputs/x-openapi-with-refs.yaml:73:26 at #/paths/~1test/get/responses/202/content/application~1json/examples/Incorrect/value
Example value must conform to the schema: type must be number.
70 | value: 42
71 | Incorrect:
72 | value: false
71 | value: 42
72 | Incorrect:
73 | value: false
| ^^^^^
73 | schema:
74 | type: number
74 | schema:
75 | type: number
referenced from applications/outputs/x-openapi-with-refs.yaml:67:15 at #/paths/~1test/get/responses/202/content/application~1json
referenced from applications/outputs/x-openapi-with-refs.yaml:68:15 at #/paths/~1test/get/responses/202/content/application~1json
Error was generated by the no-invalid-media-type-examples rule.
[5] applications/outputs/x-openapi-with-refs.yaml:86:26 at #/paths/~1test/get/responses/203/content/application~1json/examples/Incorrect/value
[5] applications/outputs/x-openapi-with-refs.yaml:87:26 at #/paths/~1test/get/responses/203/content/application~1json/examples/Incorrect/value
Example value must conform to the schema: type must be array.
84 | - anything
85 | Incorrect:
86 | value: anything
85 | - anything
86 | Incorrect:
87 | value: anything
| ^^^^^^^^
87 | schema:
88 | type: array
88 | schema:
89 | type: array
referenced from applications/outputs/x-openapi-with-refs.yaml:79:15 at #/paths/~1test/get/responses/203/content/application~1json
referenced from applications/outputs/x-openapi-with-refs.yaml:80:15 at #/paths/~1test/get/responses/203/content/application~1json
Error was generated by the no-invalid-media-type-examples rule.
[6] applications/outputs/x-openapi-with-refs.yaml:103:19 at #/paths/~1test/get/responses/404/content/application~1json/x-type/AWrongRef
[6] applications/outputs/x-openapi-with-refs.yaml:104:19 at #/paths/~1test/get/responses/404/content/application~1json/x-type/AWrongRef
Can't resolve $ref: ENOENT: no such file or directory './applications/outputs/wrong-file.yaml'
101 | x-type:
102 | AWrongRef:
103 | $ref: wrong-file.yaml
102 | x-type:
103 | AWrongRef:
104 | $ref: wrong-file.yaml
| ^^^^^^^^^^^^^^^^^^^^^
104 | example:
105 | AWrongRef: Accepts anything
105 | example:
106 | AWrongRef: Accepts anything
Error was generated by the no-unresolved-refs rule.
Expand Down
34 changes: 30 additions & 4 deletions applications/__tests__/adapter.test.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,22 +6,23 @@ describe('adapter', () => {
expect(translateXTypeToSchema('string')).toEqual({type: 'string'})
})

test('translates literals', () => {
test('literals', () => {
expect(
translateXTypeToSchema({'$literal:string': '$literal:boolean'})
).toEqual({
type: 'object',
properties: {string: {type: 'string', enum: ['boolean']}},
additionalProperties: false,
patternProperties: {},
required: ['string'],
})
})

test('translates `undefined` into `never`', () => {
test('`undefined` -> `never`', () => {
expect(translateXTypeToSchema('undefined')).toEqual({not: {}})
})

test('handles OR', () => {
test('OR', () => {
expect(translateXTypeToSchema(['string', 'number'])).toEqual({
anyOf: [{type: 'string'}, {type: 'number'}],
})
Expand Down Expand Up @@ -49,13 +50,38 @@ describe('adapter', () => {
Conditional: {type: 'string'},
},
additionalProperties: false,
patternProperties: {},
required: ['Required'],
})
})

test('handles literal $schema', () => {
test('literal $schema', () => {
expect(translateXTypeToSchema({$schema: {type: 'string'}})).toEqual({
type: 'string',
})
})

test('string formats and modifiers', () => {
expect(translateXTypeToSchema('string::date-time')).toEqual({
type: 'string',
format: 'date-time',
})
expect(
translateXTypeToSchema({
'string::pattern(some pattern)': 'string::min(10)::max(100)',
})
).toEqual({
type: 'object',
patternProperties: {
'some pattern': {
type: 'string',
maxLength: 100,
minLength: 10,
},
},
properties: {},
additionalProperties: false,
required: [],
})
})
})
9 changes: 8 additions & 1 deletion applications/__tests__/e2e.test.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -107,10 +107,17 @@ describe('bundle', () => {

test('openapi that contains literal $schema', () => {
const {stdout} = runCommand(
'redocly bundle applications/resources/openapi-literal-schema.yaml --config=applications/x-redocly.yaml'
'redocly bundle applications/resources/openapi-literal-schema.yaml --config=applications/x-redocly.yaml'
)
expect(stdout).toMatchSnapshot()
})

test('generate x-types from JSON Schemas', () => {
const {stdout} = runCommand(
'redocly bundle applications/resources/pets.yaml --config=applications/generate-x-types-redocly.yaml'
)
expect(stdout).toMatchFileSnapshot('pets-to-x-types.yaml')
})
})

describe('lint', () => {
Expand Down
Loading

0 comments on commit 9bb8462

Please sign in to comment.