Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Preliminary rules for discussion #34

Merged
merged 8 commits into from
Jul 6, 2022
Merged

Preliminary rules for discussion #34

Changes from 3 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
1d2ffe5
Preliminary rules.
ioggstream Jun 30, 2022
3b4dae0
Update spec/index.html
gkellogg Jul 5, 2022
068269a
Update spec/index.html
gkellogg Jul 5, 2022
20a0eb8
Update spec/index.html
gkellogg Jul 5, 2022
c1adb33
Fix: #46. YAML files are actually streams.
ioggstream Jul 5, 2022
6adfd73
Update spec/index.html
ioggstream Jul 5, 2022
b27637b
Update spec/index.html
ioggstream Jul 5, 2022
b73e250
Update spec/index.html
ioggstream Jul 6, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 21 additions & 11 deletions spec/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -221,7 +221,7 @@
to represent information serialized as JSON,
including Linked Data.
This document defines how to serialize linked data
in YAML documents.
in YAML.
Moreover, it registers the application/ld+yaml media type.
</p>
</section>
Expand All @@ -244,15 +244,12 @@ <h2>Introduction</h2>
Since YAML is more expressive than JSON,
both in the available data types and in the document structure
(see [[I-D.ietf-httpapi-yaml-mediatypes]]),
this document identifies constraints on YAML documents
such that they can be used to represent JSON-LD documents.
this document identifies constraints on YAML
such that it can be used to represent JSON-LD documents.
</p>
</section>

<section id="conformance">
<p>A <a>YAML-LD document</a> complies with this specification if ...</p>
<p class="ednote">Define <dfn>YAML-LD document</dfn> somewhere.</p>

<p>This specification makes use of the following namespace prefixes:</p>
<table class="simple">
<thead><tr>
Expand Down Expand Up @@ -298,9 +295,14 @@ <h2>Basic Concepts</h2>

<ul>
<li>YAML supports different encodings, including UTF-8, UTF-16, and UTF-32.</li>
<li>YAML supports more data types than JSON.</li>
<li>YAML supports more native data types than JSON.</li>
<li>the structure of a YAML document &mdash; that is, a named YAML representation graph &mdash;
is a rooted, directed graph that can have cycles.</li>
<li>YAML has the concept of stream, which is a sequence of documents.
While a stream usually contains one document,
streams with multiple documents are used to aggregate multiple,
related, documents into a single file or network stream.
</li>

<p>
The first goal of this specification is to allow a JSON-LD document to be
Expand Down Expand Up @@ -353,14 +355,22 @@ <h2>Basic Concepts</h2>
<h2>Core Requirements</h2>

<p>
A YAML-LD document is a [[YAML]] document that can be interpreted as Linked Data [[LINKED-DATA]].
A YAML-LD stream is a YAML stream of YAML-LD documents.
Note that each document in a stream is independent
from the others:
each one has its own context, YAML directives,
named anchors and so on.
ioggstream marked this conversation as resolved.
Show resolved Hide resolved
</p>
<p>
A YAML-LD document is a [[YAML]] document
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For consistency with earlier content, there should be no "YAML document", but I wonder whether that means that there should also be no YAML-LD document -- i.e., whether YAML-LD must be streams just like YAML itself.

Suggested change
A YAML-LD document is a [[YAML]] document
A YAML-LD document is [[YAML]]

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm leaving this suggestion unmerged based on @ioggstream's comments on today's meeting. It can be re-added as an issue or PR if it is inconsistent.

that can be interpreted as Linked Data [[LINKED-DATA]].
</p>
<p>
It MUST be encoded in UTF-8, to ensure interoperability with [[JSON]].
</p>
<p>
Comments in YAML-LD documents
are treated as white space
are treated as white space.
This behavior is consistent with other
Linked Data serializations like [[TURTLE]].
See Interoperability considerations of [[I-D.ietf-httpapi-yaml-mediatypes]]
Expand All @@ -381,7 +391,7 @@ <h2>Core Requirements</h2>
</p>
<p data-format="markdown">
Example: The following YAML-LD document
contains alias nodes for the `{"@id": "country:ITA"}` object:
contains alias nodes for the `{"@id": "countries:ITA"}` object:

```yaml
%YAML 1.2
Expand Down Expand Up @@ -577,7 +587,7 @@ <h3>FAQ</h3>

#### Why does YAML-LD not preserve comments?
<p class="ednote">
[[JSON]] (and hence [[JSON-LD]]) does not support comments,
[[JSON]] (and hence [[JSON-LD11]]) does not support comments,
and other Linked Data serialization formats
that support comments (such as [[TURTLE]])
do not provide a means to preserve them
Expand Down