|
|
Post by cprabhudesai on Jun 13, 2019 14:42:45 GMT
Hello, I was reading through the Fabric schema where I ran into trouble. I visited the online Schema Index, and navigated to the Fabric schema (YAML) under "Primary schema files" and opened the latest schema definition for Fabric.v1_0_5. Going over the schema I noticed the "FabricType" property had the following definition: ...
FabricType:
$ref: http://redfish.dmtf.org/schemas/v1/odata-v4.yaml#/components/schemas/idRef
description: The protocol being sent over this fabric.
nullable: true
readOnly: true
x-longDescription: The value of this property shall contain the type of
fabric being represented by this simple fabric.
...This provided very little information, so I opened the Resource and Schema Guide, where I found out the various FabricType enums. To double-check, I opened the Fabric schema (JSON), and found out that the "FabricType" property shows the following: ...
"FabricType": {
"anyOf": [
{
"$ref": "http://redfish.dmtf.org/schemas/v1/Protocol.json#/definitions/Protocol"
},
{
"type": "null"
}
],
"description": "The protocol being sent over this fabric.",
"longDescription": "The value of this property shall contain the type of fabric being represented by this simple fabric.",
"readonly": true
},
...Notice how the $ref's are different in both schema files. This left me confused, as both normative documents had different references for that same property. The resource guide had listed the enums for it, but that being just an informative document, I wasn't sure if it was recommended to refer it. So my question is: Should all schema files (XML, JSON, YAML) provide the exact same information? Is there a discrepancy in them ?How they represent the information might vary as they follow different spec, CSDL vs OpenAPI. (Please correct me if this is inaccurate!) Any help is appreciated. Questions/comments/concerns are welcome too Thanks, PS: I think this board calls for a rename to list the third schema being supported, CSDL and json-schema have a third counterpart now  |
|
|
|
Post by mraineri on Jun 13, 2019 15:41:40 GMT
Within the conversion of JSON Schema to OpenAPI, there's a simplification made to reduce the OpenAPI documentation produced; when a link is found, it will replace the link with the "idRef" property. However, there are cases where we have external enum definitions; there is a bug in how this is being handled with the conversion tool and it treats this as a link and not an enum. This was raised on the tools repo as an issue here: github.com/DMTF/Redfish-Tools/issues/218 |
|
|
|
Post by jautor on Jun 13, 2019 15:47:43 GMT
So my question is: Should all schema files (XML, JSON, YAML) provide the exact same information? Is there a discrepancy in them ?How they represent the information might vary as they follow different spec, CSDL vs OpenAPI. (Please correct me if this is inaccurate!) Yes, they should provide the same information (meaning no conflicting information) although some of the languages may provide more detail because of the limits of the schema definition languages themselves. The specification says that they are all equivalent, and any "bugs" in translation should be treated as such. Good point! I'll rename the sub-forun... Jeff |
|
|
|
Post by cprabhudesai on Jun 13, 2019 16:17:13 GMT
Hello mraineri and jautor , Thank you for your response! I also noticed for OpenAPI, the individual schema files for a Resource/Collection/Service don't list the URIs (or "paths" as they call it in OpenAPI spec), but openapi.yaml contains this information collectively for all Resources/Collections/Services. Is this by design, or also a limitation of the conversion tool? As I recall going through the OpenAPI spec, it mentions that there are a few fixed fields required in every OpenAPI document. Would the existing YAML schema files for individual resources potentially NOT comply to the OpenAPI spec in that case? Lastly, I do understand it's a lot of work to keep up and maintain these specifications, and I appreciate the teams effort, but until the pending issues are addressed, which schema type would you recommend to refer for it's completeness ? Best, |
|
|
|
Post by mraineri on Jun 13, 2019 17:27:51 GMT
The individual files for the resources (like Fabric.v1_0_5.yaml) are not meant to be used as an entire OpenAPI spec and will definitely not validate as one. These files are just individual sets of definitions. The expectation is everything would be processed from openapi.yaml file, which references the definitions within the smaller files. So, if you're building code, documentation, or something else, you will need to use the openapi.yaml file.
Beyond the migration of the URIs from the resource files to openapi.yaml, as well as the discrepancy with some of the properties that use common enum definitions, have you noticed anything else that is missing? As Jeff said, the intent is to have 100% coverage between the formats, and anything different/missing is a bug that will need to be fixed. We're not aware of other issues with the coverage between the different formats.
|
|
|
|
Post by cprabhudesai on Jun 13, 2019 18:07:05 GMT
Hello mraineri , Nothing that I can recall off the top of my head, but I do remember that when I ran the openapi.yaml file through the Swagger tool for server stub generation, the tool error'ed out (though I'm not really sure if it was a bug in the tool or a bug in the schema), this was with 2018.3 release (Redfish Version 1.6.1) I increased the verbosity to see what was failing, and noticed that there was a circular reference in the ComputerSystem Resource or the ComputerSystemCollection Resource (can't remember which one for certain). There was a lot of ambiguity in what might have been broken, so I didn't report it. I spent some time researching for relevant content/issues, both here and GitHub, but didn't find any concerns. My hunch at that time was - this might be because of the absolute links in the openapi.yaml file for most Resources/Services/Collections. Unlike the individual schemas that have the schema definitions in the same file under components -> schemas, this openapi.yaml file referenced the online hosted-versions of the schemas, and there might be some incorrect cascading links that broke tools while it crawled each individual link. (I might be completely wrong about this though). In my naivete, I also did not understand how multiple references to the same schema were handled. I tried to follow the links but that seemed to be the wrong approach. I lost track of the issue, as I was running on a schedule, and was re-assigned to work on something else temporarily. If I encounter something in the future, I'll make a note of it and create an issue on GitHub - I'll also be glad to help the community come up with a solution for it! Best, |
|
|
|
Post by mraineri on Jun 13, 2019 18:13:32 GMT
Perfect; I'd love to hear about those issues as you find them! I know some tools I've used have had mixed results for me. The only thing that seemed to consistently work was Swagger Editor for producing a human readable document of the API. From what I could tell at the time, there was lack of support of following external references in the OpenAPI community tools (especially with the code generators). There was one user who had a lot of progress though more recently and it's discussed in this thread: github.com/DMTF/Redfish-Tools/issues/179 |
|
|
|
Post by cprabhudesai on Jun 13, 2019 18:22:30 GMT
mraineri , Most definitely, and thanks for providing the links, it dawns on me that I should keep an eye on the Redfish GitHub repo as there's a lot of activity going on there. What might be worth while on a longer term (I may be too ambitious here), is that Redfish community could fork-off the codegen and maintain that (considering licenses and policies). I believe Redfish Spec has some extensions over the default Objects/properties of OpenAPI. This fork would allow a better control of addition properties added by the task force e.g. any x-Property such as x-Description/x-longDescription.Also, I edited my previous response to include some additional information, if you have a few spare moments, please do go through it again. Best, Chinmay
|
|
