How to update the management spec? name/identity index proposal.

[Alan Conway <aconway@redhat.com>]

I promised to update the management spec with the name/identity indexing
proposal but I can't figure out how. I can't find it under version
control. What's the procedure?

Here's the proposal in case someone else wants to do the edits:

---- proposed changes:

2.5.1: Remove "name" from required attribures. Keep "type" and
"identity"

New text:

Entities can always be identified by the unique "identity" attribute,
which is provided by the implementation.

An implementation MAY also provide other identifying attributes (such as
"name") that can be used to identify entities. Such attributes are
referred to as "index attributes". The existence of more index
attributes is part of the definition of an entity type, like any other
attribute.

The value of index attributes may be provided by the implementation, or
may be required from the user in the CREATE request. Index attributes
may be read-only or modifiable. This is all part of the definition of an
entity type, like any other attribute.

Index attributes are only special in that they can be used to identify
entities in READ, UPDATE and DELETE requests instead of the special
"identity" attribute.

3.3.1.1: Create request: remove name from app properties.

3.3.* READ, UPDATE, DELETE:

Replace the "name" property with:

index (string) [exactly one of index and identity is required] The name
of an index attribute to be used instead of "identity" to identify the
entity.

key (string) [required with index] The value of the index attribute to
be used to identify the entity.

----

Justification: The idea is to
- not force "name" on implementations that don't need/want it.
- allow implementations that want "name" to use it with minimal changes.
- provide additional flexibility for implementations that want
identifying attributes other than a universal user-supplied "name", e.g.
only on selected entity types or provided by system not user or even
multiple index attributes on some entities.
- not force extra uniqueness or search requirements on implementations
unless they opt for them. The whole index attribute concept is optional,
things like multi-index, different indexes per entity type etc. are
optional.

So for an implementation that wants the old "name" attribute behavior:
- All entity types are defined with a required, no-default, string
valued attribute "name" (they already do)
- The implementation must ensure that user-provided names are unique (it
already does)
- Only change: you must say READ:{index="name", key="foo"} instead of
READ:{name="foo"}