|
410 | 410 | The value of "href" is to be used as a URI Template, as defined in <xref target="RFC6570">RFC 6570</xref>. However, some special considerations apply: |
411 | 411 | </t> |
412 | 412 |
|
413 | | - <section title="Pre-processing"> |
414 | | - <t> |
415 | | - <cref>This pre-processing section is subject to significant change in upcoming drafts.</cref> |
416 | | - </t> |
417 | | - <t> |
418 | | - The <xref target="RFC6570">URI Template specification</xref> restricts the set of characters available for variable names. |
419 | | - Property names in JSON, however, can be any UTF-8 string. |
420 | | - </t> |
421 | | - |
422 | | - <t> |
423 | | - To allow the use of any JSON property name in the template, before using the value of "href" as a URI Template, the following pre-processing rules MUST be applied, in order: |
424 | | - </t> |
425 | | - |
426 | | - <section title="Bracket escaping"> |
427 | | - <t> |
428 | | - The purpose of this step is to allow the use of brackets to percent-encode variable names inside curly brackets. |
429 | | - Variable names to be escaped are enclosed within rounded brackets, with the close-rounded-bracket character ")" being escaped as a pair of close-rounded-brackets "))". |
430 | | - Since the empty string is not a valid variable name in RFC 6570, an empty pair of brackets is replaced with "%65mpty". |
431 | | - </t> |
432 | | - |
433 | | - <t> |
434 | | - The rules are as follows: |
435 | | - </t> |
436 | | - |
437 | | - <t> |
438 | | - Find the largest possible sections of the text such that: |
439 | | - <list> |
440 | | - <t>do not contain an odd number of close-rounded-bracket characters ")" in sequence in that section of the text</t> |
441 | | - <t>are surrounded by a pair of rounded brackets: ( ), where</t> |
442 | | - <t>the surrounding rounded brackets are themselves contained within a pair of curly brackets: { }</t> |
443 | | - </list> |
444 | | - </t> |
445 | | - <t> |
446 | | - Each of these sections of the text (including the surrounding rounded brackets) MUST be replaced, according to the following rules: |
447 | | - <list> |
448 | | - <t>If the brackets contained no text (the empty string), then they are replaced with "%65mpty" (which is "empty" with a percent-encoded "e")</t> |
449 | | - <t>Otherwise, the enclosing brackets are removed, and the inner text used after the following modifications |
450 | | - <list> |
451 | | - <t>all pairs of close-brackets "))" are replaced with a single close bracket</t> |
452 | | - <t>after that, the text is replaced with its percent-encoded equivalent, such that the result is a valid RFC 6570 variable name (note that this requires encoding characters such as "*" and "!")</t> |
453 | | - </list> |
454 | | - </t> |
455 | | - </list> |
456 | | - </t> |
457 | | - </section> |
458 | | - |
459 | | - <section title="Replacing $"> |
460 | | - <t> |
461 | | - After the above substitutions, if the character "$" (dollar sign) appears within a pair of curly brackets, then it MUST be replaced with the text "%73elf" (which is "self" with a percent-encoded "s"). |
462 | | - </t> |
463 | | - <t> |
464 | | - The purpose of this stage is to allow the use of the instance value itself (instead of its object properties or array items) in the URI Template, by the special value "%73elf". |
465 | | - </t> |
466 | | - </section> |
467 | | - |
468 | | - <section title="Choice of special-case values"> |
469 | | - <t> |
470 | | - The special-case values of "%73elf" and "%65mpty" were chosen because they are unlikely to be accidentally generated by either a human or automated escaping. |
471 | | - </t> |
472 | | - </section> |
473 | | - |
474 | | - <section title="Examples"> |
475 | | - <texttable> |
476 | | - <preamble>For example, here are some possible values for "href", followed by the results after pre-processing:</preamble> |
477 | | - <ttcol>Input</ttcol> |
478 | | - <ttcol>Output</ttcol> |
479 | | - <c>"no change"</c> <c>"no change"</c> |
480 | | - <c>"(no change)"</c> <c>"(no change)"</c> |
481 | | - <c>"{(escape space)}"</c> <c>"{escape%20space}"</c> |
482 | | - <c>"{(escape+plus)}"</c> <c>"{escape%2Bplus}"</c> |
483 | | - <c>"{(escape*asterisk)}"</c> <c>"{escape%2Aasterisk}"</c> |
484 | | - <c>"{(escape(bracket)}"</c> <c>"{escape%28bracket}"</c> |
485 | | - <c>"{(escape))bracket)}"</c> <c>"{escape%29bracket}"</c> |
486 | | - <c>"{(a))b)}"</c> <c>"{a%29b}</c> |
487 | | - <c>"{(a (b)))}"</c> <c>"{a%20%28b%29}</c> |
488 | | - <c>"{()}"</c> <c>"{%65mpty}</c> |
489 | | - <c>"{+$*}"</c> <c>"{+%73elf*}</c> |
490 | | - <c>"{+($)*}"</c> <c>"{+%24*}</c> |
491 | | - <postamble> |
492 | | - Note that in the final example, because the "+" was outside the brackets, it remained unescaped, whereas in the fourth example the "+" was escaped. |
493 | | - </postamble> |
494 | | - </texttable> |
495 | | - </section> |
496 | | - </section> |
497 | | - |
498 | 413 | <section title="Values for substitution"> |
499 | 414 | <t> |
500 | 415 | After pre-processing, the URI Template is filled out using data from some combination of an externa source and the instance. |
|
507 | 422 | <t> |
508 | 423 | For a given variable name in the URI Template, the value to use is determined as follows: |
509 | 424 | <list> |
510 | | - <t>If the variable name is "%73elf", then the value itself MUST be used.</t> |
511 | | - <t>If the variable name is "%65mpty", then the empty-string ("") property MUST be used (if it exists).</t> |
512 | 425 | <t>If the data is an array, and the variable name is a representation of a non-negative integer, then the value at the corresponding array index MUST be used (if it exists).</t> |
513 | 426 | <t>Otherwise, the variable name should be percent-decoded, and the corresponding object property MUST be used (if it exists).</t> |
514 | 427 | </list> |
|
0 commit comments