2. Syntax (Syntaxe)

Un modèle d'URI est une chaîne de caractères Unicode imprimables contenant zéro ou plusieurs expressions de variables (Variable Expressions) intégrées, chaque expression étant délimitée par une paire correspondante d'accolades (', ').

URI-Template  = *( literals / expression )

Bien que les modèles (et les implémentations de processeurs de modèles) soient décrits ci-dessus en termes de quatre niveaux progressifs, nous définissons la syntaxe URI-Template en termes d'ABNF pour le Level 4. Un processeur de modèle limité aux modèles de niveau inférieur PEUT (MAY) exclure les règles ABNF applicables uniquement aux niveaux supérieurs. Cependant, il est RECOMMANDÉ (RECOMMENDED) que tous les analyseurs implémentent la syntaxe complète afin que les niveaux non pris en charge puissent être correctement identifiés comme tels à l'utilisateur final.

2.1. Literals (Littéraux)

Les caractères en dehors des expressions dans une chaîne de modèle d'URI sont destinés à être copiés littéralement dans la référence URI si le caractère est autorisé dans un URI (reserved / unreserved / pct-encoded) ou, s'il n'est pas autorisé, copié dans la référence URI en tant que séquence de triplets encodés en pourcentage correspondant à l'encodage de ce caractère en UTF-8 [RFC3629].

literals      =  %x21 / %x23-24 / %x26 / %x28-3B / %x3D / %x3F-5B
              /  %x5D / %x5F / %x61-7A / %x7E / ucschar / iprivate
              /  pct-encoded
                   ; tout caractère Unicode sauf : CTL, SP,
                   ;  DQUOTE, "'", "%" (hormis pct-encoded),
                   ;  "<", ">", "\", "^", "`", "{", "|", "}"

2.2. Expressions

Les expressions de modèle sont les parties paramétrées d'un modèle d'URI. Chaque expression contient un opérateur optionnel (Operator) qui définit le type d'expression et son processus d'expansion correspondant, suivi d'une liste séparée par des virgules de spécificateurs de variables (Variable Specifiers) (noms de variables et modificateurs de valeur optionnels). Si aucun opérateur n'est fourni, l'expression par défaut est une expansion de variable simple de valeurs non réservées.

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

Les caractères d'opérateur ont été choisis pour refléter chacun de leurs rôles en tant que caractères réservés dans la syntaxe générique URI. Les opérateurs définis dans la section 3 de cette spécification incluent :

• + Chaînes de caractères réservées (Reserved character strings)
• # Identificateurs de fragment préfixés par "#" (Fragment identifiers)
• . Étiquettes de nom ou extensions préfixées par "." (Name labels or extensions)
• / Segments de chemin préfixés par "/" (Path segments)
• ; Nom de paramètre de chemin ou paires name=value préfixées par ";" (Path parameter name or name=value pairs)
• ? Composant de requête commençant par "?" et constitué de paires name=value séparées par "&" (Query component)
• & Continuation de paires &name=value de style requête dans un composant de requête littéral (Continuation of query-style pairs)

Les caractères d'opérateur égal ("="), virgule (","), point d'exclamation ("!"), arobase ("@") et pipe ("|") sont réservés pour les extensions futures.

La syntaxe d'expression exclut spécifiquement l'utilisation du dollar ("$") et des parenthèses ["(" et ")"] afin qu'ils restent disponibles pour une utilisation en dehors du champ d'application de cette spécification. Par exemple, un langage de macros pourrait utiliser ces caractères pour appliquer une substitution de macro à une chaîne avant que cette chaîne ne soit traitée comme un modèle d'URI.

2.3. Variables

Après l'opérateur (le cas échéant), chaque expression contient une liste d'un ou plusieurs spécificateurs de variables (varspec) séparés par des virgules. Les noms de variables servent plusieurs objectifs : documentation sur les types de valeurs attendues, identificateurs pour associer des valeurs dans un processeur de modèle, et chaîne littérale à utiliser pour le nom dans les expansions name=value (sauf lors de l'explosion d'un tableau associatif). Les noms de variables sont sensibles à la casse car le nom peut être expansé dans un composant URI sensible à la casse.

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

Un varname PEUT (MAY) contenir un ou plusieurs triplets encodés en pourcentage. Ces triplets sont considérés comme une partie essentielle du nom de variable et ne sont pas décodés pendant le traitement. Un varname contenant des caractères encodés en pourcentage n'est pas la même variable qu'un varname avec ces mêmes caractères décodés. Les applications qui fournissent des modèles d'URI sont censées être cohérentes dans leur utilisation de l'encodage en pourcentage dans les noms de variables.

Une expression PEUT (MAY) référencer des variables inconnues du processeur de modèle ou dont la valeur est définie sur une valeur spéciale "undefined (indéfinie)" telle que undef ou null. Ces variables indéfinies reçoivent un traitement spécial par le processus d'expansion (Section 3.2.1).

Une valeur de variable qui est une chaîne de longueur zéro n'est pas considérée comme indéfinie ; elle a la valeur définie d'une chaîne vide.

Dans les modèles Level 4, une variable peut avoir une valeur composite (Composite Value) sous forme de liste de valeurs ou de tableau associatif de paires (name, value). Ces types de valeurs ne sont pas directement indiqués par la syntaxe du modèle, mais ils ont un impact sur le processus d'expansion (Section 3.2.1).

Une variable définie comme une valeur de liste est considérée comme indéfinie si la liste contient zéro membre. Une variable définie comme un tableau associatif de paires (name, value) est considérée comme indéfinie si le tableau contient zéro membre ou si tous les noms de membres dans le tableau sont associés à des valeurs indéfinies.

2.4. Value Modifiers (Modificateurs de valeur)

Chacune des variables dans une expression de modèle Level 4 peut avoir un modificateur indiquant soit que son expansion est limitée à un préfixe de la chaîne de valeur de la variable, soit que son expansion est explosée comme une valeur composite sous forme de liste de valeurs ou de tableau associatif de paires (name, value).

modifier-level4 =  prefix / explode

2.4.1. Prefix Values (Valeurs de préfixe)

Un modificateur de préfixe (Prefix Modifier) indique que l'expansion de la variable est limitée à un préfixe de la chaîne de valeur de la variable. Les modificateurs de préfixe sont souvent utilisés pour partitionner un espace d'identificateurs de manière hiérarchique, comme c'est courant dans les indices de référence et le stockage basé sur le hachage. Il sert également à limiter la valeur expansée à un nombre maximum de caractères. Les modificateurs de préfixe ne sont pas applicables aux variables qui ont des valeurs composites.

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

Le max-length est un entier positif qui fait référence à un nombre maximum de caractères depuis le début de la valeur de la variable en tant que chaîne Unicode. Notez que cette numérotation est en caractères, pas en octets, afin d'éviter de diviser entre les octets d'un caractère codé en multi-octets ou dans un triplet encodé en pourcentage. Si le max-length est supérieur à la longueur de la valeur de la variable, la chaîne de valeur entière est utilisée.

Par exemple :

Avec les affectations de variables

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

Exemple de modèle    Expansion

  {var}              value
  {var:20}           value
  {var:3}            val
  {semi}             %3B
  {semi:2}           %3B

2.4.2. Composite Values (Valeurs composites)

Un modificateur d'explosion (Explode Modifier) ("*") indique que la variable doit être traitée comme une valeur composite composée soit d'une liste de valeurs, soit d'un tableau associatif de paires (name, value). Par conséquent, le processus d'expansion est appliqué à chaque membre du composite comme s'il était répertorié comme une variable distincte. Ce type de spécification de variable est nettement moins auto-documenté que les variables non explosées, car il y a moins de correspondance entre le nom de la variable et la manière dont la référence URI apparaît après l'expansion.

explode       =  "*"

Étant donné que les modèles d'URI ne contiennent pas d'indication de type ou de schéma, le type d'une variable explosée est supposé être déterminé par le contexte. Par exemple, le processeur peut se voir fournir des valeurs sous une forme qui différencie les valeurs en tant que chaînes, listes ou tableaux associatifs. De même, le contexte dans lequel le modèle est utilisé (script, langage de balisage, langage de définition d'interface, etc.) peut définir des règles pour associer les noms de variables aux types, structures ou schémas.

Les modificateurs d'explosion améliorent la concision de la syntaxe du modèle d'URI. Par exemple, une ressource qui fournit une carte géographique pour une adresse de rue donnée pourrait accepter une centaine de permutations sur les champs d'entrée d'adresse, y compris des adresses partielles (par exemple, juste la ville ou le code postal). Une telle ressource pourrait être décrite comme un modèle avec chaque composant d'adresse répertorié dans l'ordre, ou avec un modèle beaucoup plus simple qui utilise un modificateur d'explosion, comme dans :

/mapper{?address*}

avec un contexte qui définit ce que la variable nommée "address" peut inclure, par exemple par référence à une autre norme d'adressage (par exemple, [UPU-S42]). Un destinataire connaissant le schéma peut alors fournir des expansions appropriées, telles que :

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

Le processus d'expansion pour les variables explosées dépend à la fois de l'opérateur utilisé et du fait que la valeur composite soit traitée comme une liste de valeurs ou comme un tableau associatif de paires (name, value). Les structures sont traitées comme un tableau associatif avec des noms correspondant aux champs de la définition de structure et des séparateurs "." utilisés pour indiquer la hiérarchie des noms dans les sous-structures.

Si une variable a une structure composite et que seuls certains champs de cette structure ont des valeurs définies, alors seules les paires définies sont présentes dans l'expansion. Cela peut être utile pour les modèles composés d'un grand nombre de termes de requête potentiels.

Un modificateur d'explosion appliqué à une variable de liste provoque l'expansion pour répéter l'expansion de cette variable selon l'opérateur, une fois pour chaque membre de la liste.

---