How do I reference nested sub-schemas from RAML?


#21

Happy to help!


#22

And now I’ve just run into the same issue.
the example JSON does validate against the above JSONSchema… however the use of references (for cleanliness more than anything else) makes the RAML parser blow up.

/0247:
  displayName: 0247 - Request HIT Medical Evidence
  description: |
    The 0247 transaction is to be used to submit a user initiated request for
    medical records from a Health IT partner.
  type:
    hit:
      exampleItem: !include json/0247.json
      schemaItem: !include schema/0247.schema.json
  post:
    body:
      application/json:
        example: !include json/0247.json
        schema: !include schema/0247.schema.json
    responses:
      200:
        body:
          application/json:
            example: !include json/0248-success.json # <-- this is where it's complaining
            schema: !include schema/0248.schema.json

and here’s 0248.schema.json

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "type": "object",
    "properties": {
        "Folder": {
            "type": "object",
            "properties": {
                "Case": {
                    "type": "object",
                    "properties": {
                        "HealthITUserRequestNotification": {
                            "type": "object",
# using oneOf and referencing subschemas elsewhere in the same document
                            "oneOf": [{                                    
                                "$ref": "#/definitions/success"
                            }, {
                                "$ref": "#/definitions/error"
                            }]
                        },
                        "_adjudicativeLevelCode": {
                            "type": "string",
                            "length": 1
                        },
                        "_caseNumber": {
                            "type": "string",
                            "length": 11
                        },
                        "_folderNumber": {
                            "type": "string",
                            "length": 11
                        }
                    },
# here are my subschemas referenced by the oneOf
                    "definitions": {
                        "success": {
                            "type": "object",
                            "properties": {
                                "Status": {
                                    "type": "object",
                                    "properties": {
                                        "_code": {
                                            "enum": ["C"]
                                        },
                                        "_label": {
                                            "type": "string"
                                        },
                                        "_description": {
                                            "type": "string"
                                        }
                                    },
                                    "required": [
                                        "_code",
                                        "_label",
                                        "_description"
                                    ]
                                },
                                "HealthITDocument": {
                                    "type": "object",
                                    "properties": {
                                        "CaseDocument": {
                                            "type": "object",
                                            "properties": {
                                                "_officeCode": {
                                                    "type": "string",
                                                    "length": 3
                                                },
                                                "_treatmentSourceName": {
                                                    "type": "string",
                                                    "length": 80
                                                },
                                                "_requestId": {
                                                    "type": "string",
                                                    "length": 25
                                                },
                                                "_docCode": {
                                                    "type": "string",
                                                    "length": 4
                                                },
                                                "_docControlId": {
                                                    "type": "string",
                                                    "length": 26
                                                },
                                                "_folderNumber": {
                                                    "type": "string",
                                                    "length": 11
                                                },
                                                "_caseNumber": {
                                                    "type": "string",
                                                    "length": 11
                                                }
                                            },
                                            "required": [
                                                "_officeCode",
                                                "_docCode",
                                                "_docControlId",
                                                "_folderNumber",
                                                "_caseNumber"
                                            ]
                                        },
                                        "_docCode": {
                                            "type": "string",
                                            "length": 4
                                        },
                                        "_caseNumber": {
                                            "type": "string",
                                            "length": 11
                                        },
                                        "_folderNumber": {
                                            "type": "string",
                                            "length": 11
                                        },
                                        "_noRequestDocumentSubType": {
                                            "type": "string",
                                            "length": 1
                                        },
                                        "_responseSubType": {
                                            "type": "string",
                                            "length": 1
                                        }
                                    },
                                    "required": [
                                        "CaseDocument",
                                        "_docCode",
                                        "_caseNumber",
                                        "_folderNumber"
                                    ]
                                },
                                "_caseNumber": {
                                    "type": "string",
                                    "length": 11
                                },
                                "_folderNumber": {
                                    "type": "string",
                                    "length": 11
                                },
                                "_originatingSystemIdentifier": {
                                    "type": "string",
                                    "length": 16
                                }
                            },
                            "required": [
                                "Status",
                                "HealthITDocument",
                                "_caseNumber",
                                "_folderNumber",
                                "_originatingSystemIdentifier"
                            ]
                        },
                        "error": {
                            "type": "object",
                            "properties": {
                                "Status": {
                                    "type": "object",
                                    "properties": {
                                        "_code": {
                                            "enum": ["E"]
                                        },
                                        "_label": {
                                            "type": "string"
                                        },
                                        "_description": {
                                            "type": "string"
                                        }
                                    },
                                    "required": [
                                        "_code",
                                        "_label",
                                        "_description"
                                    ]
                                },
                                "Error": {
                                    "type": "object",
                                    "properties": {
                                        "_code": {
                                            "type": "string",
                                            "length": 2
                                        },
                                        "_label": {
                                            "type": "string",
                                            "length": 32
                                        },
                                        "_description": {
                                            "type": "string",
                                            "length": 254
                                        }
                                    },
                                    "required": [
                                        "_code",
                                        "_label",
                                        "_description"
                                    ]
                                },
                                "HealthITDocument": {
                                    "type": "object",
                                    "properties": {
                                        "CaseDocument": {
                                            "type": "object",
                                            "properties": {
                                                "_officeCode": {
                                                    "type": "string",
                                                    "length": 3
                                                },
                                                "_treatmentSourceName": {
                                                    "type": "string",
                                                    "length": 80
                                                },
                                                "_requestId": {
                                                    "type": "string",
                                                    "length": 25
                                                },
                                                "_docCode": {
                                                    "type": "string",
                                                    "length": 4
                                                },
                                                "_docControlId": {
                                                    "type": "string",
                                                    "length": 26
                                                },
                                                "_folderNumber": {
                                                    "type": "string",
                                                    "length": 11
                                                },
                                                "_caseNumber": {
                                                    "type": "string",
                                                    "length": 11
                                                }
                                            },
                                            "required": [
                                                "_officeCode",
                                                "_docCode",
                                                "_docControlId",
                                                "_folderNumber",
                                                "_caseNumber"
                                            ]
                                        },
                                        "_docCode": {
                                            "type": "string",
                                            "length": 4
                                        },
                                        "_caseNumber": {
                                            "type": "string",
                                            "length": 11
                                        },
                                        "_folderNumber": {
                                            "type": "string",
                                            "length": 11
                                        },
                                        "_noRequestDocumentSubType": {
                                            "type": "string",
                                            "length": 1
                                        },
                                        "_responseSubType": {
                                            "type": "string",
                                            "length": 1
                                        }
                                    },
                                    "required": [
                                        "CaseDocument",
                                        "_docCode",
                                        "_caseNumber",
                                        "_folderNumber"
                                    ]
                                },
                                "_caseNumber": {
                                    "type": "string",
                                    "length": 11
                                },
                                "_folderNumber": {
                                    "type": "string",
                                    "length": 11
                                },
                                "_originatingSystemIdentifier": {
                                    "type": "string",
                                    "length": 16
                                }
                            },
                            "required": [
                                "Status",
                                "Error",
                                "HealthITDocument",
                                "_caseNumber",
                                "_folderNumber",
                                "_originatingSystemIdentifier"
                            ]
                        }
                    },
                    "required": [
                        "HealthITUserRequestNotification",
                        "_caseNumber",
                        "_folderNumber"
                    ]
                },
                "_clientSSN": {
                    "type": "string",
                    "length": 9
                },
                "_folderNumber": {
                    "type": "string",
                    "length": 11
                }
            },
            "required": [
                "Case",
                "_clientSSN",
                "_folderNumber"
            ]
        }
    },
    "required": [
        "Folder"
    ]
}

and here is the example JSON body

{
  "Folder": {
    "Case": {
      "HealthITUserRequestNotification": {
        "Status": {
          "_code": "C",
          "_label": "Complete",
          "_description": ""
        },
        "HealthITDocument": {
          "CaseDocument": {
            "_officeCode": "LH0",
            "_treatmentSourceName": "",
            "_requestId": "",
            "_docCode": "0016",
            "_docControlId": "A1001001A08G22B54441I88333",
            "_folderNumber": "181228905",
            "_caseNumber": "182606496"
          },
          "_docCode": "0016",
          "_caseNumber": "182606496",
          "_folderNumber": "181228905",
          "_noRequestDocumentSubType": "",
          "_responseSubType": ""
        },
        "_caseNumber": "182606496",
        "_folderNumber": "181228905",
        "_originatingSystemIdentifier": ""
      },
      "_adjudicativeLevelCode": "3",
      "_caseNumber": "182606496",
      "_folderNumber": "181228905"
    },
    "_clientSSN": "029327143",
    "_folderNumber": "181228905"
  }
}

ignore the redundant cadeNumber & folderNumber fields, they have nothing to do with this issue. this is just an example i’m using

and the RAML parser error

Example does not conform to schema:Content is not valid according to schema:Reference could not be resolved: <path>/api.raml#/definitions/success <path>/api.raml#/definitions/success, Reference could not be resolved: <path>/api.raml#/definitions/error <path>/api.raml#/definitions/error at line 209 col 13

#23

Can you confirm that the JSON is valid JSON. If yes, let me send that to the guys.


#24

Failing to point nested schema references from dependent schema files in RAML, clearly states that RAML is NOT ENTERPRISE READY. Use it only if you have very limited amount of attributes for web service contract. I don’t know why Mule enforce to use this.


#25

@sivakkannan I am a little baffled by your statement… what is the purpose of it? For all intents and purposes, the original post has been resolved in RAML 1.0. The shortcomings of the JSON Schema issues are handled nicely with RAML 1.0 Types. Be thankful that we at least have RAML as there is no other spec available today that comes close.


#26

We are in need to use multiple JSON schema files and nested JSON types along with RAML. Reason defining types using JSON instead of RAML types is, we need to share the JSON schema files to other applications as the other applications does not support for RAML types. But, RAML does not give complete support for nested JSON schema files. This affects reusable of the JSON schema files. Reusable of schema files is a basic need when you create service contract for an enterprise.


#27

Hi @sivakkannan, thanks for your comment and I understand your concern. RAML does not explicitly call out the support of refs in JSON schema since its not in the scope of a specification like RAML. You will see that with other types of specs as well. If you see that some is not supported; it might be that the tool does not support it. That’s a different story.

So the question is how you currently use RAML and where / when you need to dereference your JSON schema?


#28

I see a lot of confusion about json-schema references. The best solution is to take the time to read the json-schema specification. The schema references in the given example have no resolution scope, so it can’t be correct. To fix this, you should add one or more ‘id’ fields into your schema, see section 7.2 on the linked page to the specs, and then make sure that “#/definitions/success” resolves correctly.