Some notes about the 1.2 specification document

[fge]

Link: https://github.com/wordnik/swagger-spec/blob/master/versions/1.2.md

• Section 3: a "fully qualified URL" can be defined as a "URI, as defined by [RFC 3986, section 3]; the scheme used by this URI MUST be http." file are also valid URLs after all ;)
• Section 4.1: should be completed with "unless otherwise specified, JSON objects defined by this specifications MUST NOT contain members [properties, fields, whatever] other than the ones defined in this specification".
• Also section 4.1: "JSON written for the swagger API MUST conform to the JSON grammar as defined in RFC 7159, section 2; security and interoperability considerations described in RFC 7159 also apply to the present specification".
• Section 4.3.3: little typo: "There currently two variations" (misses "are").

[fge]

Also, section 5.1.2: path is in fact a URI Template, as defined by RFC 6570; the only template used is a level 1 expression type as defined in section 1.2 of the URI.

Code wise, Guava has UrlEscapers.urlPathSegmentEscaper() which can perform appropriate escaping for such templates. Exploiting URI templates fully requires more than that, of course.

[webron]

Thanks for the notes - we're not going to make changes to the older specs now.