From: David H. <dav...@bl...> - 2004-09-06 14:41:21
|
Oren Ben-Kiki wrote: > Since it seems a lot of people don't get what #7 is all about. It is a rather > minor change to the current spec (as compared to the rest of the proposals), > and doesn't go into "what's the meaning of life" issues at all - it tries to > keep to the physics of the issue. Here's a more format description using > Clark's template: > > summary: > > This is draft 7b, based on the 7th pass draft, David's additions, and > the new directive syntax. Note that it is describing mainly #7a, not #7b. Corrections below. > - Missing (unspecified, implicit) tags are handled in the way > specified in the spec today. However, it seems possible to > describe this handling using improved wording; see "Unspecified > tags" below. I'll leave all discussion of unspecified tags to another post. > The details: > > R1: Directive syntax > > - Using the current spec's syntax, the directive > would look like: > > %TAG:foo.com,2002:stuff!handle > > Note the "!" is NOT optional, but the handle is (a missing handle > sets the prefix of the empty handle). > > Also note this is intentionally restricted to the 'tag:' URI scheme. > > - Using Clark's proposed "1.1" changes, the directive would look like: > > %TAG foo.com,2002:stuff handle > > Where the "handle" is optional (a missing "handle" sets the prefix > for the empty handle). > > - David pointed out that it is more intuitive to put the prefix first, and > that we can use a generic %PREFIX directive applying to any URI > rather than a %TAG directive specific to tag: URIs: > > %PRE handle http://foo.com/bar %PRE handle! http://foo.com/bar (The reason for requiring the ! is that either the handle or prefix can be empty, and that creates an ambiguity if there is no separator.) > Clark and I feel that we should not be promoting the use of any URL > scheme for tags (for very good reasons, we thing that tags should be > URNs and not URLs). The 'tag:' URI (URN, not URL) scheme was > designed _exactly_ according to the needs of something like YAML > tags, so we want to promote using that. Hence we prefer to stick with > %TAG and reserve the right to add %FOO later on if another URI > scheme, 'foo:', becomes relevant. I also agree that tag: URIs are designed exactly according to the needs of YAML, but I will explain the motivations behind making this change in #7b. The context was that Clark complained about how private tags are reported to the application in #7a: Clark wrote: # Oren wrote: # | Clark wrote: # | > - I don't like the idea of a default-default tag. I'd much rather say # | > that tag-specifiers like !! are simply not subject to default tag # | > globalization. # | # | The whole _point_ of #7 is that they _are_. So, in the context of #7, # | David's proposal of a default-default %TAG makes tons of sense, and # | as he points out, it increases backward compatibility again. # # Having !sometag reported to my application as # tag:private.yaml.org,2002:sometag is really hackish. I put in !sometag, # I should get 'sometag'. (Clark meant !!sometag, since !sometag would cook to "tag:yaml.org,2002:sometag" in #7a.) So in #7b, by default "!!sometag" will cook to "sometag". To do that the default-default prefix must be "". We also want to be able to use the private namespace after globalization. This requires *either* another special case, or the ability for the ordinary %TAG/%PRE directive to define a prefix without "tag:". #7b uses the latter. Other considerations were: - allowing other schemes in %PRE does not prevent the specification from strongly recommending the use of tag: URIs. Note that any scheme is allowed in a full URI in all variants of #7, so specifying %TAG instead of %PRE does not prevent anyone from using other URI schemes, it only makes them second-class, because prefixing is not supported. (Another way that people could use to map non-tag: URIs to tag: URIs would be to prefix them with something like "tag:workaround.org,2004:") - supporting other schemes fully can be viewed as a feature in terms of interoperability with XML. For example, we might want to treat an XML qualified name as a YAML tag, using an automatic mapping from XML to a YAML sequence of key:value pairs allowing duplicates. In any case, the differences between #7a and #7b are less than between the #7 proposals and the others. Note that allowing the no-!-prefix to be redefined is orthogonal to the other differences between #7a and #7b. At the moment, #7a seems to have more support than #7b (although we don't know what Brian thinks). I'm quite happy with that. > R2: The default <prefix> of <empty-handle>. > > - The original proposal was that this prefix be "", or possibly "!", so > that the cooked tag did not clash with any URI tag. This is nice and > intuitive ("!!foo" gets cooked as "!foo"). In this case, of course that > cooked private tags are not valid URIs. However, it is desirable > that they be valid suffixed for tag: URIs in case the document is > ever "globalized". > > - Onoma pointed out that it is impossible to specify a "private" tag if > the <prefix> of the <empty-handle> is overriden by a directive. This > can be seen as a feature. > > - Alternatively, we can say that the default <prefix> of the > <empty-handle> is "tag:private.yaml:org:". "tag:private.yaml.org,2002:" > This allows an explicit > handle to be associated with this prefix and then be used to specify > private tags. In this case, cooked private tags _are_ required to be > valid URIs. > > - Finally, a slightly magical option is to allow writing: > > %TAG ! <handle> > > To specify that all "!<handle>!<stuff>" tags be cooked as "!<stuff>". > That is, they become "private" tags. This does not require private > tags to have a URI, ensures they can't collide with URIs, and allows > private tags to be given even if the <empty-handle> is given a > global prefix. For #7a, the proposal was to write "%TAG private.yaml.org,2002: <handle>", which would cook "!<handle>!<stuff>" to "tag:private.yaml.org,2002:<stuff>". For #7b, it was to write "%PRE ! <handle>", which would cook "!<handle>!<stuff>" to "<stuff>". Neither of these are even slightly magical. > Examples: > > The following examples use the new directive syntax. > However, this isn't an inherent part of the proposal. Also, > the examples assume no URI for private tags, and that > "%TAG ! handle" is used for being able to specifty > a handle for private tags (that's one of the alternatives; > personally I'd prefer a full URI for private tags). > > John's private config file: > > --- > age: 12 # cooked as "unspecified-plain" > # but, if you need them: > john's mine: !!mine # cooked as "!mine" in #7a: cooked as "tag:private.yaml.org:2002,mine" in #7b: cooked as "mine" (It would be possible to cook it as "!mine" just by changing the default-!-prefix to "!".) [...] > A complete list of tag form samples: > > Without %TAG directive: > > --- > unspecified: > plain: ~ # cooked: "unspecified-plain" > quoted: "~" # cooked: "unspecifed-scalar" > mapping: {} # cooked: "unspecified-mapping" > sequence: [] # cooked: "unspecified-sequence" > private: !!foo # cooked: "!foo" in #7a: cooked as "tag:private.yaml.org:2002,foo" in #7b: cooked as "foo" [...] > With %TAG directive for 'foo': > > %TAG foo.com,2004: foo > --- > unspecified: > plain: ~ # cooked: "unspecified-plain" > quoted: "~" # cooked: "unspecifed-scalar" > mapping: {} # cooked: "unspecified-mapping" > sequence: [] # cooked: "unspecified-sequence" > private: !!foo # cooked: "!foo" same as above > uri: !http://domain.com/tag # cooked: "http://domain.com/tag" > yaml: !int # cooked: "tag:yaml.org,2002:int" > global: !foo!bar # cooked: "tag:foo.com.2004:foo/bar" cooked as "tag:foo.com,2004:bar". > With default %TAG: > > %TAG baz.com,2004: > --- > unspecified: > plain: ~ # cooked: "unspecified-plain" > quoted: "~" # cooked: "unspecifed-scalar" > mapping: {} # cooked: "unspecified-mapping" > sequence: [] # cooked: "unspecified-sequence" > private: !!foo # cooked: "!tag:baz.com,2004:foo" > uri: !http://domain.com/tag # cooked: "http://domain.com/tag" > yaml: !int # cooked: "tag:yaml.org,2002:int" > global: !foo!bar # cooked: "tag:foo.com.2004:foo/bar" cooked as "tag:foo.com,2004:bar". > With 'foo' as private and default %TAG: > > %TAG ! foo see comments above. Assume #7a and "%TAG:private.yaml.org,2002:!foo". > %TAG baz.com,2004: > --- > unspecified: > plain: ~ # cooked: "unspecified-plain" > quoted: "~" # cooked: "unspecifed-scalar" > mapping: {} # cooked: "unspecified-mapping" > sequence: [] # cooked: "unspecified-sequence" > private: !!foo # cooked: "!tag:baz.com,2004:foo" > uri: !http://domain.com/tag # cooked: "http://domain.com/tag" > yaml: !int # cooked: "tag:yaml.org,2002:int" > global: !foo!bar # cooked: "!bar" cooked as "tag:private.yaml.org,2002:!bar". -- David Hopwood <dav...@bl...> |