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

Spec progress #78

Merged
merged 31 commits into from
Sep 13, 2022
Merged

Spec progress #78

Changes from 2 commits
Commits
Show all changes
31 commits
Select commit Hold shift + click to select a range
2e462a7
Spec progress
gkellogg Aug 21, 2022
0214e88
Apply suggestions from code review
gkellogg Aug 22, 2022
75355aa
Simplify and provide an example for serializing the extended internal…
gkellogg Aug 22, 2022
1f137d4
Fix spec references and some document structure issues.
gkellogg Aug 22, 2022
ff1d722
Flesh out the API section.
gkellogg Aug 23, 2022
edf3583
Update examples in Basic Concepts to be simpler JSON-LD, along the li…
gkellogg Aug 24, 2022
35bd899
Add "code" CSS style manually, for some reason ReSpec isn't using it.
gkellogg Aug 24, 2022
d970d96
Improve conversion step descriptions.
gkellogg Aug 24, 2022
d3d402f
Markup errors.
gkellogg Aug 24, 2022
de22b88
Further simplify the to-YAML algorithm and use the `|var|` shorthand …
gkellogg Aug 25, 2022
3b689bf
Expand on YAML-LD profiles.
gkellogg Aug 25, 2022
336e021
Fix bad ref.
gkellogg Aug 25, 2022
532d3df
Apply suggestions from code review
gkellogg Aug 26, 2022
4af20d3
Apply suggestions from code review
gkellogg Aug 26, 2022
27be7af
Update spec/index.html
gkellogg Aug 26, 2022
53837c8
Updates to recommended YAML serialization suggested by @pchampin.
gkellogg Aug 28, 2022
9154923
Update spec/index.html
gkellogg Aug 28, 2022
202db77
#73 Add `How to read this document` section
anatoly-scherbakov Aug 27, 2022
49378ce
Update spec/index.html
anatoly-scherbakov Aug 28, 2022
569158f
Update spec/index.html
anatoly-scherbakov Aug 28, 2022
f9b5646
Update spec/index.html
anatoly-scherbakov Aug 28, 2022
8534bd5
Update spec/index.html
anatoly-scherbakov Aug 28, 2022
d9f4fc1
Update spec/index.html
anatoly-scherbakov Aug 29, 2022
e88f19f
Update spec/index.html
anatoly-scherbakov Aug 29, 2022
1ea7336
Update spec/index.html
anatoly-scherbakov Aug 29, 2022
d5c0c03
Update spec/index.html
anatoly-scherbakov Aug 29, 2022
5bbf60f
Update markup to make it valid HTML: A `<p>` can not include `<ul>`, …
gkellogg Aug 29, 2022
a8e4a29
Update spec/index.html
gkellogg Aug 29, 2022
60a0b11
Updat4 WebIDL for JsonLdOptions to make it a "partial dictionary", wh…
gkellogg Aug 29, 2022
b675cb1
Apply suggestions from code review
gkellogg Sep 6, 2022
2964629
Fix API step citation.
gkellogg Sep 7, 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
135 changes: 106 additions & 29 deletions spec/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -289,7 +289,7 @@ <h2>Introduction</h2>
<p>
To take better advantage of the broader expressivity of YAML,
this document also defines a means of extending the
JSON-LD <a>internal representation</a> to allow a more complete expression
<a>JSON-LD internal representation</a> to allow a more complete expression
of native data types within YAML-LD, and allows use of the complete
[[[JSON-LD11-API]]] [[JSON-LD11-API]]
<a data-cite="JSON-LD11-API#the-application-programming-interface">
Expand Down Expand Up @@ -337,7 +337,7 @@ <h2>Terminology</h2>

<p>
The terms
<dfn data-cite="JSON-LD11-API#dfn-internal-representation" data-no-xref="">internal representation</dfn>, and
<dfn data-cite="JSON-LD11-API#dfn-internal-representation" data-lt="JSON-LD internal representation" data-no-xref="">internal representation</dfn>, and
<dfn data-cite="JSON-LD11#dom-jsonldoptions-documentloader">documentLoader</dfn>
are imported from [[JSON-LD11-API]].
</p>
Expand Down Expand Up @@ -701,14 +701,16 @@ <h2>Streams</h2>

<p>
Each of the individual <a>YAML documents</a> in the stream
has to be converted into a separated <a>JSON-LD document</a> and
is converted into a separated <a>JSON-LD document</a> and
gkellogg marked this conversation as resolved.
Show resolved Hide resolved
processed separately.
</p>

<p class="ednote">
<p class="issue" data-number="63">
The current text does not support this, and only supports
a single <a>YAML document</a>.
This is inconsistent with the processing description in <a href="#convert-stream" class="sectionRef"></a>.
Comment on lines +761 to 764
Copy link
Contributor

Choose a reason for hiding this comment

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

@gkellogg I suggest to say that:

  1. ld+yaml can contain multiple documents even in the basic profile;
  2. they should be processed in isolation. For further details see https://github.com/ietf-wg-httpapi/mediatypes/blob/main/draft-ietf-httpapi-yaml-mediatypes.md#yaml-streams-int-yaml-streams

This is because aggregating multiple docs in a single stream is a common practice and a useful native YAML feature addressed by editors and libraries.

Copy link
Member Author

Choose a reason for hiding this comment

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

I'm not sure what the implications for the API would be, as it doesn't really provide for separate documents.

I think this is something we come back to later.

</p>
</section>

</section>
</section>

<section id="conversion-to-ir">
Expand Down Expand Up @@ -877,7 +879,6 @@ <h3>Converting a <a>YAML sequence</a></h3>
append the result of processing |n|
to |sequence content|
using the appropriate conversion step.
<div class="ednote">Ignore <a>node tags</a>? Otherwise, how can they be used in processing?</div>
</li>
<li>The conversion result is |sequence content|.</li>
</ol>
Expand Down Expand Up @@ -913,7 +914,6 @@ <h3>Converting a <a>YAML mapping</a></h3>
|mapping content| using
|key| and |value|.</li>
</ol>
<div class="ednote">Ignore <a>node tags</a>? Otherwise, how can they be used in processing?</div>
</li>
<li>The conversion result is |mapping content|.</li>
</ol>
Expand All @@ -928,10 +928,10 @@ <h3>Converting a <a>YAML scalar</a></h3>
<ol>
<li>If the {{JsonLdOptions/extendedYAML}} flag is `true`,
and <a>node</a> |n|
has a <a>node tags</a>,
has a <a>node tag</a> |t|,
|n| is mapped as follows:
<ol>
<li>If <a>node tag</a> |t| resolves
<li>If |t| resolves
with a prefix of `tag:yaml.org.2002:`,
the conversion result is mapped through the
<a data-cite="YAML#core-schema">YAML Core Schema</a>.
Expand All @@ -943,6 +943,15 @@ <h3>Converting a <a>YAML scalar</a></h3>
the conversion result is a <a>language-tagged string</a>
with value taken from |n|,
ane a <a>language tag</a> taken from the suffix of |t|.
<div class="note">
<a>Node tags</a> including an underscore (`"_"`),
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
<a>Node tags</a> including an underscore (`"_"`),
<a>Node tags</a> including an underscore ("`_`"),

Copy link
Member Author

Choose a reason for hiding this comment

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

I went back and forth on this. The JSON-LD specs use "_" instead of "_" for equivalent quoted characters (e.g., in https://www.w3.org/TR/json-ld11/#the-i18n-namespace) That may make it more readable, if not be as accurate. If we do make the change, it needs to be done comprehensively, so I'll leave this out of this batch.

Copy link
Contributor

Choose a reason for hiding this comment

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

Fair enough. There may be some W3-ish style guide or examples that provides guidance, or others in the WG with opinions. I can live with the "_" style if there's general agreement that it's better, though it's not to my taste.

Copy link
Member Author

Choose a reason for hiding this comment

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

There were about four points in the document that use this style for "_", "#", and "%23". To my mind it's easier to see these as it exists easily, given how the spec styles code blocks.

such as `i18n:ar-eg_rtl` describe a combination
of language and text direction.
See <a data-cite="JSON-LD11#the-i18n-namespace">
The `i18n` Namespace
</a>
in [[JSON-LD11]].
</div>
</li>
<li>Otherwise, the conversion result is an
<a>RDF literal</a> with value taken from |n|
Expand Down Expand Up @@ -1028,6 +1037,23 @@ <h2>Conversion to YAML</h2>
`RDF literal`.
Copy link
Contributor

Choose a reason for hiding this comment

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

this should not be "for each RDF literal", but "for each namespace of datatype(s) used in RDF literals of the input RDF graph", although this phrasing is not very clear either.

Also: how are implementation chose the name of such tags?

Copy link
Member Author

Choose a reason for hiding this comment

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

this should not be "for each RDF literal", but "for each namespace of datatype(s) used in RDF literals of the input RDF graph", although this phrasing is not very clear either.

Well, in terms of iteration, it is for each "RDF literal" with the description of specifically looking at the "datatype IRIs" of those literals left unsaid.

Also: how are implementation chose the name of such tags?

As with most other RDF serialization formats, the choice of namespace prefix to use is up to a given implementation and not something that should be specified. It's perfectly legitimate to not use any %TAG prefixes and have the node tags be full IRIs. I don't think we can say more than this.

Copy link
Contributor

Choose a reason for hiding this comment

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

Well, in terms of iteration, it is for each "RDF literal"

Ok, now that you explain it, I understand what you meant. It is however very easy to misread the current phrasing as "there should be 1 TAG declaration per RDF literal". Furthermore...

It's perfectly legitimate to not use any %TAG prefixes and have the node tags be full IRIs.

agreed, and that's why a SHOULD seems to strong for me.

I don't think we can say more than this.

I think we should even say less 😉 i.e. and replace the SHOULD by a MAY. E.g. replacing the end of the sentence with "and MAY use %TAG directives to make the serialization of some RDF literals more concise."

Copy link
Member Author

Choose a reason for hiding this comment

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

I updated language and added an example in 53837c8. See if that helps.

</p>

<div class="issue markdown" data-number="6">
<p>A concrete proposal in that direction would be to use a tag at the top-level of any "idiomatic" YAML-LD document, applying to the whole object/array that makes the document.</p>
gkellogg marked this conversation as resolved.
Show resolved Hide resolved

<p>It might also include a version
to identify the specification that it relates to, allowing
for version announcement that could be used for future-proofing.</p>

<p>E.g.</p>

<pre>
!yaml-ld
$context: http://schema.org/
$type: Person
name: Pierre-Antoine Champin
</pre>
</div>

<pre class="example yaml"
data-transform="updateExample"
data-result-for="YAML-LD with multiple documents"
Expand Down Expand Up @@ -1139,37 +1165,88 @@ <h2>Application Profiles</h2>
or for maximum expresivity.
gkellogg marked this conversation as resolved.
Show resolved Hide resolved
The <a>YAML-LD JSON profile</a> provides for complete round-tripping
between YAML-LD documents and JSON-LD documents.
The <a>YAML-LD extended profile</a> <span class="ednote">FIXME</span>.</p>
The <a>YAML-LD extended profile</a> allows for the
gkellogg marked this conversation as resolved.
Show resolved Hide resolved
fuller use of YAML features to enhance the ability to
represent a greater amount of native datatypes
gkellogg marked this conversation as resolved.
Show resolved Hide resolved
and reduce document redundancy.</p>


<p>Application profiles can be set using the {{JsonLdProcessor}}
API interface, as well as an HTTP request profile (see <a href="#iana" class="sectionRef"></a>).</p>

<section id="yaml-ld-json-profile">
<h3>YAML-LD JSON Profile</h3>

<p>
The <dfn>YAML-LD JSON profile</dfn> <span class="ednote">
FIXME:
restricts encoding to UTF-8,
restricts the document to use the <a data-cite="YAML#core-schema">YAML Core Schema</a>,
restricts a <a>YAML mapping</a> to use only <a>string</a> keys,
prohibits the use of <a>alias nodes</a>,
prohibits the use of <a>node tags</a> (or simply ignores them),
prohibits <a>YAML streams</a> having more than one <a>document</a>.
</span>
The <dfn>YAML-LD JSON profile</dfn>
is based on the <a data-cite="YAML#core-schema">YAML Core Schema</a>,
which interprets only a limited set of <a>node tags</a>.
<a>YAML scalars</a> with <a>node tags</a> outside of the defined range
SHOULD be avoided and MUST be converted to the closest
scalar type from the <a data-cite="YAML#core-schema">YAML Core Schema</a>
gkellogg marked this conversation as resolved.
Show resolved Hide resolved
if found.
See <a href="#convert-scalar" class="sectionRef"></a>
for specifics.
</p>

<p>
Although YAML supports a greater range of encodings,
gkellogg marked this conversation as resolved.
Show resolved Hide resolved
YAML-LD documents in the <a>YAML-LD JSON Profile</a>
MUST NOT use encodings other than UTF-8.
</p>

<p>
Keys used in a <a>YAML mapping</a> MUST be <a>strings</a>.
</p>

<p>
Although YAML-LD documents MAY include <a>node anchors</a>,
documents MUST NOT use <a>alias nodes</a>.
</p>

<p>
A <a>YAML stream</a> MUST include a single <a>YAML document</a>,
gkellogg marked this conversation as resolved.
Show resolved Hide resolved
as the <a>JSON-LD internal representation</a> supports
only a single document model.
gkellogg marked this conversation as resolved.
Show resolved Hide resolved
</p>
</section>

<section id="yaml-ld-extended-profile">
<h3>YAML-LD Extended Profile</h3>

<p>
The <dfn>YAML-LD extended profile</dfn> <span class="ednote">
FIXME:
restricts encoding to UTF-8,
restricts the document to use the <a data-cite="YAML#core-schema">YAML Core Schema</a> (allowing <a>node tags</a> to specifying <a>RDF literals</a>),
restricts a <a>YAML mapping</a> to use only <a>string</a> keys,
allows the use of <a>alias nodes</a>,
allows the use of <a>node tags</a> for specifying <a>RDF literals</a>,
prohibits <a>YAML streams</a> having more than one <a>document</a>,
</span>.
The <dfn>YAML-LD extended profile</dfn>
extends the <a data-cite="YAML#core-schema">YAML Core Schema</a>
gkellogg marked this conversation as resolved.
Show resolved Hide resolved
allowing <a>node tags</a> to specify <a>RDF literals</a>
by using an <a>JSON-LD extended internal representation</a> capable
gkellogg marked this conversation as resolved.
Show resolved Hide resolved
of representing <a>RDF literals</a> directly.
gkellogg marked this conversation as resolved.
Show resolved Hide resolved
</p>

<p>
As with the <a>YAML-LD JSON profile</a>,
YAML-LD documents in the <a>YAML-LD extended profile</a>
MUST NOT use encodings other than UTF-8.
</p>

<p>
As with the <a>YAML-LD JSON profile</a>,
keys used in a <a>YAML mapping</a> MUST be <a>strings</a>.
</p>

<p>
YAML-LD docucments MAY use <a>alias nodes</a>,
as long as dereferencing these aliases does not result in a loop.
</p>

<p>
As with the <a>YAML-LD JSON profile</a>,
a <a>YAML stream</a> MUST include a single <a>YAML document</a>,
as the <a>JSON-LD extended internal representation</a> supports
only a single document model.
gkellogg marked this conversation as resolved.
Show resolved Hide resolved
</p>

<p class="issue" data-number="79">
Consier something like `!id` as a local tag to denote IRIs.
</p>

<section id="extended-internal-representation">
Expand Down