CODEWITHSUNDEEP
jsonjsonschema
lyschoening
lyschoening

Reputation: 18738

JSON Hyper-Schema: different schemas for GET and POST

I want to describe an API that has fields which allows for different ways to define values when POSTing an item, but only ever output in the field in one specific way.

For example, I might want to describe an API where an item can be created or updated like this: {"name": "Task", "due": "2014-12-31"} or like this: {"name": "Task", "due": {"$date": 1419984000000}}, but it is only ever returned from the API in the first way.

The schema for POST/PUT could therefore be:

{
    "type": "object"
    "properties": {
        "name": {
            "type": "string"
        },
        "due": {
            "oneOf": [
                {
                    "type": "string",
                    "format": "date"
                },
                {
                    "type": "object",
                    "properties": {
                        "$date": {
                            "type": "number"
                        }
                    },
                    "required": ["$date"],
                    "additionalProperties": false
                }
            ]
        }
    }
}

Whereas the schema for access via GET would be much simpler:

{
    "type": "object"
    "properties": {
        "name": {
            "type": "string"
        },
        "due": {
            "type": "string",
            "format": "date"
        }
    }
}

It would be good for consumers of the API to know that they only have to account for one possible output method rather then all of them.

Is there any accepted standard approach to specify the different schemas within the context of JSON Hyper-Schema? I've thought about specifying these differences via the "links" property, but I do not know what "rel" I would define these schemas under and it seems very-non-standard.

Upvotes: 2

Views: 1706

Answers (1)

jruizaranguren
jruizaranguren

Reputation: 13625

If I understood correctly, and you want to specify one schema per operation you can do it with standard hyper-schema. Let's see and example for a post operation:

{
  "description": "create an item.",
  "href": "/items",
  "method": "POST",
  "rel": "create",
  "schema": {
    "$ref": "#/api/createitem"
  },
  "title": "Create an item"
}

The actual schema that is required is referenced in "schema" property through "$ref".

If you also wanted to describe the response types, then you could use "targetSchema" property. Be aware that this is advisory only (as it is explained in the docs)

Upvotes: 4

Related Questions