Subject: [apps-discuss] Inclusion-mechanism for draft-nottingham-json-home-01?

From: Jan Algermissen <[email-masked]>
Date: Wed, 18 Jul 2012 16:28:29 +0200

Hi Mark,

I am playing around with your json-home I-D[1].

Despite being entirely not a fan of generating artifacts like json-home documents from code I am facing a situation where this seems like the best way to get the point of following your nose across.

Having accepted generation for the moment, I am facing the issue of integrating generated aspects of the home document and non-generated aspects.

Hence the question: Have you considered an inclusion mechanism for json-home documents to split them into parts with different locations and ownership?

I am not sure about this, but it would also open up options for managing parts with differing live times, probably to allow features under development to change far more frequently than the stable 'official' parts.

Your example might then look something like this:

{
    "resources": {
      "http://example.org/rel/widgets": {
        "href": "/widgets/"
      },
      "http://example.org/rel/widget": {
        "href-template": "/widgets/{widget_id}",
        "href-vars": {
          "widget_id": "http://example.org/param/widget"
        },
        "hints": {
          "allow": ["GET", "PUT", "DELETE", "PATCH"],
          "representations": ["application/json"],
          "accept-patch": ["application/json-patch"],
          "accept-post": ["application/xml"],
          "accept-ranges": ["bytes"]
        }
      }
    },
    "include" : "/home/inc/other.js",
    "include" : "/home/inc/dev-features-02.js",
}

However, I am all for making crystal clear that such documentation is intended to be so stable that generation is actually a non-use case.

Jan

[1] http://tools.ietf.org/html/draft-nottingham-json-home-01

---

From: Mark Nottingham <[email-masked]>
Date: Thu, 19 Jul 2012 14:08:14 +1000

I've considered it, but wouldreally want to squint hard at it before doing it.

Inclusion mechanisms IME are very tricky unless they're very carefully designed; they made WSDL a mess, for example, and WADL wasn't much better. It *might* be necessary, but I'd like to get a lot more experience with the space before including (heh) it in the spec.

Right now, my bet would be on using a pre-processor of some sort (i.e., a "JSON include" mechanism) to generate the document you publish, if it's a management problem on the back end your'e trying to solve.

Make sense?

Cheers,

--
Mark Nottingham   http://www.mnot.net/

---

From: Jan Algermissen <[email-masked]>
Date: Thu, 19 Jul 2012 08:07:25 +0200

> I've considered it, but wouldreally want to squint hard at it before doing it.

Yes, my feeling, too.

> Right now, my bet would be on using a pre-processor of some sort (i.e., a "JSON include" mechanism) to generate the document you publish, if it's a management problem on the back end your'e trying…

Absolutely.

Jan

---

From: Erik Wilde <[email-masked]>
Date: Thu, 19 Jul 2012 08:39:20 +0200

> Right now, my bet would be on using a pre-processor of some sort (i.e., a "JSON include" mechanism) to generate the document you publish, if it's a management problem on the back end your'e trying…

for the XML version of home documents, that could translate into 
requiring that xml-home processors support XInclude, or publishers could 
run XInclude processes server-side, if the requirement for clients seems 
to be too much.

cheers,

dret.

-- 
erik wilde | mailto:[email-masked]  -  tel:+1-510-2061079 |
            | UC Berkeley  -  School of Information (ISchool) |
            | http://dret.net/netdret http://twitter.com/dret |

---

From: Ben Niven-Jenkins <[email-masked]>
Date: Thu, 19 Jul 2012 19:10:28 +0100

Jan,

> Hence the question: Have you considered an inclusion mechanism for json-home documents to split them into parts with different locations and ownership?

Wouldn't having a json-home document where some of the links are to 1 or more other json-home document(s) solve that for you while using the specification in the current draft as-is?

Ben

> _______________________________________________
> apps-discuss mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/apps-discuss

---

From: Jan Algermissen <[email-masked]>
Date: Thu, 19 Jul 2012 21:26:42 +0200

On Jul 19, 2012, at 8:10 PM, Ben Niven-Jenkins wrote:

> Wouldn't having a json-home document where some of the links are to 1 or more other json-home document(s)

Yes, that could be an option. Something like 'seeAlso' :-)

> solve that for you while using the specification in the current draft as-is?
> 

Is was more curious about Mark's thoughts than having a real problem. And I al all for simpler specs.

Jan

---

From: Mark Nottingham <[email-masked]>
Date: Fri, 20 Jul 2012 11:00:31 +1000

> Wouldn't having a json-home document where some of the links are to 1 or more other json-home document(s) solve that for you while using the specification in the current draft as-is?

Oof. I'm not sure I like where that leads. Would you expect a client to deref and combine all of the home documents?