IBM
OAUTH_SECURITY_SCHEME UNRESOLVABLE_SCHEMA UNKNOWN_TARGET_TYPE OBJECT_MISSING_PROPERTIES
I had a schema that was using oneOf and I saw that it didn't generate anything I tried to change the oneOf with allOf and I saw the type union in the translation
I also noticed some warning that required fillEmptyResponses and now by running
openapi-to-graphql OpenApiFixedToSupportGraphQLTranslation.json --save corrected.graphql --fillEmptyResponses
I got this warning
{
"warnings": [
{
"type": "OAUTH_SECURITY_SCHEME",
"message": "OAuth security scheme found in OAS 'API'. OAuth support is provided using the 'tokenJSONpath' option",
"mitigation": "Ignore security scheme"
},
{
"type": "UNRESOLVABLE_SCHEMA",
"message": "Resolving 'allOf' field in schema '{\"title\":\"AccountSettingsAuthentication\",\"type\":\"object\",\"allOf\":[{\"properties\":{\"meeting_authentication\":{\"type\":\"boolean\",\"description\":\"Only authenticated users can join meetings\"},\"authentication_options\":{\"type\":\"array\",\"description\":\"Meeting Authentication Options\",\"items\":{\"$ref\":\"#/components/schemas/AccountSettingsAuthentication_authentication_options\"}}}},{\"properties\":{\"recording_authentication\":{\"type\":\"boolean\",\"description\":\"Only authenticated users can view cloud recordings\"},\"authentication_options\":{\"type\":\"array\",\"items\":{\"$ref\":\"#/components/schemas/AccountSettingsAuthentication_authentication_options_1\"}}}}],\"properties\":{\"meeting_authentication\":{\"type\":\"boolean\",\"description\":\"Only authenticated users can join meetings\"},\"authentication_options\":{\"type\":\"array\",\"description\":\"Meeting Authentication Options\",\"items\":{\"$ref\":\"#/components/schemas/AccountSettingsAuthentication_authentication_options\"}},\"recording_authentication\":{\"type\":\"boolean\",\"description\":\"Only authenticated users can view cloud recordings\"}}}' results in incompatible property field 'authentication_options'.",
"mitigation": "Ignore and continue. May lead to unexpected behavior."
},
{
"type": "UNKNOWN_TARGET_TYPE",
"message": "No GraphQL target type could be identified for schema '{}'.",
"mitigation": "The data will be stored in an arbitrary JSON type."
},
{
"type": "OBJECT_MISSING_PROPERTIES",
"message": "Schema {\"description\":\"Placeholder to support operations with no response schema\",\"type\":\"object\"} does not have any properties",
"mitigation": "The (sub-)object will be stored in an arbitray JSON type."
}
],
"numOps": 2,
"numOpsQuery": 1,
"numOpsMutation": 1,
"numOpsSubscription": 0,
"numQueriesCreated": 1,
"numMutationsCreated": 1,
"numSubscriptionsCreated": 0
}
I was reading that this tool does not covert at 100% but there is something else that I can do to kind workaround it? Do you have any suggestion on how to tweak the input to make it work?
@sbilello Sorry for the late response. I think for most real-world use cases, there will be some warnings, and some of these warnings are fine.
For example, I wouldn't worry too much about the following warnings:
[
{
"type": "OAUTH_SECURITY_SCHEME",
"message": "OAuth security scheme found in OAS 'API'. OAuth support is provided using the 'tokenJSONpath' option",
"mitigation": "Ignore security scheme"
},
{
"type": "UNKNOWN_TARGET_TYPE",
"message": "No GraphQL target type could be identified for schema '{}'.",
"mitigation": "The data will be stored in an arbitrary JSON type."
},
{
"type": "OBJECT_MISSING_PROPERTIES",
"message": "Schema {\"description\":\"Placeholder to support operations with no response schema\",\"type\":\"object\"} does not have any properties",
"mitigation": "The (sub-)object will be stored in an arbitray JSON type."
}
]
We create viewers for different security schemes. However, we handle OAuth differently by relying on tokenJSONpath (see here). Hence, we have OAUTH_SECURITY_SCHEME to inform the user that we do not do any additional actions for OAuth. Unfortunately, the warning is scarier than it needs to be. I have changed it so now it should read:
{
"type": "OAUTH_SECURITY_SCHEME",
"message": "OAuth security scheme found in OAS 'API'.",
"mitigation": "Do not create viewer. OAuth support is provided using the 'tokenJSONpath' option"
}
I believe this can be resolved by removing the OAuth security scheme (as well as where ever it is referenced).
The UNKNOWN_TARGET_TYPE warning is used to designate when a schema has no type. This could be a nested schema.
For example:
{
"type": "object",
"properties": {
"a": {
"type": "string"
},
"b": {
"type": "string"
},
"c": {}
}
}
In this case, the c property does not have a type. That would throw an error. This can be resolved by adding a type to where ever this schema exists in your OAS. Is it possible to type your response? Unfortunately, there isn't a straightforward way to improve this warning message. I can see a few ways forward, like printing not just the problem schema but also the parent schema or by printing a JSON path to the problem schema. I filed an issue for this #384
The OBJECT_MISSING_PROPERTIES warning is used when an object schema does not have any properties.
For example:
{
"type": "object",
"properties": {}
}
or
{
"type": "object"
}
This can be resolved by adding properties.
The UNRESOLVABLE_SCHEMA is bad.
Here is the problematic schema in a more readable form.
{
"title": "AccountSettingsAuthentication",
"type": "object",
"allOf": [
{
"properties": {
"meeting_authentication": {
"type": "boolean",
"description": "Only authenticated users can join meetings"
},
"authentication_options": {
"type": "array",
"description": "Meeting Authentication Options",
"items": {
"$ref": "#/components/schemas/AccountSettingsAuthentication_authentication_options"
}
}
}
},
{
"properties": {
"recording_authentication": {
"type": "boolean",
"description": "Only authenticated users can view cloud recordings"
},
"authentication_options": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AccountSettingsAuthentication_authentication_options_1"
}
}
}
}
],
"properties": {
"meeting_authentication": {
"type": "boolean",
"description": "Only authenticated users can join meetings"
},
"authentication_options": {
"type": "array",
"description": "Meeting Authentication Options",
"items": {
"$ref": "#/components/schemas/AccountSettingsAuthentication_authentication_options"
}
},
"recording_authentication": {
"type": "boolean",
"description": "Only authenticated users can view cloud recordings"
}
}
}
Our current allOf and oneOf resolution is not very robust and has bugs. However, I do notice that in this schema, there is an allOf field and its own properties. Furthermore, the allOf subschemas have conflicting properties with said `properties. Is this valid?
I think OtG expects the existing properties to be listed under allOf.
Perhaps this will work better?
{
"title": "AccountSettingsAuthentication",
"type": "object",
"allOf": [
{
"properties": {
"meeting_authentication": {
"type": "boolean",
"description": "Only authenticated users can join meetings"
},
"authentication_options": {
"type": "array",
"description": "Meeting Authentication Options",
"items": {
"$ref": "#/components/schemas/AccountSettingsAuthentication_authentication_options"
}
}
}
},
{
"properties": {
"recording_authentication": {
"type": "boolean",
"description": "Only authenticated users can view cloud recordings"
},
"authentication_options": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AccountSettingsAuthentication_authentication_options_1"
}
}
}
},
{
"properties": {
"meeting_authentication": {
"type": "boolean",
"description": "Only authenticated users can join meetings"
},
"authentication_options": {
"type": "array",
"description": "Meeting Authentication Options",
"items": {
"$ref": "#/components/schemas/AccountSettingsAuthentication_authentication_options"
}
},
"recording_authentication": {
"type": "boolean",
"description": "Only authenticated users can view cloud recordings"
}
}
}
]
}
I think that OtG often produces too many warnings, some of them more severe than others. Some warning can even be ignored. Therefore, I filed #385. Feel free to comment your own opinions.
I've also filed a number of other issues such as #387, #386, and #384 which are all related to yours.
"AccountSettingsAuthentication": {
"title": "AccountSettingsAuthentication",
"type": "object",
"allOf": [
{
"properties": {
"meeting_authentication": {
"type": "boolean",
"description": "Only authenticated users can join meetings"
},
"authentication_options": {
"type": "array",
"description": "Meeting Authentication Options",
"items": {
"$ref": "#/components/schemas/AccountSettingsAuthentication_authentication_options"
}
}
}
},
{
"properties": {
"recording_authentication": {
"type": "boolean",
"description": "Only authenticated users can view cloud recordings"
},
"authentication_options": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AccountSettingsAuthentication_authentication_options_1"
}
}
}
}
]
}
This is the current snippet that has allOf. The operator was oneOf but I changed the operator from oneOf to allOf to get something out because it was not generating anything. Adding an extra element in the list of allOf didn't solve the problem.
I will try to make it work by manually fixing the graphQL schema. I wanted to report the problems so you might find the fixes to make this more robust.
@Alan-Cha Thanks for replying to me and no worries for the delay. If you want you can reach me on LinkedIn to set up a brief chat.
The viewer concept is something interesting but I am using only the translation capabilities to build the backend with the netflix dgs framework.