Draft: draft-ietf-core-coral

Commentary: as per 2021 - 10 - 08 meeting . References to " textual " persist in the Usage Considerations ; these will later be migrated to the conversions .
The secondary serialization format is a lightweight, textual encoding
of links and forms that is intended to be easy to read and to write
for humans.  The format is loosely inspired by the syntax of W3C.REC-
turtle-20140225 and is mainly intended for giving examples in
documentation and specifications with precise semantics.
For easy representation of CoRAL documents in text, CBOR diagnostic
notation is used.  Along with indentation and comments, the notation
introduced in I-D.bormann-cbor-edn-literals is used to represent
CRIs.  This format is not expected to be sent over the network.
This section defines the syntax of documents in the CoRAL textual
format using two grammars: The lexical grammar defines how Unicode
characters are combined to form line terminators, white space,
comments, and tokens.  The syntactic grammar defines how tokens are
combined to form documents.  Both grammars are presented in RFC5234.
A document in the textual format is a Unicode string in a Unicode
encoding form Unicode.  The media type for such documents is "text/
coral".  The "charset" parameter of textual media types RFC6657 is
not used; instead, charset information is transported inside the
document in the form of an OPTIONAL Byte Order Mark (BOM).  The use
of the RFC3629 without a BOM is RECOMMENDED.
The lexical structure of a document in the textual format is made up
of four basic elements: line terminators, white space, comments, and
tokens.  Of these, only tokens are significant in the syntactic
grammar.  There are three kinds of tokens: identifier tokens, literal
tokens, and punctuator tokens.
When several lexical grammar rules match a sequence of characters in
a document, the longest match takes priority.
White space is a sequence of one or more white space characters.  A
white space character is any Unicode character with the White_Space
property.
Comments are sequences of characters that are ignored when parsing
text into tokens.  Single-line comments begin with the characters
"//" and extend to the end of the line.  Delimited comments begin
with the characters "/*" and end with the characters "*/".  Delimited
comments can occupy a portion of a line, a single line, or multiple
lines.
Comments do not nest.  The character sequences "/*" and "*/" have no
special meaning within a single-line comment; the character sequences
"//" and "/*" have no special meaning within a delimited comment.
All identifiers MUST be converted into Unicode.  Comparison of
identifiers is based on NFC and case-sensitive (unless otherwise
noted).
A literal token is a textual representation of a value.
IRI reference tokens denote references to resources on the Web.
An IRI reference literal consists of a Unicode string that conforms
to the syntax defined in RFC3987.  An IRI reference is either an IRI
or a relative reference.  IRI references are enclosed in angle
brackets ("<" and ">").
The case-insensitive tokens "true" and "false" denote the Boolean
values true and false, respectively.
Integer literal tokens denote an integer value of unspecified
precision.  By default, integer literals are expressed in decimal,
but they can also be specified in an alternate base using a prefix:
Binary literals begin with "0b", octal literals begin with "0o", and
hexadecimal literals begin with "0x" (in upper- or lowercase).
Decimal literals contain the digits "0" through "9".  Binary literals
contain "0" and "1", octal literals contain "0" through "7", and
hexadecimal literals contain "0" through "9" as well as "A" through
"F" in upper- or lowercase.
Negative integers are expressed by prepending a minus sign ("-").
Floating-point literal tokens denote a floating-point number of
unspecified precision.
Floating-point literals consist of a sequence of decimal digits
followed by a fraction, an exponent, or both.  The fraction consists
of a decimal point (".") followed by a sequence of decimal digits.
The exponent consists of the letter "e" in upper- or lowercase,
followed by an optional sign and a sequence of decimal digits that
indicate a power of 10 by which the value preceding the "e" is
multiplied.
Negative floating-point values are expressed by prepending a minus
sign ("-").
A floating-point literal can additionally denote either the special
"Not-a-Number" (NaN) value, positive infinity, or negative infinity.
The NaN value is produced by the case-insensitive token "NaN".  The
two infinite values are produced by the case-insensitive tokens
"+Infinity" (or simply "Infinity") and "-Infinity".
Date/time literal tokens denote an instant in time.
A date/time literal consists of the prefix "dt" and a sequence of
Unicode characters in RFC3339, enclosed in single quotes.
Byte string literal tokens denote an ordered sequence of bytes.
A byte string literal consists of a prefix and zero or more bytes
encoded in RFC4648, enclosed in single quotes.  Byte string literals
encoded in Base16 begin with "h" or "b16", byte string literals
encoded in Base32 begin with "b32", and byte string literals encoded
in Base64 begin with "b64".
Text string literal tokens denote a Unicode string.
A text string literal consists of zero or more Unicode characters
enclosed in double quotes.  It can include simple escape sequences
(such as \t for the tab character) as well as hexadecimal and Unicode
escape sequences.
An escape sequence denotes a single Unicode code point.  For
hexadecimal and Unicode escape sequences, the code point is expressed
by the hexadecimal number following the "\x", "\X", "\u", or "\U"
prefix.  Simple escape sequences indicate the code points listed in
simple-escape-sequences.
The case-insensitive tokens "null" and "_" denote the intentional
absence of any value.
Punctuator tokens are used for grouping and separating.
The syntactic structure of a document in the textual format is made
up of three kinds of elements: links, forms, and (as an extension to
the CoRAL data model) directives.  Directives provide a way to make
documents easier to read and write by setting a base for relative IRI
references and introducing shorthands for IRIs.
A document in the textual format consists of a sequence of zero or
more elements.  An element is either a link, a form, or a directive.
Directives provide the ability to manipulate the environment while
processing elements.
All directives start with a number sign ("#") followed by an
identifier.  The identifier is case-insensitive and restricted to
Unicode characters in the Basic Latin block.
The following two types of directives are available: the Base
directive and the Using directive.
It is an error if a document processor encounters any other type of
directive.
A Base directive consists of a number sign ("#"), followed by the
case-insensitive token "base", followed by a base IRI.
The base IRI is denoted by an IRI reference.  The IRI reference MUST
be resolved against the current context (not the current base).
The directive is processed by resolving the IRI reference against the
current context and assigning the result to the current base.
A Using directive consists of a number sign ("#"), followed by the
case-insensitive token "using", optionally followed by an identifier
and an equals sign ("="), finally followed by an IRI.  If the
identifier is not specified, it is assumed to be the empty string.
The directive is processed by adding the specified identifier and IRI
to the current mapping from identifiers to IRIs.  It is an error if
the identifier is already present in the mapping or if the IRI is not
an IRI but a relative reference.
IRIs in links and forms can be either denoted by an IRI reference or
looked up in a mapping from identifiers to IRIs.  Lookups can be done
in three ways: using a simple name, a qualified name, or a predefined
name.
All IRI references and names are processed by resolving them to an
IRI, as described in the following sub-sections.
An IRI reference is resolved to an IRI as specified in RFC3987 using
the current base as the base URI.
A simple name consists of an identifier.
A simple name is resolved to an IRI by looking up the empty string in
the current mapping from identifiers to IRIs and appending the given
identifier to the result.  It is an error if the empty string is not
present in the mapping.
A qualified name consists of two identifiers separated by a colon
(":").
A qualified name is resolved to an IRI by looking up the identifier
given on the left hand side in the current mapping from identifiers
to IRIs.  The identifier given on the right hand side is appended to
the result.  It is an error if the identifier on the left hand side
is not present in the mapping.
A predefined name consists of a commercial at sign ("@") followed by
an identifier.  The identifier is case-insensitive and restricted to
Unicode characters in the Basic Latin block.
A predefined name is resolved to an IRI by looking up the identifier
in tbl-predefined-names.  It is an error if the identifier is not
present in the table.
A link consists of the link relation type, followed by the link
target, optionally followed by a sequence of zero or more nested
elements enclosed in curly brackets ("{" and "}").
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 mapping from
identifiers to IRIs is initially set to a copy of the mapping from
identifiers to IRIs in the current environment.
A form consists of the operation type, followed by a "->" token and
the submission target, optionally followed by a sequence of zero or
more form fields enclosed in square brackets ("[" and "]").
The operation type is an IRI.
The submission target is an IRI.
The request method is either implied by the operation type or encoded
as a form field.  If both are given, the form field takes precedence
over the operation type.  Either way, the method MUST be applicable
to the Web transfer protocol identified by the scheme of the
submission target.
The form fields, if any, MUST be processed in a fresh environment.
The current context is set to an unspecified URI that represents the
enclosing form.  The current base is initially set to the submission
target of the enclosing form.  The mapping from identifiers to IRIs
is initially set to a copy of the mapping from identifiers to IRIs in
the current environment.
A form field consists of a form field type, followed by a form field
value, optionally followed by a sequence of zero or more nested
elements enclosed in curly brackets ("{" and "}").
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 mapping from
identifiers to IRIs is initially set to a copy of the mapping from
identifiers to IRIs in the current environment.
Representations are CoRAL documents encoded in the binary format
defined in binary or the textual format defined in textual.
Depending on the application, additional representation formats
may be used.
Representations are CoRAL documents encoded in the binary format
defined in binary.  Depending on the application, additional
representation formats may be used.
Implementers of the CoRAL textual format need to consider the
security aspects of handling Unicode input.  See UTR36 for security
considerations relating to visual spoofing and misuse of character
encodings.  See RFC3629 for security considerations relating to UTF-
possible security problems relating to Unicode.
This document registers the media type "text/coral" according to the
procedures of RFC6838 and guidelines of RFC6657.