Loading ...
Sorry, an error occurred while loading the content.

Re: [apps-discuss] New Version Notification for draft-nottingham-link-hint-00.txt

Expand Messages
  • Mark Nottingham
    Hi Erik, Sorry for the delay - just back home now. ... It needs *a* data model. ... Whoa, hold on - who said anything about a language? This is just the
    Message 1 of 12 , Jun 24 9:17 PM
    • 0 Attachment
      Hi Erik,

      Sorry for the delay - just back home now.

      > but i have one question about the general registry model: the current draft says that hints MUST have a name (very reasonable, of course), but also that hints MUST have their data model being defined in JSON.
      >
      > http://tools.ietf.org/html/draft-nottingham-link-hint-00#section-5.1
      >
      > living in a world where we have JSON services, XML services, and RDF services, it seems that hard-coding a specific language data model into such a spec (without constraining it in any way) will limit the utility of such a registry.

      It needs *a* data model.

      > for example, in the Home Document draft, which is the original source of the link hint idea, the hints were hard-coded with very constrained data models. this made it relatively easy to expose them in a different syntax (in the XML Home Document draft):
      >
      > http://tools.ietf.org/html/draft-wilde-home-xml-01#page-4
      >
      > without getting too much into the details of this specific registry: what are the best practices about allowing/controlling language dependencies in registries?

      Whoa, hold on - who said anything about a language? This is just the underlying data model; you can express it in a document however makes sense.

      > personally, i would feel more comfortable with having a registry that is of equal value to people regardless of their implementation language

      You're using "language" quite loosely here.

      > , but then again that means that the registry itself must define a "mini-language" of its own.

      -1. Defining Yet Another Data Model as a political solution to avoid picking an existing one is sub-optimal at best.

      Cheers,


      --
      Mark Nottingham http://www.mnot.net/
    • Erik Wilde
      hello mark. ... yes, that s definitely true. i think what i m trying to figure out a first is whether there is any precedence of a registry requiring a JSON
      Message 2 of 12 , Jun 24 9:49 PM
      • 0 Attachment
        hello mark.

        On 2013-06-24 21:17 , Mark Nottingham wrote:
        >> but i have one question about the general registry model: the current draft says that hints MUST have a name (very reasonable, of course), but also that hints MUST have their data model being defined in JSON.
        >> http://tools.ietf.org/html/draft-nottingham-link-hint-00#section-5.1
        >> living in a world where we have JSON services, XML services, and RDF services, it seems that hard-coding a specific language data model into such a spec (without constraining it in any way) will limit the utility of such a registry.
        > It needs *a* data model.

        yes, that's definitely true. i think what i'm trying to figure out a
        first is whether there is any precedence of a registry requiring a JSON
        data model, or any other specific language for that matter, for a
        structured values. it seems it's mostly specific micro-syntaxes (if any
        structure beyond identifiers is required), but i am really wondering
        about what people have usually done in similar situations.

        >> for example, in the Home Document draft, which is the original source of the link hint idea, the hints were hard-coded with very constrained data models. this made it relatively easy to expose them in a different syntax (in the XML Home Document draft):
        >> http://tools.ietf.org/html/draft-wilde-home-xml-01#page-4
        >> without getting too much into the details of this specific registry: what are the best practices about allowing/controlling language dependencies in registries?
        > Whoa, hold on - who said anything about a language? This is just the underlying data model; you can express it in a document however makes sense.

        that's kind of true, but not really. since the draft allows *any* kind
        of JSON, if i had a non-JSON document format (let's say XML ;-) that
        wanted to be able to represent registry values in general, it needs to
        define a generic mapping from *any* kind of JSON to XML. that's
        technically possible, but not really what works well for any non-JSON
        document model.

        i think this is my main argument: if you have a micro-syntax for the
        registry, you can map that much easier to something that maps reasonably
        well into a variety of document models. if you require JSON, and allow
        arbitrary JSON, the JSON bias translates into rather inconvenient models
        for any non-JSON language.

        >> personally, i would feel more comfortable with having a registry that is of equal value to people regardless of their implementation language
        > You're using "language" quite loosely here.

        maybe. and like i said above, apart from having implementation concerns
        about non-JSON formats, i am also really interested to learn about prior
        art: how was this problem approached/solved in other situations like this?

        >> , but then again that means that the registry itself must define a "mini-language" of its own.
        > -1. Defining Yet Another Data Model as a political solution to avoid picking an existing one is sub-optimal at best.

        not sure. if JSON is #1 on the requirement list, then maybe define a
        well-defined subset of JSON, so that mappings into other languages don't
        need to be able to handle *any* JSON?

        more specifically, what do the current hints actually need? it seems
        that the set of possibilities is actually rather small. for example,
        http://tools.ietf.org/html/draft-nottingham-link-hint-00#section-3.2
        says "Content MUST be an object, whose keys are media types, and values
        are objects", but what are the objects containing? maybe a simple array
        of media type strings would suffice? and then, if we can boil down the
        needs to "hints are strings or arrays of strings", then we can create
        good mappings for a variety of document models, and not just for JSON.

        cheers,

        dret.

        --
        erik wilde | mailto:dret@... - tel:+1-510-2061079 |
        | UC Berkeley - School of Information (ISchool) |
        | http://dret.net/netdret http://twitter.com/dret |
      • Mark Nottingham
        Please have a look at the draft; the level of detail in the registrations is a number or a list or (infrequently) an object -- roughly on par with saying
        Message 3 of 12 , Jun 25 2:46 AM
        • 0 Attachment
          Please have a look at the draft; the level of detail in the registrations is "a number" or "a list" or (infrequently) "an object" -- roughly on par with saying that a field in a registry is "an integer," which is quite common in IANA-land.


          On 25/06/2013, at 7:36 PM, Stephen Farrell <stephen.farrell@...> wrote:

          > Just had a a quick peek at this since we've seen a case where stuff went wrong because a registry contained structured data. Roughly: 1) can we have an early allocation to work with IEEE; 2) oops that bit there should've been a 1; 3) can we mark (1) as reserved and redo stuff?
          >
          > I think it's a mistake to ask IANA to handle structured data of any sort and this does that in spades.
          >
          > As a question: what makes you think this wouldn't be very likely to result in erroneous registrations? (Damaging the effectiveness of this registry but also possibly the IANA function, a bit)
          >
          > S
          >
          >
          > On 25 Jun 2013, at 05:17, Mark Nottingham <mnot@...> wrote:
          >
          >> Hi Erik,
          >>
          >> Sorry for the delay - just back home now.
          >>
          >>> but i have one question about the general registry model: the current draft says that hints MUST have a name (very reasonable, of course), but also that hints MUST have their data model being defined in JSON.
          >>>
          >>> http://tools.ietf.org/html/draft-nottingham-link-hint-00#section-5.1
          >>>
          >>> living in a world where we have JSON services, XML services, and RDF services, it seems that hard-coding a specific language data model into such a spec (without constraining it in any way) will limit the utility of such a registry.
          >>
          >> It needs *a* data model.
          >>
          >>> for example, in the Home Document draft, which is the original source of the link hint idea, the hints were hard-coded with very constrained data models. this made it relatively easy to expose them in a different syntax (in the XML Home Document draft):
          >>>
          >>> http://tools.ietf.org/html/draft-wilde-home-xml-01#page-4
          >>>
          >>> without getting too much into the details of this specific registry: what are the best practices about allowing/controlling language dependencies in registries?
          >>
          >> Whoa, hold on - who said anything about a language? This is just the underlying data model; you can express it in a document however makes sense.
          >>
          >>> personally, i would feel more comfortable with having a registry that is of equal value to people regardless of their implementation language
          >>
          >> You're using "language" quite loosely here.
          >>
          >>> , but then again that means that the registry itself must define a "mini-language" of its own.
          >>
          >> -1. Defining Yet Another Data Model as a political solution to avoid picking an existing one is sub-optimal at best.
          >>
          >> Cheers,
          >>
          >>
          >> --
          >> Mark Nottingham http://www.mnot.net/
          >>
          >>
          >>
          >> _______________________________________________
          >> apps-discuss mailing list
          >> apps-discuss@...
          >> https://www.ietf.org/mailman/listinfo/apps-discuss

          --
          Mark Nottingham http://www.mnot.net/
        • Erik Wilde
          hello mark. ... i really like the places where it says a number and a list , because these concepts can be easily mapped into pretty much any
          Message 4 of 12 , Jun 25 9:45 AM
          • 0 Attachment
            hello mark.

            On 2013-06-25 02:46 , Mark Nottingham wrote:
            > Please have a look at the draft; the level of detail in the registrations is "a number" or "a list" or (infrequently) "an object" -- roughly on par with saying that a field in a registry is "an integer," which is quite common in IANA-land.
            > On 25/06/2013, at 7:36 PM, Stephen Farrell <stephen.farrell@...> wrote:
            >> As a question: what makes you think this wouldn't be very likely to result in erroneous registrations? (Damaging the effectiveness of this registry but also possibly the IANA function, a bit)

            i really like the places where it says "a number" and "a list", because
            these concepts can be easily mapped into pretty much any representation.
            when it says "an object", however, that's an entirely different matter.
            it would be great for the registry to really be clear about what kind of
            structures to expect for hints (single values, value lists, and maybe
            lists of key/value pairs or something along those lines), and then the
            registry would not depend on a specific language.

            cheers,

            dret.

            --
            erik wilde | mailto:dret@... - tel:+1-510-2061079 |
            | UC Berkeley - School of Information (ISchool) |
            | http://dret.net/netdret http://twitter.com/dret |
          • Mark Nottingham
            ... It s certainly possible to map the JSON data model into XML; it just won t make XML people happy, because it ll have lots of elements named object and
            Message 5 of 12 , Jun 25 11:51 PM
            • 0 Attachment
              On 26/06/2013, at 2:45 AM, Erik Wilde <dret@...> wrote:

              > i really like the places where it says "a number" and "a list", because these concepts can be easily mapped into pretty much any representation. when it says "an object", however, that's an entirely different matter. it would be great for the registry to really be clear about what kind of structures to expect for hints (single values, value lists, and maybe lists of key/value pairs or something along those lines), and then the registry would not depend on a specific language.

              It's certainly possible to map the JSON data model into XML; it just won't make XML people happy, because it'll have lots of elements named "object" and "array" (although I see a fair amount of "native" XML like this anyway!).

              Likewise for (most any, since JSON is pretty basic) other data models.

              I very much agree that it would be good to not have a dependency upon the JSON data model here. However, I don't see a way to avoid that, without either a) using another data model with exactly the same problem, or b) prohibiting any structured information.

              AIUI you're suggesting (b). Looking through the current list of hints, we already have quite a few that need structure. Can you suggest how to convey the information without using structured data?

              Regards,

              --
              Mark Nottingham http://www.mnot.net/
            • Matt McClure
              ... Is it just an issue of terminology? If so, using the name of an abstract data type instead of the JSON name for it is an option. Something like associative
              Message 6 of 12 , Jun 26 5:04 AM
              • 0 Attachment
                On Jun 26, 2013, at 2:51 AM, Mark Nottingham <mnot@...> wrote:
                 

                Can you suggest how to convey the information without using structured data?

                Is it just an issue of terminology? If so, using the name of an abstract data type instead of the JSON name for it is an option. Something like associative arraymap, or dictionary.

                -- 
              • Erik Wilde
                hello mark. ... sure, with enough effort, anything can be mapped to anything. my point was to have something for the link hints that can be mapped into more
                Message 7 of 12 , Jun 26 10:25 AM
                • 0 Attachment
                  hello mark.

                  On 2013-06-25 23:51 , Mark Nottingham wrote:
                  >> i really like the places where it says "a number" and "a list", because these concepts can be easily mapped into pretty much any representation. when it says "an object", however, that's an entirely different matter. it would be great for the registry to really be clear about what kind of structures to expect for hints (single values, value lists, and maybe lists of key/value pairs or something along those lines), and then the registry would not depend on a specific language.
                  > It's certainly possible to map the JSON data model into XML; it just won't make XML people happy, because it'll have lots of elements named "object" and "array" (although I see a fair amount of "native" XML like this anyway!).

                  sure, with enough effort, anything can be mapped to anything. my point
                  was to have something for the link hints that can be mapped into more
                  useful structures for any target mapping, and not just for JSON.

                  > I very much agree that it would be good to not have a dependency upon the JSON data model here. However, I don't see a way to avoid that, without either a) using another data model with exactly the same problem, or b) prohibiting any structured information.
                  > AIUI you're suggesting (b). Looking through the current list of hints, we already have quite a few that need structure. Can you suggest how to convey the information without using structured data?

                  i think there are three possibilities:

                  - pick a generic format (such as JSON) as allow anything it allows. this
                  makes things great for JSON and not so great for non-JSON.

                  - be structure agnostic (hints are strings) and then hints will probably
                  define their own mappings into string-based structures (using regexes
                  and usual patterns such as whitespace- or comma-separated lists). this
                  might be bad because then parsing a hint's value needs to be done on a
                  per-hint basis.

                  - pick a small set of structures allowed such as the ones i suggested
                  above (single values, value lists, and maybe lists of key/value pairs)
                  and require that any hint is defined in terms of this more restricted
                  model. this maps better to many formats, but you're stuck with the
                  choices you make.

                  so my suggestion is not so much your (b) but my (c) ;-) fwiw, it seems
                  that thew current draft uses overly complicated structures, for example,
                  "formats" maybe just could be an array of formats?

                  it's clearly a trade-off between allowing arbitrarily structured hints
                  (in which case you need some generic metamodel) or predefining the kinds
                  of structures that hints can use (in which case you can remove the
                  dependency on a particular generic metamodel). i am still trying to
                  understand how that problem has been solved in similar cases. i assume
                  this is not the first (proposed) IANA registry that has to deal with
                  this tradeoff; does anybody have pointers to this has been handled in
                  similar cases?

                  thanks and cheers,

                  dret.

                  --
                  erik wilde | mailto:dret@... - tel:+1-510-2061079 |
                  | UC Berkeley - School of Information (ISchool) |
                  | http://dret.net/netdret http://twitter.com/dret |
                • Mark Nottingham
                  ... Yep, this is where we re at. ... I m -1 on this; it hasn t worked out so well for HTTP headers (and in fact a significant number of people are agitating to
                  Message 8 of 12 , Jun 26 4:40 PM
                  • 0 Attachment
                    On 27/06/2013, at 3:25 AM, Erik Wilde <dret@...> wrote:

                    > hello mark.
                    >
                    > On 2013-06-25 23:51 , Mark Nottingham wrote:
                    >>> i really like the places where it says "a number" and "a list", because these concepts can be easily mapped into pretty much any representation. when it says "an object", however, that's an entirely different matter. it would be great for the registry to really be clear about what kind of structures to expect for hints (single values, value lists, and maybe lists of key/value pairs or something along those lines), and then the registry would not depend on a specific language.
                    >> It's certainly possible to map the JSON data model into XML; it just won't make XML people happy, because it'll have lots of elements named "object" and "array" (although I see a fair amount of "native" XML like this anyway!).
                    >
                    > sure, with enough effort, anything can be mapped to anything. my point was to have something for the link hints that can be mapped into more useful structures for any target mapping, and not just for JSON.
                    >
                    >> I very much agree that it would be good to not have a dependency upon the JSON data model here. However, I don't see a way to avoid that, without either a) using another data model with exactly the same problem, or b) prohibiting any structured information.
                    >> AIUI you're suggesting (b). Looking through the current list of hints, we already have quite a few that need structure. Can you suggest how to convey the information without using structured data?
                    >
                    > i think there are three possibilities:
                    >
                    > - pick a generic format (such as JSON) as allow anything it allows. this makes things great for JSON and not so great for non-JSON.

                    Yep, this is where we're at.


                    > - be structure agnostic (hints are strings) and then hints will probably define their own mappings into string-based structures (using regexes and usual patterns such as whitespace- or comma-separated lists). this might be bad because then parsing a hint's value needs to be done on a per-hint basis.

                    I'm -1 on this; it hasn't worked out so well for HTTP headers (and in fact a significant number of people are agitating to just define new headers in JSON) nor for media type parameters.


                    > - pick a small set of structures allowed such as the ones i suggested above (single values, value lists, and maybe lists of key/value pairs) and require that any hint is defined in terms of this more restricted model. this maps better to many formats, but you're stuck with the choices you make.
                    >
                    > so my suggestion is not so much your (b) but my (c) ;-) fwiw, it seems that thew current draft uses overly complicated structures, for example, "formats" maybe just could be an array of formats?

                    Could you spell out an example?


                    > it's clearly a trade-off between allowing arbitrarily structured hints (in which case you need some generic metamodel) or predefining the kinds of structures that hints can use (in which case you can remove the dependency on a particular generic metamodel). i am still trying to understand how that problem has been solved in similar cases. i assume this is not the first (proposed) IANA registry that has to deal with this tradeoff; does anybody have pointers to this has been handled in similar cases?
                    >
                    > thanks and cheers,


                    Cheers,

                    --
                    Mark Nottingham http://www.mnot.net/
                  • Erik Wilde
                    hello mark. ... i agree that this is not such a great way to go. it makes things easy in the short run, but harder in the long run. in particular, it means
                    Message 9 of 12 , Jun 26 5:24 PM
                    • 0 Attachment
                      hello mark.

                      On 2013-06-26 16:40 , Mark Nottingham wrote:
                      > On 27/06/2013, at 3:25 AM, Erik Wilde <dret@...> wrote:
                      >>> I very much agree that it would be good to not have a dependency upon the JSON data model here. However, I don't see a way to avoid that, without either a) using another data model with exactly the same problem, or b) prohibiting any structured information.
                      >>> AIUI you're suggesting (b). Looking through the current list of hints, we already have quite a few that need structure. Can you suggest how to convey the information without using structured data?
                      >> i think there are three possibilities:
                      >> - pick a generic format (such as JSON) as allow anything it allows. this makes things great for JSON and not so great for non-JSON.
                      > Yep, this is where we're at.
                      >> - be structure agnostic (hints are strings) and then hints will probably define their own mappings into string-based structures (using regexes and usual patterns such as whitespace- or comma-separated lists). this might be bad because then parsing a hint's value needs to be done on a per-hint basis.
                      > I'm -1 on this; it hasn't worked out so well for HTTP headers (and in fact a significant number of people are agitating to just define new headers in JSON) nor for media type parameters.

                      i agree that this is not such a great way to go. it makes things easy in
                      the short run, but harder in the long run. in particular, it means that
                      the same concepts ("a list") may be serialized differently in different
                      hints (a "comma-separated" one, a "space-separated" one), which makes it
                      harder to build general facilities for hints.

                      >> - pick a small set of structures allowed such as the ones i suggested above (single values, value lists, and maybe lists of key/value pairs) and require that any hint is defined in terms of this more restricted model. this maps better to many formats, but you're stuck with the choices you make.
                      >> so my suggestion is not so much your (b) but my (c) ;-) fwiw, it seems that thew current draft uses overly complicated structures, for example, "formats" maybe just could be an array of formats?
                      > Could you spell out an example?

                      afaict, "formats"
                      (http://tools.ietf.org/html/draft-nottingham-link-hint-00#section-3.2)
                      right now says says it's an object with the keys being media types, but
                      the values are not specified. but maybe i am reading it wrong and where
                      it says "The object" in the second and third paragraph it actually
                      refers to the object that's a value of one of the keys? hmmm, i guess
                      that's what it means... i had been reading it wrong so far. but for a
                      minute, let's just assume it's only media types, which is how i am using
                      it in an example using link hints here:
                      https://github.com/dret/I-D/blob/master/link-desc/ld-atompub-00.xml

                      so let's assume for a minute that this is just a list. then i would
                      suggest is the following: the hint is defined as follows (stealing your
                      structure here):

                      o Hint Name: formats
                      o Description: Hints the representation type(s) that the target
                      resource can produce and consume, using the GET and PUT (if allowed)
                      methods respectively.
                      o Content Model: list
                      o Specification: [this document]
                      Content MUST be a list, whose values are media types.

                      then, the term "list" in the content model must be defined somewhere.
                      like i said, maybe we could say there are three "content models" hints
                      support: single values, lists, key/value pairs. how a particular hint
                      value would be serialized then would be up to the format where it's
                      being represented.

                      - in JSON, you might represent them as string, array, something else.

                      - in XML, you might choose a mix of element/attribute designs. or you
                      could go text-based such as my example (which is text-based because it
                      uses JSON syntax right now)

                      none of these representations would be binding, they would just be one
                      way of mapping the abstract link hint model into some concrete model. i
                      guess the only exception for this would be how to represent links
                      outside of media types, i.e. in HTTP.
                      http://tools.ietf.org/html/draft-nottingham-link-hint-00#appendix-A
                      could be changed then to map the abstract moden into a concrete JSON
                      syntax (or whatever else looks like a good syntax choice to go into a
                      Link header).

                      as i see it, when i design media types that use link hints, it would be
                      nice if i could expose them in a way that is as useful as possible for
                      consumers of that media type. my example from above is from an XML
                      design for link descriptions that i plan to base on link hints. if that
                      means that the XML-oriented clients using this format need to include a
                      general-purpose JSON parser, then that's certainly doable, but i don't
                      think the link hints design has to be like that.

                      but again, of course my option (c) means that link hints have a
                      predefined and probably small set of structures that hints can use to
                      expose whatever they want to expose, and if they want to go beyond that,
                      that's not covered by the link hint framework anymore.

                      cheers,

                      dret.

                      --
                      erik wilde | mailto:dret@... - tel:+1-510-2061079 |
                      | UC Berkeley - School of Information (ISchool) |
                      | http://dret.net/netdret http://twitter.com/dret |
                    • Mark Nottingham
                      ... Yes, I need to spell that out more completely. Thanks. ... I m all for that, IF we can be reasonably sure that the current data can fit comfortably into
                      Message 10 of 12 , Jul 3, 2013
                      • 0 Attachment
                        On 27/06/2013, at 10:24 AM, Erik Wilde <dret@...> wrote:
                        >>>
                        >>> so my suggestion is not so much your (b) but my (c) ;-) fwiw, it seems that thew current draft uses overly complicated structures, for example, "formats" maybe just could be an array of formats?
                        >> Could you spell out an example?
                        >
                        > afaict, "formats" (http://tools.ietf.org/html/draft-nottingham-link-hint-00#section-3.2) right now says says it's an object with the keys being media types, but the values are not specified. but maybe i am reading it wrong and where it says "The object" in the second and third paragraph it actually refers to the object that's a value of one of the keys?

                        Yes, I need to spell that out more completely. Thanks.


                        > hmmm, i guess that's what it means... i had been reading it wrong so far. but for a minute, let's just assume it's only media types, which is how i am using it in an example using link hints here: https://github.com/dret/I-D/blob/master/link-desc/ld-atompub-00.xml
                        >
                        > so let's assume for a minute that this is just a list. then i would suggest is the following: the hint is defined as follows (stealing your structure here):
                        >
                        > o Hint Name: formats
                        > o Description: Hints the representation type(s) that the target resource can produce and consume, using the GET and PUT (if allowed) methods respectively.
                        > o Content Model: list
                        > o Specification: [this document]
                        > Content MUST be a list, whose values are media types.
                        >
                        > then, the term "list" in the content model must be defined somewhere. like i said, maybe we could say there are three "content models" hints support: single values, lists, key/value pairs. how a particular hint value would be serialized then would be up to the format where it's being represented.
                        >
                        > - in JSON, you might represent them as string, array, something else.
                        >
                        > - in XML, you might choose a mix of element/attribute designs. or you could go text-based such as my example (which is text-based because it uses JSON syntax right now)
                        >
                        > none of these representations would be binding, they would just be one way of mapping the abstract link hint model into some concrete model. i guess the only exception for this would be how to represent links outside of media types, i.e. in HTTP. http://tools.ietf.org/html/draft-nottingham-link-hint-00#appendix-A could be changed then to map the abstract moden into a concrete JSON syntax (or whatever else looks like a good syntax choice to go into a Link header).

                        I'm all for that, IF we can be reasonably sure that the current data can fit comfortably into that simplified model.

                        The current hints that use "complex" objects are (keeping in mind that we've just started):
                        - formats
                        - links
                        - accept-post (same format as formats)
                        - auth-schemes

                        Formats and accept-post COULD specify a list of strings, and state that it's either a media type OR a profile URI. This means we'd need a separate representation format for profiles, which would need to convey a media type.

                        This is certainly possible, but the downsides I see are:
                        - It's baking in profiles in at a pretty high level. I like some aspects of profiles, but they certainly haven't taken off in mindshare yet.
                        - Parsing the string to check which it is is nasty.

                        For auth-schemes, we'd need to specify a tuple, probably. Not great, but OK. Extensibility would be right out the window, though, which may be significant for some schemes.

                        Links are fundamentally not possible without some really ugly mapping to a string, I think.

                        My concern is that this is starting not to meet my use cases for json-home, which is where link-hints comes from.

                        While I could address this by making those things NOT link hints, but other "bumps" on json-home, it would make it significantly more complex. That seems like a poor tradeoff, considering that it's *possible* to map generic hints into XML, it's just not "pretty."


                        > as i see it, when i design media types that use link hints, it would be nice if i could expose them in a way that is as useful as possible for consumers of that media type. my example from above is from an XML design for link descriptions that i plan to base on link hints. if that means that the XML-oriented clients using this format need to include a general-purpose JSON parser, then that's certainly doable, but i don't think the link hints design has to be like that.

                        To be brutally frank (and I'm sure this isn't going to surprise you too much, dret ;) I don't see a lot of value in catering to the XML API market; it's dying, and introducing constraints on the JSON APIs seems like a bad tradeoff.

                        I absolutely acknowledge that JSON will one day face its own demise, and will be in a similar situation, but planning for that seems like premature optimisation to me.


                        > but again, of course my option (c) means that link hints have a predefined and probably small set of structures that hints can use to expose whatever they want to expose, and if they want to go beyond that, that's not covered by the link hint framework anymore.


                        Yes. That's what I'm struggling with. We're already seeing a number of places that chafe against these constraints, and we're just getting started.

                        What do other folks think?

                        Cheers,


                        --
                        Mark Nottingham http://www.mnot.net/
                      • Erik Wilde
                        hello mark. ... i guess that s true. but i have to admit that i am struggling a bit with that specific hint anyway. it can hint at links you might find at the
                        Message 11 of 12 , Jul 5, 2013
                        • 0 Attachment
                          hello mark.

                          On 2013-07-04 3:30 , Mark Nottingham wrote:
                          >> none of these representations would be binding, they would just be one way of mapping the abstract link hint model into some concrete model. i guess the only exception for this would be how to represent links outside of media types, i.e. in HTTP. http://tools.ietf.org/html/draft-nottingham-link-hint-00#appendix-A could be changed then to map the abstract moden into a concrete JSON syntax (or whatever else looks like a good syntax choice to go into a Link header).
                          > I'm all for that, IF we can be reasonably sure that the current data can fit comfortably into that simplified model.
                          > The current hints that use "complex" objects are (keeping in mind that we've just started):
                          > - formats
                          > - links
                          > - accept-post (same format as formats)
                          > - auth-schemes
                          > Formats and accept-post COULD specify a list of strings, and state that it's either a media type OR a profile URI. This means we'd need a separate representation format for profiles, which would need to convey a media type.
                          > This is certainly possible, but the downsides I see are:
                          > - It's baking in profiles in at a pretty high level. I like some aspects of profiles, but they certainly haven't taken off in mindshare yet.
                          > - Parsing the string to check which it is is nasty.
                          > For auth-schemes, we'd need to specify a tuple, probably. Not great, but OK. Extensibility would be right out the window, though, which may be significant for some schemes.
                          > Links are fundamentally not possible without some really ugly mapping to a string, I think.

                          i guess that's true. but i have to admit that i am struggling a bit with
                          that specific hint anyway. it can hint at links you might find at the
                          target resource. it may contain hints, so it can also contain link
                          hints. so in theory, you could build a multi-level structure of links to
                          be expected several link traversals away, right?

                          more generally speaking, i am having troubles rationalizing hints that
                          give me some "preview" of the target resource. my personal mental model
                          of link hints is that they constrain interactions with the target
                          resource, but really don't tell you what to expect.

                          is http://tools.ietf.org/html/draft-nottingham-json-home-03#section-9
                          (the separation into "resource" and "representation" hints in the home
                          draft, where the link hint idea started) what might make te difference
                          between hints talking about interactions, and hints talking about the
                          result of an interaction?

                          > My concern is that this is starting not to meet my use cases for json-home, which is where link-hints comes from.

                          that would be bad, but again, i am struggling a bit with the hints that
                          tell you what to expect, and not just what to do. my thoughts were that
                          hints should just be about what to do; do you have a different model in
                          mind?

                          > While I could address this by making those things NOT link hints, but other "bumps" on json-home, it would make it significantly more complex. That seems like a poor tradeoff, considering that it's *possible* to map generic hints into XML, it's just not "pretty."
                          > To be brutally frank (and I'm sure this isn't going to surprise you too much, dret ;) I don't see a lot of value in catering to the XML API market; it's dying, and introducing constraints on the JSON APIs seems like a bad tradeoff.

                          yes, i am not overly surprised ;) but i am not really trying to optimize
                          this for XML, i just try to make it more workable for non-JSON consumers
                          in general. and i am still hoping that somebody will be able to point to
                          prior decisions that were made in similar situations: are there IANA
                          registries that are using JSON as a data model for their entries, and
                          which other approaches were taken in cases where registries attempted to
                          register structured entries? maybe we should just use ASN.1... ;-)

                          > I absolutely acknowledge that JSON will one day face its own demise, and will be in a similar situation, but planning for that seems like premature optimisation to me.

                          sure, and if the consensus is that it's ok to have JSON-based
                          registries, then this is how it is. personally, i think i will then use
                          serialized JSON in XML representations, which are a little less horrible
                          to look at than generic JSON serialized in JSON.

                          >> but again, of course my option (c) means that link hints have a predefined and probably small set of structures that hints can use to expose whatever they want to expose, and if they want to go beyond that, that's not covered by the link hint framework anymore.
                          > Yes. That's what I'm struggling with. We're already seeing a number of places that chafe against these constraints, and we're just getting started.
                          > What do other folks think?

                          good point, so far it's just mark and me. anybody who faced similar
                          design issues who could share their considerations and decisions?

                          thanks and cheers,

                          dret.

                          --
                          erik wilde | mailto:dret@... - tel:+1-510-2061079 |
                          | UC Berkeley - School of Information (ISchool) |
                          | http://dret.net/netdret http://twitter.com/dret |
                        Your message has been successfully submitted and would be delivered to recipients shortly.