The following schema doesn't pass the validation with jsonschema
$defs:
names:
- n1
- n2
- n3
properties:
name:
enum:
$ref: "#/$defs/names"
With a minimal fragment such as name: "n1", jsonschema will complain jsonschema.exceptions.SchemaError: ['n1', 'n2', 'n3'] is not of type 'object', 'boolean'.
So can I put an array in a schema's $defs? I don't see this limitation in the tutorial on json-schema.org. If not, how can I reuse an array in a schema?
First, the enum property expects a a list of values not a schema (via the $ref keyword). Second, the schemas in $defs (in your example names) have to be a schema - directly setting a list indeed doesn't work.
To make your example work, you have to use the enum keyword as part of the $defs schema like this:
"$defs":
names:
enum:
- n1
- n2
- n2
properties:
name:
"$ref": "#/$defs/names"
This allows you to validate as expected: https://www.jsonschemavalidator.net/s/RGx6COQf
Related
I have a request body for an API specification in Swagger V2.0, which looks like follows.
"/uri/path":
...
parameters:
- in: body
...
schema:
$ref: '#/definitions/StatusObject'
definitions:
StatusObject:
status:
$ref: '#/definitions/StatusEnum'
StatusEnum:
type: string
enum: ['ALPHA', 'BRAVO', 'UNKNOWN']
Now, I want StatusObject.status to have the value UNKNOWN by default, if it is not set from the client end. I tried to achieve this as follows, with no luck.
"/uri/path":
...
parameters:
- in: body
...
schema:
$ref: '#/definitions/StatusObject'
definitions:
StatusObject:
status:
$ref: '#/definitions/StatusEnum'
default: 'UNKNOWN'
StatusEnum:
type: string
enum: ['ALPHA', 'BRAVO', 'UNKNOWN']
I also have tried with '#/definitions/StatusEnum.UNKNOWN' which again didn't work. Combed through the documentation as well but couldn't find anything further. What am I missing?
Response to marked duplicate
What I am trying to achieve is to set a default value for this property status. This works when the enum is defined in line as follows.
"/uri/path":
...
parameters:
- in: body
...
schema:
$ref: '#/definitions/StatusObject'
definitions:
StatusObject:
status:
type: string
enum:
- 'ALPHA'
- 'BRAVO'
- 'UNKNOWN'
default: 'UNKNOWN'
But, this won't work for me, as I'd like to reuse the enum, which otherwise I'll have to repeat at multiple places.
Since this is just a workaround and I am not sure if I can confirm if this is an answer, I won't mark this as accepted answer. That way, I think it will be still open for someone who figured out the right way, or a better way to achieve the expectation.
Apparently, the problem is with $ref. It's already known that the siblings of $ref are ignored in OpenAPI V2.0. So, enforcing any further constraints once you use $ref won't be possible.
For my specific use case, since I want to reuse my enum definition, I used YAML Anchors as defined in V2.0 docs. Even though the enum definition is repeated in each POJO it's not that much of a headache to manage, at least for the time being. The implementation I came up is as follows.
"/uri/path":
...
parameters:
- in: body
...
schema:
$ref: '#/definitions/StatusObject'
definitions:
StatusObject:
status:
enum: *STATUS_ENUM # Referencing the anchor
default: 'UNKNOWN'
StatusEnum:
type: string
enum: &STATUS_ENUM # This is the anchor
- 'ALPHA'
- 'BRAVO'
- 'UNKNOWN'
It must also be noted that, the enum values in this case cannot be defined using array syntax (i.e. ['ALPHA', 'BRAVO', 'UNKNOWN']) as it'll break the YAML syntax rules when you try to use YAML anchors alongside that.
I'm trying to achieve an OpenAPI definition where I define a shared, complete list of allowed values as an enum and then use subgroups of the values in different places to show which values are allowed in each case.
Using the example from the enum spec on Swagger.io, if I have a definition like this:
paths:
/products:
get:
parameters:
- in: query
name: color
required: true
schema:
$ref: '#/components/schemas/Color'
responses:
'200':
description: OK
components:
schemas:
Color:
type: string
enum:
- black
- white
- red
- green
- blue
then is it possible to define e.g. two different paths that take a color as a parameter, but one of them only accepts black or white whereas the other accepts all colors?
There's no good way to reuse a part of an enum. The best way is to define separate enums.
A possible workaround is to use oneOf to "combine" partial enums into the full enum as suggested here. However, oneOf enum schemas probably won't work as enums in Swagger UI and code generators.
components:
schemas:
BlackOrWhite:
type: string
enum:
- black
- white
Color:
oneOf:
- $ref: '#/components/schemas/BlackOrWhite'
- type: string
enum:
- red
- green
- blue
Tricks with YAML &anchors and merge keys << will NOT work because YAML only supports merge keys in mappings (objects) but not in sequences (arrays).
# This will NOT work in YAML
components:
schemas:
BlackOrWhite:
type: string
enum: &BLACK_WHITE
- black
- white
Color:
type: string
enum:
<< : *BLACK_WHITE
- red
- green
- blue
I am using RAML 0.8 and I am defining a query string parameter.
the value for the querystring should be a comma separated list of predefined values
So I have used enum to define the list of acceptable values to use
sort:
description: Comma separated list of stock item properties to sort on.
enum: ['status', 'orderType', 'stockType', 'model', orderNumber']
example: 'orderType,status'
However with the example, I am getting this warning
value should be one of 'status', 'orderType', 'stockType', 'model', 'orderNumber'
I would prefer if possible to get rid of this warning for the example. With RAML 0.8 is this even possible, or should I just ignore it as its only a warning and not an error
The warning is valid. An enum type will only expect one of the possible value. If you need to send an array of those values like: ?sort=status,orderType Then you will need to use a pattern. The example below uses regex to allow a comma seperate list of values. And the specific enum values that can be used are in the pattern.
#%RAML 0.8
title: enum-list
version: v1
protocols: [ HTTP ]
mediaType: application/json
traits:
sortable:
queryParameters:
sort?:
type: string
pattern: ^(\s?[<<fieldset>>,]+\s?,)*(\s?[<<fieldset>>,]+)$
example: 'status,orderType'
/api:
displayName: api
get:
is: [ sortable: { fieldset: status|orderType|stockType|model|orderNumber } ]
I am writing an OpenAPI (Swagger) definition where a query parameter can take none, or N values, like this:
/path?sort=field1,field2
How can I write this in OpenAPI YAML?
I tried the following, but it does not produce the expected result:
- name: sort
in: query
schema:
type: string
enum: [field1,field2,field3]
allowEmptyValue: true
required: false
description: Sort the results by attributes. (See http://jsonapi.org/format/1.1/#fetching-sorting)
A query parameter containing a comma-separated list of values is defined as an array. If the values are predefined, then it's an array of enum.
By default, an array may have any number of items, which matches your "none or more" requirement. If needed, you can restrict the number of items using minItems and maxItems, and optionally enforce uniqueItems: true.
OpenAPI 2.0
The parameter definition would look as follows. collectionFormat: csv indicates that the values are comma-separated, but this is the default format so it can be omitted.
parameters:
- name: sort
in: query
type: array # <-----
items:
type: string
enum: [field1, field2, field3]
collectionFormat: csv # <-----
required: false
description: Sort the results by attributes. (See http://jsonapi.org/format/1.1/#fetching-sorting)
OpenAPI 3.x
collectionFormat: csv from OpenAPI 2.0 has been replaced with style: form + explode: false. style: form is the default style for query parameters, so it can be omitted.
parameters:
- name: sort
in: query
schema:
type: array # <-----
items:
type: string
enum: [field1, field2, field3]
required: false
description: Sort the results by attributes. (See http://jsonapi.org/format/1.1/#fetching-sorting)
explode: false # <-----
I think there's no need for allowEmptyValue, because an empty array will be effectively an empty value in this scenario. Moreover, allowEmptyValue is not recommended for use since OpenAPI 3.0.2 "as it will be removed in a future version."
I am using the raml2html tool to generate html documentation for my ReST apis.
I have defined all my types in a raml file memberTypes.raml that I include in the main service.raml.
Following is a sample from the service.raml file.
#%RAML 1.0
title: update member object
uses:
memberTypes: /memberTypes.raml
types:
Member:
properties:
termsAndConditions:
type: memberTypes.TermsAndConditions[]
description: The terms and conditions that the member has accepted.
required: false
person:
type: memberTypes.Person
description: The personal details of the member.
required: true
And following is a sample for the 2 properties above in memberTypes.raml
Person:
properties:
personName:
type: NameType
description: The name of the member.
required: true
dateOfBirth:
type: DateOfBirth
required: true
TermsAndConditions:
properties:
version:
type: string
description: The version of the terms and conditions.
acceptedDate:
type: date-only
description: The date on which the corresponding terms and conditions were accepted. Format is YYYY-MM-DD, ISO-8601 Calendar date format.
Now, below is the what I get in the html
The array is shown as array of memberTypes.TermsAndConditions. The questions is how do i get rid of the memberTypes? i simply want the type to be array of TermsAndConditions.
How do I achieve this? is there a command line option to raml2html tool that will do the trick?
I don't think there is command line option to do that, since the template / theme of raml2html defines how things are shown in HTML. You can edit the default theme. If I recall correctly that is defined in item.nunjucks file.
The usual use case for that is "array of objects" or "array of strings" but there is also definitions how to show non standard type types.