We have following json response for /papers/15
{
"data": [
{
"id": 1,
"title": "foo"
},
{
"id": 2,
"title": "bar"
}
],
"meta": {
"total": 15
}
}
Does anyone know how to describe it swagger yaml file?
Ok, I just figured out how to do this, in case somebody will need id.
Beside dedicated model definitions section ("definitions") it is possible to do inline model descriptions. Code above will looks like:
responses:
"200":
description: Matched Objects
schema:
type: object
properties:
data:
type: object
properties:
authors:
type: array
items:
$ref: "#/definitions/object_with_id_and_title"
Related
i was building a integration with the facebook ads audience API, and according the documentation the request must be created like this:
POST - https://graph.facebook.com/v15.0/<MY_CUSTOM_AUDIENCE_ID>/users?access_token=<MY_ACCESS_TOKEN>
{
"session":{
"session_id":1,
"batch_seq":1,
"last_batch_flag":true,
"estimated_num_total":1
},
"payload":{
"schema":[
"FN"
],
"data":
[
"8b1ebea129cee0d2ca86be6706cd2dfcf79aaaea259fd0c311bdbf2a192be148"
]
}
}
Using the previus example a received a error 400:
{
"error": {
"message": "(#100) Data is missing or does not match schema",
"type": "OAuthException",
"code": 100,
"fbtrace_id": "AqrLd9uIw0D4BBFtHF33bdU"
}
}
For do this i used this documentation https://developers.facebook.com/docs/marketing-api/audiences/guides/custom-audiences#hash
Anyone has use this before?
Your schema field type is array but array use form multi-key qualification.
Change it to string: schema: 'FN'
In docs you can see all formats.
This payload with multi keys work for me:
{
"session": {
"session_id": 123,
"batch_seq": 1,
"last_batch_flag": true
},
"payload": {
"schema": [
"EMAIL",
"PHONE",
"FN"
],
"data": [
["EMAIL_HASH", "PHONE_HASH", "FN_HASH"]
]
}
}
I want to validate objects like this
{
type: "user",
data: {id: 1},
}
and
{
type: "account",
data: {uuid: "xxxx"},
}
I thought I can write schema like this
{
type: "object",
properties: {
type: {enum: ["user", "account"]},
data: {
"if": {properties: {type: {const: "user"}}},
"then": {
type: "object",
properties: {
id: {type: "number"}
}
},
"else": {
type: "object",
properties: {
uuid: {type: "string"}
}
},
}
}
}
but it looks like I can't refer to root type field from context of data field. So I have two questions. Can I use if deeper than root? If I can then how to refer to parent or root object from nested object? I'm using node ajv for validation.
You're correct, you cannot apply validation to a different part of your data than where your subschems is being applied. Let me explain a little.
The first thing that happens when processing a JSON Schema is the Schema as a whole is "applied" to the instance as a whole.
properties is an applicator keyword, in that it doesn't assert any validation rules by itself. The VALUES of a properties object are subschemas (which are Schemas in their own right) which are APPLIED to the instance location value when the associated KEY matches.
To give you an exanple, in your Schema, the subschema at properties > type is applied to instance location type, which means the VALUE of the object key type. If type didn't exist in your data, the subschema in your Schema wouldn't do anything (it wouldn't be applied anywhere).
This is broadly the processing model of a Schema against an instance. Hopefully this explains why you can't work in the way you're expecting. However it's still possible to achive what you want.
then and else are conditional applicator keywords, and so need to be applied following the same model.
What you need to do is use if, then, else at the top level, but have deep / nested application of the validation you want to do.
Here's a demo with a new Schema and instance
https://jsonschema.dev/s/sejHF
{
"$schema": "http://json-schema.org/draft-07/schema",
"type": "object",
"properties": {
"type": {
"enum": [
"user",
"account"
]
},
"data": {}
},
"if": {
"properties": {
"type": {
"const": "user"
}
}
},
"then": {
"type": "object",
"properties": {
"data": {
"properties": {
"id": {
"type": "number"
}
}
}
}
},
"else": {
"type": "object",
"properties": {
"data": {
"properties": {
"uuid": {
"type": "string"
}
}
}
}
}
}
If you also want to make sure that id is present when type is user, then you also need to add required: ['id'] in the then subschema. (You'll need to do similar in the else clause if you want to check for uuid too.
So I'm extracting a JSON schema out of my RAML spec to validate output in GET methods and also the input in the POST method.
Every entity of this type has a "required" ID property - at least it's required when listing those entities in a 'get item' or 'get collection'-request.
But when validating the received post data to create such an entity the ID is obviously not required (and discarded if it's send anyway).
What's the best DRY way to have this ID property required for GET requests, but not required, or even better not existing in the type for POST requests?
TL;DR: start reading below ;)
Example to make it easier to understand:
For GET requests the type should be like:
properties:
id:
something1:
something2?:
For POST requests the type should be like:
properties:
something1:
something2?:
without having to define both separately, but also without using inheritance to have to create two types for every resource.
Ideally I would solve it that way, but that doesn't seem to work:
get:
description: Retrieve a list of <<resourcePathName|!uppercamelcase>>.
responses:
200:
body:
application/json:
type: [ entity_id_object, <<resourcePathName|!singularize|!uppercamelcase>> ][]
example: <<exampleCollection>>
and entity_id_object ist just:
entity_id_object:
properties:
id:
I think it's because the <<resourcePathName|!singularize|!uppercamelcase>> is not working in this combination.
I can't think of a way of doing it without two types yet. But this example at least only makes you only pass one type and automatically appends 'NoId' to the type name for POST requests.
#%RAML 1.0
title: My API
version: v1
mediaType: application/json
types:
ResponseNoId:
properties:
something1:
something2?:
ResponseId:
properties:
id:
something1:
something2?:
Response:
ResponseNoId|ResponseId
resourceTypes:
collection:
usage: Use this resourceType to represent a collection of items
description: A collection of <<resourcePathName|!uppercamelcase>>
get:
description: |
Get all <<resourcePathName|!uppercamelcase>>,
optionally filtered
is: [ hasResponseCollection: { typeName: <<typeName>> } ]
post:
description: |
Create a new <<resourcePathName|!uppercamelcase|!singularize>>
is: [ hasRequestItem: { typeName: <<typeName>> } ]
item:
usage: Use this resourceType to represent any single item
description: A single <<typeName>>
get:
description: Get a <<typeName>>
is: [ hasResponseItem: { typeName: <<typeName>> } ]
traits:
hasRequestItem:
body:
application/json:
type: <<typeName>>
hasResponseItem:
responses:
200:
body:
application/json:
type: <<typeName>>
hasResponseCollection:
responses:
200:
body:
application/json:
type: <<typeName>>[]
/myResource:
type: { collection: { typeName: Response } }
get:
/{id}:
type: { item: { typeName: Response } }
post:
body:
application/json:
You can mark the id field as readOnly to make the intent clear, although it won't have an effect on the way that the data is validated.
To affect validation, you can create a "Read" type and a "Write" type, where the "Read" type has the extra required id property.
{
"$schema": "http://json-schema.org/draft-07/schema#",
"definitions": {
"MyWriteEntity": {
"type": "object",
"properties": {
"something1": { "type": "string"},
"something2": { "type": "string"}
},
"required": "something1"
},
"MyReadEntity": {
"allOf": [
{ "$ref": "#/definitions/MyWriteEntity" },
{
"id": { "type": "string", "readOnly": true},
"required": ["id"]
}
]
}
}
}
The best way to do this is to create a RAML Library fragment, lets say "foo.raml" for a data model "foo" for resources /foos and /foos/{fooID}.
In the library, create three types:
fooInput:
properties:
something1:
something2:
fooOutput:
type: fooInput
properties:
id: integer
fooPatch:
properties:
something1?:
something2?:
Now in ONE file you have 3 data types. Use the Input version with PUT/POST, use the Output version for GET and use the Patch version for PATCH endpoints. This is even better when paired with resourceTypes.
I am designing an API operation and am going to use the expand standard.
Here is an example of my first API response....
{
"id": "000000001",
"createdDateTime": "2017-12-19T16:39:57-08:00",
"lastUpdatedDateTime": "2017-12-19T16:45:57-08:00",
"holdingDetails": {
"status": "SUCCESSFUL",
"instrument": "/api/v1//instruments/123456789"
}
}
Here is an example of my second API response....
{
"id": "000000001",
"createdDateTime": "2017-12-19T16:39:57-08:00",
"lastUpdatedDateTime": "2017-12-19T16:45:57-08:00",
"holdingDetails": {
"status": "SUCCESSFUL",
"instrument": {
"instrumentId":"123456789",
"nickName":"My NickName",
"type": "BLAH"
}
}
}
In my raml I would like to define a type for this i'm not sure what is would look like...
#%RAML 1.0 DataType
type: object
properties:
id?:
type: string
createdDateTime?:
type: datetime
lastUpdatedDateTime?:
type: datetime
What goes next? i.e. How do I say it can be either listed below
instrument?:
type: string
description: A link to the instrument
instrument?:
type: !include instrument.raml
You can use an union
e.g.:
instrument?:
type: string | InstrumentType
and of course also define InstrumentType, for example with something like this:
InstrumentType:
properties:
instrumentId:
nickName:
type:
I have been given the attached RAML file to use in Mule but I am having problems working out how to clean up the errors in the file and not even sure this raml file conforms to standards. The errors I am getting are for missing {} and another is missing block entry when I remove the version. Can't figure out how to resolve them.
Below is a cut down version of the RAML:
#%RAML 0.8
---
title: Databox
version: v1
protocols: [HTTPS]
baseUri: https://databox/v1/{version}
mediaType: application/json
traits:
- http-data: !include http-data.raml
resourceTypes: !include types.raml
documentation:
- title: Home
content: |
Databox 1st draft
/stores:
type:
store:
description: Stores
dataSchema: !include stores.json
The traits (http-data.raml):
responses:
200:
description: |
Success
The resourceType (types.raml):
- store:
head:
description: Retrieve data for <<description>>.
is: [ http-data ]
get:
description: Retrieve data for <<description>>.
responses:
200:
body:
application/json:
schema: |
{
"type": "object",
"properties": {
"meta": {
"title": "Data",
"type": "object",
"properties": {
"createdOn": {
"type": "string",
"format": "date-time"
}
},
"required": [
"createdOn"
]
},
"data": {
"type": "array",
"items": <<dataSchema>>
}
},
"required": [
"data"
]
}
description: |
Success. Returns a JSON object containing all <<description>>.
The schema (stores.json):
{
"id": "http://localhost:8000/stores.json#",
"$schema": "http://json-schema.org/draft-04/schema",
"title": "Databox Store Schema",
"type": "object",
"properties": {
"storeId": {
"type": "string"
},
"storeDescription": {
"type": "string"
},
},
"required": [
"storeId"
],
"additionalProperties": false
}
Thanks
RAML is valid except for that <<dataSchema>> parameter used in the json schema, not sure if that's a valid use of parameters.
I would start by replacing that <<dataSchema>> for the json in stores.json and try again.
Let me know if that works or what errors you get.
UPDATE:
Mulesoft's anypoint portal validates your RAML with just that single change, you can see it here