Sample PostgREST JSON Hyperlink Schema

resources.md

For more resources on JSON hyperlink schemas, see:

• The spec.
• Brandur's introductory article.
• JSON Schema reference.
• Heroku's JSON Schema API documentation and production schema (make sure to use a application/vnd.heroku+json; version=3 accept header).

schema.json

{
  "title": "Conference API",
  "description": "A demonstration PostgREST API modeling conference speakers.",
  "definitions": {
    "speakers": {
      "title": "Speaker",
      "description": "One of our beautiful conference speakers.",
      "type": "object",
      "required": ["name", "avatar_url", "featured"],
      "properties": {
        "id": {
          "type": "number",
          "readOnly": true
        },
        "name": {
          "title": "Name",
          "description": "The conference speaker's name.",
          "type": "string"
        },
        "twitter": {
          "title": "Twitter handle",
          "description": "A handle to find the speaker on Twitter.",
          "type": "string",
          "pattern": "^@?([a-zA-Z0-9_]{1,15})$"
        },
        "avatar_url": {
          "title": "Avatar",
          "description": "A depiction of the speaker.",
          "type": "string"
        },
        "bio": {
          "title": "Bio",
          "description": "A short bio about the speaker.",
          "type": "string"
        },
        "featured": {
          "title": "Featured",
          "description": "Whether or not the speaker is featured.",
          "type": "boolean",
          "default": false
        }
      }
    },
    "sessions": {
      "title": "Session",
      "description": "A single conference talk",
      "type": "object",
      "required": ["start_time", "end_time"],
      "properties": {
        "id": {
          "type": "number",
          "readOnly": true
        },
        "speaker_id": {
          "$ref": "#/definitions/speakers/properties/id",
          "title": "Speaker",
          "description": "The speaker for this session."
        },
        "start_time": {
          "title": "Start Time",
          "description": "The projected time this session starts.",
          "type": "string",
          "format": "date-time"
        },
        "end_time": {
          "title": "End Time",
          "description": "The projected timme this session ends.",
          "type": "string",
          "format": "date-time"
        },
        "location": {
          "title": "Location",
          "description": "Where to go to attend this session.",
          "type": "string"
        }
      }
    },
    "queryParams": {
      "type": "object",
      "properties": {
        "select": {
          "title": "Select",
          "description": "Specify which columns to have in the response. Allows for document embedding.",
          "type": "string",
          "format": "select-param"
        },
        "order": {
          "title": "Order",
          "description": "Specify the order in which the instances should be arranged.",
          "type": "string",
          "format": "order-param"
        }
      }
    }
  },
  "links": [
    {
      "href": "/speakers",
      "method": "POST",
      "rel": "create",
      "schema": {
        "$ref": "#/definitions/speakers"
      }
    },
    {
      "href": "/speakers",
      "method": "GET",
      "rel": "instances",
      "schema": {
        "$ref": "#/definitions/queryParams"
      },
      "targetSchema": {
        "type": "array",
        "items": {
          "$ref": "#/definitions/speakers"
        }
      }
    },
    {
      "href": "/speakers?id=eq.{id}",
      "method": "GET",
      "rel": "instance",
      "schema": {
        "$ref": "#/definitions/queryParams"
      },
      "targetSchema": {
        "type": "array",
        "items": {
          "$ref": "#/definitions/speakers"
        }
      }
    },
    {
      "href": "/speakers",
      "method": "PATCH",
      "rel": "update",
      "schema": {
        "$ref": "#/defintions/speakers"
      }
    },
    {
      "href": "/speakers",
      "method": "DELETE",
      "rel": "destroy"
    },
    {
      "href": "/sessions",
      "method": "POST",
      "rel": "create",
      "schema": {
        "$ref": "#/definitions/sessions"
      }
    },
    {
      "href": "/sessions",
      "method": "GET",
      "rel": "instances",
      "schema": {
        "$ref": "#/definitions/queryParams"
      },
      "targetSchema": {
        "type": "array",
        "items": {
          "$ref": "#/definitions/sessions"
        }
      }
    },
    {
      "method": "GET",
      "href": "/sessions?id=eq.{id}",
      "rel": "instance",
      "schema": {
        "$ref": "#/definitions/queryParams"
      },
      "targetSchema": {
        "type": "array",
        "items": {
          "$ref": "#/definitions/sessions"
        }
      }
    },
    {
      "href": "/sessions",
      "method": "PATCH",
      "rel": "update",
      "schema": {
        "$ref": "#/defintions/sessions"
      }
    },
    {
      "href": "/sessions",
      "method": "DELETE",
      "rel": "destroy"
    }
  ]
}