JSON Schema for an array of values in a Rails API

Question

I'm gonna be flat out: The documentation for JSON Schema is shit. If someone could lead me to a link that shows otherwise, I'll gladly take a look and potentially change my opinion.

I've been spending the past 3 hours trying to get JSON Schema for the following VERY SIMPLE request/response:

When someone pings /api/v1/payers?term=uni&max_results=6 the results they get are:

[
        {
           "label" : "United",
           "value" : "161a016e-8d06-49b9-9ddb-6bdbde248bcc"
        },
        {
           "label" : "United Healthcare",
           "value" : "1610426e-8de6-49b9-9ddb-6bfawf8bccew"
        }
]

I have the directory docs/schema/schemata. Do I have a payer.json in schemata that details ONE payer? Namely:

{
    "label" : "United",
    "value" : "161a016e-8d06-49b9-9ddb-6bdbde248bcc"
}

Then where do I define the array? Would that be in schema.json in the schema folder? Or... am I supposed to have a payers.json in schemata. I'm also using the prmd gem.

Nothing I read online leads me to an answer.

I agree the documentation is poor. The Space Telescope Science Institute wrote an alternative: spacetelescope.github.io/understanding-json-schema — cloudfeet
– cloudfeet, Commented Jun 27, 2014 at 11:51
BTW, the first code-block in your answer isn't valid JSON. Are you missing a property name? — cloudfeet
– cloudfeet, Commented Jun 27, 2014 at 11:57

cloudfeet · Accepted Answer · 2014-06-27 11:58:09Z

To specify a list of items, your schema should say:

{
    "type": "array",
    "items": {... item schema ...}
}

You could put the item schema inside the "items" property:

{
    "type": "array",
    "items": {
        "type": "object",
        "properties": {...},
        "required": ["label", "value"]
    }
}

Or you could store it somewhere else and reference it using $ref:

{
    "type": "array",
    "items": {"$ref": "#/definitions/payer"},
    "definitions": {
        "payer": {
            "type": "object",
            ...
        }
    }
}

You can also reference other schemas, so you can store the payer schema in a separate directory:

// payer-array.json
{
    "type": "array",
    "items": {"$ref": "/schemas/payers.json"
}

// payers.json
{
    "type": "object",
    ...
}

So, in short: there are no limitations on where your schemas are stored, etc. All that matters is that if you use a $ref, that it resolves correctly as a relative URL.

Collectives™ on Stack Overflow

JSON Schema for an array of values in a Rails API

1 Answer 1

Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

Comments

Your Answer

Sign up or log in

Post as a guest

Related