Strawman2

Second Strawman proposal:

(also - apologies to @hoegertn, did not mean to clobber your changes on strawman1 yesterday!)

I've made the following changes from the first example:

• Renamed 'body' to 'accepts' to make it's purpose more clear.
• Changed the 'representations' array items to objects as in alternative #1, with the exception of the 'body' element.
• Changed example request bodies to strings.
• Added an optional "headers" element to example requests.
• Added a query param to the request template as an alternative to alternative #1's 'style' member.
  • The above is also an example of using an enum for parameter descriptions.
• Removed redundant type: "string" elements from parameter descriptions.
• Added more comments.

{
  // Keeping the top level open in the schema means we could allow other metadata such as API versions,
  // authors, and so on. (Idea lifted from https://github.com/SPORE/specifications)
  resources: [
    {
      id: "LocalizedMessage",
      doc: "A localized message",
      path: "/{language}/{messageId}{?seasonal}", // representing query params with L3 URI templates
      params: { // Request parameters only, JSON schemas with type: 'string' implied
        locale: {
          description: "A standard locale string, e.g. \"en_US.utf-8\"",
          pattern: "[a-z]+(_[A-Z]+)?(\\.[a-z-]+)?"
        },
        messageId: {
          description: "A free-form message string",
          pattern: "[a-z_]+"
        },
        seasonal: {
          description: "Whether the message is seasonal.",
          enum: ['true', 'false', 'yes', 'no'],
        } 
      },
      methods: {
        PUT: {
          doc: "Update or create a message",
          statusCodes: [ 201 ],
          accepts: [   // Representations accepted by this method on this resource.
            { type: "text/plain" },
            { type: "application/json", schema: "http://some.json/schema" }
          ],
          examples: [
            {
              path: "/en_US/greeting",
              body: "Hello, world!"
            },
            {
              path: "/en_US/greeting",
              headers: {"content-type": "application/json"},
              body: "{\"message\":\"Hello, world!\"}", // Should bodies *always* be strings?
            },
            {
              path: "/en_US/greeting",
              headers: {"content-type": "application/xml"},
              body: "<message>Hello, world</message>",
            }
          ]
        },
        GET: {
          doc: "Retrieve a message",
          statusCodes: [ 200, 302 ],
          accepts: null, // Possible to explicitly indicate that this method takes no request body. 
        }
      },
      representations: [ // Response representations this resource provides
        { type: 'application/json', schema: 'http://my.json/schema' },
        { type: 'application/xml', schema: 'http://my.xml/dtd' }, // Externally referenced schema
        { type: 'text/plain' },
      ]
    },
    {
      // This resource has no human-readable documentation, but still provides some info on how to use it.
      id: "FallbackLocale",
      methods: {
        GET: { statusCodes: [ 200 ] },
        PUT: { statusCodes: [ 201 ] }
      },
      parameters: {
        locale: { pattern: "[a-z]+(_[A-Z]+)?(\\.[a-z-]+)?" }
      }
    }
  ]
}

(Perceived) Improvements:

• This version handles multiple representation formats for requests and responses independently of each other.
• It is independent of JSON, (could just as easily be represented in XML, Avro, MessagePack, etc). While this may not be of immediate necessity, it seems prudent to try not to bind ourselves to strongly to one serialization format.