JSON schema and JSON pointers


I am a first-time RAML user. I am having trouble specifying my JSON schema without duplicating my work. I’ll explain the problem by supposing I have three different JSON schemas: element", “user” and “image”. The problem starts when I say that that both “element” and “user” need the “image” schema.

The JSON schema solution is to ues $ref. The $ref object includes a JSON pointer to the reused “image” schema. Something like this:

  "title" : "element",
  "definitions" : {
    "image" : {
        "height" : ...,
        "width" : ...,
       "url" : ...
  "properties" : {
    default: { "$ref" : "#/definitions/image"}

So here is the problem. I read RFC 6901 and it looks to me like a JSON pointer is always internal, within the current document. That is why the convention is to include a definitions section in the schema. The implicit assumption is themphasized textat all of your schema are in a single file.

However, it looks like RAML is organized to use many different schema files, one per type. For example:

#%RAML 0.8
title: GitHub API
version: v3
baseUri: https://api.github.com
mediaType:  application/json
  - User:  schema/user.json
    Users: schema/users.json
    Org:   schema/org.json
    Orgs:  schema/orgs.json

In this example, it looks like each schema (User, Users, Org, etc.) is contained in its own file.

If, for example, the schemas Users and Org were 80% the same, what do would I do? The only solution I see at the moment is to copy and paste the common schema information into multiple .json files. Is there a better solution?


As you point out, JSON Schema uses JSON References. The JSON References are just URIs. They don’t have to be just a fragment pointing internally to the same schema. They have be a full or partial URI pointing to a file. E.g. {"$ref": "some_other_file.json"}.


Thank you a lot!!!