https://codereview.appspot.com/5836049/diff/1/source/drafts/relation-reference.rst
File source/drafts/relation-reference.rst (right):

https://codereview.appspot.com/5836049/diff/1/source/drafts/relation-reference.rst#newcode6
source/drafts/relation-reference.rst:6: relation name or the relation
id:
You need to back these statements. The proposal starts by already saying
that the feature is required, and that it's going to be required in one
of two ways. I suggest dropping part of this introduction and starting
the spec at the point mentioned below.

https://codereview.appspot.com/5836049/diff/1/source/drafts/relation-reference.rst#newcode18
source/drafts/relation-reference.rst:18: Relation ids are also sometimes
required. This is because a service
Start at "[A] service may provide an interface (...)". Here you have a
good introduction to why you're proposing a change to the current
mechanism.

https://codereview.appspot.com/5836049/diff/1/source/drafts/relation-reference.rst#newcode22
source/drafts/relation-reference.rst:22: ``mysql`` interface to multiple
consuming clients using the relation
Examples benefit from unique names so that one can tell what is being
referred to:

     (...). For example, the ``mysql5`` service might provide
     a relation named `db` with a ``mysql`` interface.

https://codereview.appspot.com/5836049/diff/1/source/drafts/relation-reference.rst#newcode24
source/drafts/relation-reference.rst:24: to use its relation id, not the
relation name.
This sentence has to be more specific. In many circumstances, it is
possible to specify a relation solely by its name, even in the scenario
you provide. Note that so far we don't have this setting, and we manage
to do reasonably well without it. Please finish this paragraph with an
actual example that requires such unique id, to give context to the
whole proposal.

https://codereview.appspot.com/5836049/diff/1/source/drafts/relation-reference.rst#newcode27
source/drafts/relation-reference.rst:27: as described in a subsequent
section.
Also needs context. Why is this necessary? You've also mentioned
$JUJU_RELATION_ID above. What's the difference between them?

The paragraph also needs to be moved. It's saying how a relation id may
be obtained, without ever describing what it is, which is done by the
following paragraph.

https://codereview.appspot.com/5836049/diff/1/source/drafts/relation-reference.rst#newcode30
source/drafts/relation-reference.rst:30: be ``<interface
name>-<normalized internal relation
This should probably be <relation name> rather than <interface name>
and, it'd be good to avoid the dash between those entries, because
relation names are often named after the charm, and "mysql-42" looks
like a charm name-revision. Might also look nicer if indented.

I suggest something like:

"""
To ensure readability of this relation id, its format is specified to
be::

     <relation name>:<normalized internal relation id>

Normalization removes any padding zeros from the internal id. For
example, if the relation is associated with a relation named ``http``
and the respective relation id is ``relation-0000000042``, then the
relation id is ``http:42``.
"""

Please put the bug in a references section at the end. It's not relevant
to the point being made here.

https://codereview.appspot.com/5836049/diff/1/source/drafts/relation-reference.rst#newcode42
source/drafts/relation-reference.rst:42: followed by a number.
This is unnecessary given the above suggestion of using a colon.

https://codereview.appspot.com/5836049/diff/1/source/drafts/relation-reference.rst#newcode44
source/drafts/relation-reference.rst:44: Lastly, relation ids are never
visible outside of relation hooks or
This paragraph must be inverted. It's stating where the id isn't
visible, but the spec never describes where the setting *is* visible.

https://codereview.appspot.com/5836049/