Internet Engineering Task Force (IETF)                       J. Gregorio
Request for Comments: 6570                                        Google
Category: Standards Track                                    R. Fielding
ISSN: 2070-1721                                                    Adobe
                                                               M. Hadley
                                                                   MITRE
                                                           M. Nottingham
                                                               Rackspace
                                                              D. Orchard
                                                          Salesforce.com
                                                              March 2012
        
Internet Engineering Task Force (IETF)                       J. Gregorio
Request for Comments: 6570                                        Google
Category: Standards Track                                    R. Fielding
ISSN: 2070-1721                                                    Adobe
                                                               M. Hadley
                                                                   MITRE
                                                           M. Nottingham
                                                               Rackspace
                                                              D. Orchard
                                                          Salesforce.com
                                                              March 2012
        

URI Template

URI模板

Abstract

摘要

A URI Template is a compact sequence of characters for describing a range of Uniform Resource Identifiers through variable expansion. This specification defines the URI Template syntax and the process for expanding a URI Template into a URI reference, along with guidelines for the use of URI Templates on the Internet.

URI模板是一个紧凑的字符序列,用于通过变量扩展描述一系列统一的资源标识符。本规范定义了URI模板语法和将URI模板扩展为URI引用的过程,以及在Internet上使用URI模板的指南。

Status of This Memo

关于下段备忘

This is an Internet Standards Track document.

这是一份互联网标准跟踪文件。

This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on Internet Standards is available in Section 2 of RFC 5741.

本文件是互联网工程任务组(IETF)的产品。它代表了IETF社区的共识。它已经接受了公众审查,并已被互联网工程指导小组(IESG)批准出版。有关互联网标准的更多信息,请参见RFC 5741第2节。

Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at http://www.rfc-editor.org/info/rfc6570.

有关本文件当前状态、任何勘误表以及如何提供反馈的信息,请访问http://www.rfc-editor.org/info/rfc6570.

Copyright Notice

版权公告

Copyright (c) 2012 IETF Trust and the persons identified as the document authors. All rights reserved.

版权所有(c)2012 IETF信托基金和确定为文件作者的人员。版权所有。

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must

本文件受BCP 78和IETF信托有关IETF文件的法律规定的约束(http://trustee.ietf.org/license-info)自本文件出版之日起生效。请仔细阅读这些文件,因为它们描述了您对本文件的权利和限制。从该文档中提取的代码组件必须

include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.

包括信托法律条款第4.e节中所述的简化BSD许可证文本,且不提供简化BSD许可证中所述的担保。

Table of Contents

目录

   1. Introduction ....................................................3
      1.1. Overview ...................................................3
      1.2. Levels and Expression Types ................................5
      1.3. Design Considerations ......................................9
      1.4. Limitations ...............................................10
      1.5. Notational Conventions ....................................11
      1.6. Character Encoding and Unicode Normalization ..............12
   2. Syntax .........................................................13
      2.1. Literals ..................................................13
      2.2. Expressions ...............................................13
      2.3. Variables .................................................14
      2.4. Value Modifiers ...........................................15
           2.4.1. Prefix Values ......................................15
           2.4.2. Composite Values ...................................16
   3. Expansion ......................................................18
      3.1. Literal Expansion .........................................18
      3.2. Expression Expansion ......................................18
           3.2.1. Variable Expansion .................................19
           3.2.2. Simple String Expansion: {var} .....................21
           3.2.3. Reserved Expansion: {+var} .........................22
           3.2.4. Fragment Expansion: {#var} .........................23
           3.2.5. Label Expansion with Dot-Prefix: {.var} ............24
           3.2.6. Path Segment Expansion: {/var} .....................24
           3.2.7. Path-Style Parameter Expansion: {;var} .............25
           3.2.8. Form-Style Query Expansion: {?var} .................26
           3.2.9. Form-Style Query Continuation: {&var} ..............27
   4. Security Considerations ........................................27
   5. Acknowledgments ................................................28
   6. References .....................................................28
      6.1. Normative References ......................................28
      6.2. Informative References ....................................29
   Appendix A. Implementation Hints ..................................30
        
   1. Introduction ....................................................3
      1.1. Overview ...................................................3
      1.2. Levels and Expression Types ................................5
      1.3. Design Considerations ......................................9
      1.4. Limitations ...............................................10
      1.5. Notational Conventions ....................................11
      1.6. Character Encoding and Unicode Normalization ..............12
   2. Syntax .........................................................13
      2.1. Literals ..................................................13
      2.2. Expressions ...............................................13
      2.3. Variables .................................................14
      2.4. Value Modifiers ...........................................15
           2.4.1. Prefix Values ......................................15
           2.4.2. Composite Values ...................................16
   3. Expansion ......................................................18
      3.1. Literal Expansion .........................................18
      3.2. Expression Expansion ......................................18
           3.2.1. Variable Expansion .................................19
           3.2.2. Simple String Expansion: {var} .....................21
           3.2.3. Reserved Expansion: {+var} .........................22
           3.2.4. Fragment Expansion: {#var} .........................23
           3.2.5. Label Expansion with Dot-Prefix: {.var} ............24
           3.2.6. Path Segment Expansion: {/var} .....................24
           3.2.7. Path-Style Parameter Expansion: {;var} .............25
           3.2.8. Form-Style Query Expansion: {?var} .................26
           3.2.9. Form-Style Query Continuation: {&var} ..............27
   4. Security Considerations ........................................27
   5. Acknowledgments ................................................28
   6. References .....................................................28
      6.1. Normative References ......................................28
      6.2. Informative References ....................................29
   Appendix A. Implementation Hints ..................................30
        
1. Introduction
1. 介绍
1.1. Overview
1.1. 概述

A Uniform Resource Identifier (URI) [RFC3986] is often used to identify a specific resource within a common space of similar resources (informally, a "URI space"). For example, personal web spaces are often delegated using a common pattern, such as

统一资源标识符(URI)[RFC3986]通常用于在类似资源的公共空间(非正式地称为“URI空间”)内标识特定资源。例如,个人web空间通常使用公共模式进行委派,例如

     http://example.com/~fred/
     http://example.com/~mark/
        
     http://example.com/~fred/
     http://example.com/~mark/
        

or a set of dictionary entries might be grouped in a hierarchy by the first letter of the term, as in

或者,一组词典条目可以按照术语的第一个字母在层次结构中分组,如中所示

     http://example.com/dictionary/c/cat
     http://example.com/dictionary/d/dog
        
     http://example.com/dictionary/c/cat
     http://example.com/dictionary/d/dog
        

or a service interface might be invoked with various user input in a common pattern, as in

或者,可以使用公共模式中的各种用户输入调用服务接口,如

     http://example.com/search?q=cat&lang=en
     http://example.com/search?q=chien&lang=fr
        
     http://example.com/search?q=cat&lang=en
     http://example.com/search?q=chien&lang=fr
        

A URI Template is a compact sequence of characters for describing a range of Uniform Resource Identifiers through variable expansion.

URI模板是一个紧凑的字符序列,用于通过变量扩展描述一系列统一的资源标识符。

URI Templates provide a mechanism for abstracting a space of resource identifiers such that the variable parts can be easily identified and described. URI Templates can have many uses, including the discovery of available services, configuring resource mappings, defining computed links, specifying interfaces, and other forms of programmatic interaction with resources. For example, the above resources could be described by the following URI Templates:

URI模板提供了一种抽象资源标识符空间的机制,这样就可以很容易地识别和描述可变部分。URI模板有很多用途,包括发现可用服务、配置资源映射、定义计算链接、指定接口以及其他形式的与资源的编程交互。例如,可以通过以下URI模板来描述上述资源:

     http://example.com/~{username}/
     http://example.com/dictionary/{term:1}/{term}
     http://example.com/search{?q,lang}
        
     http://example.com/~{username}/
     http://example.com/dictionary/{term:1}/{term}
     http://example.com/search{?q,lang}
        

We define the following terms:

我们定义了以下术语:

expression: The text between '{' and '}', including the enclosing braces, as defined in Section 2.

表达式:“{”和“}”之间的文本,包括第2节中定义的括号。

expansion: The string result obtained from a template expression after processing it according to its expression type, list of variable names, and value modifiers, as defined in Section 3.

展开:根据模板表达式的表达式类型、变量名列表和值修饰符(如第3节所定义)对其进行处理后,从模板表达式获得的字符串结果。

template processor: A program or library that, given a URI Template and a set of variables with values, transforms the template string into a URI reference by parsing the template for expressions and substituting each one with its corresponding expansion.

模板处理器:一个程序或库,给定一个URI模板和一组带值的变量,通过解析模板中的表达式并用相应的扩展替换每个表达式,将模板字符串转换为URI引用。

A URI Template provides both a structural description of a URI space and, when variable values are provided, machine-readable instructions on how to construct a URI corresponding to those values. A URI Template is transformed into a URI reference by replacing each delimited expression with its value as defined by the expression type and the values of variables named within the expression. The expression types range from simple string expansion to multiple name=value lists. The expansions are based on the URI generic syntax, allowing an implementation to process any URI Template without knowing the scheme-specific requirements of every possible resulting URI.

URI模板提供URI空间的结构描述,并且在提供变量值时,提供关于如何构造与这些值对应的URI的机器可读指令。通过使用表达式类型和表达式中命名的变量值定义的值替换每个分隔表达式,将URI模板转换为URI引用。表达式类型的范围从简单的字符串扩展到多个名称=值列表。扩展基于URI通用语法,允许实现处理任何URI模板,而不知道每个可能产生的URI的特定于方案的要求。

For example, the following URI Template includes a form-style parameter expression, as indicated by the "?" operator appearing before the variable names.

例如,下面的URI模板包括一个表单样式参数表达式,如变量名称前出现的“?”运算符所示。

     http://www.example.com/foo{?query,number}
        
     http://www.example.com/foo{?query,number}
        

The expansion process for expressions beginning with the question-mark ("?") operator follows the same pattern as form-style interfaces on the World Wide Web:

以问号(“?”)运算符开头的表达式的扩展过程遵循与万维网上表单样式接口相同的模式:

     http://www.example.com/foo{?query,number}
                               \_____________/
                                  |
                                  |
             For each defined variable in [ 'query', 'number' ],
             substitute "?" if it is the first substitution or "&"
             thereafter, followed by the variable name, '=', and the
             variable's value.
        
     http://www.example.com/foo{?query,number}
                               \_____________/
                                  |
                                  |
             For each defined variable in [ 'query', 'number' ],
             substitute "?" if it is the first substitution or "&"
             thereafter, followed by the variable name, '=', and the
             variable's value.
        

If the variables have the values

如果变量具有

     query  := "mycelium"
     number := 100
        
     query  := "mycelium"
     number := 100
        

then the expansion of the above URI Template is

然后对上述URI模板进行扩展

     http://www.example.com/foo?query=mycelium&number=100
        
     http://www.example.com/foo?query=mycelium&number=100
        

Alternatively, if 'query' is undefined, then the expansion would be

或者,如果“查询”未定义,则扩展将是

     http://www.example.com/foo?number=100
        
     http://www.example.com/foo?number=100
        

or if both variables are undefined, then it would be

或者,如果两个变量都未定义,那么它将是

     http://www.example.com/foo
        
     http://www.example.com/foo
        

A URI Template may be provided in absolute form, as in the examples above, or in relative form. A template is expanded before the resulting reference is resolved from relative to absolute form.

URI模板可以以绝对形式提供,如上面的示例所示,也可以以相对形式提供。在将结果引用从相对形式解析为绝对形式之前,将展开模板。

Although the URI syntax is used for the result, the template string is allowed to contain the broader set of characters that can be found in Internationalized Resource Identifier (IRI) references [RFC3987]. Therefore, a URI Template is also an IRI template, and the result of template processing can be transformed to an IRI by following the process defined in Section 3.2 of [RFC3987].

尽管结果使用了URI语法,但允许模板字符串包含可在国际化资源标识符(IRI)引用[RFC3987]中找到的更广泛的字符集。因此,URI模板也是IRI模板,模板处理的结果可以按照[RFC3987]第3.2节中定义的过程转换为IRI。

1.2. Levels and Expression Types
1.2. 级别和表达式类型

URI Templates are similar to a macro language with a fixed set of macro definitions: the expression type determines the expansion process. The default expression type is simple string expansion, wherein a single named variable is replaced by its value as a string after pct-encoding any characters not in the set of unreserved URI characters (Section 1.5).

URI模板类似于具有一组固定宏定义的宏语言:表达式类型决定扩展过程。默认的表达式类型是简单的字符串扩展,其中单个命名变量在pct编码不在非保留URI字符集中的任何字符后,被其值替换为字符串(第1.5节)。

Since most template processors implemented prior to this specification have only implemented the default expression type, we refer to these as Level 1 templates.

由于在此规范之前实现的大多数模板处理器只实现了默认表达式类型,因此我们将其称为级别1模板。

   .-----------------------------------------------------------------.
   | Level 1 examples, with variables having values of               |
   |                                                                 |
   |             var   := "value"                                    |
   |             hello := "Hello World!"                             |
   |                                                                 |
   |-----------------------------------------------------------------|
   | Op       Expression            Expansion                        |
   |-----------------------------------------------------------------|
   |     | Simple string expansion                       (Sec 3.2.2) |
   |     |                                                           |
   |     |    {var}                 value                            |
   |     |    {hello}               Hello%20World%21                 |
   `-----------------------------------------------------------------'
        
   .-----------------------------------------------------------------.
   | Level 1 examples, with variables having values of               |
   |                                                                 |
   |             var   := "value"                                    |
   |             hello := "Hello World!"                             |
   |                                                                 |
   |-----------------------------------------------------------------|
   | Op       Expression            Expansion                        |
   |-----------------------------------------------------------------|
   |     | Simple string expansion                       (Sec 3.2.2) |
   |     |                                                           |
   |     |    {var}                 value                            |
   |     |    {hello}               Hello%20World%21                 |
   `-----------------------------------------------------------------'
        

Level 2 templates add the plus ("+") operator, for expansion of values that are allowed to include reserved URI characters (Section 1.5), and the crosshatch ("#") operator for expansion of fragment identifiers.

第2级模板添加了加号(“+”)运算符,用于扩展允许包含保留URI字符的值(第1.5节),以及交叉线(“#”)运算符,用于扩展片段标识符。

   .-----------------------------------------------------------------.
   | Level 2 examples, with variables having values of               |
   |                                                                 |
   |             var   := "value"                                    |
   |             hello := "Hello World!"                             |
   |             path  := "/foo/bar"                                 |
   |                                                                 |
   |-----------------------------------------------------------------|
   | Op       Expression            Expansion                        |
   |-----------------------------------------------------------------|
   |  +  | Reserved string expansion                     (Sec 3.2.3) |
   |     |                                                           |
   |     |    {+var}                value                            |
   |     |    {+hello}              Hello%20World!                   |
   |     |    {+path}/here          /foo/bar/here                    |
   |     |    here?ref={+path}      here?ref=/foo/bar                |
   |-----+-----------------------------------------------------------|
   |  #  | Fragment expansion, crosshatch-prefixed       (Sec 3.2.4) |
   |     |                                                           |
   |     |    X{#var}               X#value                          |
   |     |    X{#hello}             X#Hello%20World!                 |
   `-----------------------------------------------------------------'
        
   .-----------------------------------------------------------------.
   | Level 2 examples, with variables having values of               |
   |                                                                 |
   |             var   := "value"                                    |
   |             hello := "Hello World!"                             |
   |             path  := "/foo/bar"                                 |
   |                                                                 |
   |-----------------------------------------------------------------|
   | Op       Expression            Expansion                        |
   |-----------------------------------------------------------------|
   |  +  | Reserved string expansion                     (Sec 3.2.3) |
   |     |                                                           |
   |     |    {+var}                value                            |
   |     |    {+hello}              Hello%20World!                   |
   |     |    {+path}/here          /foo/bar/here                    |
   |     |    here?ref={+path}      here?ref=/foo/bar                |
   |-----+-----------------------------------------------------------|
   |  #  | Fragment expansion, crosshatch-prefixed       (Sec 3.2.4) |
   |     |                                                           |
   |     |    X{#var}               X#value                          |
   |     |    X{#hello}             X#Hello%20World!                 |
   `-----------------------------------------------------------------'
        

Level 3 templates allow multiple variables per expression, each separated by a comma, and add more complex operators for dot-prefixed labels, slash-prefixed path segments, semicolon-prefixed path parameters, and the form-style construction of a query syntax consisting of name=value pairs that are separated by an ampersand character.

第3级模板允许每个表达式使用多个变量,每个变量用逗号分隔,并为点前缀标签、斜杠前缀路径段、分号前缀路径参数以及由名称=值对(由符号和字符分隔)组成的查询语法的表单样式构造添加更复杂的运算符。

   .-----------------------------------------------------------------.
   | Level 3 examples, with variables having values of               |
   |                                                                 |
   |             var   := "value"                                    |
   |             hello := "Hello World!"                             |
   |             empty := ""                                         |
   |             path  := "/foo/bar"                                 |
   |             x     := "1024"                                     |
   |             y     := "768"                                      |
   |                                                                 |
   |-----------------------------------------------------------------|
   | Op       Expression            Expansion                        |
   |-----------------------------------------------------------------|
   |     | String expansion with multiple variables      (Sec 3.2.2) |
   |     |                                                           |
   |     |    map?{x,y}             map?1024,768                     |
   |     |    {x,hello,y}           1024,Hello%20World%21,768        |
   |     |                                                           |
        
   .-----------------------------------------------------------------.
   | Level 3 examples, with variables having values of               |
   |                                                                 |
   |             var   := "value"                                    |
   |             hello := "Hello World!"                             |
   |             empty := ""                                         |
   |             path  := "/foo/bar"                                 |
   |             x     := "1024"                                     |
   |             y     := "768"                                      |
   |                                                                 |
   |-----------------------------------------------------------------|
   | Op       Expression            Expansion                        |
   |-----------------------------------------------------------------|
   |     | String expansion with multiple variables      (Sec 3.2.2) |
   |     |                                                           |
   |     |    map?{x,y}             map?1024,768                     |
   |     |    {x,hello,y}           1024,Hello%20World%21,768        |
   |     |                                                           |
        
   |-----+-----------------------------------------------------------|
   |  +  | Reserved expansion with multiple variables    (Sec 3.2.3) |
   |     |                                                           |
   |     |    {+x,hello,y}          1024,Hello%20World!,768          |
   |     |    {+path,x}/here        /foo/bar,1024/here               |
   |     |                                                           |
   |-----+-----------------------------------------------------------|
   |  #  | Fragment expansion with multiple variables    (Sec 3.2.4) |
   |     |                                                           |
   |     |    {#x,hello,y}          #1024,Hello%20World!,768         |
   |     |    {#path,x}/here        #/foo/bar,1024/here              |
   |     |                                                           |
   |-----+-----------------------------------------------------------|
   |  .  | Label expansion, dot-prefixed                 (Sec 3.2.5) |
   |     |                                                           |
   |     |    X{.var}               X.value                          |
   |     |    X{.x,y}               X.1024.768                       |
   |     |                                                           |
   |-----+-----------------------------------------------------------|
   |  /  | Path segments, slash-prefixed                 (Sec 3.2.6) |
   |     |                                                           |
   |     |    {/var}                /value                           |
   |     |    {/var,x}/here         /value/1024/here                 |
   |     |                                                           |
   |-----+-----------------------------------------------------------|
   |  ;  | Path-style parameters, semicolon-prefixed     (Sec 3.2.7) |
   |     |                                                           |
   |     |    {;x,y}                ;x=1024;y=768                    |
   |     |    {;x,y,empty}          ;x=1024;y=768;empty              |
   |     |                                                           |
   |-----+-----------------------------------------------------------|
   |  ?  | Form-style query, ampersand-separated         (Sec 3.2.8) |
   |     |                                                           |
   |     |    {?x,y}                ?x=1024&y=768                    |
   |     |    {?x,y,empty}          ?x=1024&y=768&empty=             |
   |     |                                                           |
   |-----+-----------------------------------------------------------|
   |  &  | Form-style query continuation                 (Sec 3.2.9) |
   |     |                                                           |
   |     |    ?fixed=yes{&x}        ?fixed=yes&x=1024                |
   |     |    {&x,y,empty}          &x=1024&y=768&empty=             |
   |     |                                                           |
   `-----------------------------------------------------------------'
        
   |-----+-----------------------------------------------------------|
   |  +  | Reserved expansion with multiple variables    (Sec 3.2.3) |
   |     |                                                           |
   |     |    {+x,hello,y}          1024,Hello%20World!,768          |
   |     |    {+path,x}/here        /foo/bar,1024/here               |
   |     |                                                           |
   |-----+-----------------------------------------------------------|
   |  #  | Fragment expansion with multiple variables    (Sec 3.2.4) |
   |     |                                                           |
   |     |    {#x,hello,y}          #1024,Hello%20World!,768         |
   |     |    {#path,x}/here        #/foo/bar,1024/here              |
   |     |                                                           |
   |-----+-----------------------------------------------------------|
   |  .  | Label expansion, dot-prefixed                 (Sec 3.2.5) |
   |     |                                                           |
   |     |    X{.var}               X.value                          |
   |     |    X{.x,y}               X.1024.768                       |
   |     |                                                           |
   |-----+-----------------------------------------------------------|
   |  /  | Path segments, slash-prefixed                 (Sec 3.2.6) |
   |     |                                                           |
   |     |    {/var}                /value                           |
   |     |    {/var,x}/here         /value/1024/here                 |
   |     |                                                           |
   |-----+-----------------------------------------------------------|
   |  ;  | Path-style parameters, semicolon-prefixed     (Sec 3.2.7) |
   |     |                                                           |
   |     |    {;x,y}                ;x=1024;y=768                    |
   |     |    {;x,y,empty}          ;x=1024;y=768;empty              |
   |     |                                                           |
   |-----+-----------------------------------------------------------|
   |  ?  | Form-style query, ampersand-separated         (Sec 3.2.8) |
   |     |                                                           |
   |     |    {?x,y}                ?x=1024&y=768                    |
   |     |    {?x,y,empty}          ?x=1024&y=768&empty=             |
   |     |                                                           |
   |-----+-----------------------------------------------------------|
   |  &  | Form-style query continuation                 (Sec 3.2.9) |
   |     |                                                           |
   |     |    ?fixed=yes{&x}        ?fixed=yes&x=1024                |
   |     |    {&x,y,empty}          &x=1024&y=768&empty=             |
   |     |                                                           |
   `-----------------------------------------------------------------'
        

Finally, Level 4 templates add value modifiers as an optional suffix to each variable name. A prefix modifier (":") indicates that only a limited number of characters from the beginning of the value are used by the expansion (Section 2.4.1). An explode ("*") modifier

最后,级别4模板将值修饰符作为可选后缀添加到每个变量名中。前缀修饰符(“:”)表示扩展仅使用值开头的有限数量的字符(第2.4.1节)。分解(“*”)修饰符

indicates that the variable is to be treated as a composite value, consisting of either a list of names or an associative array of (name, value) pairs, that is expanded as if each member were a separate variable (Section 2.4.2).

表示变量将被视为复合值,由名称列表或(名称、值)对的关联数组组成,并将其展开,就像每个成员是单独的变量一样(第2.4.2节)。

   .-----------------------------------------------------------------.
   | Level 4 examples, with variables having values of               |
   |                                                                 |
   |             var   := "value"                                    |
   |             hello := "Hello World!"                             |
   |             path  := "/foo/bar"                                 |
   |             list  := ("red", "green", "blue")                   |
   |             keys  := [("semi",";"),("dot","."),("comma",",")]   |
   |                                                                 |
   | Op       Expression            Expansion                        |
   |-----------------------------------------------------------------|
   |     | String expansion with value modifiers         (Sec 3.2.2) |
   |     |                                                           |
   |     |    {var:3}               val                              |
   |     |    {var:30}              value                            |
   |     |    {list}                red,green,blue                   |
   |     |    {list*}               red,green,blue                   |
   |     |    {keys}                semi,%3B,dot,.,comma,%2C         |
   |     |    {keys*}               semi=%3B,dot=.,comma=%2C         |
   |     |                                                           |
   |-----+-----------------------------------------------------------|
   |  +  | Reserved expansion with value modifiers       (Sec 3.2.3) |
   |     |                                                           |
   |     |    {+path:6}/here        /foo/b/here                      |
   |     |    {+list}               red,green,blue                   |
   |     |    {+list*}              red,green,blue                   |
   |     |    {+keys}               semi,;,dot,.,comma,,             |
   |     |    {+keys*}              semi=;,dot=.,comma=,             |
   |     |                                                           |
   |-----+-----------------------------------------------------------|
   |  #  | Fragment expansion with value modifiers       (Sec 3.2.4) |
   |     |                                                           |
   |     |    {#path:6}/here        #/foo/b/here                     |
   |     |    {#list}               #red,green,blue                  |
   |     |    {#list*}              #red,green,blue                  |
   |     |    {#keys}               #semi,;,dot,.,comma,,            |
   |     |    {#keys*}              #semi=;,dot=.,comma=,            |
   |     |                                                           |
   |-----+-----------------------------------------------------------|
   |  .  | Label expansion, dot-prefixed                 (Sec 3.2.5) |
   |     |                                                           |
   |     |    X{.var:3}             X.val                            |
   |     |    X{.list}              X.red,green,blue                 |
        
   .-----------------------------------------------------------------.
   | Level 4 examples, with variables having values of               |
   |                                                                 |
   |             var   := "value"                                    |
   |             hello := "Hello World!"                             |
   |             path  := "/foo/bar"                                 |
   |             list  := ("red", "green", "blue")                   |
   |             keys  := [("semi",";"),("dot","."),("comma",",")]   |
   |                                                                 |
   | Op       Expression            Expansion                        |
   |-----------------------------------------------------------------|
   |     | String expansion with value modifiers         (Sec 3.2.2) |
   |     |                                                           |
   |     |    {var:3}               val                              |
   |     |    {var:30}              value                            |
   |     |    {list}                red,green,blue                   |
   |     |    {list*}               red,green,blue                   |
   |     |    {keys}                semi,%3B,dot,.,comma,%2C         |
   |     |    {keys*}               semi=%3B,dot=.,comma=%2C         |
   |     |                                                           |
   |-----+-----------------------------------------------------------|
   |  +  | Reserved expansion with value modifiers       (Sec 3.2.3) |
   |     |                                                           |
   |     |    {+path:6}/here        /foo/b/here                      |
   |     |    {+list}               red,green,blue                   |
   |     |    {+list*}              red,green,blue                   |
   |     |    {+keys}               semi,;,dot,.,comma,,             |
   |     |    {+keys*}              semi=;,dot=.,comma=,             |
   |     |                                                           |
   |-----+-----------------------------------------------------------|
   |  #  | Fragment expansion with value modifiers       (Sec 3.2.4) |
   |     |                                                           |
   |     |    {#path:6}/here        #/foo/b/here                     |
   |     |    {#list}               #red,green,blue                  |
   |     |    {#list*}              #red,green,blue                  |
   |     |    {#keys}               #semi,;,dot,.,comma,,            |
   |     |    {#keys*}              #semi=;,dot=.,comma=,            |
   |     |                                                           |
   |-----+-----------------------------------------------------------|
   |  .  | Label expansion, dot-prefixed                 (Sec 3.2.5) |
   |     |                                                           |
   |     |    X{.var:3}             X.val                            |
   |     |    X{.list}              X.red,green,blue                 |
        
   |     |    X{.list*}             X.red.green.blue                 |
   |     |    X{.keys}              X.semi,%3B,dot,.,comma,%2C       |
   |     |    X{.keys*}             X.semi=%3B.dot=..comma=%2C       |
   |     |                                                           |
   |-----+-----------------------------------------------------------|
   |  /  | Path segments, slash-prefixed                 (Sec 3.2.6) |
   |     |                                                           |
   |     |    {/var:1,var}          /v/value                         |
   |     |    {/list}               /red,green,blue                  |
   |     |    {/list*}              /red/green/blue                  |
   |     |    {/list*,path:4}       /red/green/blue/%2Ffoo           |
   |     |    {/keys}               /semi,%3B,dot,.,comma,%2C        |
   |     |    {/keys*}              /semi=%3B/dot=./comma=%2C        |
   |     |                                                           |
   |-----+-----------------------------------------------------------|
   |  ;  | Path-style parameters, semicolon-prefixed     (Sec 3.2.7) |
   |     |                                                           |
   |     |    {;hello:5}            ;hello=Hello                     |
   |     |    {;list}               ;list=red,green,blue             |
   |     |    {;list*}              ;list=red;list=green;list=blue   |
   |     |    {;keys}               ;keys=semi,%3B,dot,.,comma,%2C   |
   |     |    {;keys*}              ;semi=%3B;dot=.;comma=%2C        |
   |     |                                                           |
   |-----+-----------------------------------------------------------|
   |  ?  | Form-style query, ampersand-separated         (Sec 3.2.8) |
   |     |                                                           |
   |     |    {?var:3}              ?var=val                         |
   |     |    {?list}               ?list=red,green,blue             |
   |     |    {?list*}              ?list=red&list=green&list=blue   |
   |     |    {?keys}               ?keys=semi,%3B,dot,.,comma,%2C   |
   |     |    {?keys*}              ?semi=%3B&dot=.&comma=%2C        |
   |     |                                                           |
   |-----+-----------------------------------------------------------|
   |  &  | Form-style query continuation                 (Sec 3.2.9) |
   |     |                                                           |
   |     |    {&var:3}              &var=val                         |
   |     |    {&list}               &list=red,green,blue             |
   |     |    {&list*}              &list=red&list=green&list=blue   |
   |     |    {&keys}               &keys=semi,%3B,dot,.,comma,%2C   |
   |     |    {&keys*}              &semi=%3B&dot=.&comma=%2C        |
   |     |                                                           |
   `-----------------------------------------------------------------'
        
   |     |    X{.list*}             X.red.green.blue                 |
   |     |    X{.keys}              X.semi,%3B,dot,.,comma,%2C       |
   |     |    X{.keys*}             X.semi=%3B.dot=..comma=%2C       |
   |     |                                                           |
   |-----+-----------------------------------------------------------|
   |  /  | Path segments, slash-prefixed                 (Sec 3.2.6) |
   |     |                                                           |
   |     |    {/var:1,var}          /v/value                         |
   |     |    {/list}               /red,green,blue                  |
   |     |    {/list*}              /red/green/blue                  |
   |     |    {/list*,path:4}       /red/green/blue/%2Ffoo           |
   |     |    {/keys}               /semi,%3B,dot,.,comma,%2C        |
   |     |    {/keys*}              /semi=%3B/dot=./comma=%2C        |
   |     |                                                           |
   |-----+-----------------------------------------------------------|
   |  ;  | Path-style parameters, semicolon-prefixed     (Sec 3.2.7) |
   |     |                                                           |
   |     |    {;hello:5}            ;hello=Hello                     |
   |     |    {;list}               ;list=red,green,blue             |
   |     |    {;list*}              ;list=red;list=green;list=blue   |
   |     |    {;keys}               ;keys=semi,%3B,dot,.,comma,%2C   |
   |     |    {;keys*}              ;semi=%3B;dot=.;comma=%2C        |
   |     |                                                           |
   |-----+-----------------------------------------------------------|
   |  ?  | Form-style query, ampersand-separated         (Sec 3.2.8) |
   |     |                                                           |
   |     |    {?var:3}              ?var=val                         |
   |     |    {?list}               ?list=red,green,blue             |
   |     |    {?list*}              ?list=red&list=green&list=blue   |
   |     |    {?keys}               ?keys=semi,%3B,dot,.,comma,%2C   |
   |     |    {?keys*}              ?semi=%3B&dot=.&comma=%2C        |
   |     |                                                           |
   |-----+-----------------------------------------------------------|
   |  &  | Form-style query continuation                 (Sec 3.2.9) |
   |     |                                                           |
   |     |    {&var:3}              &var=val                         |
   |     |    {&list}               &list=red,green,blue             |
   |     |    {&list*}              &list=red&list=green&list=blue   |
   |     |    {&keys}               &keys=semi,%3B,dot,.,comma,%2C   |
   |     |    {&keys*}              &semi=%3B&dot=.&comma=%2C        |
   |     |                                                           |
   `-----------------------------------------------------------------'
        
1.3. Design Considerations
1.3. 设计考虑

Mechanisms similar to URI Templates have been defined within several specifications, including WSDL [WSDL], WADL [WADL], and OpenSearch [OpenSearch]. This specification extends and formally defines the

与URI模板类似的机制已在多个规范中定义,包括WSDL[WSDL]、WADL[WADL]和OpenSearch[OpenSearch]。本规范扩展并正式定义了

syntax so that URI Templates can be used consistently across multiple Internet applications and within Internet message fields, while at the same time retaining compatibility with those earlier definitions.

语法,以便URI模板可以在多个Internet应用程序和Internet消息字段中一致使用,同时保持与这些早期定义的兼容性。

The URI Template syntax has been designed to carefully balance the need for a powerful expansion mechanism with the need for ease of implementation. The syntax is designed to be trivial to parse while at the same time providing enough flexibility to express many common template scenarios. Implementations are able to parse the template and perform the expansions in a single pass.

URI模板语法的设计是为了谨慎地平衡对强大扩展机制的需求和对易于实现的需求。语法被设计为可以轻松解析,同时提供足够的灵活性来表达许多常见的模板场景。实现能够在单个过程中解析模板并执行扩展。

Templates are simple and readable when used with common examples because the single-character operators match the URI generic syntax delimiters. The operator's associated delimiter (".", ";", "/", "?", "&", and "#") is omitted when none of the listed variables are defined. Likewise, the expansion process for ";" (path-style parameters) will omit the "=" when the variable value is empty, whereas the process for "?" (form-style parameters) will not omit the "=" when the value is empty. Multiple variables and list values have their values joined with "," if there is no predefined joining mechanism for the operator. The "+" and "#" operators will substitute unencoded reserved characters found inside the variable values; the other operators will pct-encode reserved characters found in the variable values prior to expansion.

模板与常见示例一起使用时简单易读,因为单字符运算符与URI通用语法分隔符匹配。如果未定义任何列出的变量,则省略运算符的关联分隔符(“.”、“;”、“/”、“?”、“&”和“#”)。同样地,“;”(路径样式参数)的扩展过程将在变量值为空时忽略“=”,而“?”(表单样式参数)的扩展过程将在值为空时不忽略“=”。如果运算符没有预定义的联接机制,则多个变量和列表值的值将与“,”联接。“+”和“#”运算符将替换变量值中未编码的保留字符;其他运算符将pct编码扩展前变量值中的保留字符。

The most common cases for URI spaces can be described with Level 1 template expressions. If we were only concerned with URI generation, then the template syntax could be limited to just simple variable expansion, since more complex forms could be generated by changing the variable values. However, URI Templates have the additional goal of describing the layout of identifiers in terms of preexisting data values. Therefore, the template syntax includes operators that reflect how resource identifiers are commonly allocated. Likewise, since prefix substrings are often used to partition large spaces of resources, modifiers on variable values provide a way to specify both the substring and the full value string with a single variable name.

URI空间最常见的情况可以用级别1模板表达式来描述。如果我们只关心URI的生成,那么模板语法可能仅限于简单的变量扩展,因为通过更改变量值可以生成更复杂的表单。然而,URI模板还有一个额外的目标,即根据预先存在的数据值来描述标识符的布局。因此,模板语法包括反映通常如何分配资源标识符的运算符。同样,由于前缀子字符串通常用于划分大空间的资源,因此变量值上的修饰符提供了一种使用单个变量名指定子字符串和完整值字符串的方法。

1.4. Limitations
1.4. 局限性

Since a URI Template describes a superset of the identifiers, there is no implication that every possible expansion for each delimited variable expression corresponds to a URI of an existing resource. Our expectation is that an application constructing URIs according to the template will be provided with an appropriate set of values for the variables being substituted, or at least a means of validating user data-entry for those values.

由于URI模板描述标识符的超集,所以并不意味着每个分隔变量表达式的每个可能扩展都对应于现有资源的URI。我们的期望是,根据模板构造URI的应用程序将为被替换的变量提供一组适当的值,或者至少提供一种验证这些值的用户数据输入的方法。

URI Templates are not URIs: they do not identify an abstract or physical resource, they are not parsed as URIs, and they should not be used in places where a URI would be expected unless the template expressions will be expanded by a template processor prior to use. Distinct field, element, or attribute names should be used to differentiate protocol elements that carry a URI Template from those that expect a URI reference.

URI模板不是URI:它们不标识抽象资源或物理资源,也不被解析为URI,并且不应在需要URI的地方使用,除非模板表达式在使用前由模板处理器展开。应该使用不同的字段、元素或属性名称来区分携带URI模板的协议元素和期望URI引用的协议元素。

Some URI Templates can be used in reverse for the purpose of variable matching: comparing the template to a fully formed URI in order to extract the variable parts from that URI and assign them to the named variables. Variable matching only works well if the template expressions are delimited by the beginning or end of the URI or by characters that cannot be part of the expansion, such as reserved characters surrounding a simple string expression. In general, regular expression languages are better suited for variable matching.

一些URI模板可以反过来用于变量匹配:将模板与完全格式的URI进行比较,以便从该URI提取变量部分并将其分配给命名变量。变量匹配仅在模板表达式由URI的开头或结尾或不能作为扩展的一部分的字符(例如简单字符串表达式周围的保留字符)分隔时才有效。一般来说,正则表达式语言更适合于变量匹配。

1.5. Notational Conventions
1.5. 符号约定

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119].

本文件中的关键词“必须”、“不得”、“必需”、“应”、“不应”、“应”、“不应”、“建议”、“可”和“可选”应按照[RFC2119]中所述进行解释。

This specification uses the Augmented Backus-Naur Form (ABNF) notation of [RFC5234]. The following ABNF rules are imported from the normative references [RFC5234], [RFC3986], and [RFC3987].

本规范使用[RFC5234]的增广巴科斯诺尔形式(ABNF)符号。以下ABNF规则从规范性参考文献[RFC5234]、[RFC3986]和[RFC3987]中导入。

     ALPHA          =  %x41-5A / %x61-7A   ; A-Z / a-z
     DIGIT          =  %x30-39             ; 0-9
     HEXDIG         =  DIGIT / "A" / "B" / "C" / "D" / "E" / "F"
                       ; case-insensitive
        
     ALPHA          =  %x41-5A / %x61-7A   ; A-Z / a-z
     DIGIT          =  %x30-39             ; 0-9
     HEXDIG         =  DIGIT / "A" / "B" / "C" / "D" / "E" / "F"
                       ; case-insensitive
        
     pct-encoded    =  "%" HEXDIG HEXDIG
     unreserved     =  ALPHA / DIGIT / "-" / "." / "_" / "~"
     reserved       =  gen-delims / sub-delims
     gen-delims     =  ":" / "/" / "?" / "#" / "[" / "]" / "@"
     sub-delims     =  "!" / "$" / "&" / "'" / "(" / ")"
                    /  "*" / "+" / "," / ";" / "="
        
     pct-encoded    =  "%" HEXDIG HEXDIG
     unreserved     =  ALPHA / DIGIT / "-" / "." / "_" / "~"
     reserved       =  gen-delims / sub-delims
     gen-delims     =  ":" / "/" / "?" / "#" / "[" / "]" / "@"
     sub-delims     =  "!" / "$" / "&" / "'" / "(" / ")"
                    /  "*" / "+" / "," / ";" / "="
        
     ucschar        =  %xA0-D7FF / %xF900-FDCF / %xFDF0-FFEF
                    /  %x10000-1FFFD / %x20000-2FFFD / %x30000-3FFFD
                    /  %x40000-4FFFD / %x50000-5FFFD / %x60000-6FFFD
                    /  %x70000-7FFFD / %x80000-8FFFD / %x90000-9FFFD
                    /  %xA0000-AFFFD / %xB0000-BFFFD / %xC0000-CFFFD
                    /  %xD0000-DFFFD / %xE1000-EFFFD
        
     ucschar        =  %xA0-D7FF / %xF900-FDCF / %xFDF0-FFEF
                    /  %x10000-1FFFD / %x20000-2FFFD / %x30000-3FFFD
                    /  %x40000-4FFFD / %x50000-5FFFD / %x60000-6FFFD
                    /  %x70000-7FFFD / %x80000-8FFFD / %x90000-9FFFD
                    /  %xA0000-AFFFD / %xB0000-BFFFD / %xC0000-CFFFD
                    /  %xD0000-DFFFD / %xE1000-EFFFD
        
     iprivate       =  %xE000-F8FF / %xF0000-FFFFD / %x100000-10FFFD
        
     iprivate       =  %xE000-F8FF / %xF0000-FFFFD / %x100000-10FFFD
        
1.6. Character Encoding and Unicode Normalization
1.6. 字符编码和Unicode规范化

This specification uses the terms "character", "character encoding scheme", "code point", "coded character set", "glyph", "non-ASCII", "normalization", "protocol element", and "regular expression" as they are defined in [RFC6365].

本规范使用[RFC6365]中定义的术语“字符”、“字符编码方案”、“代码点”、“编码字符集”、“字形”、“非ASCII”、“规范化”、“协议元素”和“正则表达式”。

The ABNF notation defines its terminal values to be non-negative integers (code points) that are a superset of the US-ASCII coded character set [ASCII]. This specification defines terminal values as code points within the Unicode coded character set [UNIV6].

ABNF符号将其终端值定义为非负整数(代码点),它是US-ASCII编码字符集[ASCII]的超集。本规范将终端值定义为Unicode编码字符集[UNIV6]内的代码点。

In spite of the syntax and template expansion process being defined in terms of Unicode code points, it should be understood that templates occur in practice as a sequence of characters in whatever form or encoding is suitable for the context in which they occur, whether that be octets embedded in a network protocol element or glyphs painted on the side of a bus. This specification does not mandate any particular character encoding scheme for mapping between URI Template characters and the octets used to store or transmit those characters. When a URI Template appears in a protocol element, the character encoding scheme is defined by that protocol; without such a definition, a URI Template is assumed to be in the same character encoding scheme as the surrounding text. It is only during the process of template expansion that a string of characters in a URI Template is REQUIRED to be processed as a sequence of Unicode code points.

尽管语法和模板扩展过程是根据Unicode代码点定义的,但应该理解的是,模板在实践中作为字符序列出现,其形式或编码适合其出现的上下文,无论是嵌入在网络协议元素中的八位字节还是绘制在总线侧面的标志符号。本规范不要求任何特定的字符编码方案用于URI模板字符和用于存储或传输这些字符的八位字节之间的映射。当URI模板出现在协议元素中时,字符编码方案由该协议定义;如果没有这样的定义,则假定URI模板与周围文本采用相同的字符编码方案。只有在模板扩展过程中,URI模板中的字符串才需要作为Unicode代码点序列进行处理。

The Unicode Standard [UNIV6] defines various equivalences between sequences of characters for various purposes. Unicode Standard Annex #15 [UTR15] defines various Normalization Forms for these equivalences. The normalization form determines how to consistently encode equivalent strings. In theory, all URI processing implementations, including template processors, should use the same normalization form for generating a URI reference. In practice, they do not. If a value has been provided by the same server as the resource, then it can be assumed that the string is already in the form expected by that server. If a value is provided by a user, such as via a data-entry dialog, then the string SHOULD be normalized as Normalization Form C (NFC: Canonical Decomposition, followed by Canonical Composition) prior to being used in expansions by a template processor.

Unicode标准[UNIV6]为各种目的定义了字符序列之间的各种等价性。Unicode标准附录#15[UTR15]定义了这些等价物的各种规范化形式。规范化表单确定如何一致地编码等效字符串。理论上,所有URI处理实现,包括模板处理器,都应该使用相同的规范化形式来生成URI引用。实际上,它们并不是这样。如果与资源相同的服务器提供了一个值,那么可以假定字符串已经是该服务器所期望的格式。如果一个值是由用户提供的,例如通过数据输入对话框提供的,那么在模板处理器用于扩展之前,字符串应该被规范化为规范化形式C(NFC:规范分解,然后是规范组合)。

Likewise, when non-ASCII data that represents readable strings is pct-encoded for use in a URI reference, a template processor MUST first encode the string as UTF-8 [RFC3629] and then pct-encode any octets that are not allowed in a URI reference.

同样,当表示可读字符串的非ASCII数据被pct编码以用于URI引用时,模板处理器必须首先将字符串编码为UTF-8[RFC3629],然后pct编码URI引用中不允许的任何八位字节。

2. Syntax
2. 语法

A URI Template is a string of printable Unicode characters that contains zero or more embedded variable expressions, each expression being delimited by a matching pair of braces ('{', '}').

URI模板是一个包含零个或多个嵌入变量表达式的可打印Unicode字符字符串,每个表达式由一对匹配的大括号('{','}')分隔。

     URI-Template  = *( literals / expression )
        
     URI-Template  = *( literals / expression )
        

Although templates (and template processor implementations) are described above in terms of four gradual levels, we define the URI-Template syntax in terms of the ABNF for Level 4. A template processor limited to lower-level templates MAY exclude the ABNF rules applicable only to higher levels. However, it is RECOMMENDED that all parsers implement the full syntax such that unsupported levels can be properly identified as such to the end user.

尽管模板(和模板处理器实现)在上面是按照四个级别描述的,但是我们根据级别4的ABNF定义URI模板语法。仅限于较低级别模板的模板处理器可能会排除仅适用于较高级别的ABNF规则。但是,建议所有解析器实现完整语法,以便最终用户能够正确识别不支持的级别。

2.1. Literals
2.1. 直接常量

The characters outside of expressions in a URI Template string are intended to be copied literally to the URI reference if the character is allowed in a URI (reserved / unreserved / pct-encoded) or, if not allowed, copied to the URI reference as the sequence of pct-encoded triplets corresponding to that character's encoding in UTF-8 [RFC3629].

如果URI(保留/非保留/pct编码)中允许该字符,则URI模板字符串中表达式之外的字符将被逐字复制到URI引用,或者,如果不允许,将该字符复制到URI引用中,作为对应于UTF-8中该字符编码的pct编码三元组序列[RFC3629]。

     literals      =  %x21 / %x23-24 / %x26 / %x28-3B / %x3D / %x3F-5B
                   /  %x5D / %x5F / %x61-7A / %x7E / ucschar / iprivate
                   /  pct-encoded
                        ; any Unicode character except: CTL, SP,
                        ;  DQUOTE, "'", "%" (aside from pct-encoded),
                        ;  "<", ">", "\", "^", "`", "{", "|", "}"
        
     literals      =  %x21 / %x23-24 / %x26 / %x28-3B / %x3D / %x3F-5B
                   /  %x5D / %x5F / %x61-7A / %x7E / ucschar / iprivate
                   /  pct-encoded
                        ; any Unicode character except: CTL, SP,
                        ;  DQUOTE, "'", "%" (aside from pct-encoded),
                        ;  "<", ">", "\", "^", "`", "{", "|", "}"
        
2.2. Expressions
2.2. 表达

Template expressions are the parameterized parts of a URI Template. Each expression contains an optional operator, which defines the expression type and its corresponding expansion process, followed by a comma-separated list of variable specifiers (variable names and optional value modifiers). If no operator is provided, the expression defaults to simple variable expansion of unreserved values.

模板表达式是URI模板的参数化部分。每个表达式都包含一个可选运算符,该运算符定义表达式类型及其相应的扩展过程,后面是一个逗号分隔的变量说明符列表(变量名称和可选值修饰符)。如果未提供运算符,则表达式默认为无保留值的简单变量展开。

     expression    =  "{" [ operator ] variable-list "}"
     operator      =  op-level2 / op-level3 / op-reserve
     op-level2     =  "+" / "#"
     op-level3     =  "." / "/" / ";" / "?" / "&"
     op-reserve    =  "=" / "," / "!" / "@" / "|"
        
     expression    =  "{" [ operator ] variable-list "}"
     operator      =  op-level2 / op-level3 / op-reserve
     op-level2     =  "+" / "#"
     op-level3     =  "." / "/" / ";" / "?" / "&"
     op-reserve    =  "=" / "," / "!" / "@" / "|"
        

The operator characters have been chosen to reflect each of their roles as reserved characters in the URI generic syntax. The operators defined in Section 3 of this specification include:

已选择运算符字符以反映其在URI通用语法中作为保留字符的每个角色。本规范第3节中定义的操作员包括:

+ Reserved character strings;

+ 保留字符串;

      #   Fragment identifiers prefixed by "#";
        
      #   Fragment identifiers prefixed by "#";
        

. Name labels or extensions prefixed by ".";

. 以“.”为前缀的名称标签或扩展名;

      /   Path segments prefixed by "/";
        
      /   Path segments prefixed by "/";
        
      ;   Path parameter name or name=value pairs prefixed by ";";
        
      ;   Path parameter name or name=value pairs prefixed by ";";
        

? Query component beginning with "?" and consisting of name=value pairs separated by "&"; and,

? 查询组件以“?”开头,由名称=值对组成,以“&”分隔;和

& Continuation of query-style &name=value pairs within a literal query component.

&文本查询组件中查询样式和名称=值对的延续。

The operator characters equals ("="), comma (","), exclamation ("!"), at sign ("@"), and pipe ("|") are reserved for future extensions.

运算符字符等于(“=”)、逗号(“,”)、感叹号(“!”)、符号(@)和管道(“|”)保留用于将来的扩展。

The expression syntax specifically excludes use of the dollar ("$") and parentheses ["(" and ")"] characters so that they remain available for use outside the scope of this specification. For example, a macro language might use these characters to apply macro substitution to a string prior to that string being processed as a URI Template.

表达式语法明确排除了使用美元($)和括号[“(”和“)”]字符,以便在本规范范围外使用它们。例如,宏语言可能会在将字符串作为URI模板处理之前,使用这些字符对该字符串应用宏替换。

2.3. Variables
2.3. 变量

After the operator (if any), each expression contains a list of one or more comma-separated variable specifiers (varspec). The variable names serve multiple purposes: documentation for what kinds of values are expected, identifiers for associating values within a template processor, and the literal string to use for the name in name=value expansions (aside from when exploding an associative array). Variable names are case-sensitive because the name might be expanded within a case-sensitive URI component.

在运算符(如果有)之后,每个表达式都包含一个或多个逗号分隔变量说明符(varspec)的列表。变量名有多种用途:用于说明需要哪种类型的值的文档、用于在模板处理器中关联值的标识符,以及用于名称=值扩展中的名称的文字字符串(分解关联数组时除外)。变量名区分大小写,因为该名称可能在区分大小写的URI组件中展开。

     variable-list =  varspec *( "," varspec )
     varspec       =  varname [ modifier-level4 ]
     varname       =  varchar *( ["."] varchar )
     varchar       =  ALPHA / DIGIT / "_" / pct-encoded
        
     variable-list =  varspec *( "," varspec )
     varspec       =  varname [ modifier-level4 ]
     varname       =  varchar *( ["."] varchar )
     varchar       =  ALPHA / DIGIT / "_" / pct-encoded
        

A varname MAY contain one or more pct-encoded triplets. These triplets are considered an essential part of the variable name and are not decoded during processing. A varname containing pct-encoded characters is not the same variable as a varname with those same characters decoded. Applications that provide URI Templates are expected to be consistent in their use of pct-encoding within variable names.

varname可以包含一个或多个pct编码的三元组。这些三元组被认为是变量名的重要组成部分,在处理过程中不会被解码。包含pct编码字符的varname与解码相同字符的varname不是同一变量。提供URI模板的应用程序在变量名中使用pct编码时应保持一致。

An expression MAY reference variables that are unknown to the template processor or whose value is set to a special "undefined" value, such as undef or null. Such undefined variables are given special treatment by the expansion process (Section 3.2.1).

表达式可以引用模板处理器未知的变量,或者其值设置为特殊的“未定义”值,例如undef或null。此类未定义变量通过扩展过程进行特殊处理(第3.2.1节)。

A variable value that is a string of length zero is not considered undefined; it has the defined value of an empty string.

长度为零的字符串的变量值不被视为未定义;它的定义值为空字符串。

In Level 4 templates, a variable may have a composite value in the form of a list of values or an associative array of (name, value) pairs. Such value types are not directly indicated by the template syntax, but they do have an impact on the expansion process (Section 3.2.1).

在级别4模板中,变量可能具有值列表形式的复合值或(名称、值)对的关联数组。这些值类型不是由模板语法直接指示的,但它们确实对扩展过程有影响(第3.2.1节)。

A variable defined as a list value is considered undefined if the list contains zero members. A variable defined as an associative array of (name, value) pairs is considered undefined if the array contains zero members or if all member names in the array are associated with undefined values.

如果列表包含零个成员,则定义为列表值的变量被视为未定义。如果数组包含零个成员或数组中的所有成员名称都与未定义的值关联,则定义为(名称、值)对的关联数组的变量被视为未定义的变量。

2.4. Value Modifiers
2.4. 值修饰符

Each of the variables in a Level 4 template expression can have a modifier indicating either that its expansion is limited to a prefix of the variable's value string or that its expansion is exploded as a composite value in the form of a value list or an associative array of (name, value) pairs.

级别4模板表达式中的每个变量都可以有一个修饰符,指示其扩展仅限于变量值字符串的前缀,或者其扩展以值列表或(名称、值)对的关联数组的形式分解为复合值。

     modifier-level4 =  prefix / explode
        
     modifier-level4 =  prefix / explode
        
2.4.1. Prefix Values
2.4.1. 前缀值

A prefix modifier indicates that the variable expansion is limited to a prefix of the variable's value string. Prefix modifiers are often used to partition an identifier space hierarchically, as is common in reference indices and hash-based storage. It also serves to limit the expanded value to a maximum number of characters. Prefix modifiers are not applicable to variables that have composite values.

前缀修饰符表示变量扩展仅限于变量值字符串的前缀。前缀修饰符通常用于按层次划分标识符空间,这在引用索引和基于散列的存储中很常见。它还用于将扩展值限制为最大字符数。前缀修饰符不适用于具有复合值的变量。

     prefix        =  ":" max-length
     max-length    =  %x31-39 0*3DIGIT   ; positive integer < 10000
        
     prefix        =  ":" max-length
     max-length    =  %x31-39 0*3DIGIT   ; positive integer < 10000
        

The max-length is a positive integer that refers to a maximum number of characters from the beginning of the variable's value as a Unicode string. Note that this numbering is in characters, not octets, in order to avoid splitting between the octets of a multi-octet-encoded character or within a pct-encoded triplet. If the max-length is greater than the length of the variable's value, then the entire value string is used.

最大长度是一个正整数,表示变量值开头作为Unicode字符串的最大字符数。请注意,此编号以字符而不是八位字节为单位,以避免在多个八位字节编码字符的八位字节之间或在pct编码的三位字节内分裂。如果最大长度大于变量值的长度,则使用整个值字符串。

For example,

例如

Given the variable assignments

给定变量赋值

       var   := "value"
       semi  := ";"
        
       var   := "value"
       semi  := ";"
        

Example Template Expansion

模板扩展示例

       {var}              value
       {var:20}           value
       {var:3}            val
       {semi}             %3B
       {semi:2}           %3B
        
       {var}              value
       {var:20}           value
       {var:3}            val
       {semi}             %3B
       {semi:2}           %3B
        
2.4.2. Composite Values
2.4.2. 复合值

An explode ("*") modifier indicates that the variable is to be treated as a composite value consisting of either a list of values or an associative array of (name, value) pairs. Hence, the expansion process is applied to each member of the composite as if it were listed as a separate variable. This kind of variable specification is significantly less self-documenting than non-exploded variables, since there is less correspondence between the variable name and how the URI reference appears after expansion.

explode(“*”)修饰符表示变量将被视为复合值,由值列表或(名称、值)对的关联数组组成。因此,展开过程将应用于组合的每个成员,就像它被列为单独的变量一样。这种变量规范的自文档化程度明显低于非分解变量,因为变量名和URI引用在扩展后的显示方式之间的对应关系较少。

explode = "*"

explode=“*”

Since URI Templates do not contain an indication of type or schema, the type for an exploded variable is assumed to be determined by context. For example, the processor might be supplied values in a form that differentiates values as strings, lists, or associative arrays. Likewise, the context in which the template is used (script, mark-up language, Interface Definition Language, etc.) might define rules for associating variable names with types, structures, or schema.

由于URI模板不包含类型或模式的指示,因此假定分解变量的类型由上下文确定。例如,处理器可能以将值区分为字符串、列表或关联数组的形式提供值。同样,使用模板的上下文(脚本、标记语言、接口定义语言等)可能会定义将变量名与类型、结构或模式关联的规则。

Explode modifiers improve brevity in the URI Template syntax. For example, a resource that provides a geographic map for a given street address might accept a hundred permutations on fields for address input, including partial addresses (e.g., just the city or postal code). Such a resource could be described as a template with each and every address component listed in order, or with a far more simple template that makes use of an explode modifier, as in

分解修饰符提高了URI模板语法的简洁性。例如,为给定街道地址提供地理地图的资源可能会接受地址输入字段上的一百个排列,包括部分地址(例如,仅城市或邮政编码)。这样的资源可以描述为一个模板,每个地址组件都按顺序列出,或者使用一个更简单的模板,使用分解修改器,如中所示

      /mapper{?address*}
        
      /mapper{?address*}
        

along with some context that defines what the variable named "address" can include, such as by reference to some other standard for addressing (e.g., [UPU-S42]). A recipient aware of the schema can then provide appropriate expansions, such as:

以及一些定义名为“address”的变量可以包括什么的上下文,例如通过引用一些其他寻址标准(例如,[UPU-S42])。然后,知道该模式的接收者可以提供适当的扩展,例如:

      /mapper?city=Newport%20Beach&state=CA
        
      /mapper?city=Newport%20Beach&state=CA
        

The expansion process for exploded variables is dependent on both the operator being used and whether the composite value is to be treated as a list of values or as an associative array of (name, value) pairs. Structures are processed as if they are an associative array with names corresponding to the fields in the structure definition and "." separators used to indicate name hierarchy in substructures.

分解变量的展开过程取决于所使用的运算符以及复合值是作为值列表还是作为(名称、值)对的关联数组处理。结构的处理就像它们是一个关联数组,其名称对应于结构定义中的字段,并使用“.”分隔符指示子结构中的名称层次结构。

If a variable has a composite structure and only some of the fields in that structure have defined values, then only the defined pairs are present in the expansion. This can be useful for templates that consist of a large number of potential query terms.

如果变量具有复合结构,并且该结构中只有一些字段具有定义的值,则展开中仅存在定义的对。这对于包含大量潜在查询词的模板非常有用。

An explode modifier applied to a list variable causes the expansion to iterate over the list's member values. For path and query parameter expansions, each member value is paired with the variable's name as a (varname, value) pair. This allows path and query parameters to be repeated for multiple values, as in

应用于列表变量的分解修改器会导致展开在列表的成员值上迭代。对于路径和查询参数展开,每个成员值都与变量名成对(varname,value)。这允许对多个值重复路径和查询参数,如中所示

Given the variable assignments

给定变量赋值

       year  := ("1965", "2000", "2012")
       dom   := ("example", "com")
        
       year  := ("1965", "2000", "2012")
       dom   := ("example", "com")
        

Example Template Expansion

模板扩展示例

       find{?year*}       find?year=1965&year=2000&year=2012
       www{.dom*}         www.example.com
        
       find{?year*}       find?year=1965&year=2000&year=2012
       www{.dom*}         www.example.com
        
3. Expansion
3. 膨胀

The process of URI Template expansion is to scan the template string from beginning to end, copying literal characters and replacing each expression with the result of applying the expression's operator to the value of each variable named in the expression. Each variable's value MUST be formed prior to template expansion.

URI模板扩展的过程是从头到尾扫描模板字符串,复制文字字符并用将表达式的运算符应用于表达式中命名的每个变量的值的结果替换每个表达式。每个变量的值必须在模板展开之前形成。

The requirements on expansion for each aspect of the URI Template grammar are defined in this section. A non-normative algorithm for the expansion process as a whole is provided in Appendix A.

本节定义了URI模板语法各个方面的扩展要求。附录A中提供了整个扩展过程的非规范算法。

If a template processor encounters a character sequence outside an expression that does not match the <URI-Template> grammar, then processing of the template SHOULD cease, the URI reference result SHOULD contain the expanded part of the template followed by the remainder unexpanded, and the location and type of error SHOULD be indicated to the invoking application.

如果模板处理器在表达式外遇到与<URI template>语法不匹配的字符序列,则应停止对模板的处理,URI引用结果应包含模板的展开部分,后跟未展开的其余部分,并且应该向调用应用程序指示错误的位置和类型。

If an error is encountered in an expression, such as an operator or value modifier that the template processor does not recognize or does not yet support, or a character is found that is not allowed by the <expression> grammar, then the unprocessed parts of the expression SHOULD be copied to the result unexpanded, processing of the remainder of the template SHOULD continue, and the location and type of error SHOULD be indicated to the invoking application.

如果表达式中遇到错误,例如模板处理器无法识别或尚不支持的运算符或值修饰符,或者发现<expression>语法不允许的字符,则应将表达式的未处理部分复制到未展开的结果中,应继续处理模板的其余部分,并向调用应用程序指示错误的位置和类型。

If an error occurs, the result returned might not be a valid URI reference; it will be an incompletely expanded template string that is only intended for diagnostic use.

如果发生错误,返回的结果可能不是有效的URI引用;它将是一个未完全展开的模板字符串,仅用于诊断用途。

3.1. Literal Expansion
3.1. 文字展开

If the literal character is allowed anywhere in the URI syntax (unreserved / reserved / pct-encoded ), then it is copied directly to the result string. Otherwise, the pct-encoded equivalent of the literal character is copied to the result string by first encoding the character as its sequence of octets in UTF-8 and then encoding each such octet as a pct-encoded triplet.

如果URI语法中的任何位置都允许使用文字字符(未保留/保留/pct编码),则直接将其复制到结果字符串。否则,通过首先将字符编码为UTF-8中的八位字节序列,然后将每个八位字节编码为pct编码的三元组,将文字字符的pct编码等价物复制到结果字符串。

3.2. Expression Expansion
3.2. 表达式扩展

Each expression is indicated by an opening brace ("{") character and continues until the next closing brace ("}"). Expressions cannot be nested.

每个表达式由一个大括号(“{”)字符表示,并一直持续到下一个大括号(“}”)为止。表达式不能嵌套。

An expression is expanded by determining its expression type and then following that type's expansion process for each comma-separated varspec in the expression. Level 1 templates are limited to the default operator (simple string value expansion) and a single variable per expression. Level 2 templates are limited to a single varspec per expression.

表达式是通过确定其表达式类型,然后对表达式中每个逗号分隔的varspec执行该类型的扩展过程来扩展的。级别1模板仅限于默认运算符(简单字符串值扩展)和每个表达式一个变量。级别2模板仅限于每个表达式一个varspec。

The expression type is determined by looking at the first character after the opening brace. If the character is an operator, then remember the expression type associated with that operator for later expansion decisions and skip to the next character for the variable-list. If the first character is not an operator, then the expression type is simple string expansion and the first character is the beginning of the variable-list.

表达式类型通过查看大括号后面的第一个字符来确定。如果字符是运算符,请记住与该运算符关联的表达式类型,以便以后进行扩展决策,并跳到变量列表的下一个字符。如果第一个字符不是运算符,则表达式类型为简单字符串扩展,第一个字符是变量列表的开头。

The examples in the subsections below use the following definitions for variable values:

以下小节中的示例使用以下变量值定义:

         count := ("one", "two", "three")
         dom   := ("example", "com")
         dub   := "me/too"
         hello := "Hello World!"
         half  := "50%"
         var   := "value"
         who   := "fred"
         base  := "http://example.com/home/"
         path  := "/foo/bar"
         list  := ("red", "green", "blue")
         keys  := [("semi",";"),("dot","."),("comma",",")]
         v     := "6"
         x     := "1024"
         y     := "768"
         empty := ""
         empty_keys  := []
         undef := null
        
         count := ("one", "two", "three")
         dom   := ("example", "com")
         dub   := "me/too"
         hello := "Hello World!"
         half  := "50%"
         var   := "value"
         who   := "fred"
         base  := "http://example.com/home/"
         path  := "/foo/bar"
         list  := ("red", "green", "blue")
         keys  := [("semi",";"),("dot","."),("comma",",")]
         v     := "6"
         x     := "1024"
         y     := "768"
         empty := ""
         empty_keys  := []
         undef := null
        
3.2.1. Variable Expansion
3.2.1. 可变膨胀

A variable that is undefined (Section 2.3) has no value and is ignored by the expansion process. If all of the variables in an expression are undefined, then the expression's expansion is the empty string.

未定义的变量(第2.3节)没有值,扩展过程将忽略该变量。如果表达式中的所有变量都未定义,则表达式的展开形式为空字符串。

Variable expansion of a defined, non-empty value results in a substring of allowed URI characters. As described in Section 1.6, the expansion process is defined in terms of Unicode code points in order to ensure that non-ASCII characters are consistently pct-encoded in the resulting URI reference. One way for a template

定义的非空值的变量扩展会导致允许的URI字符的子字符串。如第1.6节所述,扩展过程是根据Unicode代码点定义的,以确保在生成的URI引用中对非ASCII字符进行一致的pct编码。模板的一种方法

processor to obtain a consistent expansion is to transcode the value string to UTF-8 (if it is not already in UTF-8) and then transform each octet that is not in the allowed set into the corresponding pct-encoded triplet. Another is to map directly from the value's native character encoding to the set of allowed URI characters, with any remaining disallowed characters mapping to the sequence of pct-encoded triplets that correspond to the octet(s) of that character when encoded as UTF-8 [RFC3629].

获得一致扩展的处理器是将值字符串转换为UTF-8(如果它不在UTF-8中),然后将不在允许集合中的每个八位字节转换为相应的pct编码三位字节。另一种方法是直接从值的本机字符编码映射到允许的URI字符集,任何剩余的不允许字符映射到pct编码的三元组序列,该序列在编码为UTF-8时对应于该字符的八位字节[RFC3629]。

The allowed set for a given expansion depends on the expression type: reserved ("+") and fragment ("#") expansions allow the set of characters in the union of ( unreserved / reserved / pct-encoded ) to be passed through without pct-encoding, whereas all other expression types allow only unreserved characters to be passed through without pct-encoding. Note that the percent character ("%") is only allowed as part of a pct-encoded triplet and only for reserved/fragment expansion: in all other cases, a value character of "%" MUST be pct-encoded as "%25" by variable expansion.

给定扩展的允许集取决于表达式类型:保留(“+”)和片段(#”)扩展允许(未保留/保留/pct编码)并集中的字符集在没有pct编码的情况下通过,而所有其他表达式类型只允许传递未保留的字符而不进行pct编码。请注意,百分比字符(“%”)仅允许作为pct编码的三元组的一部分,并且仅用于保留/片段扩展:在所有其他情况下,“%”的值字符必须通过变量扩展pct编码为“%25”。

If a variable appears more than once in an expression or within multiple expressions of a URI Template, the value of that variable MUST remain static throughout the expansion process (i.e., the variable must have the same value for the purpose of calculating each expansion). However, if reserved characters or pct-encoded triplets occur in the value, they will be pct-encoded by some expression types and not by others.

如果一个变量在一个表达式或URI模板的多个表达式中出现多次,则该变量的值在整个扩展过程中必须保持静态(即,为了计算每个扩展,该变量必须具有相同的值)。但是,如果值中出现保留字符或pct编码的三元组,则它们将由某些表达式类型而不是其他表达式类型进行pct编码。

For a variable that is a simple string value, expansion consists of appending the encoded value to the result string. An explode modifier has no effect. A prefix modifier limits the expansion to the first max-length characters of the decoded value. If the value contains multi-octet or pct-encoded characters, care must be taken to avoid splitting the value in mid-character: count each Unicode code point as one character.

对于简单字符串值的变量,展开包括将编码值附加到结果字符串。“分解”修改器没有效果。前缀修饰符将扩展限制为解码值的第一个最大长度字符。如果该值包含多个八位字节或pct编码的字符,则必须注意避免在字符中间拆分该值:将每个Unicode代码点计为一个字符。

For a variable that is an associative array, expansion depends on both the expression type and the presence of an explode modifier. If there is no explode modifier, expansion consists of appending a comma-separated concatenation of each (name, value) pair that has a defined value. If there is an explode modifier, expansion consists of appending each pair that has a defined value as either "name=value" or, if the value is the empty string and the expression type does not indicate form-style parameters (i.e., not a "?" or "&" type), simply "name". Both name and value strings are encoded in the same way as simple string values. A separator string is appended between defined pairs according to the expression type, as defined by the following table:

对于关联数组的变量,展开取决于表达式类型和分解修改器的存在。如果没有“分解”修饰符,则展开包括在具有定义值的每个(名称、值)对上附加逗号分隔的连接。如果有分解修饰符,则展开包括追加定义值为“name=value”的每一对,或者,如果该值为空字符串且表达式类型未指示表单样式参数(即,不是“?”或“&”类型),则仅添加“name”。名称字符串和值字符串的编码方式与简单字符串值相同。根据下表定义的表达式类型,在定义的对之间追加分隔符字符串:

Type Separator "," (default) + "," # "," . "." / "/" ; ";" ? "&" & "&"

类型分隔符“,”(默认值)+“,”#“,”。"." / "/" ; ";" ? "&" & "&"

For a variable that is a list of values, expansion depends on both the expression type and the presence of an explode modifier. If there is no explode modifier, the expansion consists of a comma-separated concatenation of the defined member string values. If there is an explode modifier and the expression type expands named parameters (";", "?", or "&"), then the list is expanded as if it were an associative array in which each member value is paired with the list's varname. Otherwise, the value will be expanded as if it were a list of separate variable values, each value separated by the expression type's associated separator as defined by the table above.

对于作为值列表的变量,展开取决于表达式类型和分解修改器的存在。如果没有“分解”修改器,则展开由已定义的成员字符串值的逗号分隔串联组成。如果存在分解修饰符且表达式类型展开命名参数(“;”、“?”或“&”),则列表将展开,就像它是一个关联数组,其中每个成员值都与列表的varname成对出现一样。否则,该值将被展开,就像它是一个单独变量值的列表一样,每个值由上表定义的表达式类型的关联分隔符分隔。

Example Template Expansion

模板扩展示例

       {count}            one,two,three
       {count*}           one,two,three
       {/count}           /one,two,three
       {/count*}          /one/two/three
       {;count}           ;count=one,two,three
       {;count*}          ;count=one;count=two;count=three
       {?count}           ?count=one,two,three
       {?count*}          ?count=one&count=two&count=three
       {&count*}          &count=one&count=two&count=three
        
       {count}            one,two,three
       {count*}           one,two,three
       {/count}           /one,two,three
       {/count*}          /one/two/three
       {;count}           ;count=one,two,three
       {;count*}          ;count=one;count=two;count=three
       {?count}           ?count=one,two,three
       {?count*}          ?count=one&count=two&count=three
       {&count*}          &count=one&count=two&count=three
        
3.2.2. Simple String Expansion: {var}
3.2.2. 简单字符串扩展:{var}

Simple string expansion is the default expression type when no operator is given.

当没有给定运算符时,简单字符串扩展是默认的表达式类型。

For each defined variable in the variable-list, perform variable expansion, as defined in Section 3.2.1, with the allowed characters being those in the unreserved set. If more than one variable has a defined value, append a comma (",") to the result string as a separator between variable expansions.

对于变量列表中定义的每个变量,按照第3.2.1节中的定义执行变量扩展,允许的字符为未保留集合中的字符。如果有多个变量具有定义的值,请在结果字符串中附加逗号(“,”),作为变量展开之间的分隔符。

Example Template Expansion

模板扩展示例

       {var}              value
       {hello}            Hello%20World%21
       {half}             50%25
       O{empty}X          OX
       O{undef}X          OX
       {x,y}              1024,768
       {x,hello,y}        1024,Hello%20World%21,768
       ?{x,empty}         ?1024,
       ?{x,undef}         ?1024
       ?{undef,y}         ?768
       {var:3}            val
       {var:30}           value
       {list}             red,green,blue
       {list*}            red,green,blue
       {keys}             semi,%3B,dot,.,comma,%2C
       {keys*}            semi=%3B,dot=.,comma=%2C
        
       {var}              value
       {hello}            Hello%20World%21
       {half}             50%25
       O{empty}X          OX
       O{undef}X          OX
       {x,y}              1024,768
       {x,hello,y}        1024,Hello%20World%21,768
       ?{x,empty}         ?1024,
       ?{x,undef}         ?1024
       ?{undef,y}         ?768
       {var:3}            val
       {var:30}           value
       {list}             red,green,blue
       {list*}            red,green,blue
       {keys}             semi,%3B,dot,.,comma,%2C
       {keys*}            semi=%3B,dot=.,comma=%2C
        
3.2.3. Reserved Expansion: {+var}
3.2.3. 保留扩展:{+var}

Reserved expansion, as indicated by the plus ("+") operator for Level 2 and above templates, is identical to simple string expansion except that the substituted values may also contain pct-encoded triplets and characters in the reserved set.

如2级及以上模板的加号(“+”)运算符所示,保留扩展与简单字符串扩展相同,只是替换的值也可能包含保留集中的pct编码的三元组和字符。

For each defined variable in the variable-list, perform variable expansion, as defined in Section 3.2.1, with the allowed characters being those in the set (unreserved / reserved / pct-encoded). If more than one variable has a defined value, append a comma (",") to the result string as a separator between variable expansions.

对于变量列表中定义的每个变量,按照第3.2.1节的定义执行变量扩展,允许的字符为集合中的字符(未保留/保留/pct编码)。如果有多个变量具有定义的值,请在结果字符串中附加逗号(“,”),作为变量展开之间的分隔符。

Example Template Expansion

模板扩展示例

       {+var}                value
       {+hello}              Hello%20World!
       {+half}               50%25
        
       {+var}                value
       {+hello}              Hello%20World!
       {+half}               50%25
        
       {base}index           http%3A%2F%2Fexample.com%2Fhome%2Findex
       {+base}index          http://example.com/home/index
       O{+empty}X            OX
       O{+undef}X            OX
        
       {base}index           http%3A%2F%2Fexample.com%2Fhome%2Findex
       {+base}index          http://example.com/home/index
       O{+empty}X            OX
       O{+undef}X            OX
        
       {+path}/here          /foo/bar/here
       here?ref={+path}      here?ref=/foo/bar
       up{+path}{var}/here   up/foo/barvalue/here
       {+x,hello,y}          1024,Hello%20World!,768
       {+path,x}/here        /foo/bar,1024/here
        
       {+path}/here          /foo/bar/here
       here?ref={+path}      here?ref=/foo/bar
       up{+path}{var}/here   up/foo/barvalue/here
       {+x,hello,y}          1024,Hello%20World!,768
       {+path,x}/here        /foo/bar,1024/here
        

{+path:6}/here /foo/b/here {+list} red,green,blue {+list*} red,green,blue {+keys} semi,;,dot,.,comma,, {+keys*} semi=;,dot=.,comma=,

{+path:6}/here/foo/b/here{+list}红,绿,蓝{+list*}红,绿,蓝{+keys}半,;,点,,,逗号,,{+keys*}半=;,点=,逗号=,

3.2.4. Fragment Expansion: {#var}
3.2.4. 片段扩展:{#var}

Fragment expansion, as indicated by the crosshatch ("#") operator for Level 2 and above templates, is identical to reserved expansion except that a crosshatch character (fragment delimiter) is appended first to the result string if any of the variables are defined.

如2级及以上模板的交叉线(“#”)运算符所示,片段展开与保留展开相同,只是如果定义了任何变量,则首先在结果字符串中追加交叉线字符(片段分隔符)。

Example Template Expansion

模板扩展示例

{#var} #value {#hello} #Hello%20World! {#half} #50%25 foo{#empty} foo# foo{#undef} foo {#x,hello,y} #1024,Hello%20World!,768 {#path,x}/here #/foo/bar,1024/here {#path:6}/here #/foo/b/here {#list} #red,green,blue {#list*} #red,green,blue {#keys} #semi,;,dot,.,comma,, {#keys*} #semi=;,dot=.,comma=,

{#var}value{#hello}#hello%20World!{一半}50%25福{空}福{福{未定义}福{x,你好,y}1024,你好%20世界!,768{路径,x}/这里{foo/bar,1024/这里{路径:6}/这里{foo/b/这里{列表}红,绿,蓝{列表}红,绿,蓝{键}半,,;,点、、逗号、{#键*}#半=;,点=,逗号=,

3.2.5. Label Expansion with Dot-Prefix: {.var}
3.2.5. 带点前缀的标签扩展:{.var}

Label expansion, as indicated by the dot (".") operator for Level 3 and above templates, is useful for describing URI spaces with varying domain names or path selectors (e.g., filename extensions).

如3级及以上模板的点(“.”运算符所示,标签扩展用于描述具有不同域名或路径选择器(例如文件扩展名)的URI空间。

For each defined variable in the variable-list, append "." to the result string and then perform variable expansion, as defined in Section 3.2.1, with the allowed characters being those in the unreserved set.

对于变量列表中定义的每个变量,将“.”附加到结果字符串中,然后按照第3.2.1节中的定义执行变量扩展,允许的字符为无保留集中的字符。

Since "." is in the unreserved set, a value that contains a "." has the effect of adding multiple labels.

由于“.”在非保留集中,因此包含“.”的值具有添加多个标签的效果。

Example Template Expansion

模板扩展示例

       {.who}             .fred
       {.who,who}         .fred.fred
       {.half,who}        .50%25.fred
       www{.dom*}         www.example.com
       X{.var}            X.value
       X{.empty}          X.
       X{.undef}          X
       X{.var:3}          X.val
       X{.list}           X.red,green,blue
       X{.list*}          X.red.green.blue
       X{.keys}           X.semi,%3B,dot,.,comma,%2C
       X{.keys*}          X.semi=%3B.dot=..comma=%2C
       X{.empty_keys}     X
       X{.empty_keys*}    X
        
       {.who}             .fred
       {.who,who}         .fred.fred
       {.half,who}        .50%25.fred
       www{.dom*}         www.example.com
       X{.var}            X.value
       X{.empty}          X.
       X{.undef}          X
       X{.var:3}          X.val
       X{.list}           X.red,green,blue
       X{.list*}          X.red.green.blue
       X{.keys}           X.semi,%3B,dot,.,comma,%2C
       X{.keys*}          X.semi=%3B.dot=..comma=%2C
       X{.empty_keys}     X
       X{.empty_keys*}    X
        
3.2.6. Path Segment Expansion: {/var}
3.2.6. 路径段扩展:{/var}

Path segment expansion, as indicated by the slash ("/") operator in Level 3 and above templates, is useful for describing URI path hierarchies.

如级别3及以上模板中的斜杠(“/”)运算符所示,路径段扩展对于描述URI路径层次结构非常有用。

For each defined variable in the variable-list, append "/" to the result string and then perform variable expansion, as defined in Section 3.2.1, with the allowed characters being those in the unreserved set.

对于变量列表中定义的每个变量,将“/”附加到结果字符串,然后按照第3.2.1节的定义执行变量扩展,允许的字符为未保留集中的字符。

Note that the expansion process for path segment expansion is identical to that of label expansion aside from the substitution of "/" instead of ".". However, unlike ".", a "/" is a reserved character and will be pct-encoded if found in a value.

请注意,路径段扩展的扩展过程与标签扩展的扩展过程相同,只是将“/”替换为“.”。但是,与“.”不同,“/”是一个保留字符,如果在值中找到,则将对其进行pct编码。

Example Template Expansion

模板扩展示例

       {/who}             /fred
       {/who,who}         /fred/fred
       {/half,who}        /50%25/fred
       {/who,dub}         /fred/me%2Ftoo
       {/var}             /value
       {/var,empty}       /value/
       {/var,undef}       /value
       {/var,x}/here      /value/1024/here
       {/var:1,var}       /v/value
       {/list}            /red,green,blue
       {/list*}           /red/green/blue
       {/list*,path:4}    /red/green/blue/%2Ffoo
       {/keys}            /semi,%3B,dot,.,comma,%2C
       {/keys*}           /semi=%3B/dot=./comma=%2C
        
       {/who}             /fred
       {/who,who}         /fred/fred
       {/half,who}        /50%25/fred
       {/who,dub}         /fred/me%2Ftoo
       {/var}             /value
       {/var,empty}       /value/
       {/var,undef}       /value
       {/var,x}/here      /value/1024/here
       {/var:1,var}       /v/value
       {/list}            /red,green,blue
       {/list*}           /red/green/blue
       {/list*,path:4}    /red/green/blue/%2Ffoo
       {/keys}            /semi,%3B,dot,.,comma,%2C
       {/keys*}           /semi=%3B/dot=./comma=%2C
        
3.2.7. Path-Style Parameter Expansion: {;var}
3.2.7. 路径样式参数扩展:{;var}

Path-style parameter expansion, as indicated by the semicolon (";") operator in Level 3 and above templates, is useful for describing URI path parameters, such as "path;property" or "path;name=value".

如级别3及以上模板中的分号(;)运算符所示,路径样式参数扩展对于描述URI路径参数非常有用,例如“Path;property”或“Path;name=value”。

For each defined variable in the variable-list:

对于变量列表中定义的每个变量:

o append ";" to the result string;

o 将“;”附加到结果字符串中;

o if the variable has a simple string value or no explode modifier is given, then:

o 如果变量有一个简单的字符串值或未提供分解修改器,则:

* append the variable name (encoded as if it were a literal string) to the result string;

* 将变量名(编码为文字字符串)附加到结果字符串;

* if the variable's value is not empty, append "=" to the result string;

* 如果变量的值不为空,则在结果字符串后追加“=”;

o perform variable expansion, as defined in Section 3.2.1, with the allowed characters being those in the unreserved set.

o 执行第3.2.1节中定义的变量扩展,允许的字符为未保留集中的字符。

Example Template Expansion

模板扩展示例

       {;who}             ;who=fred
       {;half}            ;half=50%25
       {;empty}           ;empty
       {;v,empty,who}     ;v=6;empty;who=fred
       {;v,bar,who}       ;v=6;who=fred
       {;x,y}             ;x=1024;y=768
       {;x,y,empty}       ;x=1024;y=768;empty
       {;x,y,undef}       ;x=1024;y=768
       {;hello:5}         ;hello=Hello
       {;list}            ;list=red,green,blue
       {;list*}           ;list=red;list=green;list=blue
       {;keys}            ;keys=semi,%3B,dot,.,comma,%2C
       {;keys*}           ;semi=%3B;dot=.;comma=%2C
        
       {;who}             ;who=fred
       {;half}            ;half=50%25
       {;empty}           ;empty
       {;v,empty,who}     ;v=6;empty;who=fred
       {;v,bar,who}       ;v=6;who=fred
       {;x,y}             ;x=1024;y=768
       {;x,y,empty}       ;x=1024;y=768;empty
       {;x,y,undef}       ;x=1024;y=768
       {;hello:5}         ;hello=Hello
       {;list}            ;list=red,green,blue
       {;list*}           ;list=red;list=green;list=blue
       {;keys}            ;keys=semi,%3B,dot,.,comma,%2C
       {;keys*}           ;semi=%3B;dot=.;comma=%2C
        
3.2.8. Form-Style Query Expansion: {?var}
3.2.8. 表单样式查询扩展:{?var}

Form-style query expansion, as indicated by the question-mark ("?") operator in Level 3 and above templates, is useful for describing an entire optional query component.

如级别3及以上模板中的问号(“?”)运算符所示,表单样式查询扩展对于描述整个可选查询组件非常有用。

For each defined variable in the variable-list:

对于变量列表中定义的每个变量:

o append "?" to the result string if this is the first defined value or append "&" thereafter;

o 如果这是第一个定义的值,则在结果字符串中追加“?”,或在其后追加“&”;

o if the variable has a simple string value or no explode modifier is given, append the variable name (encoded as if it were a literal string) and an equals character ("=") to the result string; and,

o 如果变量有一个简单的字符串值或没有给出分解修饰符,则在结果字符串中附加变量名(编码方式与文字字符串相同)和一个等于字符(“=”);和

o perform variable expansion, as defined in Section 3.2.1, with the allowed characters being those in the unreserved set.

o 执行第3.2.1节中定义的变量扩展,允许的字符为未保留集中的字符。

Example Template Expansion

模板扩展示例

       {?who}             ?who=fred
       {?half}            ?half=50%25
       {?x,y}             ?x=1024&y=768
       {?x,y,empty}       ?x=1024&y=768&empty=
       {?x,y,undef}       ?x=1024&y=768
       {?var:3}           ?var=val
       {?list}            ?list=red,green,blue
       {?list*}           ?list=red&list=green&list=blue
       {?keys}            ?keys=semi,%3B,dot,.,comma,%2C
       {?keys*}           ?semi=%3B&dot=.&comma=%2C
        
       {?who}             ?who=fred
       {?half}            ?half=50%25
       {?x,y}             ?x=1024&y=768
       {?x,y,empty}       ?x=1024&y=768&empty=
       {?x,y,undef}       ?x=1024&y=768
       {?var:3}           ?var=val
       {?list}            ?list=red,green,blue
       {?list*}           ?list=red&list=green&list=blue
       {?keys}            ?keys=semi,%3B,dot,.,comma,%2C
       {?keys*}           ?semi=%3B&dot=.&comma=%2C
        
3.2.9. Form-Style Query Continuation: {&var}
3.2.9. 表单样式查询继续:{&var}

Form-style query continuation, as indicated by the ampersand ("&") operator in Level 3 and above templates, is useful for describing optional &name=value pairs in a template that already contains a literal query component with fixed parameters.

如级别3及以上模板中的符号(&)运算符所示,表单样式查询继续对于描述已包含具有固定参数的文本查询组件的模板中的可选&name=值对非常有用。

For each defined variable in the variable-list:

对于变量列表中定义的每个变量:

o append "&" to the result string;

o 将“&”附加到结果字符串中;

o if the variable has a simple string value or no explode modifier is given, append the variable name (encoded as if it were a literal string) and an equals character ("=") to the result string; and,

o 如果变量有一个简单的字符串值或没有给出分解修饰符,则在结果字符串中附加变量名(编码方式与文字字符串相同)和一个等于字符(“=”);和

o perform variable expansion, as defined in Section 3.2.1, with the allowed characters being those in the unreserved set.

o 执行第3.2.1节中定义的变量扩展,允许的字符为未保留集中的字符。

Example Template Expansion

模板扩展示例

       {&who}             &who=fred
       {&half}            &half=50%25
       ?fixed=yes{&x}     ?fixed=yes&x=1024
       {&x,y,empty}       &x=1024&y=768&empty=
       {&x,y,undef}       &x=1024&y=768
        
       {&who}             &who=fred
       {&half}            &half=50%25
       ?fixed=yes{&x}     ?fixed=yes&x=1024
       {&x,y,empty}       &x=1024&y=768&empty=
       {&x,y,undef}       &x=1024&y=768
        
       {&var:3}           &var=val
       {&list}            &list=red,green,blue
       {&list*}           &list=red&list=green&list=blue
       {&keys}            &keys=semi,%3B,dot,.,comma,%2C
       {&keys*}           &semi=%3B&dot=.&comma=%2C
        
       {&var:3}           &var=val
       {&list}            &list=red,green,blue
       {&list*}           &list=red&list=green&list=blue
       {&keys}            &keys=semi,%3B,dot,.,comma,%2C
       {&keys*}           &semi=%3B&dot=.&comma=%2C
        
4. Security Considerations
4. 安全考虑

A URI Template does not contain active or executable content. However, it might be possible to craft unanticipated URIs if an attacker is given control over the template or over the variable values within an expression that allows reserved characters in the expansion. In either case, the security considerations are largely determined by who provides the template, who provides the values to use for variables within the template, in what execution context the expansion occurs (client or server), and where the resulting URIs are used.

URI模板不包含活动或可执行内容。但是,如果攻击者可以控制模板或表达式中允许扩展中保留字符的变量值,则可能会创建意外的URI。在这两种情况下,安全性考虑主要取决于谁提供模板、谁提供用于模板内变量的值、在什么执行上下文中进行扩展(客户机或服务器)以及结果URI的使用位置。

This specification does not limit where URI Templates might be used. Current implementations exist within server-side development frameworks and within client-side javascript for computed links or forms.

此规范不限制可能使用URI模板的位置。当前的实现存在于服务器端开发框架和计算链接或表单的客户端javascript中。

Within frameworks, templates usually act as guides for where data might occur within later (request-time) URIs in client requests. Hence, the security concerns are not in the templates themselves, but rather in how the server extracts and processes the user-provided data within a normal Web request.

在框架中,模板通常充当数据可能在客户端请求的稍后(请求时)URI中出现的位置的指南。因此,安全问题不在于模板本身,而在于服务器如何在正常的Web请求中提取和处理用户提供的数据。

Within client-side implementations, a URI Template has many of the same properties as HTML forms, except limited to URI characters and possibly included in HTTP header field values instead of just message body content. Care ought to be taken to ensure that potentially dangerous URI reference strings, such as those beginning with "javascript:", do not appear in the expansion unless both the template and the values are provided by a trusted source.

在客户端实现中,URI模板具有许多与HTML表单相同的属性,除了限于URI字符,并且可能包含在HTTP头字段值中,而不仅仅是消息体内容。应该注意确保潜在危险的URI引用字符串(例如以“javascript:”开头的字符串)不会出现在扩展中,除非模板和值都由可信源提供。

Other security considerations are the same as those for URIs, as described in Section 7 of [RFC3986].

其他安全注意事项与URI相同,如[RFC3986]第7节所述。

5. Acknowledgments
5. 致谢

The following people made contributions to this specification: Mike Burrows, Michaeljohn Clement, DeWitt Clinton, John Cowan, Stephen Farrell, Robbie Gates, Vijay K. Gurbani, Peter Johanson, Murray S. Kucherawy, James H. Manger, Tom Petch, Marc Portier, Pete Resnick, James Snell, and Jiankang Yao.

以下人员对本规范做出了贡献:迈克·伯罗斯、迈克尔·约翰·克莱门特、德维特·克林顿、约翰·考恩、斯蒂芬·法雷尔、罗比·盖茨、维杰·K·古巴尼、彼得·约翰逊、默里·S·库奇拉维、詹姆斯·马格尔、汤姆·佩奇、马克·波蒂尔、彼得·雷斯尼克、詹姆斯·斯奈尔和姚建康。

6. References
6. 工具书类
6.1. Normative References
6.1. 规范性引用文件

[ASCII] American National Standards Institute, "Coded Character Set - 7-bit American Standard Code for Information Interchange", ANSI X3.4, 1986.

[ASCII]美国国家标准协会,“编码字符集-信息交换用7位美国标准代码”,ANSI X3.41986。

[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.

[RFC2119]Bradner,S.,“RFC中用于表示需求水平的关键词”,BCP 14,RFC 2119,1997年3月。

[RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 10646", STD 63, RFC 3629, November 2003.

[RFC3629]Yergeau,F.,“UTF-8,ISO 10646的转换格式”,STD 63,RFC 3629,2003年11月。

[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, January 2005.

[RFC3986]Berners Lee,T.,Fielding,R.,和L.Masinter,“统一资源标识符(URI):通用语法”,STD 66,RFC 3986,2005年1月。

[RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource Identifiers (IRIs)", RFC 3987, January 2005.

[RFC3987]Duerst,M.和M.Suignard,“国际化资源标识符(IRIs)”,RFC 3987,2005年1月。

[RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", STD 68, RFC 5234, January 2008.

[RFC5234]Crocker,D.和P.Overell,“语法规范的扩充BNF:ABNF”,STD 68,RFC 5234,2008年1月。

[RFC6365] Hoffman, P. and J. Klensin, "Terminology Used in Internationalization in the IETF", BCP 166, RFC 6365, September 2011.

[RFC6365]Hoffman,P.和J.Klensin,“IETF国际化中使用的术语”,BCP 166,RFC 6365,2011年9月。

[UNIV6] The Unicode Consortium, "The Unicode Standard, Version 6.0.0", (Mountain View, CA: The Unicode Consortium, 2011. ISBN 978-1-936213-01-6), <http://www.unicode.org/versions/Unicode6.0.0/>.

[UNIV6]Unicode联盟,“Unicode标准,版本6.0.0”(加利福尼亚州山景城:Unicode联盟,2011年,ISBN 978-1-936213-01-6)<http://www.unicode.org/versions/Unicode6.0.0/>.

[UTR15] Davis, M. and M. Duerst, "Unicode Normalization Forms", Unicode Standard Annex # 15, April 2003, <http://www.unicode.org/unicode/reports/tr15/ tr15-23.html>.

[UTR15]Davis,M.和M.Duerst,“Unicode规范化格式”,Unicode标准附录#15,2003年4月<http://www.unicode.org/unicode/reports/tr15/ tr15-23.html>。

6.2. Informative References
6.2. 资料性引用

[OpenSearch] Clinton, D., "OpenSearch 1.1", Draft 5, December 2011, <http://www.opensearch.org/Specifications/OpenSearch>.

[OpenSearch]Clinton,D.,“OpenSearch 1.1”,草案5,2011年12月<http://www.opensearch.org/Specifications/OpenSearch>.

[UPU-S42] Universal Postal Union, "International Postal Address Components and Templates", UPU S42-1, November 2002, <http://www.upu.int/en/activities/addressing/ standards.html>.

[UPU-S42]万国邮政联盟,“国际邮政地址组件和模板”,UPU S42-112002年11月<http://www.upu.int/en/activities/addressing/ standards.html>。

[WADL] Hadley, M., "Web Application Description Language", World Wide Web Consortium Member Submission SUBM-wadl-20090831, August 2009, <http://www.w3.org/Submission/2009/ SUBM-wadl-20090831/>.

[WADL]Hadley,M.,“Web应用程序描述语言”,万维网联盟成员提交SUBM-WADL-200908312009年8月<http://www.w3.org/Submission/2009/ SUBM-wadl-20090831/>。

[WSDL] Weerawarana, S., Moreau, J., Ryman, A., and R. Chinnici, "Web Services Description Language (WSDL) Version 2.0 Part 1: Core Language", World Wide Web Consortium Recommendation REC-wsdl20-20070626, June 2007, <http://www.w3.org/TR/2007/ REC-wsdl20-20070626>.

[WSDL]Weerawarana,S.,Moreau,J.,Ryman,A.,和R.Chinnici,“Web服务描述语言(WSDL)版本2.0第1部分:核心语言”,万维网联盟建议REC-wsdl20-200706262007年6月<http://www.w3.org/TR/2007/ REC-wsdl20-20070626>。

Appendix A. Implementation Hints
附录A.实施提示

The normative sections on expansion describe each operator with a separate expansion process for the sake of descriptive clarity. In actual implementations, we expect the expressions to be processed left-to-right using a common algorithm that has only minor variations in process per operator. This non-normative appendix describes one such algorithm.

关于扩展的规范性章节描述了每个操作员的单独扩展过程,以便于描述清晰。在实际实现中,我们希望使用一种通用算法从左到右处理表达式,该算法在每个运算符的处理过程中只有很小的变化。本非规范性附录描述了一种此类算法。

Initialize an empty result string and its non-error state.

初始化空结果字符串及其非错误状态。

Scan the template and copy literals to the result string (as in Section 3.1) until an expression is indicated by a "{", an error is indicated by the presence of a non-literals character other than "{", or the template ends. When it ends, return the result string and its current error or non-error state.

扫描模板并将文本复制到结果字符串(如第3.1节所示),直到表达式由“{”表示,错误由“{”以外的非文本字符表示,或者模板结束。结束时,返回结果字符串及其当前错误或非错误状态。

o If an expression is found, scan the template to the next "}" and extract the characters in between the braces.

o 如果找到表达式,请将模板扫描到下一个“}”,并提取大括号之间的字符。

o If the template ends before a "}", then append the "{" and extracted characters to the result string and return with an error status indicating the expression is malformed.

o 如果模板在“}”之前结束,则将“{”和提取的字符追加到结果字符串中,并返回一个错误状态,指示表达式格式错误。

Examine the first character of the extracted expression for an operator.

为运算符检查提取表达式的第一个字符。

o If the expression ended (i.e., is "{}"), an operator is found that is unknown or unimplemented, or the character is not in the varchar set (Section 2.3), then append "{", the extracted expression, and "}" to the result string, remember that the result is in an error state, and then go back to scan the remainder of the template.

o 如果表达式结束(即为“{}”),则发现未知或未实现的运算符,或字符不在varchar集合中(第2.3节),然后将“{”、提取的表达式和“}”附加到结果字符串中,记住结果处于错误状态,然后返回扫描模板的其余部分。

o If a known and implemented operator is found, store the operator and skip to the next character to begin the varspec-list.

o 如果找到已知且已实现的运算符,请存储该运算符并跳到下一个字符以开始varspec列表。

o Otherwise, store the operator as NUL (simple string expansion).

o 否则,将运算符存储为NUL(简单字符串扩展)。

Use the following value table to determine the processing behavior by expression type operator. The entry for "first" is the string to append to the result first if any of the expression's variables are defined. The entry for "sep" is the separator to append to the result before any second (or subsequent) defined variable expansion. The entry for "named" is a boolean for whether or not the expansion includes the variable or key name when no explode modifier is given. The entry for "ifemp" is a string to append to the name if its corresponding value is empty. The entry for "allow" indicates what

使用以下值表确定表达式类型运算符的处理行为。如果定义了表达式的任何变量,“first”的条目是要首先附加到结果的字符串。“sep”的条目是在任何第二次(或后续)定义的变量展开之前附加到结果的分隔符。“named”的条目是一个布尔值,表示在未指定分解修改器时,展开是否包含变量名或键名。“ifemp”的条目是一个字符串,如果其对应值为空,则要附加到名称中。“允许”的条目表示什么

characters to allow unencoded within the value expansion: (U) means any character not in the unreserved set will be encoded; (U+R) means any character not in the union of (unreserved / reserved / pct-encoding) will be encoded; and, for both cases, each disallowed character is first encoded as its sequence of octets in UTF-8 and then each such octet is encoded as a pct-encoded triplet.

允许在值扩展中未编码的字符:(U)表示不在未保留集中的任何字符都将被编码;(U+R)表示任何不在(非保留/保留/pct编码)联合中的字符将被编码;并且,对于这两种情况,每个不允许的字符首先被编码为UTF-8中的八位元序列,然后每个这样的八位元被编码为pct编码的三位元。

   .------------------------------------------------------------------.
   |          NUL     +      .       /       ;      ?      &      #   |
   |------------------------------------------------------------------|
   | first |  ""     ""     "."     "/"     ";"    "?"    "&"    "#"  |
   | sep   |  ","    ","    "."     "/"     ";"    "&"    "&"    ","  |
   | named | false  false  false   false   true   true   true   false |
   | ifemp |  ""     ""     ""      ""      ""     "="    "="    ""   |
   | allow |   U     U+R     U       U       U      U      U     U+R  |
   `------------------------------------------------------------------'
        
   .------------------------------------------------------------------.
   |          NUL     +      .       /       ;      ?      &      #   |
   |------------------------------------------------------------------|
   | first |  ""     ""     "."     "/"     ";"    "?"    "&"    "#"  |
   | sep   |  ","    ","    "."     "/"     ";"    "&"    "&"    ","  |
   | named | false  false  false   false   true   true   true   false |
   | ifemp |  ""     ""     ""      ""      ""     "="    "="    ""   |
   | allow |   U     U+R     U       U       U      U      U     U+R  |
   `------------------------------------------------------------------'
        

With the above table in mind, process the variable-list as follows:

记住上表,按如下方式处理变量列表:

For each varspec, extract a variable name and optional modifier from the expression by scanning the variable-list until a character not in the varname set is found or the end of the expression is reached.

对于每个varspec,通过扫描变量列表从表达式中提取变量名和可选修饰符,直到找到不在varname集中的字符或到达表达式的末尾。

o If it is the end of the expression and the varname is empty, go back to scan the remainder of the template.

o 如果它是表达式的结尾,并且varname为空,请返回扫描模板的其余部分。

o If it is not the end of the expression and the last character found indicates a modifier ("*" or ":"), remember that modifier. If it is an explode ("*"), scan the next character. If it is a prefix (":"), continue scanning the next one to four characters for the max-length represented as a decimal integer and then, if it is still not the end of the expression, scan the next character.

o 如果它不是表达式的结尾,并且找到的最后一个字符表示修饰符(“*”或“:”),请记住该修饰符。如果是分解(“*”),请扫描下一个字符。如果它是前缀(“:”),则继续扫描下一个一到四个字符,以获取表示为十进制整数的最大长度,然后,如果它仍然不是表达式的结尾,则扫描下一个字符。

o If it is not the end of the expression and the last character found is not a comma (","), append "{", the stored operator (if any), the scanned varname and modifier, the remaining expression, and "}" to the result string, remember that the result is in an error state, and then go back to scan the remainder of the template.

o 如果它不是表达式的结尾,并且找到的最后一个字符不是逗号(“,”),请将“{”、存储的运算符(如果有)、扫描的varname和修饰符、剩余的表达式和“}”附加到结果字符串,记住结果处于错误状态,然后返回扫描模板的剩余部分。

Lookup the value for the scanned variable name, and then

查找扫描的变量名的值,然后

o If the varname is unknown or corresponds to a variable with an undefined value (Section 2.3), then skip to the next varspec.

o 如果varname未知或对应于具有未定义值的变量(第2.3节),则跳到下一个varspec。

o If this is the first defined variable for this expression, append the first string for this expression type to the result string and remember that it has been done. Otherwise, append the sep string to the result string.

o 如果这是此表达式的第一个定义变量,请将此表达式类型的第一个字符串附加到结果字符串,并记住已完成此操作。否则,将sep字符串附加到结果字符串。

o If this variable's value is a string, then

o 如果此变量的值是字符串,则

* if named is true, append the varname to the result string using the same encoding process as for literals, and

* 如果named为true,则使用与文本相同的编码过程将varname附加到结果字符串,然后

+ if the value is empty, append the ifemp string to the result string and skip to the next varspec;

+ 如果值为空,则将ifemp字符串附加到结果字符串并跳到下一个varspec;

+ otherwise, append "=" to the result string.

+ 否则,将“=”附加到结果字符串。

* if a prefix modifier is present and the prefix length is less than the value string length in number of Unicode characters, append that number of characters from the beginning of the value string to the result string, after pct-encoding any characters that are not in the allow set, while taking care not to split multi-octet or pct-encoded triplet characters that represent a single Unicode code point;

* 如果存在前缀修饰符,且前缀长度小于Unicode字符数的值字符串长度,则在对不在允许集中的任何字符进行pct编码后,将该值字符串开头的字符数追加到结果字符串中,注意不要拆分表示单个Unicode码点的多个八位或pct编码的三位字符;

* otherwise, append the value to the result string after pct-encoding any characters that are not in the allow set.

* 否则,在pct编码任何不在允许集中的字符后,将该值附加到结果字符串。

o else if no explode modifier is given, then

o 否则,如果未指定“分解”修改器,则

* if named is true, append the varname to the result string using the same encoding process as for literals, and

* 如果named为true,则使用与文本相同的编码过程将varname附加到结果字符串,然后

+ if the value is empty, append the ifemp string to the result string and skip to the next varspec;

+ 如果值为空,则将ifemp字符串附加到结果字符串并跳到下一个varspec;

+ otherwise, append "=" to the result string; and

+ 否则,将“=”追加到结果字符串中;和

* if this variable's value is a list, append each defined list member to the result string, after pct-encoding any characters that are not in the allow set, with a comma (",") appended to the result between each defined list member;

* 如果此变量的值是一个列表,则在对不在允许集中的任何字符进行pct编码后,将每个定义的列表成员追加到结果字符串中,并在每个定义的列表成员之间的结果中追加逗号(“,”);

* if this variable's value is an associative array or any other form of paired (name, value) structure, append each pair with a defined value to the result string as "name,value", after pct-encoding any characters that are not in the allow set, with a comma (",") appended to the result between each defined pair.

* 如果此变量的值是关联数组或任何其他形式的成对(名称、值)结构,请在对不在允许集中的任何字符进行pct编码后,在结果字符串中附加定义值作为“名称、值”的每一对,并在每一定义对之间的结果中附加逗号(“,”)。

o else if an explode modifier is given, then

o 否则,如果给定了“分解”修改器,则

* if named is true, then for each defined list member or array (name, value) pair with a defined value, do:

* 如果named为true,则对于每个定义的列表成员或数组(名称、值)对和定义的值,执行以下操作:

+ if this is not the first defined member/value, append the sep string to the result string;

+ 如果这不是第一个定义的成员/值,请将sep字符串附加到结果字符串;

+ if this is a list, append the varname to the result string using the same encoding process as for literals;

+ 如果这是一个列表,则使用与文本相同的编码过程将varname追加到结果字符串中;

+ if this is a pair, append the name to the result string using the same encoding process as for literals;

+ 如果这是一对,则使用与文本相同的编码过程将名称附加到结果字符串;

+ if the member/value is empty, append the ifemp string to the result string; otherwise, append "=" and the member/value to the result string, after pct-encoding any member/value characters that are not in the allow set.

+ 如果成员/值为空,则将ifemp字符串追加到结果字符串中;否则,在对不在允许集中的任何成员/值字符进行pct编码后,将“=”和成员/值附加到结果字符串中。

* else if named is false, then

* 否则,如果named为false,则

+ if this is a list, append each defined list member to the result string, after pct-encoding any characters that are not in the allow set, with the sep string appended to the result between each defined list member.

+ 如果这是一个列表,则在对不在允许集中的任何字符进行pct编码后,将每个已定义的列表成员追加到结果字符串中,并将sep字符串追加到每个已定义列表成员之间的结果中。

+ if this is an array of (name, value) pairs, append each pair with a defined value to the result string as "name=value", after pct-encoding any characters that are not in the allow set, with the sep string appended to the result between each defined pair.

+ 如果这是一个(名称、值)对数组,则在pct编码任何不在允许集中的字符后,将每对定义的值作为“名称=值”附加到结果字符串,并将sep字符串附加到每个定义对之间的结果。

When the variable-list for this expression is exhausted, go back to scan the remainder of the template.

当此表达式的变量列表用尽时,返回扫描模板的其余部分。

Authors' Addresses

作者地址

Joe Gregorio Google

乔·格雷戈里奥·谷歌

   EMail: joe@bitworking.org
   URI:   http://bitworking.org/
        
   EMail: joe@bitworking.org
   URI:   http://bitworking.org/
        

Roy T. Fielding Adobe Systems Incorporated

Roy T.菲尔丁Adobe系统公司

   EMail: fielding@gbiv.com
   URI:   http://roy.gbiv.com/
        
   EMail: fielding@gbiv.com
   URI:   http://roy.gbiv.com/
        

Marc Hadley The MITRE Corporation

马克·哈德利米特尔公司

   EMail: mhadley@mitre.org
   URI:   http://mitre.org/
        
   EMail: mhadley@mitre.org
   URI:   http://mitre.org/
        

Mark Nottingham Rackspace

马克诺丁汉货架空间

   EMail: mnot@mnot.net
   URI:   http://www.mnot.net/
        
   EMail: mnot@mnot.net
   URI:   http://www.mnot.net/
        

David Orchard Salesforce.com

David Orchard Salesforce.com

   EMail: orchard@pacificspirit.com
   URI:   http://www.pacificspirit.com/
        
   EMail: orchard@pacificspirit.com
   URI:   http://www.pacificspirit.com/