Skip to content

Commit 1d2ffe5

Browse files
ioggstreamgkelloggTallTed
committed
Preliminary rules.
 * Basic concepts and Core requirements * MUST UTF-8 * comments are white spaces * anchored nodes are considered static * FAQ Co-authored-by: Gregg Kellogg <[email protected]> Co-authored-by: Ted Thibodeau Jr <[email protected]>
1 parent 13ff5f8 commit 1d2ffe5

File tree

1 file changed

+240
-2
lines changed

1 file changed

+240
-2
lines changed

‎spec/index.html

Lines changed: 240 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -243,7 +243,7 @@ <h2>Introduction</h2>
243243
<p>
244244
Since YAML is more expressive than JSON,
245245
both in the available data types and in the document structure
246-
(see I-D.ietf-yaml-mediatypes),
246+
(see [[I-D.ietf-httpapi-yaml-mediatypes]]),
247247
this document identifies constraints on YAML documents
248248
such that they can be used to represent JSON-LD documents.
249249
</p>
@@ -283,9 +283,156 @@ <h2>Introduction</h2>
283283
<section id="basic-concepts" class="informative">
284284
<h2>Basic Concepts</h2>
285285

286-
<p>FIXME.</p>
286+
<p>
287+
To ease writing and collaborating on JSON-LD documents, it is a common practice
288+
to serialize them as YAML.
289+
This requires a registered media type, not only to enable content negotiation
290+
of linked data documents in YAML, but even to define the expected behavior of
291+
applications that processes these documents, including fragment identifiers and
292+
interoperability considerations.
293+
</p>
294+
295+
<p>
296+
This is because YAML is more flexible than JSON:
297+
</p>
298+
299+
<ul>
300+
<li>YAML supports different encodings, including UTF-8, UTF-16, and UTF-32.</li>
301+
<li>YAML supports more data types than JSON.</li>
302+
<li>the structure of a YAML document &mdash; that is, a named YAML representation graph &mdash;
303+
is a rooted, directed graph that can have cycles.</li>
304+
305+
<p>
306+
The first goal of this specification is to allow a JSON-LD document to be
307+
processed and serialized into YAML, and then back into JSON-LD, without
308+
losing any information.
309+
310+
This is always possible, because a YAML representation graph can always represent
311+
a tree, because JSON data types are a subset of YAML's, and because
312+
JSON encoding is UTF-8.
313+
</p>
314+
315+
<p data-format="markdown>Example: the JSON-LD document below
316+
317+
```
318+
{
319+
"@context": "http://example.org/context.jsonld",
320+
"@graph": [
321+
{"@id": "http://example.org/1", "title": "Example 1"},
322+
{"@id": "http://example.org/2", "title": "Example 2"},
323+
{"@id": "http://example.org/3", "title": "Example 3"}
324+
]
325+
}
326+
```
327+
328+
can be serialized as YAML as follows.
329+
Note that entries
330+
starting with `@` need to be enclosed in quotes or escaped because
331+
`@` is a reserved character in YAML.
332+
333+
```yaml
334+
%YAML 1.2
335+
---
336+
"@context": http://example.org/context.jsonld
337+
\@graph:
338+
-
339+
"@id": http://example.org/1
340+
title: Example 1
341+
-
342+
\@id: http://example.org/2
343+
title: Example 2
344+
-
345+
'@id': http://example.org/3
346+
title: Example 3
347+
```
348+
349+
350+
</p>
287351
</section>
352+
<section id="specifications" class="normative">
353+
<h2>Core Requirements</h2>
288354

355+
<p>
356+
A YAML-LD document is a [[YAML]] document that can be interpreted as Linked Data [[LINKED-DATA]].
357+
</p>
358+
<p>
359+
It MUST be encoded in UTF-8, to ensure interoperability with [[JSON]].
360+
</p>
361+
<p>
362+
Comments in YAML-LD documents
363+
are treated as white space
364+
This behavior is consistent with other
365+
Linked Data serializations like [[TURTLE]].
366+
See Interoperability considerations of [[I-D.ietf-httpapi-yaml-mediatypes]]
367+
for more details.
368+
</p>
369+
<p>
370+
Since named anchors are a serialization detail,
371+
such names
372+
MUST NOT be used to convey relevant information,
373+
MAY be altered when processing the document,
374+
and MAY be dropped when interpreting the document as JSON-LD.
375+
</p>
376+
<p>
377+
A YAML-LD document MAY contain named anchors and alias nodes,
378+
but its representation graph MUST NOT contain cycles.
379+
When interpreting the document as JSON-LD,
380+
alias nodes MUST be resolved by value to their target nodes.
381+
</p>
382+
<p data-format="markdown">
383+
Example: The following YAML-LD document
384+
contains alias nodes for the `{"@id": "country:ITA"}` object:
385+
386+
```yaml
387+
%YAML 1.2
388+
---
389+
"@context":
390+
"@vocab": "http://schema.org/"
391+
"countries": "http://publication.europa.eu/resource/authority/country/"
392+
"@graph":
393+
- &ITA
394+
"@id": countries:ITA
395+
- "@id": http://people.example/Homer
396+
name: Homer Simpson
397+
nationality: *ITA
398+
- "@id": http://people.example/Lisa
399+
name: Lisa Simpson
400+
nationality: *ITA
401+
```
402+
403+
While the representation graph (and eventually the in-memory representation
404+
of the data structure, e.g., a Python dictionary or a Java hashmap) will still
405+
contain references between nodes, the JSON-LD serialization will not.
406+
407+
```json
408+
{
409+
"@context": {
410+
"@vocab": "http://schema.org/",
411+
"countries": "http://publication.europa.eu/resource/authority/country/"
412+
},
413+
"@graph": [
414+
{
415+
"@id": "countries:ITA"
416+
},
417+
{
418+
"@id": "http://people.example/Homer",
419+
"full_name": "Homer Simpson",
420+
"country": {
421+
"@id": "countries:ITA"
422+
}
423+
},
424+
{
425+
"@id": "http://people.example/Lisa",
426+
"full_name": "Lisa Simpson",
427+
"country": {
428+
"@id": "countries:ITA"
429+
}
430+
}
431+
]
432+
}
433+
```
434+
</p>
435+
</section>
289436
<section id="sec" class="informative">
290437
<h2>Security Considerations</h2>
291438

@@ -423,5 +570,96 @@ <h3>Examples</h3>
423570
</section>
424571
</section>
425572

573+
<section id="faq" class="informative" data-format="markdown">
574+
<p class="ednote">REMOVE THIS SECTION BEFORE PUBLICATION.</p>
575+
576+
<h3>FAQ</h3>
577+
578+
#### Why does YAML-LD not preserve comments?
579+
<p class="ednote">
580+
[[JSON]] (and hence [[JSON-LD]]) does not support comments,
581+
and other Linked Data serialization formats
582+
that support comments (such as [[TURTLE]])
583+
do not provide a means to preserve them
584+
when processing and serializing the document
585+
in other formats.
586+
The proposed behavior is thus consistent with
587+
other implementations.
588+
589+
While YAML-LD could define a specific predicate for comments,
590+
that is insufficient because, for example,
591+
the order of keywords is not preserved in JSON, so the
592+
comments could be displaced.
593+
This specification does not provide a means for preserving
594+
YAML comments after a JSON serialization.
595+
596+
```yaml
597+
# First comment
598+
"@context": "http://schema.org"
599+
600+
# Second comment
601+
givenName: John
602+
```
603+
604+
transforming the above entry into a JSON-LD document
605+
results in:
606+
607+
```json
608+
{
609+
"@context": "http://schema.org",
610+
"givenName": "John"
611+
}
612+
```
613+
614+
615+
#### Why does YAML-LD not extend the JSON-LD data model ?
616+
<p class="ednote">
617+
[[JSON]] only represents simple trees while [[YAML]] can support
618+
rooted, directed graphs with references and cycles.
619+
620+
The above structures cannot be preserved when serializing
621+
to JSON-LD and - with respect to cycles - the serialization
622+
will fail.
623+
624+
Programming languages such as Java and Python already support
625+
YAML representation graphs, but these implementations may behave
626+
differently.
627+
In the following example, `&value` references the value
628+
of the keyword `value`.
629+
630+
```yaml
631+
value: &value 100
632+
valve1:
633+
temperature: &temp100C
634+
value: *value
635+
unit: degC
636+
valve2:
637+
temperature: *temp100C
638+
```
639+
640+
Processing this entry in Python, I get the following
641+
structure that preserve the references to
642+
mutable objects (e.g., the `temperature` dict)
643+
but not to scalars (e.g., the `value` keyword).
644+
645+
```python
646+
temperature = { "value": 100, "unit": "degC" }
647+
document = {
648+
"value": 100,
649+
"valve1": { "temperature": temperature },
650+
"valve2": { "temperature": temperature }
651+
}
652+
```
653+
654+
Since all these implementations pre-date this
655+
specification, some more interoperable choices include the following:
656+
657+
* to forbid cycles in YAML-LD documents
658+
* to consider all references in YAML-LD as static,
659+
i.e., a shorthand way to repeat specific patterns
660+
661+
</p>
662+
</section>
663+
426664
</body>
427665
</html>

0 commit comments

Comments
 (0)