Arrays of objects do not render a proper schema despite body being correct #155
Comments
|
Also for reference Drafter renders the following section for videos: {
"content": {
"name": {
"literal": "videos"
},
"description": "Collection of videos",
"valueDefinition": {
"values": [],
"typeDefinition": {
"typeSpecification": {
"name": "array",
"nestedTypes": [
{
"literal": "Video",
"variable": false
}
]
},
"attributes": [
"required"
]
}
},
"sections": []
},
"class": "property"
}If it helps I've also included the full output from drafter {
"_version": "3.0",
"metadata": [],
"name": "",
"description": "",
"element": "category",
"resourceGroups": [
{
"name": "Videos",
"description": "",
"resources": [
{
"element": "resource",
"name": "Videos Collection",
"description": "",
"uriTemplate": "/videos",
"model": {},
"parameters": [],
"actions": [
{
"name": "Get All",
"description": "",
"method": "GET",
"parameters": [],
"attributes": {
"relation": "",
"uriTemplate": ""
},
"content": [],
"examples": [
{
"name": "",
"description": "",
"requests": [],
"responses": [
{
"name": "200",
"description": "",
"headers": [
{
"name": "Content-Type",
"value": "application/json; charset=utf-8"
}
],
"body": "",
"schema": "",
"content": [
{
"element": "dataStructure",
"name": null,
"typeDefinition": {
"typeSpecification": {
"name": {
"literal": "Videos",
"variable": false
},
"nestedTypes": []
},
"attributes": []
},
"sections": []
}
]
}
]
}
]
}
],
"content": []
}
]
}
],
"content": [
{
"element": "category",
"attributes": {
"name": "Videos"
},
"content": [
{
"element": "resource",
"name": "Videos Collection",
"description": "",
"uriTemplate": "/videos",
"model": {},
"parameters": [],
"actions": [
{
"name": "Get All",
"description": "",
"method": "GET",
"parameters": [],
"attributes": {
"relation": "",
"uriTemplate": ""
},
"content": [],
"examples": [
{
"name": "",
"description": "",
"requests": [],
"responses": [
{
"name": "200",
"description": "",
"headers": [
{
"name": "Content-Type",
"value": "application/json; charset=utf-8"
}
],
"body": "",
"schema": "",
"content": [
{
"element": "dataStructure",
"name": null,
"typeDefinition": {
"typeSpecification": {
"name": {
"literal": "Videos",
"variable": false
},
"nestedTypes": []
},
"attributes": []
},
"sections": []
}
]
}
]
}
]
}
],
"content": []
}
]
},
{
"element": "category",
"content": [
{
"element": "dataStructure",
"name": {
"literal": "Video",
"variable": false
},
"typeDefinition": {
"typeSpecification": {
"name": "object",
"nestedTypes": []
},
"attributes": []
},
"sections": [
{
"class": "memberType",
"content": [
{
"content": {
"name": {
"literal": "id"
},
"description": "The ID of the video",
"valueDefinition": {
"values": [
{
"literal": "72d7cd9e-1438-470a-9c9b-cbc6a696dafe",
"variable": false
}
],
"typeDefinition": {
"typeSpecification": {
"name": "string",
"nestedTypes": []
},
"attributes": [
"required"
]
}
},
"sections": []
},
"class": "property"
},
{
"content": {
"name": {
"literal": "created_at"
},
"description": "The date the video was created",
"valueDefinition": {
"values": [
{
"literal": "2015-04-20T13:34:29.863005Z",
"variable": false
}
],
"typeDefinition": {
"typeSpecification": {
"name": "string",
"nestedTypes": []
},
"attributes": [
"required"
]
}
},
"sections": []
},
"class": "property"
},
{
"content": {
"name": {
"literal": "title"
},
"description": "Title of the video",
"valueDefinition": {
"values": [
{
"literal": "sample.mkv",
"variable": false
}
],
"typeDefinition": {
"typeSpecification": {
"name": "string",
"nestedTypes": []
},
"attributes": [
"required"
]
}
},
"sections": []
},
"class": "property"
},
{
"content": {
"name": {
"literal": "size"
},
"description": "Size in bytes of the video",
"valueDefinition": {
"values": [
{
"literal": "0",
"variable": false
}
],
"typeDefinition": {
"typeSpecification": {
"name": "number",
"nestedTypes": []
},
"attributes": [
"required"
]
}
},
"sections": []
},
"class": "property"
}
]
}
]
},
{
"element": "dataStructure",
"name": {
"literal": "Videos",
"variable": false
},
"typeDefinition": {
"typeSpecification": {
"name": "object",
"nestedTypes": []
},
"attributes": []
},
"sections": [
{
"class": "memberType",
"content": [
{
"content": {
"name": {
"literal": "title"
},
"description": "Title of the collection",
"valueDefinition": {
"values": [
{
"literal": "Sports Movies",
"variable": false
}
],
"typeDefinition": {
"typeSpecification": {
"name": "string",
"nestedTypes": []
},
"attributes": [
"required"
]
}
},
"sections": []
},
"class": "property"
},
{
"content": {
"name": {
"literal": "videos"
},
"description": "Collection of videos",
"valueDefinition": {
"values": [],
"typeDefinition": {
"typeSpecification": {
"name": "array",
"nestedTypes": [
{
"literal": "Video",
"variable": false
}
]
},
"attributes": [
"required"
]
}
},
"sections": []
},
"class": "property"
}
]
}
]
}
]
}
]
} |
|
Hey @obihann this seems like an issue in the dependency of Aglio – the API Blueprint parser (and JSON Schema renderer). Please bear with as as we are working towards the final version of Attributes (MSON) implementation. |
|
@zdne Thanks for the reply, so your saying this is a bug with drafter or with your implementation of the JSON that drafter generates? I'm more than happy to help out work to a solution, as I'm using apiary to create an API for a very large product right now and this is causing a bit of a headache for us. Let me know if I can help. Thanks. |
|
Hey @obihann thanks for being so helpful! I believe this issue is in Boutique.js which is now being deprecated as we are moving towards complete C++ parser / renderer built on top of Data Structure refract tree instead of MSON AST (see explanation here Aconex/drakov#60 (comment)). We are now close to the release of Drafter which comes with rewritten JSON renderer. Next on the list is rewrite JSON Schema rendering – that is where hands are needed the most at the moment (if you are into C++). I believe that will fix the issue we were discussing here. Let me know should you have any questions! |
|
I am into C++ and would be up for helping. I've already looked a bit into the snow crash and drafter code so if you want I can pitch in, just point me to the correct issues or branch and I can take a look. |
|
Awesome! Please check https:/apiaryio/drafter/blob/shared/refract/src/Render.cc#L55 this is where the JSON is rendered from parsed MSON. The "parsed MSON" is in the form of Data Structure Refract. Prior to this "JSON rendering" the refract is expanded in Something similar is needed for the I am sure @pksunkara or @klokane will gladly provide more insight into this. |
|
@obihann I will be available to chat if you need some help. 😄 |
|
Thanks @pksunkara, later today I'm going to go through the drafter refactor code some more and then I'm sure I will have some questions. |
|
Just a poke I haven't forgotten about this. |
|
+1 |
|
Mentioning apiaryio/drafter#47 because it seems to be related. |
|
+1 |
|
@pksunkara should an issue be created for this in apiary/drafter since it is related to the rendering of JSON? |
|
@obihann Isn't this issue about rendering JSON Schema? |
|
@pksunkara I'm not 100% sure on that, the issue is that the JSON schema is not rendered for nested arrays which is very similar (if not identical) to apiaryio/drafter#117 perhaps @zdne can help me pinpoint this better, but I have a feeling it is an issue with drafter and how it expands the MSON prior to render. |
|
@obihann We are completely overhauling JSON Schema rendering to be inside C++ Drafter. So, I would treat this issue as a separate one and see if the above change solves this (which I think it would). If it doesn't then we can look into the other drafter issues and see if anything else is also a problem here. |
|
@pksunkara an example I can provide to hopefully prove this theory is if I use your MSON example from apiaryio/drafter#117 I get the following: blueprint# GET /
+ Response 200 (application/json)
+ Attributes (array[User])
# Data Structures
## User
+ username: pksunkaraagliobody[
"id: `72d7cd9e-1438-470a-9c9b-cbc6a696dafe`"
]schema{
"type": "array",
"$schema": "http://json-schema.org/draft-04/schema#"
}So we can see right now that the body is correct but the schema is missing, so if we look at what drafter generates we can see the problem is that drafter itself doesn't generate a schema. If I had just used an array that was not a nested type it would provide a schema as expected. {
"element": "category",
"meta": {
"classes": [
"api"
],
"title": ""
},
"content": [
{
"element": "category",
"meta": {
"classes": [
"resourceGroup"
],
"title": ""
},
"content": [
{
"element": "resource",
"meta": {
"title": ""
},
"attributes": {
"href": "/"
},
"content": [
{
"element": "transition",
"meta": {
"title": ""
},
"content": [
{
"element": "httpTransaction",
"content": [
{
"element": "httpRequest",
"attributes": {
"method": "GET"
},
"content": []
},
{
"element": "httpResponse",
"attributes": {
"statusCode": "200",
"headers": {
"element": "httpHeaders",
"content": [
{
"element": "member",
"content": {
"key": {
"element": "string",
"content": "Content-Type"
},
"value": {
"element": "string",
"content": "application/json"
}
}
}
]
}
},
"content": [
{
"element": "dataStructure",
"content": [
{
"element": "array"
}
]
},
{
"element": "asset",
"meta": {
"classes": "messageBody"
},
"attributes": {
"contentType": "application/json"
},
"content": "[]"
}
]
}
]
}
]
}
]
}
]
},
{
"element": "category",
"meta": {
"classes": [
"dataStructures"
]
},
"content": [
{
"element": "dataStructure",
"content": [
{
"element": "object",
"meta": {
"id": "User"
},
"content": [
{
"element": "member",
"content": {
"key": {
"element": "string",
"content": "username"
},
"value": {
"element": "string",
"content": "pksunkara"
}
}
}
]
}
]
}
]
}
] |
|
Even if apiaryio/drafter#117 is fixed, we will still have the main problem of the JSON schema not being rendered correctly because it is a bug with JSON Schema not rendering |
|
@pksunkara thanks for the reply, that sounds reasonable to me (keeping things separate and solving them individually that is). So your feeling is that the bug exists when aglio expands the JSON Thanks again! |
No, bug exists when JSON Schema is rendered. Current aglio is still using [email protected] which uses boutique.js to render JSON Schema which contains the above bug. Since we are scrapping boutique.js and are going to implement JSON Schema in C++ Drafter, please don't waste your time trying to fix this issue specifically. If you want to, you can contribute by fixing apiaryio/drafter#117 |
|
@pksunkara ahhh I was confused because of @43eccc1ba58c97950bacbebce694d74fd1f32124 which hasn't been released yet. I thought we wen't to protagonist 1.x already. I can help on apiaryio/drafter#117 but I will need a bit of assistance getting started on it, I've been looking into it and I see the differences when Feel free to pm / email me or ping me on gitter, since this is now off topic of this issue. |
|
@obihann I did switch |
|
@danielgtaylor @zdne I might have the same issue, or a related issue, however this time the body is not rendered correctly, see this example: Using aglio: FORMAT: 1A
HOST: https://test.api.com/
# Test API
Hi, welcome to the API!
# Group Projects
Wow, we are using projects!
### Retrieve single project [GET /projects/{id}]
+ Parameters
+ id: `5` (string, required)
+ Response 200 (application/json)
+ Attributes (object)
+ data (Project1_Get, required)
# Data Structures
## Project_Link (object)
+ self: `https://test.api.com/projects/5` (string, required)
## Project1_Get (object)
+ type: `projects` (string, required)
+ id: `5` (string, required)
+ attributes (object, required)
+ number: `PRO-5` (string) - A readable identifier for employees to refer to projects.
+ links (Project_Link, required)This results in the following body: {
"data": {
"attributes": {
"number": "PRO-5"
},
"id": "5",
"links": {},
"type": "projects"
}
}I don't really like the fact that my data structure order of appearance is changed as well (but that's something different) What I expect: {
"data": {
"type": "projects",
"id": "5",
"attributes": {
"number": "PRO-5"
},
"links": {
"self": "https://test.api.com/projects/5"
}
}
} |
|
@robbinjanssen that is a separate bug from this issue (but related). See my comments about it for more of an explanation. |
|
@obihann with the release of the default theme olio-1.4.0 the schema in the original issue now renders correctly. Please give it a try (see |
|
@danielgtaylor Sorry to pass (slightly) bad news but I think we have gone one step forward and one step back. I can confirm the schema is now fixed however the actual JSON body is now broken. Here is what I'm talking about: # Group Videos
## Videos Collection [/videos]
### Get All [GET]
+ Response 200 (application/json; charset=utf-8)
+ Attributes (Videos)
# Data Structures
## Video (object)
+ id: `72d7cd9e-1438-470a-9c9b-cbc6a696dafe` (string, required) - The ID of the video
+ created_at: `2015-04-20T13:34:29.863005Z` (string, required) - The date the video was created
+ title: `sample.mkv` (string, required) - Title of the video
+ size: 0 (number, required) - Size in bytes of the video
## Videos (object)
+ title: `Sports Movies` (string, required) - Title of the collection
+ videos (array[Video], required) - Collection of videos {
"title": "Sports Movies",
"videos": [
{}
]
}{
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Title of the collection"
},
"videos": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The ID of the video"
},
"created_at": {
"type": "string",
"description": "The date the video was created"
},
"title": {
"type": "string",
"description": "Title of the video"
},
"size": {
"type": "number",
"description": "Size in bytes of the video"
}
},
"required": [
"id",
"created_at",
"title",
"size"
]
},
"description": "Collection of videos"
}
},
"required": [
"title",
"videos"
],
"$schema": "http://json-schema.org/draft-04/schema#"
}My first comment the results were almost the exact opposite, a valid body with an invalid schema. Let me know if I can help in any way, and thanks for looking into this. |
|
@obihann thanks for the feedback. The JSON Schema is fixed because I wrote a JSON Schema generator that uses Refract inside of Aglio (rather than waiting for Drafter to be updated). The JSON body is broken due to Drafter regressions which are currently being fixed. Unfortunately I can't do too much about that from within Aglio. Getting those regressions fixed is a high priority, however. |
|
@obihann please install the latest (with |
|
@danielgtaylor I can confirm that the |
|
Awesome! Closing this as fixed then, please let me know if there are other issues! |
|
Hey @danielgtaylor sorry for the delay but I can confirm as well this fixed the issue I originally reported. Thanks a lot! |
|
Still having this issue on version (aglio 2.2.0 / olio 1.6.2): ## Zone (object)
+ id: `1` (number) - The unque id
+ name: `Backstage` (string, required) - The name of the Zone
+ indicator: `E` (string, required) - The unique indicator
## Profile (object)
+ id: `1` (number) - The unique id
+ name: `Crew Member` (string, required) - The name of the Profile
+ zones (array[Zone], required) - The associated zones
## GET /profiles
+ Parameters
+ event_id: `12` (number, required) - Id of the event
+ Response 200 (application/json)
+ Attributes
+ profiles (array)
+ Attributes(Profile)Generates following JSON Body {
"profiles": [
{
"id": 1,
"name": "Crew Member",
"zones": [
{}
]
}
]
} |
|
Hey, The correct syntax is: + Response 200 (application/json)
+ Attributes
+ profiles (array)
+ (Profile) |
|
@JanStevens see the comment above ^. I believe that |
|
I'm also still experiencing issues with aglio Given these Data Structures: ## User (object)
+ id: 1 (number) - The user's unique ID.
+ name: Danni (string) - The user's name.
## Users (array)
+ (User)These all work on Apiary, but not with aglio: + Response 200 (application/json)
+ Attributes (array[User], fixed)+ Response 200 (application/json)
+ Attributes (array, fixed)
- (User)+ Response 200 (application/json)
+ Attributes (Users, fixed)Without the |
|
@ppvg You need |
|
I'm also still having issue on version (aglio 2.2.0 / olio 1.6.2): FORMAT: 1A
HOST: https://api.example.com
# Data Structures
## Book (object)
+ title: api blueprint (string, required) - Title
# Group Book
## List book [GET /books_good]
+ Response 200
+ Attributes (object)
+ books (array[Book], required) - books description
## List book [GET /books_bad]
+ Response 200 (application/json)
+ Attributes (object)
+ books (array[Book], required) - books descriptionWhen specified media type (application/json) at Response Section, JSON Schema is not correct. Schema (books_good) {
"type": "object",
"properties": {
"books": {
"type": "array",
"items": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Title"
}
},
"required": [
"title"
]
},
"description": "books description"
}
},
"required": [
"books"
],
"$schema": "http://json-schema.org/draft-04/schema#"
}Schema (books_bad) {
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"books": {
"type": "array",
"description": "books description"
}
},
"required": [
"books"
]
} |
|
no news ? |
|
Hi, I can confirm this. Without
|
|
Hey, we have recently added a keyword |
Thanks, this is exactly what I need. It's now clear from documentation for |
|
|
|
+1 |
|
Thanks @pksunkara, the + Response 200 (application/json)
+ Attributes (object)
+ data (array, fixed-type)
+ (object)
+ marca: `Motorola` (string) - Marca do smartphone
+ quantidade: 8234 (number) - Quantidade de smartphones
{
"data": [
{
"marca": "Motorola",
"quantidade": 8234
}
]
}
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"marca": {
"type": "string",
"description": "Marca do smartphone"
},
"quantidade": {
"type": "number",
"description": "Quantidade de smartphones"
}
}
}
}
}
} |
Basically if I have a data structure called video, and then another structure that includes an array of that base type, the compiled JSON will be valid however the compiled schema will not include any information from the base type.
An example of what I mean is if I have the following blueprint:
I end up with the following:
JSON:
{ "title": "Sports Movies", "videos": [ { "id": "72d7cd9e-1438-470a-9c9b-cbc6a696dafe", "created_at": "2015-04-20T13:34:29.863005Z", "title": "sample.mkv", "size": 0 } ] }Schema:
{ "type": "object", "properties": { "title": { "type": "string", "description": "Title of the collection" }, "videos": { "type": "array", "description": "Collection of videos" } }, "required": [ "title", "videos" ], "$schema": "http://json-schema.org/draft-04/schema#" }The text was updated successfully, but these errors were encountered: