jsonapi.org has a good format

[nschonni]

http://jsonapi.org/ has a good "standard" format with a MUST/SHOULD/MAY/CAN vocab and examples

PS: GitHub source https://github.com/json-api/json-api

[chrismajewski]

Much like an RFP.

Interesting but isn't the present layout closer to how standards are defined? Metadata Experts Working Group's Task Group 2 "Metadata for the Web" is proceeding in this fashion. Requirements, Options, Best practices.

[nschonni]

The format page might be a better example http://jsonapi.org/format/. I was trying to get at something like the conformance section that W3C spec docs use http://dev.w3.org/csswg/css-template/#conformance

[chrismajewski]

We are still trying to get to a standard. We should look more like: http://www.tbs-sct.gc.ca/pol/doc-eng.aspx?id=18909&section=text

[nschonni]

Except that that "standard" is actually a policy document (which isn't the same thing outside of Government)

[chrismajewski]

Yes, as it is now it's a guideline with the hopes of making it a standard in the TBS sense.

Use of the word standard started in the american document, or more specifically "standards", meaning each defined section was a standard way of executing that logical block.

Using that document directly caused this confusion, I was planing to change then when I got to talk to Ashley. I do that tomorrow.

Seeing the end goal does this still make sense?

[nschonni]

Kind of, I guess this is more towards what would be called a "Guidance" doc or Technical Specification (http://www.tbs-sct.gc.ca/ws-nw/mo-om/ts-st/f-p-eng.asp)

PS: FIPS http://www.nist.gov/manuscript-publication-search.cfm?pub_id=902003 would be an example that comes down between Policy (fake standard :wink: ) and and ISO/W3C standard

[chrismajewski]

More bare bones it's a document we are trying to get in place prior to a potential API explosion to direct the blast in a common direction. This is the Web Interoperability Working Group trying to live up to it's raison d'être.

We've seen and are paying for what happens when direction is late in form of consolidation. There will still be aspects of that regardless of how it's implemented but the closer we can get to a document that's beneficial to the developer ( helpful, simple, practical, ... ) and something with a bit of teeth ( warranting dev, enforcing interoperability, reducing platforms to adapt ) the better we can accomplish that.

That's the spirit of where I'm trying to go. Any significant directional change I need to take to the WIWG.

[nschonni]

Sorry for getting off track, but back to the original idea of adopting a more standard like format:

The header variables SHALL support media type through Accept: and language through Accept-Language:. On response Content-Type: and Content-Language: MUST be returned with the appropriate media type and language(s) respectively.

The response SHOULD default to sending multilingual content if Accept-Language: is not specified in the request.

[chrismajewski]

Real standard or fake standard? ;)

Review for language is planned as one of the final steps prior to formally presenting a draft or translation. This document chances so much that I'd like to continue down this human language path till required to be more formal. Before I'd review for language I'd like to review for accuracy and then consistency.

It's an interesting idea and I may ask you to do so at the appropriate time if your still willing to then.

[chrismajewski]

We went in circles MUST/SHOULD/MAY/CAN are a good idea.