[Date Prev][Date Next]
[Chronological]
[Thread]
[Top]
models-09 comments
draft-ietf-ldapbis-models-09.txt says:
> 1.4. Common ABNF Productions
> ALPHA = %x41-5A / %x61-7A ; "A"-"Z" / "a"-"z"
> DIGIT = %x30 / LDIGIT ; "0"-"9"
Why spell out the character codes of these definitions instead of
using the more readable '"0" / LDIGIT' when you in any case say e.g.
ObjectClassDescription = LPAREN WSP
(...)
[ SP "NAME" SP qdescrs ] ; short names (descriptors)
instead of
[ SP %x4E %x41 %x4D %x45 SP qdescrs ]
later in the document?
> While the <descr> form is generally preferred when the usage is
> restricted to short names referring to object identifiers which
> identify like kinds of objects (e.g., attribute type descriptions,
> matching rule descriptions, object class descriptions), (...)
>
> When the <descr> form is used, the representation SHALL be considered
> invalid if the usage is not restricted as discussed above or the
> implementation cannot determine unambiguously which object identifier
^^^^^^^^^^^^^^
> the <descr> refers to.
This requires client implementations to fail if they don't maintain
descr->numericoid mappings.
Suggest to replace "the implementation" with "the server", or maybe
"an implementation which uses numericoids as the primary key to the
above objects (e.g. an LDAP server)".
> 2.1. The Directory Information Tree
> Similarly, the superior/subordinate relationship between object
..."and alias"...
> entries can be used to derive a relation between the objects they
> represent. DIT structure rules can be used to govern relationships
> between objects.
> 2.2.3. Alias Names
>
> An alias, or alias name, is "an name for an object, provided by the
> use of alias entries" [X.501]. Alias entries are described in Section
> 2.6.
This subsection doesn't say enough to tell the reader anything -
unless he already has read section 2.6 (Alias Entries), in which case
he doesn't need this subsection. I suggest it is deleted. Or if not,
replace it with something like this:
An entry may in some situations also be referred to via the DN
(alias name) of an alias entry which points to it. See Section
2.6.
> 2.4.2. Structural Object Classes
> An object or alias entry is characterised by precisely one
> structural object class superclass chain
This implies that structural object classes with multiple inheritance
cannot be used, since that gives two or more chains joined at both
ends. (No, that is not 'one chain'. 2.4 (Object Classes) says:
"An object class may be derived from two or more direct
superclasses (superclasses not part of the same superclass chain).
This feature of subclassing is termed multiple inheritance.")
> 2.5.1. Attribute Types
> An attribute type (a subtype) may derive from another attribute type
> (a direct supertype). The subtype inherits the matching rules and
> syntax of its supertype
..."unless those are overridden."
> 2.5.2.1. Tagging Options
> An attribute description with N tagging options is considered a direct
> (description) subtype of all attribute descriptions of the same
> attribute type and all but one of the N options. If the attribute
> type has a supertype, then the attribute description is also
> considered a direct (description) subtype of the attribute description
> of the supertype and the N tagging options. That is,
> 'cn;lang-de;lang-en' is considered a direct subtype of 'cn;lang-de',
> 'cn;lang-en', and 'name;lang-de;lang-en' ('cn' is a subtype of 'name',
> both are defined in [Schema]).
Why 'considered'? Aren't they really direct subtypes?
Suggest s/considered// in this paragraph.
> 3.1. Subtrees
>
> As defined in [X.501]:
> (...)
> Similarly, the
> scope of a subtree defining a specific administrative area is
> limited to the context of an enclosing autonomous administrative
> area.
Strike that sentence. It is unnecessary and will only confuse the
reader, since administrative areas (autonomous or otherwise) are
neither defined or mentioned elsewhere in this or other LDAPbis
drafts.
> 3.2. Subentries
> The term "(sub)entry" in this specification indicates that servers
> implementing X.500(93) models are, in accordance with X.500(93), to
> use a subentry and that other servers are to use an object entry
> belonging to the appropriate auxiliary class normally used with the
> subentry (e.g., 'subschema' for subschema subentries) to mimic the
> subentry. This object entry's RDN SHALL be formed from a value of the
^^^^^^^^^^^^
> 'cn' (commonName) attribute [Schema].
Only if it is an object entry? True subentries need not have a CN for
RDN?
> 3.3. The 'objectClass' attribute
> The 'objectClass' attribute specifies the object classes of an entry,
> which (among other things) is used in conjunction with user and system
> schema to determine the permitted attributes of an entry.
Suggest s/user and system schema/schema/ here, in 4.1.6, and in 7.1.
The terms "user schema" and "system schema" are neither defined nor
used elsewhere in this or other LDAPbis drafts, except in A.1.2 ("user
schema" and in the name of [Schema] and RFC2256.
Otherwise, these terms should be defined somewhere.
> 4.1. Schema Definitions
> xstring = X HYPHEN 1*( ALPHA / HYPHEN / USCORE )
Should xstring allow DIGIT?
> 4.1.1. Object Class Definitions
> [ SP "NAME" SP qdescrs ] ; short names (descriptors)
Are keywords like "NAME" supposed to be case-sensitive?
> 4.1.3. Matching Rules
> A matching rule specifies the syntax of the assertion value.
The matching rules in [Syntaxes] also specify the syntaxes of the
attribute values they can be used with. Should all matching rules be
required to do that?
> 4.1.4. Matching Rule Uses
> <numericoid> is the object identifier of the matching rule
> associated with this matching rule use description;
> NAME <qdescrs> are short names (descriptors) identifying this
> matching rule use;
What is NAME used for - how does it identify the matching rule use?
objectIdentifierFirstComponentMatch matches against oid of the
matching rule, not of the matching rule use. I would assume that is
true whether the assertion value is a numericoid or a descriptor,
otherwise it is a very strange objectIdentifierFirstComponentMatch.
NAMEs of DIT Content Rules has the same problem, though that has some
extra text:
> 4.1.6. DIT Content Rules
> Each content rule is identified by the object identifier, as well as
> any short names (descriptors), of the structural object class it
> applies to.
At first I read that as saying that the rule must have all the object
class' short names in its NAME field. That solves the above problem,
though it seems cumbersome.
Otherwise, if it just means that one can search for a rule by the
names of its corresponding object class as well as the by numericoid,
why is that specified only here and not somewhere which covers the
other schema elements in section 4?
> 4.1.7. DIT Structure Rules and Name Forms
>
> It is sometimes desirable to regulate where object
..."and alias"...
> entries can be
> placed in the DIT and how they can be named based upon their
> structural object class.
> 4.2. Subschema Subentries
What is 'subschema' as opposed to 'schema'?
> 4.2.6. 'dITContentRules'
> This attribute lists DIT Content Rules which are in force.
> 4.2.7. 'dITStructureRules'
> This attribute lists DIT Structure Rules which are in force.
> 4.2.8 'nameForms'
> This attribute lists Name Forms which are in force.
Does 'in force' mean that OBSOLETE rules/forms are not listed?
> 4.3. 'extensibleObject' object class
> Note that not all servers will implement this object class,
I think the following is wrong:
> and those
> which do not will reject requests to add entries which contain this
> object class, or modify an entry to add this object class.
Section 7.1 (Server Guidelines) says the server need not support all
object classes it recognizes. I assume that if it merely recognizes
'extensibleObject', it may add it to an entry. OTOH, it will refuse
to attributes that were supposed to be allowed by that object class.
I think it would be simplest to just delete the above text, and let
the reader figure out that extensibleObject is useless if it is not
implemented.
> 5. DSA (Server) Informational Model
> DIB fragment: The portion of the DIB that is held by one master
> DSA, comprising one or more naming contexts.
Please delete this definition (and split up the X.501 quote it is part
of). DIB fragments are not referred to elsewhere in this or other
LDAPbis drafts, so the reader doesn't need to learn what they are.
Instead, mention that a server may hold several naming contexts, since
the remaining text can be read as saying that it may only hold one.
> naming context: A subtree of entries held in a single master DSA.
'Mastering' or 'master DSAs' are not defined. Please add something
like: "A master DSA for a naming context is the DSA (server) which
holds the master copy of that naming context."
> 5.1.1. 'altServer'
>
> The 'altServer' attribute lists URLs referring to alternative servers
> which may be contacted when this server becomes unavailable.
Please mention whether or not the URLs may have other schemes than
'ldap'. I hope they may.
> 5.1.2. 'namingContexts'
> The 'namingContexts' attribute lists the context prefixes of the
> naming contexts the server masters or shadows (in part or in whole).
> If the server is a first-level DSA [X.501], it should list (in
> addition) an empty string (indicating the root of the DIT). If the
> server does not master or shadow any information (e.g. it is an LDAP
> gateway to a public X.500 directory) this attribute will be absent.
> If the server believes it masters or shadows the entire directory, the
> attribute will have a single value, and that value will be the empty
> string (indicating the root of the DIT).
'Shadowing' is not defined anywhere. Possibly the best place for a
definition is in section 6.3 (Cache and Shadowing). If so, this
section should refer to 6.3.
> 5.1.4. 'supportedExtension'
> An extended operation comprises a ExtendedRequest, possibly other PDUs
> defined by
..."the"?
> extension, and an ExtendedResponse [Protocol].
The term PDU is not defined in [Models]. I hope it can be avoided
without complicating the above text, though I have no suggestion at
the moment. Except, I didn't think there could be any other PDUs?
[Protocol] 4.12 says:
Each extended operation consists of an extended request and an
extended response.
No mention of other PDUs.
> 6.3. Cache and Shadowing
> Some servers may hold cache or shadow copies of entries,
Please define 'shadow copy'.
> 7.2 Client Guidelines
> Clients MUST NOT display nor attempt to decode as ASN.1, a value if
> its syntax is not known.
I think this is too strict. I suggest s/display/present as text/.
A client should be able to present all attributes, as long as it does
not make any assumptions about their format. E.g. the old ldapsearch
command presents all the attributes in an extended LDIF format,
without decoding UTF-8.
> Clients MUST NOT send attribute values in a request that are not valid
> according to the syntax defined for the attributes.
Again, too strict. It should be possible to search for attributes
whose syntax are not known to the client, if the user takes care of
the syntax. If the user makes a mistake there, the server will catch
it in an orderly fashion.
> 9. IANA Considerations
> The following descriptors (short names) should be updated to refer
> to RFC XXXX.
> aliasedEntryName A 2.5.4.1
This document does not define aliasedEntryName, it only refers to it.
If IANA is to refer that name to this document, section 2.6.2 should
define it:
( 2.5.4.1 NAME ( 'aliasedObjectName' 'aliasedEntryName' )
... )
and the text in 2.6 and 2.6.2 should be changed to match.
The current aliasedEntryName reference in
ftp://ftp.iana.org/assignments/ldap-parameters is to X.501.
------------------------------------------------------------------------
Clarifications, references & a bit more:
> 1.4. Common ABNF Productions
> ; Any UTF-8 character
Suggest [UTF-8] reference. First mention of UTF-8.
> 2.2. Naming of Entries
>
> 2.2.1. Relative Distinguished Names
>
> Each entry is named relative to its immediate superior. This relative
> name, known as its Relative Distinguished Name (RDN) [X.501], is
> composed of an unordered set of one or more attribute value assertions
> (AVA) consisting of an attribute description with zero options and an
> attribute value. These AVAs are chosen from the attributes of the
> entry.
This will be much easier to understand for first-time readers if
section 2.2 is placed after section 2.3 (Structure of an Entry), which
describes how the entry consists of attributes with attribute
descriptions and values. (Now that I write this, I remember I
suggested to put it after 2.5 as well before, and I see the problem
with that, but just swapping 2.2 and 2.3 will also help a lot.)
> 2.4.1. Abstract Object Classes
Suggest to put
"'top' is defined as follows:"
in front of this:
> ( 2.5.6.0 NAME 'top' ABSTRACT MUST objectClass )
because it is the first time the reader sees this notation, and may
not know what that piece of Greek is all about.
> 2.4.2. Structural Object Classes
> Each entry is said to belong to its structural object class as well as
> all classes in its structural object class's superclass chain,
Suggest to delete this:
> which
> always includes 'top'.
It was just mentioned two paragraphs ago, and before that in 2.5.1.
> 2.5.3. Attribute Description Hierarchies
> For the purpose of subschema administration of the entry, a required
> attribute specification is fulfilled if the entry contains a value of
Suggest "required attribute specification" is replaced with
"specification that an attribute is required" to make the sentence
easier to parse.
> an attribute description belonging to an attribute hierarchy if the
> attribute type of that description is the same as the required
> attribute's type. That is, a "MUST name" specification is fulfilled
> by 'name' or 'name;x-tag-option', but is not fulfilled by 'CN' nor by
> 'CN;x-tag-option'
..."even though 'cn' is a subtype of 'name'."
> 3.4. Operational attributes
> A DSA-shared operational attribute is used to represent information of
> the DSA Information Model. Its values, if shared between DSAs
> (servers) are identical (except during periods of transient
> inconsistency).
>
> A DSA-specific operational attribute is
..."also"...
(To emphasize that this is no different from DSA-shared.)
> used to represent information
> of the DSA Information Model. Its values, if shared between DSAs
> (servers), need not be identical.
Suggest to add "(E.g. 'supportedLDAPVersion'.)".
> 4.1.2. Attribute Types
> Note that the <AttributeTypeDescription> does not list the matching
> rules which can be used with that attribute type in an extensibleMatch
> search filter. This is done using the 'matchingRuleUse' attribute
Please add a reference to [Protocol] for extensibleMatch search
filters.
> Note that a single character
> of the Directory String syntax may be encoded in more than one octet
> since UTF-8 is a variable-length encoding.
Suggest [UTF-8] reference. First mention of UTF-8 outside of
examples.
> 4.1.3. Matching Rules
> Matching rules are used by servers to compare attribute values against
> assertion values
Please add "(values to search for or compare with)" since a first-time
reader may not have read about assertion values in [Protocol] yet.
> SYNTAX identifies the assertion syntax
Suggest to add "(the syntax of the assertion value)"
> by object identifier;
> 4.1.4. Matching Rule Uses
> A matching rule use lists the attributes which are suitable for use
> with an extensibleMatch search filter.
Suggest a reference to [Protocol] for extensibleMatch.
> 4.1.7.2. Name Forms
> Each name form indicates the structural object class to be named,
> a set of required attribute types, and a set of allowed attributes
> types. A particular attribute type cannot be listed in both sets.
The last sentence, or the following, is redundant:
> All attribute types in the required ("MUST") and allowed ("MAY") lists
> shall be different.
> 4.4. Subschema Discovery
> To discover the DN of the subschema (sub)entry holding the subschema
> controlling a particular entry, a client reads that entry's
> 'subschemaSubentry' operational attribute. To read schema attributes
> from the subschema (sub)entry, clients MUST issue a base object search
..."[Protocol]"... (as 'base object searches' have not been defined)
..."at that DN"...
> where the filter is "(objectClass=subschema)" [Filters] and the list
> of attributes includes the names of the desired schema attributes (as
> they are operational).
> 5.1. Server-specific Data Requirements
>
> An LDAP server SHALL provide information about itself and other
> information that is specific to each server. This is represented as a
> group of attributes located in the root DSE (DSA-Specific Entry),
> which is named with the zero-length LDAPDN.
LDAPDNs are not defined in this document, though there is a reference
(to "DNs") with that name.
I suggest s/zero-length LDAPDN/empty DN/.
> if a
> client performs a base object search of the root with the filter
Suggest a reference to [Protocol] for base object search.
> 5.1.2. 'namingContexts'
> This attribute allows a
> client to choose suitable base objects for searching
..."(i.e. the objects from which to search)"...
again since the reader may not have read [Protocol] yet. Unless the
text suggested in my message 'models: about using the directory' is
added.
> when it has
> contacted a server.
> 5.1.3. 'supportedControl'
> The 'supportedControl' attribute lists object identifiers identifying
> the request controls the server supports. If the server does not
> support any request controls, this attribute will be absent.
Suggest to add: "(A control [Protocol] alters the semantics of the
message between client and server it is attached to.)". The sentence
is roughly stolen from [Protocol] 4.1.11.
Or if not, at least add a reference to [Protocol] for controls.
> 5.1.6. 'supportedSASLMechanisms'
> The 'supportedSASLMechanisms' attribute lists the SASL mechanisms
> [RFC2222] which the server recognizes.
Suggest to add: "(SASL is an authentication framework.)"
[RFC2222] is not in References. Should be [SASL].
> 6.1. Preservation of User Information
> Where such requirements have not be explicitly stated, servers SHOULD
> preserve the value of user information but MAY return the value in a
> different form.
Suggest to add:
(For example, the DN "O=Widget\2C Inc." may be returned as
"o=Widget\, Inc." since "\2C" and "\," are different ways to
represent commas in DNs, and "O" and "o" represent the same
attribute's numericoid.)
> 12.1. Normative References
> [LDAPURL] Smith, M. (editor), "LDAP: Uniform Resource Locator",
> draft-ietf-ldapbis-url-xx.txt, a work in progress.
This reference is not used in the document.
> [ASCII] Coded Character Set--7-bit American Standard Code for
> Information Interchange, ANSI X3.4-1986.
This reference is not used in the document, though the name ASCII is.
------------------------------------------------------------------------
Editorial comments:
> 1.2. Relationship to X.501
>
> This document includes material, with and without adaptation, from the
> [X.501].
s/the//.
> 1.4. Common ABNF Productions
> HEX = DIGIT / %x41-46 / %x61-66 ; 0-9 / A-F / a-f
^^^^^^^^^^^^^^^
"0"-"9" / "A"-"F" / "a"-"f"
> 2.3. Structure of an Entry
>
> An entry consists of a set of attributes which hold information about
> the object which
..."the"...
> entry represents.
> The 'givenName' attribute cannot hold both "John" and "JOHN" as these
> are equivalent values (...)
s/The/One/ since two different 'givenName' attributes _can_ hold
"John" and "JOHN".
> 2.4.3. Auxiliary Object Classes
> They are commonly used to augment the sets of attributes
> required and allowed attributes to be present in an entry.
Suggest to delete the second "attributes".
> An entry can belong to any subset of the set of auxiliary object
> classes allowed by the DIT content rule associated with
..."the"...
> structural
> object class of the entry.
> 2.5. Attribute Descriptions
> An attribute description which consisting of an unrecognized attribute
> type is to be treated as unrecognized.
s/which consisting of/with/. The original wording does not include
attribute descriptions that contain options. Or use: "An attribute
description whose attribute type is unrecognized ...".
> All attributes of an entry must have distinct attribute descriptions.
Maybe s/distinct/different/. 'Distinct' may be more precise, except
it has several meanings.
> 2.5.1. Attribute Types
> If operational, the attribute type
> indicates the operational usage and whether the attribute can
s/can/is/
> modifiable by users or not. Operational attributes
..."are"...
> discussed in Section 3.4.
> An attribute description consisting of a subtype and no options is
> said to
..."be"...
> the direct description subtype of the attribute description
> consisting of the subtype's direct supertype and no options.
> 2.6.2. 'aliasedObjectName' attribute type
> The 'distinguishedNameMatch' matching rule and the DistinguishedName
> (1.3.6.1.4.1.1466.115.121.1.12) syntax is defined in [Syntaxes].
s/is/are/.
> 3.3. The 'objectClass' attribute
> The 'objectIdentifierMatch' matching rule and OBJECT IDENTIFIER
> (1.3.6.1.4.1.1466.115.121.1.38) syntax is defined in [Syntaxes].
s/and/and the/, s/is/are/.
> That is, if the auxiliary class 'x-a' is
> a subclass of the class 'x-b', adding 'x-a' to 'objectClass' causes
> 'x-b' to be implicitly added (if
..."it"...
> is not already present).
>
> Servers SHALL restrict modifications of this attribute to prevent a
^^^
Strike "a".
> superclasses of remaining 'objectClass' values from being deleted.
> 3.4. Operational attributes
> Servers SHOULD maintain the 'creatorsName', 'createTimestamp',
> 'modifiersName', and 'modifyTimestamp' for all entries of the DIT.
Remove the first "the" or add "attributes".
> 4. Directory Schema
> Formally, the Directory Schema comprises a set of:
This is indented 2 spaces too much.
> g) LDAP Syntaxes definitions that define encodings used in LDAP.
s/Syntaxes definitions/Syntax definitions/
> 4.1.2. Attribute Types
> COLLECTIVE requires usage userApplications. Use of collective
> attribute types in LDAP is not discussed in this technical
> specification.
Suggest to put this paragraph in front of NO-USER-MODIFICATION below
instead of in the middle of the description of usages.
> 4.1.7.2. Name Forms
> Each name form indicates the structural object class to be named,
> a set of required attribute types, and a set of allowed attributes
> types. A particular attribute type cannot be listed in both sets.
s/attributes types/attribute types/.
> 4.2.1. 'objectClasses'
> 4.2.2. 'attributeTypes'
> (...)
Suggest 4.2.1 - 4.2.8 are sorted alphabetically.
> 4.3. 'extensibleObject' object class
> The 'extensibleObject auxiliary object class allows entries belong to
^^^ ^^^
missing <'> missing "which"
> it to hold any attribute type.
> 5.1. Server-specific Data Requirements
> The values of these attributes provided may depend on session specific
> and other factors.
A bit hard to parse.
Suggest "The values provided for these attributes may..."
> attributes of the root DSE. Client SHOULD NOT assume that the
> subschema (sub)entry controlling the root DSE controls any entry held
> by the server.
s/Client/Clients/.
s/any entry/any other entries/. It does control the root DSE, after
all.
> 5.1.2. 'namingContexts'
Suggest a paragraph break in front of:
> This attribute allows a
> client to choose suitable base objects for searching when it has
> contacted a server.
> 6.1. Preservation of User Information
> Where such requirements have not be explicitly stated, servers SHOULD
s/be/been/.
> 7.1 Server Guidelines
>
> Servers MUST recognize all attribute types and object classes names
> defined in this document but, unless stated otherwise, need not
> support the associated functionality.
Move "unless stated otherwise" to the front of the sentence, since
extensibleObject is an exception to object classes which MUST be
supported.
> 7.2 Client Guidelines
> Clients MUST NOT assume the LDAP-specific string encoding is
> restricted to a UTF-8 encoded string of UCS characters or any
> particular subset of particular subset of UCS (such as a printable
> subset) unless such restriction is explicitly stated.
s/particular subset of particular subset of/particular subset of/.
> 12.1. Normative References
Suggest to put the references in alphabetical order.
> A.1.1 Section 3.2 of RFC 2251
> This document describes the X.500 data models, as used by LDAP
> in greater detail, especially in areas where the models require
> adaptation is needed.
s/require adaptation is needed/require adaptation/.
> A.1.2 Section 3.4 of RFC 2251
> of subschema (sub)entries is not terrible useful. This document (in
s/terrible/terribly/
--
Hallvard