Draft: draft-ietf-core-coral

Commentary: Remnants of versions before these were littered all over the place ; I went through the document and changed things in what I hope to be managable commits . ( Created as a draft as it 's still incomplete ; especially I 'd like to move the information model around and deduplicate against what was the precursor to the information model ) . 
 I did n't get around to performing all the clean - up yet , leaving the model duplication for now in order to create a publishable as - good - as - it - is version .
The Constrained RESTful Application Language (CoRAL) defines a data
model and interaction model as well as two specialized serialization
formats for the description of typed connections between resources on
the Web ("links"), possible operations on such resources ("forms"),
and simple resource metadata.
The Constrained RESTful Application Language (CoRAL) defines a data
model and interaction model as well as a compact serialization
formats for the description of typed connections between resources on
the Web ("links"), possible operations on such resources ("forms"),
and simple resource metadata.
This document defines the CoRAL data model and interaction model as
well as two specialized CoRAL serialization formats.
This document defines the CoRAL data model and interaction model as
well as a compatct serialization format.
Exceeding the RDF-like model, this represents CoRAL's focus on the
discovery of possivble future application states over the description
of a graph of resources.
The primary serialization format is a compact, binary encoding of
links and forms in RFC8949.  This format is intended for RFC7228 and
shares many similarities with the message format of CoAP: In place of
verbose strings, small numeric identifiers are used to encode link
relation types and operation types.  RFC3986 are pre-parsed into
(what CoAP considers to be) their components, which considerably
simplifies URI processing for constrained nodes that already have a
CoAP implementation.  As a result, link serializations in CoRAL are
often much more compact and easier to process than equivalent
serializations in RFC6690.
The primary serialization format is a compact, binary encoding of
links and forms in RFC8949.  This format is intended for RFC7228 and
shares many similarities with the message format of CoAP: In place of
verbose strings, small numeric identifiers are used to encode link
relation types and operation types.  RFC3986 are expressed as I-
D.ietf-core-href and thus pre-parsed for easy use with CoAP.  As a
result, link serializations in CoRAL are often much more compact and
easier to process than equivalent serializations in RFC6690.
A link relation type identifies the semantics of a link.  In HTML and
in RFC8288, link relation types are typically denoted by an IANA-
registered name, such as "stylesheet" or "type".  In CoRAL, all link
relation types are, in contrast, denoted by an RFC3987, such as
<http://www.iana.org/assignments/relation/stylesheet> or
<http://www.w3.org/1999/02/22-rdf-syntax-ns#type>.  This allows for
the decentralized creation of new link relation types without the
risk of collisions when they come from different organizations or
domains of knowledge.  IRIs can also lead to documentation, schema,
and other information about a link relation type.  In CoRAL
documents, these IRIs are only used as identity tokens, though, and
are compared with Simple String Comparison as specified in RFC3987.
A link relation type identifies the semantics of a link.  In HTML and
in RFC8288, link relation types are typically denoted by an IANA-
registered name, such as "stylesheet" or "type".  In CoRAL, all link
relation types are, in contrast, denoted by a RFC3986, such as
<http://www.iana.org/assignments/relation/stylesheet> or
<http://www.w3.org/1999/02/22-rdf-syntax-ns#type>.  This allows for
the decentralized creation of new link relation types without the
risk of collisions when they come from different organizations or
domains of knowledge.  URIs can also lead to documentation, schema,
and other information about a link relation type.  In CoRAL
documents, these URIs are only used as identity tokens, though, and
are compared with Simple String Comparison as specified in RFC3986.
An operation type identifies the semantics of the operation.
Operation types are denoted (like link relation types) by an IRI.
An operation type identifies the semantics of the operation.
Operation types are denoted (like link relation types) by a URI.
A form field type identifies the semantics of the form field.  Form
field types are denoted (like link relation types and operation
types) by an IRI.
A form field type identifies the semantics of the form field.  Form
field types are denoted (like link relation types and operation
types) by a URI.
from the link target or submission target.  Link targets and
submission targets can be denoted by relative URI references,
which need to be resolved against a base URI to obtain the request
URI.  Fragment identifiers are not part of the request URI and
MUST be separated from the rest of the URI prior to the next step.
The agent constructs a new request with the request URI.  If the
agent is following a link, then the request method MUST be GET.
If the agent is submitting a form, then the request method MUST be
the one supplied by the form.  An IRI may need to be converted to
a URI (see RFC3987) for protocols that do not support IRIs.
from the link target or submission target.  Fragment identifiers
are not part of the request URI and MUST be separated from the
rest of the URI prior to the next step.
The agent constructs a new request with the request URI.  If the
agent is following a link, then the request method MUST be GET.
If the agent is submitting a form, then the request method MUST be
the one supplied by the form.
IRIs in links and forms are encoded as CRI references.
A CRI reference is processed by resolving it to an IRI as specified
in I-D.ietf-core-href using the current base.
URIs in links and forms are encoded as CRI references.
A CRI reference is processed by resolving it to a URI as specified in
I-D.ietf-core-href using the current base.
The link relation type is an IRI.
The link target is either an IRI, a literal value, or null.
The nested elements, if any, MUST be processed in a fresh
environment.  The current context is set to the link target of the
enclosing link.  The current base is initially set to the link
target, if the link target is an IRI; otherwise, it is set to the
current base of the current environment.
The link relation type is a URI.
The link target is either a URI, a literal value, or null.
The nested elements, if any, MUST be processed in a fresh
environment.  The current context is set to the link target of the
enclosing link.  The current base is initially set to the link
target, if the link target is a URI; otherwise, it is set to the
current base of the current environment.
The operation type is an IRI.
The submission target is an IRI.
The operation type is a URI.
The submission target is a URI.
The form field type is an IRI.
The form field value is either an IRI, a literal value, or null.
The nested elements, if any, MUST be processed in a fresh
environment.  The current context is set to the form field value of
the enclosing form field.  The current base is initially set to the
form field value, if the form field value is an IRI; otherwise, it is
set to the current base of the current environment.
The form field type is a URI.
The form field value is either a URI, a literal value, or null.
The nested elements, if any, MUST be processed in a fresh
environment.  The current context is set to the form field value of
the enclosing form field.  The current base is initially set to the
form field value, if the form field value is a URI; otherwise, it is
set to the current base of the current environment.
Resources are identified by IRIs or represented by literal values.
Resources are identified by URIs or represented by literal values.
Use of only either the binary format or the text format.
New link relation types, operation types, and form field types can be
minted by defining an IRI that uniquely identifies the item.
Although the IRI may point to a resource that contains a definition
of the semantics, clients SHOULD NOT automatically access that
resource to avoid overburdening its server.  The IRI SHOULD be under
the control of the person or party defining it, or be delegated to
them.
IRIs that identify vocabulary do not need to be registered.  The
inclusion of domain names in IRIs allows for the decentralized
creation of new IRIs without the risk of collisions.
However, IRIs can be relatively verbose and impose a high overhead on
a representation.  This can be a problem in RFC7228.  Therefore,
CoRAL alternatively allows the use of unsigned integers to reference
CBOR data items from a dictionary, as specified in dictionary-
compression.  These impose a much smaller overhead but instead need
to be assigned by an authority to avoid collisions.
New link relation types, operation types, and form field types can be
minted by defining a URI that uniquely identifies the item.  Although
the URI may point to a resource that contains a definition of the
semantics, clients SHOULD NOT automatically access that resource to
avoid overburdening its server.  The URI SHOULD be under the control
of the person or party defining it, or be delegated to them.
To avoid interoperability problems, it is RECOMMENDED that only URIs
are minted that are normalized according to RFC3986.  This is easily
achieved when the URIs are defined in CRI form (in which they also
become part of the dictionary), as this avoids many common non-
normalized forms of URIs by construction.
URIs that identify vocabulary do not need to be registered.  The
inclusion of domain names in URIs allows for the decentralized
creation of new URIs without the risk of collisions.
However, URIs can be relatively verbose and impose a high overhead on
a representation.  This can be a problem in RFC7228.  Therefore,
CoRAL alternatively allows the use of packed entities to reference
CBOR data items from a dictionary, as specified in dictionary-
compression.  These impose a much smaller overhead but instead need
to be assigned by an authority to avoid collisions.
The convention of appending the relation type name to the prefix
<http://www.iana.org/assignments/relation/> to form IRIs is adopted
from the RFC4287; see also RFC8288.
The convention of appending the relation type name to the prefix
<http://www.iana.org/assignments/relation/> to form URIs is adopted
from the RFC4287; see also RFC8288.
CoRAL makes extensive use of resource identifiers.  See RFC3986 for
security considerations relating to URIs.  See RFC3987 for security
considerations relating to IRIs.  See I-D.ietf-core-href for security
considerations relating to CRIs.
CoRAL makes extensive use of resource identifiers.  See RFC3986 for
security considerations relating to URIs.  See I-D.ietf-core-href for
security considerations relating to CRIs.
The security of applications using CoRAL can depend on the proper
preparation and comparison of internationalized strings.  For
example, such strings can be used to make authentication and
authorization decisions, and the security of an application could be
compromised if an entity providing a given string is connected to the
wrong account or online resource based on different interpretations
of the string.  See RFC6943 for security considerations relating to
identifiers in IRIs and other strings.
The security of applications using CoRAL can depend on the proper
preparation and comparison of internationalized strings.  For
example, such strings can be used to make authentication and
authorization decisions, and the security of an application could be
compromised if an entity providing a given string is connected to the
wrong account or online resource based on different interpretations
of the string.  See RFC6943 for security considerations relating to
identifiers in URIs and other strings.
This document registers a CBOR tag for dictionary references
according to the procedures of RFC8949.