PSADv1: specify the content body using "mediatype", not "resource"

[automatthew]

The first round of work, for expedience, specifies the schema for the request or response body using a reference to a key in the dictionary of JSON Schemas.

resources:
  blurbs:
    path: /blurbs
    description: "Virtual collection of blurbs"
    methods:
      POST:
        signatures:
          request:
            resource: blurb
          response:
            status: [201, 400]
schema:
  blurb:
    $schema: "http://json-schema.org/draft-04/schema"
    title: Blurb
    type: object
    properties:
      content:
        type: string
      expiration:
        type: string
        format: date-time

Using a media-type is preferable, and part of the original redesign for PSAD.

To make this work, each schema in the API Description must declare a "mediaType" at its top level. Unfortunately, the API Gateway JSON Schema validator is slightly non-compliant, disallowing unknown keywords. We can handle this by stripping the "mediaType" property from the schema definition we use to define API Gateway Models in the CloFoTemp.

This addition will not break existing apps, which may transition to using mediatype instead of resource in the api.yaml at will.

[dyoder]

Maybe the indirection is kind of nice? We'd still need to add mediaType to the schema, but we'd look it up when constructing the API GW template. It's always been a little bit annoying to have to put the full media type in the signature. The only trouble with this is versioning, since the media type may include a version attribute. But we could introduce a version attribute in the signature.

Another possibility would be to construct the media type via convention, ex:

application/vnd.{{vendor}}.{{resource}};charset={{charset}};version={{version}}

where vendor and charset are perhaps set in sky.yaml (charset could default to utf-8).

That is, rather than burden the developer with figuring this out, we just do the right thing by default. Later, we could (if people demand it), add a mediaType attribute either to the schema or to the signature to override the convention.

Also, technically, we will want eventually to allow for an arrays of types in the signature. Or perhaps an array of versions? So we'd end up with something like this:

resources:
  blurbs:
    path: /blurbs
    description: "Virtual collection of blurbs"
    methods:
      POST:
        signatures:
          request:
            resource: blurb
            # this is the part that's changed
            versions: [1, 2]
          response:
            status: [201, 400]
schema:
  blurb:
    $schema: "http://json-schema.org/draft-04/schema"
    title: Blurb
    type: object
    properties:
      content:
        type: string
      expiration:
        type: string
        format: date-time

[automatthew]

We should definitely have multiple mediatypes allowed for request/response bodies.

In addition to having signatures.request.mediatype, we can have signatures.request.schema, with the value being a JSON Pointer to a particular schema, either relative to the one we define, or fully specified as a URL:

signatures:
  request:
    schema:
      - "#/blurb"
      - "https://schema.blurb9.com/v1#blurb"

[dyoder]

@automatthew I'm unsure if you intended this or if we're talking past each other, but that's more or less the opposite direction of what I'm suggesting.

Can't we incorporate external schemas by reference? That is, in the schema itself.