Draft: draft-ietf-httpapi-yaml-mediatypes

Commentary: This defines fragment identifiers to be parsed as YAML aliases , which currently means that they must point to an explicitly defined anchor in the document , a feature natively supported by YAML . The definition intentionally allows for changes in later editions of the YAML spec to be automatically supported , e.g. as we 're working towards supporting something like  pointers as well . The language in the fragment identifier section seems a bit complex , and I 'm not sure if it should be updated as well . Formats should be allowed to define their own rules for fragment identifiers . Is this currently the case ? 
 Can you please add an example YAML URI with fragment identifier , so that we could find a way to provide it ? 
 Struggling a bit to figure out just what you 're looking for here . For an example of how this would work , let 's presume that we have with the following contents : Then , would be pointing at the node with the value , while would point to the node with the value . Do you want this sort of example to be included in the RFC ? 
 probably it could be useful to add either an example section or a normative section that explicits that . An alternative could be to add this information in the YAML spec .  ? I imagine something brief like which includes some considerations on percent - encoding and some examples . A couple of question , for example : yaml can be encoded in UTF-8 , 16 , 32 . Can anchor / alias nodes identifier be non - ascii / non - utf8 encoded ? 
 Let 's discuss this topic in the issue 
 The YAML spec already includes sections on and , which then include some examples of them in use . The intent here is to defer to that spec 's definition of alias nodes . At the point where the YAML spec defines anchors and aliases , it 's treating its input as a sequence of Unicode code points , i.e. it does n't care about their encoding . The YAML 1.2 set of acceptable characters for these is tbh far too wide , as it allows for nearly all printable Unicode code points . 
 reading iiuc I need to % encode the string , right ? In this case I am not sure how this should work with UTF-8 , 16 , 32 ... Can you make some examples ? ( maybe related to ) 
 Merging and moving discussion in 
 Currently the spec supports fragment identifier based on " named anchors " , e.g. references . Today alias nodes syntax is , but in the future alias nodes could support " pathlike " expressions , e.g. . Can " named anchors " fragment identifiers be extended in the future in a backward compatible way to suppot " alias nodes " syntax ? Consider the following examples is a valid character for a named anchor , using as a pathlike separator might be non - trivial . Currently many YAML parser do only support though , so future YAML spec might restrict the syntax of named anchors might contain non - string characters ( e.g. vs ) . We need to know how pathlike elements are serialized , to identify a human - readable encoding ( e.g.   ) example . A non human - readable encoding such as base64url would solve the issue , since we could just decode the string . This could be supported when pathlike are messy , e.g. 
 Feedback from Maybe we could use something like 
 The easiest solution might be to initially restrict valid characters in the fragment identifier to . This would mean that while not all anchors are addressable , most would be . It would also allow relatively easy extension e.g. by making invalid as an fragment identifier , and therefore usable by a schema that extends it . Not sure how to express it , but it might be good to still reserve for future use by later YAML versions ? 
 Or you could do the inverse and just keep = for application - specific fragment identifier schemes . BTW , why do n't you include  pointer ( RFC6901 ) in the standard set ? That is quite useful for the majority of YAML applications ( certainly the JSON compatible ones ) . 
 WRT sub - mediatypes like openapi and jsonschema , we are discussing in jsonschema supports two fragment identifiers : JSON Pointers and . Plain names are just strings , e.g. " foo " . We could ask if there is some space to tweak the usage of plain names as fragment identifiers . I think it would be useful , but I think it 's YAML community choice ( aka ) . Probably the easiest way to do it is : use JSONPointers if starts with use alias names if starts with This will allow further space for subtypes , eg . use jsonpath if starts with I am not sure that using unstructured strings as fragment identifiers is an interoperable choice at all . What do you think ? 
 What 's the problem that we 're trying to solve here ? If we 're talking about fragment identifiers for , I do n't see why we need to consider other specs at all . If we 're talking about fragment identifiers for , we currently have this : Hence I think the proposal to limit fragment identifiers to makes sense , as that 'll allow targeting nearly all real - world YAML anchors while keeping future YAML - spec compatibility good . Which may later bring in " native " support for something like JSON Pointers , and which this mediatype spec should not try to pre - empt . For cases , many formats need to be embeddable in JSON as well and include some form of internal anchor syntax . Those may of may not want to make the YAML anchors addressable by fragment identifiers as well , but they get to make that choice independently , much like they do already for . 
 Q1 . What 's the problem that we 're trying to solve here ? Identify a fragment identifier syntax that is compatible with existing formats like jsonpath and  pointers Q2 . Why ? Because implementers are accustomed to use json pointers and could for example just ignore our syntax Q3 . Should n't implementers use JSON Pointers only when using openapi+yaml ? Theoretically yes . In practice , since openapi+yaml is not yet registered , implementers just use application / yaml + JSON Pointers . Using will at the same time : enable support for alias nodes ( provided that a suitable encoding is defined in future YAML version ) enable implementation to distinguish between  pointers and alias nodes just using the first character . Q4 . What happens if we do n't find a workaround for JSON Pointers ? There 's the possibility that implementers will anyway continue to use JSON Pointers for processing fragment identifiers . Q4 . Is there some interest in using JSON Pointers in conjunction with ? While I thought there was n't , iiuc wrote that there could be some interest for that ( but please correct me if I 'm wrong ) . 
 We could ask if there is some space to tweak the usage of plain names as fragment identifiers . There 's no reason we could n't constrain how plain name fragments work in future dialects of   , but we still would n't be able to change the media type definition because then it would n't support the existing dialects that do n't have those constraints . 
 Since with plain names do not overlap with application / yaml fragment syntax , implementers could decide to process fragments where ( 0 , " " ) = ~ /^[a - zA - Z]/ as plain names and still be interoperable with YAML . This behavior wo n't be interoperable with other + yaml media types that redefine fragment syntax though . Question : should we specify that supporting further syntaxes in conjunction with application / yaml could create interoperability issues with future implementations ? cc : 
 Closed in 
 Compile fragment identifier section [ ] for [ x ] for ? Can we pospone this ? 
 It seems strange to me that a media type would define a new " language " intrinsic . 
 I believe the registration should include the fragment identifier .   does not identify one , which creates problems . It probably should have a registration update to address it . Not registering fragment handling means that a reference to a YAML - borne schema can not be referenced . The part beyond the # would be formally nonsensical ( as it is today ) . We can take some inspiration from the work on the same issue for   .   tells us how to craft fragments . The same format applies to the semantic equivalent in YAML documents . I 'll put in a pull request . 
 we have splitted the two documents . I think that yaml fragment identifiers should probably be delegated to " structured " media types since there are multiple possibilities ( eg .  - path ,  pointers , ... ) WRT openapi+yaml for example , we can state that the fragment uses json pointers . 
 Can you confirm that the YAML community agrees with the current statement wrt fragment identifiers ? 
 I 'm pretty sure that fragment identifiers should not be defined for at least for now . As demonstrated e.g. by the work going on even in this repo , YAML is used to represent multiple different forms of structured data , some of which may at times be represented by other formats , such as JSON . So while YAML 1.1 and 1.2 do explicitly support on nodes that would rather naturally work as fragment identifiers , there 's somewhat significant risk that this would complicate usage with sub - formats that natively use different methods , such as JSON Pointers . On the other hand , defining fragment identifiers for to follow the YAML spec for referring to anchors would make sense . 
 FWIW , I completely agree . 
 The choice to leave the fragment identifier of the structured syntax suffix to the media type is sensible : I will PR that .
The fragment identifier is parsed as if it were a YAML alias node,
but without a leading "*" indicator.  For example, in YAML 1.2,
this means that it designates a node which has a correspondingly
named anchor.  If multiple nodes would match a fragment
identifier, the first such match is selected.