git.sur5r.net Git - openldap/blob - doc/rfc/rfc2596.txt

   1
   2
   3
   4
   5
   6
   7 Network Working Group                                            M. Wahl
   8 Request for Comments: 2596                  Innosoft International, Inc.
   9 Category: Standards Track                                       T. Howes
  10                                            Netscape Communications Corp.
  11                                                                 May 1999
  12
  13
  14                      Use of Language Codes in LDAP
  15
  16
  17 Status of this Memo
  18
  19    This document specifies an Internet standards track protocol for the
  20    Internet community, and requests discussion and suggestions for
  21    improvements.  Please refer to the current edition of the "Internet
  22    Official Protocol Standards" (STD 1) for the standardization state
  23    and status of this protocol.  Distribution of this memo is unlimited.
  24
  25 Copyright Notice
  26
  27    Copyright (C) The Internet Society (1999).  All Rights Reserved.
  28
  29 1. Abstract
  30
  31    The Lightweight Directory Access Protocol [1] provides a means for
  32    clients to interrogate and modify information stored in a distributed
  33    directory system.  The information in the directory is maintained as
  34    attributes [2] of entries.  Most of these attributes have syntaxes
  35    which are human-readable strings, and it is desirable to be able to
  36    indicate the natural language associated with attribute values.
  37
  38    This document describes how language codes [3] are carried in LDAP
  39    and are to be interpreted by LDAP servers.  All implementations MUST
  40    be prepared to accept language codes in the LDAP protocols.  Servers
  41    may or may not be capable of storing attributes with language codes
  42    in the directory.  This document does not specify how to determine
  43    whether particular attributes can or cannot have language codes.
  44
  45    The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
  46    "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and "OPTIONAL" in this
  47    document are to be interpreted as described in RFC 2119 [4].
  48
  49 2. Language Codes
  50
  51    Section 2 of RFC 1766 [3] describes the language code format which is
  52    used in LDAP.  Briefly, it is a string of ASCII alphabetic characters
  53    and hyphens.  Examples include "fr", "en-US" and "ja-JP".
  54
  55
  56
  57
  58 Wahl & Howes                Standards Track                     [Page 1]
  59 \f
  60 RFC 2596             Use of Language Codes in LDAP              May 1999
  61
  62
  63    Language codes are case insensitive.  For example, the language code
  64    "en-us" is the same as "EN-US" and "en-US".
  65
  66    Implementations MUST NOT otherwise interpret the structure of the
  67    code when comparing two codes, and MUST treat them as simply strings
  68    of characters. Client and server implementations MUST allow any
  69    arbitrary string which follows the patterns given in RFC 1766 to be
  70    used as a language code.
  71
  72 3. Use of Language Codes in LDAP
  73
  74    This section describes how LDAP implementations MUST interpret
  75    language codes in performing operations.
  76
  77    In general, an attribute with a language code is to be treated as a
  78    subtype of the attribute without a language code.  If a server does
  79    not support storing language codes with attribute values in the DIT,
  80    then it MUST always treat an attribute with a language code as an
  81    unrecognized attribute.
  82
  83 3.1. Attribute Description
  84
  85    An attribute consists of a type, a list of options for that type, and
  86    a set of one or more values.  In LDAP, the type and the options are
  87    combined into the AttributeDescription, defined in section 4.1.5 of
  88    [1]. This is represented as an attribute type name and a possibly-
  89    empty list of options.  One of these options associates a natural
  90    language with values for that attribute.
  91
  92         language-option = "lang-" lang-code
  93
  94         lang-code = printable-ascii ; a code as defined in RFC 1766
  95
  96    Multiple language options may be present on a particular value.
  97
  98    The language code has no effect on the character set encoding for
  99    string representations of DirectoryString syntax values; the UTF-8
 100    representation of UniversalString (ISO 10646) is always used.
 101
 102    Examples of valid AttributeDescription:
 103         givenName;lang-en-US
 104         CN;lang-ja
 105
 106    In LDAP and in examples in this document, a directory attribute is
 107    represented as an AttributeDescription with a list of values.  Note
 108    that the data could be stored in the LDAP server in a different
 109    representation.
 110
 111
 112
 113
 114 Wahl & Howes                Standards Track                     [Page 2]
 115 \f
 116 RFC 2596             Use of Language Codes in LDAP              May 1999
 117
 118
 119 3.2. Distinguished Names and Relative Distinguished Names
 120
 121    No attribute description options are permitted in Distinguished Names
 122    or Relative Distinguished Names.  Thus language codes MUST NOT be
 123    used in forming DNs.
 124
 125 3.3. Search Filter
 126
 127    If a language code is present in an AttributeDescription in a search
 128    filter, then only attribute values in the directory which match the
 129    base attribute type or its subtype, the language code and the
 130    assertion value match this filter.
 131
 132    Thus for example a filter of an equality match of type "name;lang-
 133    en-US" and assertion value "Billy Ray", against the following
 134    directory entry
 135
 136    objectclass: top                     DOES NOT MATCH (wrong type)
 137    objectclass: person                  DOES NOT MATCH (wrong type)
 138    name;lang-EN-US: Billy Ray           MATCHES
 139    name;lang-EN-US: Billy Bob           DOES NOT MATCH (wrong value)
 140    CN;lang-en-us: Billy Ray                MATCHES
 141    CN;lang-EN-US;dynamic: Billy Ray     MATCHES
 142    CN;lang-en;dynamic: Billy Ray        DOES NOT MATCH (differing lang-)
 143    name: Billy Ray                      DOES NOT MATCH (no lang-)
 144    SN: Ray                              DOES NOT MATCH (wrong value)
 145
 146    (Note that "CN" and "SN" are subtypes of "name".)
 147
 148    Client implementors should however note that providing a language
 149    code in a search filter AttributeDescription will often filter out
 150    desirable values where the language code does not match exactly.  For
 151    example, the filter (name;lang-en=Billy Ray) does NOT match the
 152    attribute "name;lang-en-US: Billy Ray".
 153
 154    If the server does not support storing language codes with attribute
 155    values in the DIT, then any filter which includes a language code
 156    will always fail to match, as it is an unrecognized attribute type.
 157    No error would be returned because of this; a presence filter would
 158    evaluate to FALSE and all other forms to Undefined.
 159
 160    If no language code is specified in the search filter, then only the
 161    base attribute type and the assertion value need match the value in
 162    the directory.
 163
 164    Thus for example a filter of an equality match of type "name" and
 165    assertion value "Billy Ray", against the following directory entry
 166
 167
 168
 169
 170 Wahl & Howes                Standards Track                     [Page 3]
 171 \f
 172 RFC 2596             Use of Language Codes in LDAP              May 1999
 173
 174
 175    objectclass: top                     DOES NOT MATCH (wrong type)
 176    objectclass: person                  DOES NOT MATCH (wrong type)
 177    name;lang-EN-US: Billy Ray           MATCHES
 178    name;lang-EN-US: Billy Bob           DOES NOT MATCH (wrong value)
 179    CN;lang-EN-US;dynamic: Billy Ray     MATCHES
 180    CN;lang-en;dynamic: Billy Ray        MATCHES
 181    name: Billy Ray                      MATCHES
 182    SN: Ray                              DOES NOT MATCH (wrong value)
 183
 184    Thus in general, clients SHOULD NOT use the language code option in
 185    AttributeDescription fields in search filters.
 186
 187 3.4. Compare
 188
 189    A language code can be present in an AttributeDescription used in a
 190    compare request AttributeValueAssertion.  This is to be treated by
 191    servers the same as the use of language codes in a search filter with
 192    an equality match, as described in the previous section.  If there is
 193    no attribute in the entry with the same subtype and language code,
 194    the noSuchAttributeType error will be returned.
 195
 196    Thus for example a compare request of type "name" and assertion value
 197    "Johann", against an entry with all the following directory entry
 198
 199    objectclass: top
 200    objectclass: person
 201    givenName;lang-de-DE: Johann
 202    CN: Johann Sibelius
 203    SN: Sibelius
 204
 205    will cause the server to return compareTrue.
 206
 207    However, if the client issued a compare request of type "name;lang-
 208    de" and assertion value "Johann" against the above entry, the request
 209    would fail with the noSuchAttributeType error.
 210
 211    If the server does not support storing language codes with attribute
 212    values in the DIT, then any comparison which includes a language code
 213    will always fail to locate an attribute type, and noSuchAttributeType
 214    will be returned.
 215
 216    Thus in general, clients SHOULD NOT use the language code option in
 217    AttributeDescription fields in the compare request.
 218
 219 3.5. Requested Attributes in Search
 220
 221    Clients MAY provide language codes in AttributeDescription in the
 222    requested attribute list in a search request.
 223
 224
 225
 226 Wahl & Howes                Standards Track                     [Page 4]
 227 \f
 228 RFC 2596             Use of Language Codes in LDAP              May 1999
 229
 230
 231    If a language code is provided in an attribute description, then only
 232    attribute values in a directory entry which have the same language
 233    code as that provided are to be returned. Thus if a client requests
 234    an attribute "description;lang-en", the server MUST NOT return values
 235    of an attribute "description" or "description;lang-fr".
 236
 237    Clients MAY provide in the attribute list multiple
 238    AttributeDescription which have the same base attribute type but
 239    different options. For example a client MAY provide both "name;lang-
 240    en" and "name;lang-fr", and this would permit an attribute with
 241    either language code to be returned.  Note there would be no need to
 242    provide both "name" and "name;lang-en" since all subtypes of name
 243    would match "name".
 244
 245    If a server does not support storing language codes with attribute
 246    values in the DIT, then any attribute descriptions in the list which
 247    include language codes are to be ignored, just as if they were
 248    unknown attribute types.
 249
 250    If a request is made specifying all attributes or an attribute is
 251    requested without providing a language code, then all attribute
 252    values regardless of their language code are returned.
 253
 254    For example, if the client requests a "description" attribute, and a
 255    matching entry contains
 256
 257    objectclass: top
 258    objectclass: organization
 259    O: Software GmbH
 260    description: software
 261    description;lang-en: software products
 262    description;lang-de: Softwareprodukte
 263    postalAddress: Berlin 8001 Germany
 264    postalAddress;lang-de: Berlin 8001 Deutschland
 265
 266    The server will return:
 267
 268    description: software
 269    description;lang-en: software products
 270    description;lang-de: Softwareprodukte
 271
 272 3.6. Add Operation
 273
 274    Clients MAY provide language codes in AttributeDescription in
 275    attributes of a new entry to be created, subject to the limitation
 276    that the client MUST NOT use language codes in the attribute value or
 277    values which form the RDN of the entry.
 278
 279
 280
 281
 282 Wahl & Howes                Standards Track                     [Page 5]
 283 \f
 284 RFC 2596             Use of Language Codes in LDAP              May 1999
 285
 286
 287    A client MAY provide multiple attributes with the same attribute type
 288    and value, so long as each attribute has a different language code,
 289    and at most one attribute does not have a language code option.
 290
 291    Servers which support storing language codes in the DIT MUST allow
 292    any attribute it recognizes that has the Directory String syntax to
 293    have a language option associated with it. Servers SHOULD allow
 294    language options to be associated with other attributes.
 295
 296    For example, the following is a legal request.
 297
 298    objectclass: top
 299    objectclass: person
 300    objectclass: residentialPerson
 301    name: John Smith
 302    CN: John Smith
 303    CN;lang-en: John Smith
 304    SN: Smith
 305    streetAddress: 1 University Street
 306    streetAddress;lang-en: 1 University Street
 307    streetAddress;lang-fr: 1 rue Universite
 308    houseIdentifier;lang-fr: 9e etage
 309
 310    If a server does not support storing language codes with attribute
 311    values in the DIT, then it MUST treat an AttributeDescription with a
 312    language code as an unrecognized attribute. If the server forbids the
 313    addition of unrecognized attributes then it MUST fail the add request
 314    with the appropriate result code.
 315
 316 3.7. Modify Operation
 317
 318    A client MAY provide a language code in an AttributeDescription as
 319    part of a modification element in the modify operation.
 320
 321    Attribute types and language codes MUST match exactly against values
 322    stored in the directory.  For example, if the modification is a
 323    "delete", then if the stored values to be deleted have a language
 324    code, the language code MUST be provided in the modify operation, and
 325    if the stored values to be deleted do not have a language code, then
 326    no language code is to be provided.
 327
 328    If the server does not support storing language codes with attribute
 329    values in the DIT, then it MUST treat an AttributeDescription with a
 330    language code as an unrecognized attribute, and MUST fail the request
 331    with an appropriate result code.
 332
 333
 334
 335
 336
 337
 338 Wahl & Howes                Standards Track                     [Page 6]
 339 \f
 340 RFC 2596             Use of Language Codes in LDAP              May 1999
 341
 342
 343 3.8. Diagnostic Messages
 344
 345    Servers SHOULD use only printable ASCII characters in the
 346    errorMessage field, as not all clients will be able to display the
 347    full range of Unicode.
 348
 349 4. Differences from X.500(1997)
 350
 351    X.500(1997) defines a different mechanism, contexts, as the means of
 352    representing language tags.  This section summarizes the major
 353    differences in approach.
 354
 355    a) An X.500 operation which has specified a language code on a value
 356       matches a value in the directory without a language code.
 357    b) LDAP references RFC 1766, which allows for IANA registration of
 358       new tags.
 359    c) LDAP does not allow language codes in distinguished names.
 360    d) X.500 describes subschema administration procedures to allow
 361       language codes to be associated with particular attributes types.
 362
 363 5. Security Considerations
 364
 365    There are no known security considerations for this document.  See
 366    the security considerations sections of [1] and [2] for security
 367    considerations of LDAP in general.
 368
 369 6. Acknowledgements
 370
 371    This document is a product of the IETF ASID and LDAPEXT working
 372    groups.  Martin Duerst provided many valuable comments on an earlier
 373    version of this document.
 374
 375 7. Bibliography
 376
 377    [1] Wahl, M., Howes, T. and S. Kille, "Lightweight Directory Access
 378        Protocol (v3)", RFC 2251, December 1997.
 379
 380    [2] Wahl, M., Coulbeck, A., Howes, T. and S. Kille, "Lightweight
 381        X.500 Directory Access Protocol Attribute Syntax Definitions",
 382        RFC 2252, December 1997.
 383
 384    [3] Alvestrand, H.,"Tags for the Identification of Languages", RFC
 385        1766, March 1995.
 386
 387    [4] Bradner, S., "Key words for use in RFCs to Indicate Requirement
 388        Levels", BCP 14, RFC 2119, March 1997.
 389
 390
 391
 392
 393
 394 Wahl & Howes                Standards Track                     [Page 7]
 395 \f
 396 RFC 2596             Use of Language Codes in LDAP              May 1999
 397
 398
 399 8. Authors' Addresses
 400
 401    Mark Wahl
 402    Innosoft International, Inc.
 403    8911 Capital of Texas Hwy Suite 4140
 404    Austin, TX 78759 USA
 405
 406    EMail:  M.Wahl@innosoft.com
 407
 408
 409    Tim Howes
 410    Netscape Communications Corp.
 411    501 E. Middlefield Rd
 412    Mountain View, CA 94043 USA
 413
 414    Phone:  +1 650 937-3419
 415    EMail:   howes@netscape.com
 416
 417
 418
 419
 420
 421
 422
 423
 424
 425
 426
 427
 428
 429
 430
 431
 432
 433
 434
 435
 436
 437
 438
 439
 440
 441
 442
 443
 444
 445
 446
 447
 448
 449
 450 Wahl & Howes                Standards Track                     [Page 8]
 451 \f
 452 RFC 2596             Use of Language Codes in LDAP              May 1999
 453
 454
 455 Full Copyright Statement
 456
 457    Copyright (C) The Internet Society (1999).  All Rights Reserved.
 458
 459    This document and translations of it may be copied and furnished to
 460    others, and derivative works that comment on or otherwise explain it
 461    or assist in its implementation may be prepared, copied, published
 462    and distributed, in whole or in part, without restriction of any
 463    kind, provided that the above copyright notice and this paragraph are
 464    included on all such copies and derivative works.  However, this
 465    document itself may not be modified in any way, such as by removing
 466    the copyright notice or references to the Internet Society or other
 467    Internet organizations, except as needed for the purpose of
 468    developing Internet standards in which case the procedures for
 469    copyrights defined in the Internet Standards process must be
 470    followed, or as required to translate it into languages other than
 471    English.
 472
 473    The limited permissions granted above are perpetual and will not be
 474    revoked by the Internet Society or its successors or assigns.
 475
 476    This document and the information contained herein is provided on an
 477    "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
 478    TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
 479    BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
 480    HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
 481    MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
 482
 483 Acknowledgement
 484
 485    Funding for the RFC Editor function is currently provided by the
 486    Internet Society.
 487
 488
 489
 490
 491
 492
 493
 494
 495
 496
 497
 498
 499
 500
 501
 502
 503
 504
 505
 506 Wahl & Howes                Standards Track                     [Page 9]
 507 \f