Draft: draft-ietf-core-resource-directory

Commentary: This is the documenting text to the changes worked out first on the examples in . It does not ( yet ) contain explaining overall text , but updates the various smaller mentions of the parameter to fit together . It does change the semantics of using on a registration update , but I believe that the previous wording was not what the original authors had intended . ( Previously , an endpoint registering over TCP would need to explicitly repeat its con on every update ) .
Paragraph (version A):
When registering links to a Resource Directory, the Context refers
to the scheme, address, port, and base path for all the links
registered on behalf of an endpoint, of the general form
scheme://host:port/path/ where the client may explicitly set the
scheme and host, and may supply the port and path as optional
parameters.  When the context of a registration is explicitly set,
the URI resolution rules in RFC3986 MUST be applied.
Paragraph (version B):
A Context is a base URL that gives scheme and (typically)
authority information about an Endpoint.  The Context of an
Endpoint is provided at registration time, and is used by the
Resource Directory to resolve relative references inside the
registration into absolute URIs.
Paragraph (version B):
The host is free to choose links it deems appropriate to be exposed
in its ".well-known/core".  Typically, the links describe resources
that are served by the host, but the set can also contain links to
resources on other servers (see examples in [RFC6690] page 14).  The
set does not necessarily contain links to all resources served by the
host.
Paragraph (version B):
One or more link relations (expressed as space-separated values in
the "rel" attribute, defaulting to "hosts").  They describe a
relations between the link context and the link target.
Paragraph (version B):
A link context URI ("anchor").  The link context defines the
source of the relation, and serves as the Base URI for resolving
the target.  It can be relative, in which case it gets resolved
against the Base URI of the ".well-known/core" document it was
obtained from . It can be absent, in which the Base URI of the
document is used as the context.
Paragraph (version B):
A link target URI ("href", expressed between the angular brackets
in link-format).  The link target defines the destination of the
relation, and is the topic of all other target attributes.  If it
is a relative URI, it gets resolved against the link context URI.
Paragraph (version B):
Other target attributes (eg. resource type (rt), interface (if),
cor content-type (ct)).  These provide additional information
about the target URI.
Paragraph (version B):
Links are modelled as they are in fig-ER-WKC.  As they do not have
their ".well-known/core" document associated with them any more which
would originally provide its Base URI, the "con" attribute of the
registration fills that gap and is used as a Base URI.
Paragraph (version A):
Context (optional).  This parameter sets the scheme, address,
port and path at which this server is available in the form
scheme://host:port/path.  In the absence of this parameter the
scheme of the protocol, source address and source port of the
register request are assumed.  This parameter is mandatory when
the directory is filled by a third party such as an
commissioning tool.  When con is used, scheme and host are
mandatory and port and path parameters are optional.  If the
endpoint uses an ephemeral port to register with, it MUST
include the con: parameter in the registration to provide a
valid network path.  If the endpoint which is located behind a
NAT gateway is registering with a Resource Directory which is
on the network service side of the NAT gateway, the endpoint
MUST use a persistent port for the outgoing registration in
order to provide the NAT gateway with a valid network address
for replies and incoming requests.
Paragraph (version B):
Context (optional).  This parameter sets the Default Base URI
under which the request's body are be interpreted.  The URI
scheme provided MUST allow a path component, but the path
component of the Context parameter MUST be empty.  The
parameter is therefore of the shape "scheme://authority" for
HTTP and CoAP URIs.  In the absence of this parameter the
scheme of the protocol, source address and source port of the
register request are assumed.  This parameter is mandatory when
the directory is filled by a third party such as an
commissioning tool.  If the endpoint uses an ephemeral port to
register with, it MUST include the con parameter in the
registration to provide a valid network path.  If the endpoint
which is located behind a NAT gateway is registering with a
Resource Directory which is on the network service side of the
NAT gateway, the endpoint MUST use a persistent port for the
outgoing registration in order to provide the NAT gateway with
a valid network address for replies and incoming requests.
Paragraph (version A):
The endpoint MUST include the endpoint name and MAY include the
registration parameters d, lt, and et, in the POST request as per
registration.  The scheme://authority value of the registration is
taken from the requesting server's URI.
Paragraph (version B):
The endpoint MUST include the endpoint name and MAY include the
registration parameters d, lt, and et, in the POST request as per
registration.  The context of the registration is taken from the
requesting server's URI.
Paragraph (version A):
Context (optional).  This parameter sets the scheme, address
and port at which this server is available in the form
scheme://host:port/path.  In the absence of this parameter the
scheme of the protocol, source address and source port of the
register request are assumed.  This parameter is mandatory when
the directory is filled by a third party such as an
commissioning tool.  When con is used, scheme and host are
mandatory and port and path parameters are optional.
Paragraph (version B):
Context (optional).  This parameter updates the context
established in the original registration to a new value.  If
the parameter is set in an update, it is stored by the RD as
the new Base URI under which to interpret the links of the
registration, following the same restrictions as in the
registration.  If the parameter is not set and was set
explicitly before, the previous context value is kept
unmodified.  If the parameter is not set and was not set
explicitly before either, the source address and source port of
the update request are stored as the context.
Paragraph (version A):
RD Lookup does not expose registration resources directly, but
returns link content from registration resource entries which satisfy
RD Lookup queries.
Paragraph (version A):
Each endpoint and resource lookup result returns respectively the
scheme (IP address and port) followed by the path part of the URI of
every endpoint and resource inside angle brackets ("<>") and followed
by the other parameters.
Paragraph (version A):
The target of these links SHOULD be the actual location of the
endpoint or resource, but MAY be an intermediate proxy e.g. in the
case of an HTTP lookup interface for CoAP endpoints.
Paragraph (version A):
In case that a group does not implement any multicast address, the
group lookup returns every group lookup with a group base resource
value encapsulated within angle brackets (e.g. "/rd/look-up").
Otherwise, the group lookup returns the multicast address of the
group inside angle brackets.
Paragraph (version B):
While Endpoint Lookup does expose the registration resources, the RD
does not need to make them accessible to clients.  Clients SHOULD NOT
attempt to dereference or manipulate them.
Paragraph (version B):
Resource lookup results in links that are semantically equivalent to
the links submitted to the RD if they were accessed on the endpoint
itself.  The links and link parameters returned are equal to the
submitted ones except for anchor, which gets resolved according to
the endpoint's context.  That allows the client to interpret the
response as links without any further knowledge of what the RD does.
The Resource Directory MAY replace the contexts with a configured
intermediate proxy, e.g. in the case of an HTTP lookup interface for
CoAP endpoints.
Paragraph (version B):
Endpoint and group lookups result in links to the selected
registration and group resources.  Endpoint registration resources
are annotated with their endpoint names (ep), domains (d, if present)
and context (con).  Group resources are annotated with their group
names (gp), domain (d, if present) and multicast address (con, if
present).
Paragraph (version A):
Domain (optional).  Used for domain, group, endpoint and
resource lookups.
Paragraph (version B):
Domain (optional).  Used for group, endpoint and resource
lookups.